> ## 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.

# Regras de acesso

> Agende um início e um fim, limite o número de leituras, exija uma senha e pause, reative ou exclua um QR code.

> [!NOTE]
>
> A API do GetQR está em beta e disponível para workspaces selecionados. Os detalhes podem mudar antes do lançamento oficial.

Controle quando um QR code é resolvido, quantas vezes ele pode ser lido, se pede uma senha e se está pausado ou excluído.

## Antes de começar

* **Função.** Definir regras, pausar, reativar e excluir exigem acesso de escrita aos QR codes do workspace. Veja [Autenticação](https://docs.getqr.com/pt-br/api/authentication.md).
* **Assinatura.** Toda requisição à API exige uma assinatura ativa do proprietário do workspace, inclusive estas.

## O objeto access

Envie um objeto `access` ao [criar](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#criar-um-qr-code) ou [atualizar](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#atualizar-um-qr-code) um QR code:

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

| Campo | Tipo | Descrição |
| - | - | - |
| `activeAt` | string (ISO 8601) \| null | Início agendado. Antes desse momento, as leituras mostram a página de pausa em vez do destino. `null` significa ativo imediatamente. |
| `pauseAt` | string (ISO 8601) \| null | Fim agendado. A partir desse momento, as leituras mostram a página de pausa. `null` significa sem data de término. |
| `scanLimit` | integer \| null | Número máximo de leituras durante toda a vida do QR code. Depois de excedido, as leituras mostram a página de pausa. `null` significa ilimitado. |
| `password` | string \| null | Senha que os visitantes precisam digitar antes de serem redirecionados. Enviá-la também ativa a proteção. |
| `passwordProtected` | boolean | Se o QR code pede uma senha. `false` desativa a proteção, mas mantém a senha armazenada. `true` a ativa de novo. |

Os campos omitidos permanecem inalterados. Envie `null` para limpar uma regra. Um objeto `access` parcial nunca redefine regras que você não mencionou.

> [!WARNING]
>
> As regras de acesso ficam em `access`. Enviar `activeAt`, `pauseAt`, `scanLimit`, `password` ou `passwordProtected` dentro de `link` retorna `422`.

## Agende um início e um fim

`activeAt` e `pauseAt` são independentes: defina um deles ou os dois. Ambos aceitam data e hora ISO 8601, com `Z` ou um deslocamento de 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"
    }
  }'
```

Envie `null` para limpar o agendamento. Isso deixa o QR code ativo imediatamente e remove a data de término:

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

## Limite de leituras

Limite o número total de leituras. Depois disso, o QR code deixa de ser resolvido:

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

O contador de leituras de toda a vida do QR code está sempre ativo, com ou sem limite definido. Isso torna previsível a alteração do limite:

* **Aumentar o limite** libera exatamente (novo limite menos total de leituras) leituras adicionais.
* **Reduzir o limite** abaixo do total atual bloqueia o QR code imediatamente.
* **Definir um limite depois** conta as leituras feitas enquanto não havia limite.

`scanLimit` deve ser um inteiro positivo, até 2147483647. Envie `null` para ilimitado.

## Proteção por senha

Defina uma senha pelo mesmo objeto `access`. A senha armazenada é mantida quando você desativa a proteção, então você pode reativá-la sem enviar a senha de novo.

**1. Defina ou altere a senha**

Isso também ativa a proteção.

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

**2. Desative a proteção**

A senha armazenada é mantida.

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

**3. Reative a proteção**

Não é preciso reenviar a senha. Isso só funciona depois que uma senha foi definida. Caso contrário, a requisição recebe `422`.

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

* **Na criação.** Envie `password` para ativar a proteção. `passwordProtected` sozinho não tem efeito enquanto não existir uma senha.
* **Remover a senha.** Envie `"password": null`. A proteção também é desativada.
* **Leitura.** As respostas nunca retornam a senha, apenas `access.passwordProtected`.

## Pausar, reativar e excluir

Pausar e reativar são endpoints separados, e não campos de `access`, porque entram em vigor na hora, e não por agendamento.

| Método | Caminho | Descrição |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [Pausa o QR code agora](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#pausar-um-qr-code). As leituras mostram a página de pausa até você reativá-lo. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Reativa um QR code pausado](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#reativar-um-qr-code). Agendamentos e limites de leituras continuam valendo. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Exclui o QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#excluir-um-qr-code) e o link curto dele de forma permanente. |

Pausar e ativar não recebem corpo de requisição e retornam o [QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#o-objeto-qr-code) atualizado:

```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,
  "…": "…"
}
```

Você também pode definir o estado de pausa com `PUT /api/v1/qrs/{qrId}` e `{ "archived": true }`, ou com `archived` em um `PATCH`. Veja [Definir o estado de pausa](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#definir-o-estado-de-pausa).

A exclusão remove o QR code e o link curto dele juntos:

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

> [!WARNING]
>
> A exclusão não pode ser desfeita. O link curto deixa de ser resolvido, então os códigos impressos param de funcionar. Se você puder precisar do QR code de novo, pause-o em vez de excluí-lo.

## Quando as mudanças entram em vigor

* **Próxima leitura.** As regras são verificadas quando um código é lido, então uma mudança vale a partir da próxima leitura, não retroativamente.
* **Página de pausa.** Um QR code bloqueado por agendamento, limite de leituras ou pausa mostra a página de pausa. A leitura não é redirecionada.
* **Senha.** Visitantes que já digitaram a senha mantêm o acesso até a senha mudar, ou até a proteção ser desativada e ativada de novo.
* **Relógio.** Os agendamentos usam o relógio do servidor em UTC, não o horário local do visitante.
* **Regras combinadas.** Um QR code só é resolvido quando não está pausado, está dentro do agendamento e está abaixo do limite de leituras.

## Problemas comuns

> [accordion] 422 ao definir uma regra dentro de link
>
> Envie a regra em `access`, não em `link`.

> [accordion] 422 ao ativar a proteção por senha
>
> O QR code ainda não tem senha. Envie `password` em vez de `passwordProtected: true`.

> [accordion] O QR code continua mostrando a página de pausa depois de reativado
>
> Um agendamento ou limite de leituras ainda se aplica. Verifique `access.activeAt`, `access.pauseAt` e `access.scanLimit` no [QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#obter-um-qr-code) e compare `scans` com o limite.

> [accordion] Preciso que o link expire
>
> `link.expiresAt` não está disponível nesta API. Use `access.pauseAt`.

## Próximos passos

> [card] [QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md)

> [card] [Dados do QR code por tipo](https://docs.getqr.com/pt-br/api/guides/qr-types.md)


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