Integração de portaria

Versão 1 · para o sistema que controla catracas e leitores de QR code na casa

Como funciona

O dropz ingressos emite os ingressos e é o registro oficial de quem entrou. O sistema da portaria faz duas coisas:

1. Busca a carga de ingressos de tempos em tempos, para saber quais códigos valem.
2. Avisa cada entrada assim que o QR code é lido. A partir daí o ingresso fica usado também aqui, e nenhuma outra porta o aceita.

Entradas feitas pela portaria do próprio dropz ingressos e ingressos cancelados chegam na carga seguinte.

Endereço e chave

Todas as chamadas são HTTPS em https://integracoes.wearedropz.com.br/v1/, com o corpo e a resposta em JSON (UTF-8).

Cada integração tem uma chave, que vale só para os eventos de uma casa. Ela vai em toda chamada, no cabeçalho:

Authorization: Bearer dzi_SUA_CHAVE

A chave é mostrada uma única vez, quando a integração é criada. Guarde em local seguro e nunca a coloque em aplicativo ou página que o público acesse. Se vazar, peça a troca: a antiga para de valer na hora.

O QR code do ingresso

O QR code traz o endereço do ingresso, por exemplo https://ingressos.wearedropz.com.br/i/ABCDE23456. O código é a parte final: 10 caracteres, com letras maiúsculas e números. Nas chamadas você pode mandar o código sozinho ou o endereço inteiro, do jeito que o leitor entregou.

1. Eventos

GET /v1/eventos

Lista os eventos da casa, de ontem em diante.

{
  "eventos": [
    { "id": "0b6f…", "nome": "Evento Teste", "data": "2026-12-12T02:00:00.000Z", "intervalo_segundos": 1200 }
  ]
}

2. Carga de ingressos

GET /v1/carga?evento=ID_DO_EVENTO&desde=MARCADOR&limite=2000

{
  "evento": { "id": "0b6f…", "nome": "Evento Teste", "data": "2026-12-12T02:00:00.000Z" },
  "marcador": 1483,
  "tem_mais": false,
  "intervalo_segundos": 1200,
  "ingressos": [
    { "codigo": "ABCDE23456", "nome": "NOME TESTE", "setor": "Pista", "situacao": "valido", "entrou_em": null }
  ]
}

Como usar:

1. Na primeira vez, chame sem desde. Enquanto tem_mais for verdadeiro, chame de novo com desde igual ao marcador recebido.
2. Guarde o último marcador. Na busca seguinte, mande-o em desde: vem só o que mudou (ingresso novo, nome trocado, cancelado, usado).
3. Cada ingresso recebido substitui o que você tinha com o mesmo codigo.
4. Espere intervalo_segundos até a próxima busca. Esse tempo é definido pela casa e fica menor na noite do evento; leia o valor em toda resposta, sem deixá-lo fixo no seu sistema.

O marcador é um número que só cresce. Ele não depende de relógio: mesmo com a hora errada num dos lados, nada se perde nem se repete.

Situações

3. Avisar entradas

POST /v1/entradas

{
  "evento": "0b6f…",
  "leituras": [
    { "id": "catraca2-000187", "codigo": "ABCDE23456", "em": "2026-12-12T02:14:09Z", "local": "Catraca 2", "offline": false }
  ]
}

{
  "resultados": [
    { "id": "catraca2-000187", "resultado": "liberado", "conflito": false, "mensagem": "Liberado",
      "nome": "NOME TESTE", "setor": "Pista", "entrou_em": "2026-12-12T02:14:09.000Z" }
  ]
}

Repetição segura: se a resposta não chegar (queda de rede, tempo esgotado), mande a mesma leitura de novo com o mesmo id. A resposta será a mesma, com "repetida": true, e a entrada não conta duas vezes.

Duas portas ao mesmo tempo: se o mesmo QR code for lido em dois lugares no mesmo instante, só uma leitura recebe liberado.

Catraca sem internet: libere pela última carga recebida, guarde as leituras e mande todas quando a conexão voltar, com "offline": true e a hora real em em. Se algum desses ingressos já tinha entrado por outra porta, a resposta vem ja_entrou com "conflito": true, e a casa vê o caso no painel.

4. Consultar um ingresso

GET /v1/ingresso?codigo=ABCDE23456

Devolve a situação do ingresso naquele instante, sem marcar entrada. Serve para conferir antes de liberar, quando a catraca está com internet.

{ "encontrado": true, "codigo": "ABCDE23456", "nome": "NOME TESTE", "setor": "Pista",
  "situacao": "valido", "entrou_em": null, "evento": { "id": "0b6f…", "nome": "Evento Teste" } }

O caminho mais seguro com internet é chamar direto /v1/entradas: a resposta já diz se pode liberar e registra a entrada na mesma operação.

Erros

{ "erro": "Evento não encontrado." }

Dados pessoais

A carga leva só o necessário para a portaria: código, nome e setor. Não leva e-mail nem telefone. O sistema da portaria deve usar esses dados apenas para o controle de acesso do evento e apagá-los depois dele.

Teste antes do evento

Peça à casa um evento de teste com ingressos de teste. Confira, nessa ordem: a carga completa, a carga só do que mudou, uma entrada, a mesma entrada repetida, o mesmo QR code em duas catracas, um ingresso cancelado e uma catraca sem internet.