> ## 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 palavra-passe e coloque em pausa, reative ou elimine um código QR.

> [!NOTE]
>
> A API do GetQR está em versão beta e só está disponível para alguns espaços de trabalho. Os detalhes podem mudar antes do lançamento geral.

Controle quando um código QR é resolvido, quantas vezes pode ser lido, se pede uma palavra-passe e se está em pausa ou eliminado.

## Antes de começar

* **Função.** Para definir regras, colocar em pausa, reativar e eliminar, precisa de acesso de escrita aos códigos QR do espaço de trabalho. Consulte [Autenticação](https://docs.getqr.com/pt/api/authentication.md).
* **Subscrição.** Todos os pedidos à API, incluindo estes, exigem uma subscrição ativa do dono do espaço de trabalho.

## O objeto de acesso

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

```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 deste momento, as leituras mostram a página de pausa em vez do destino. `null` significa ativo de imediato. |
| `pauseAt` | string (ISO 8601) \| null | Fim agendado. A partir deste momento, as leituras mostram a página de pausa. `null` significa sem data de fim. |
| `scanLimit` | integer \| null | Número máximo de leituras durante toda a vida do código QR. Depois de ultrapassado, as leituras mostram a página de pausa. `null` significa ilimitado. |
| `password` | string \| null | Palavra-passe que os visitantes têm de introduzir antes de serem redirecionados. Enviá-la também ativa a proteção. |
| `passwordProtected` | boolean | Se o código QR pede uma palavra-passe. `false` desativa a proteção, mas mantém a palavra-passe guardada. `true` volta a ativá-la. |

Os campos que omitir não são alterados. Envie `null` para apagar uma regra. Um objeto `access` parcial nunca repõe as regras que não mencionou.

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

## Agendar um início e um fim

`activeAt` e `pauseAt` são independentes: defina um deles ou ambos. Ambos aceitam datas e horas ISO 8601, com `Z` ou um desvio em relação 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"
    }
  }'
```

Envie `null` para apagar o agendamento. O código QR fica ativo de imediato e a data de fim é removida:

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

## Limite de leituras

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

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

O contador de leituras de toda a vida do código funciona sempre, haja ou não um limite definido. Por isso, alterar o limite é previsível:

* **Aumentar o limite** liberta exatamente (novo limite menos leituras totais) leituras adicionais.
* **Reduzir o limite** para um valor abaixo do total atual bloqueia o código QR de imediato.
* **Definir um limite mais tarde** conta as leituras feitas enquanto não havia limite.

`scanLimit` tem de ser um número inteiro positivo, até 2147483647. Envie `null` para ilimitado.

## Proteção por palavra-passe

Defina uma palavra-passe através do mesmo objeto `access`. A palavra-passe guardada é mantida quando desativa a proteção, pelo que a pode voltar a ativar sem a enviar novamente.

**1. Defina ou altere a palavra-passe**

Isto também ativa a proteção.

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

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

A palavra-passe guardada é mantida.

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

**3. Volte a ativar a proteção**

Não precisa de reenviar a palavra-passe. Só funciona se já tiver sido definida uma palavra-passe. Caso contrário, o pedido devolve `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 palavra-passe.
* **Remover a palavra-passe.** Envie `"password": null`. A proteção também é desativada.
* **Leitura.** As respostas nunca devolvem a palavra-passe, apenas `access.passwordProtected`.

## Pausar, reativar e eliminar

Colocar em pausa e reativar são endpoints próprios em vez de campos de `access`, porque produzem efeito de imediato e não segundo um agendamento.

| Método | Caminho | Descrição |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [Coloque o código QR em pausa agora](https://docs.getqr.com/pt/api/endpoints/qr-codes.md#pausar-um-código-qr). As leituras mostram a página de pausa até o reativar. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Reative um código QR em pausa](https://docs.getqr.com/pt/api/endpoints/qr-codes.md#reativar-um-código-qr). O agendamento e o limite de leituras continuam a aplicar-se. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Elimine o código QR](https://docs.getqr.com/pt/api/endpoints/qr-codes.md#eliminar-um-código-qr) e a respetiva ligação curta de forma permanente. |

Colocar em pausa e ativar não aceitam corpo de pedido e devolvem o [código QR](https://docs.getqr.com/pt/api/endpoints/qr-codes.md#o-objeto-de-código-qr) 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,
  "…": "…"
}
```

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

Eliminar remove o código QR e a respetiva ligação curta em conjunto:

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

> [!WARNING]
>
> A eliminação não pode ser anulada. A ligação curta deixa de ser resolvida, pelo que os códigos impressos deixam de funcionar. Se puder voltar a precisar dele, coloque o código QR em pausa.

## Quando as alterações entram em vigor

* **Próxima leitura.** As regras são verificadas quando um código é lido, pelo que uma alteração se aplica a partir da próxima leitura, e não retroativamente.
* **Página de pausa.** Um código QR bloqueado por um agendamento, um limite de leituras ou uma pausa mostra a página de pausa. A leitura não é redirecionada.
* **Palavra-passe.** Os visitantes que já introduziram a palavra-passe mantêm o acesso até a palavra-passe mudar, ou até a proteção ser desativada e reativada.
* **Relógio.** Os agendamentos usam o relógio do servidor em UTC, e não a hora local do visitante.
* **As regras combinam-se.** Um código QR só é resolvido se não estiver em pausa, estiver dentro do agendamento e estiver abaixo do limite de leituras.

## Problemas comuns

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

> [accordion] 422 ao ativar a proteção por palavra-passe
>
> O código QR ainda não tem palavra-passe. Envie `password` em vez de `passwordProtected: true`.

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

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

## Próximos passos

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

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


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