Regras de acesso

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.
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 ou atualizar um código QR:

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.

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.

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:

{
  "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:

{
  "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.

Defina ou altere a palavra-passe

Isto também ativa a proteção.

{ "access": { "password": "hunter2" } }

Desative a proteção

A palavra-passe guardada é mantida.

{ "access": { "passwordProtected": false } }

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.

{ "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. As leituras mostram a página de pausa até o reativar.
`POST`	`/api/v1/qrs/{qrId}/activate`	Reative um código QR em pausa. O agendamento e o limite de leituras continuam a aplicar-se.
`DELETE`	`/api/v1/qrs/{qrId}`	Elimine o 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 atualizado:

curl -X POST "https://getqr.com/api/v1/qrs/qr_abc123/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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. Eliminar remove o código QR e a respetiva ligação curta em conjunto:

{ "id": "qr_abc123", "deleted": true }

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

422 ao definir uma regra dentro de link

Envie a regra dentro de access e não de link.

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.

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 e compare scans com o limite.

Preciso que a ligação expire

link.expiresAt não está disponível nesta API. Use access.pauseAt em alternativa.

API

Antes de começar

O objeto de acesso

Agendar um início e um fim

Limite de leituras

Proteção por palavra-passe

Pausar, reativar e eliminar

Quando as alterações entram em vigor

Problemas comuns

Próximos passos

Códigos QR

Dados do código QR por tipo

​Antes de começar

​O objeto de acesso

​Agendar um início e um fim

​Limite de leituras

​Proteção por palavra-passe

​Pausar, reativar e eliminar

​Quando as alterações entram em vigor

​Problemas comuns

​Próximos passos

Códigos QR

Dados do código QR por tipo

Antes de começar

O objeto de acesso

Agendar um início e um fim

Limite de leituras

Proteção por palavra-passe

Pausar, reativar e eliminar

Quando as alterações entram em vigor

Problemas comuns

Próximos passos