Regras de acesso

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.
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 ou atualizar um QR code:

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.

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.

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:

{
  "access": { "activeAt": null, "pauseAt": null }
}

Limite de leituras

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

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

Defina ou altere a senha

Isso também ativa a proteção.

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

Desative a proteção

A senha armazenada é mantida.

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

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.

{ "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. As leituras mostram a página de pausa até você reativá-lo.
`POST`	`/api/v1/qrs/{qrId}/activate`	Reativa um QR code pausado. Agendamentos e limites de leituras continuam valendo.
`DELETE`	`/api/v1/qrs/{qrId}`	Exclui o 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 atualizado:

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

{
  "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. A exclusão remove o QR code e o link curto dele juntos:

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

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

422 ao definir uma regra dentro de link

Envie a regra em access, não em link.

422 ao ativar a proteção por senha

O QR code ainda não tem senha. Envie password em vez de passwordProtected: true.

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

Preciso que o link expire

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

API

Antes de começar

O objeto access

Agende um início e um fim

Limite de leituras

Proteção por senha

Pausar, reativar e excluir

Quando as mudanças entram em vigor

Problemas comuns

Próximos passos

QR codes

Dados do QR code por tipo

​Antes de começar

​O objeto access

​Agende um início e um fim

​Limite de leituras

​Proteção por senha

​Pausar, reativar e excluir

​Quando as mudanças entram em vigor

​Problemas comuns

​Próximos passos

QR codes

Dados do QR code por tipo

Antes de começar

O objeto access

Agende um início e um fim

Limite de leituras

Proteção por senha

Pausar, reativar e excluir

Quando as mudanças entram em vigor

Problemas comuns

Próximos passos