> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reglas de acceso

> Programa un inicio y un final, limita el número de escaneos, exige una contraseña y pausa, reactiva o elimina un código QR.

> [!NOTE]
>
> La API de GetQR está en beta y solo está disponible para algunos espacios de trabajo. Los detalles pueden cambiar antes del lanzamiento general.

Controla cuándo se resuelve un código QR, cuántas veces se puede escanear, si pide una contraseña y si está pausado o eliminado.

## Antes de empezar

* **Rol.** Para definir reglas, pausar, reactivar y eliminar necesitas acceso de escritura a los códigos QR del espacio de trabajo. Consulta [Autenticación](https://docs.getqr.com/es/api/authentication.md).
* **Suscripción.** Todas las solicitudes a la API, incluidas estas, requieren que el propietario del espacio de trabajo tenga una suscripción activa.

## El objeto de acceso

Envía un objeto `access` al [crear](https://docs.getqr.com/es/api/endpoints/qr-codes.md#crear-un-código-qr) o [actualizar](https://docs.getqr.com/es/api/endpoints/qr-codes.md#actualizar-un-código-qr) un código QR:

```text theme={null}
POST  /api/v1/qrs
PATCH /api/v1/qrs/{qrId}
```

| Campo | Tipo | Descripción |
| - | - | - |
| `activeAt` | string (ISO 8601) \| null | Inicio programado. Antes de este momento, los escaneos muestran la página de pausa en lugar del destino. `null` significa activo de inmediato. |
| `pauseAt` | string (ISO 8601) \| null | Final programado. A partir de este momento, los escaneos muestran la página de pausa. `null` significa sin fecha de fin. |
| `scanLimit` | integer \| null | Número máximo de escaneos durante toda la vida del código QR. Una vez superado, los escaneos muestran la página de pausa. `null` significa ilimitado. |
| `password` | string \| null | Contraseña que los visitantes deben introducir antes de ser redirigidos. Enviarla también activa la protección. |
| `passwordProtected` | boolean | Si el código QR pide contraseña. `false` desactiva la protección, pero conserva la contraseña guardada. `true` la vuelve a activar. |

Los campos que omites no cambian. Envía `null` para borrar una regla. Un objeto `access` parcial nunca restablece las reglas que no mencionas.

> [!WARNING]
>
> Las reglas de acceso van dentro de `access`. Enviar `activeAt`, `pauseAt`, `scanLimit`, `password` o `passwordProtected` dentro de `link` devuelve `422`.

## Programa un inicio y un final

`activeAt` y `pauseAt` son independientes: define uno de ellos o ambos. Los dos aceptan fechas y horas ISO 8601, con `Z` o un desfase respecto a UTC.

```bash theme={null}
curl -X PATCH "https://getqr.com/api/v1/qrs/qr_abc123" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {
      "activeAt": "2026-08-01T09:00:00Z",
      "pauseAt": "2026-08-31T23:59:59Z"
    }
  }'
```

Envía `null` para borrar la programación. El código QR pasa a estar activo de inmediato y se elimina la fecha de fin:

```json theme={null}
{
  "access": { "activeAt": null, "pauseAt": null }
}
```

## Límite de escaneos

Limita el número total de escaneos. Al alcanzarlo, el código QR deja de resolverse:

```json theme={null}
{
  "access": { "scanLimit": 500 }
}
```

El contador de escaneos de toda la vida del código funciona siempre, haya o no un límite definido. Por eso, cambiar el límite es predecible:

* **Subir el límite** libera exactamente (nuevo límite menos escaneos totales) escaneos más.
* **Bajar el límite** por debajo del total actual bloquea el código QR de inmediato.
* **Definir un límite más tarde** cuenta los escaneos realizados mientras no había límite.

`scanLimit` debe ser un número entero positivo, hasta 2147483647. Envía `null` para que sea ilimitado.

## Protección con contraseña

Define una contraseña con el mismo objeto `access`. La contraseña guardada se conserva cuando desactivas la protección, así que puedes volver a activarla sin enviarla de nuevo.

**1. Define o cambia la contraseña**

Esto también activa la protección.

```json theme={null}
{ "access": { "password": "hunter2" } }
```

**2. Desactiva la protección**

La contraseña guardada se conserva.

```json theme={null}
{ "access": { "passwordProtected": false } }
```

**3. Vuelve a activar la protección**

No hace falta reenviar la contraseña. Solo funciona si ya se ha definido una contraseña. Si no, la solicitud devuelve `422`.

```json theme={null}
{ "access": { "passwordProtected": true } }
```

* **Al crear.** Envía `password` para activar la protección. `passwordProtected` por sí solo no tiene efecto hasta que exista una contraseña.
* **Quitar la contraseña.** Envía `"password": null`. La protección también se desactiva.
* **Lectura.** Las respuestas nunca devuelven la contraseña, solo `access.passwordProtected`.

## Pausar, reactivar y eliminar

Pausar y reactivar son endpoints independientes en lugar de campos de `access`, porque surten efecto al instante y no según una programación.

| Método | Ruta | Descripción |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [Pausa el código QR ahora](https://docs.getqr.com/es/api/endpoints/qr-codes.md#pausar-un-código-qr). Los escaneos muestran la página de pausa hasta que lo reactives. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Reactiva un código QR pausado](https://docs.getqr.com/es/api/endpoints/qr-codes.md#reactivar-un-código-qr). La programación y el límite de escaneos siguen aplicándose. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Elimina el código QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md#eliminar-un-código-qr) y su enlace corto de forma permanente. |

Pausar y activar no llevan cuerpo de solicitud y devuelven el [código QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md#el-objeto-de-código-qr) actualizado:

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_abc123/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json theme={null}
{
  "id": "qr_abc123",
  "archived": true,
  "…": "…"
}
```

También puedes definir el estado de pausa con `PUT /api/v1/qrs/{qrId}` y `{ "archived": true }`, o con `archived` en un `PATCH`. Consulta [Establecer el estado de pausa](https://docs.getqr.com/es/api/endpoints/qr-codes.md#establecer-el-estado-de-pausa).

Eliminar borra a la vez el código QR y su enlace corto:

```json theme={null}
{ "id": "qr_abc123", "deleted": true }
```

> [!WARNING]
>
> La eliminación no se puede deshacer. El enlace corto deja de resolverse, así que los códigos impresos dejan de funcionar. Si puedes volver a necesitarlo, pausa el código QR en su lugar.

## Cuándo entran en vigor los cambios

* **Siguiente escaneo.** Las reglas se comprueban al escanear un código, así que un cambio se aplica desde el siguiente escaneo, no de forma retroactiva.
* **Página de pausa.** Un código QR bloqueado por una programación, un límite de escaneos o una pausa muestra la página de pausa. El escaneo no se redirige.
* **Contraseña.** Los visitantes que ya introdujeron la contraseña mantienen el acceso hasta que la contraseña cambia, o hasta que la protección se desactiva y se vuelve a activar.
* **Reloj.** Las programaciones usan el reloj del servidor en UTC, no la hora local del visitante.
* **Las reglas se combinan.** Un código QR solo se resuelve si no está pausado, está dentro de su programación y no ha superado su límite de escaneos.

## Problemas habituales

> [accordion] 422 al definir una regla dentro de link
>
> Envía la regla dentro de `access`, no de `link`.

> [accordion] 422 al activar la protección con contraseña
>
> El código QR todavía no tiene contraseña. Envía `password` en lugar de `passwordProtected: true`.

> [accordion] El código QR sigue mostrando la página de pausa después de reactivarlo
>
> Todavía se aplica una programación o un límite de escaneos. Comprueba `access.activeAt`, `access.pauseAt` y `access.scanLimit` en el [código QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md#obtener-un-código-qr) y compara `scans` con el límite.

> [accordion] Necesito que el enlace caduque
>
> `link.expiresAt` no está disponible en esta API. Usa `access.pauseAt` en su lugar.

## Siguientes pasos

> [card] [Códigos QR](https://docs.getqr.com/es/api/endpoints/qr-codes.md)

> [card] [Datos del código QR por tipo](https://docs.getqr.com/es/api/guides/qr-types.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.