Access Control API

Validation API

Valida códigos de acesso em lote (check-in). Aceita um array com no máximo 1000 validações por requisição.

POST/v1/events/:event_id/sessions/:session_id/validation

Ambientes

Para alternar entre ambientes, troque apenas o host: use <ACCESS_CONTROL_PROD_HOST> em produção (fornecido junto com suas credenciais) e apigw-access-control.dev.ingresse.com em desenvolvimento.

Headers obrigatórios

Parâmetro	Tipo	Descrição
`Authorization`Obrigatório	Bearer {token}	Token de acesso OAuth.
`Content-Type`Obrigatório	application/json	Obrigatório no corpo JSON.

Parâmetros de URL

Todos são obrigatórios.

Parâmetro	Tipo
`event_id`Obrigatório	string (UUID)
`session_id`Obrigatório	string (UUID)

Corpo da requisição

Parâmetro	Tipo	Descrição
`operator_id`Obrigatório	string (UUID)	Identificador do operador que realiza a validação. Ausente: 400 "operator_id is required". Presente mas não é um UUID válido: a requisição retorna 200, e o item correspondente aparece em errors[] com "Invalid operator ID format".
`validations`Obrigatório	array	Lista de validações (máximo 1000 itens).

Item de validations[]

O array validations aceita no máximo 1000 itens. Em cada item, code e date são obrigatórios; type é opcional (default checkin).

Há duas categorias de falha. Recusa do lote inteiro (HTTP 400, nenhum item processado): array vazio ou ausente, array com mais de 1000 itens, ou qualquer item com code ausente, date ausente, date em formato não reconhecido ou type diferente de checkin/checkout. Falha por item (HTTP 200, item listado em errors[]): code inexistente, code de outra sessão, code repetido dentro do mesmo lote ("duplicate code found in request") ou operator_id malformado.

Parâmetro	Tipo	Descrição
`code`Obrigatório	string	Código de acesso a validar.
`date`Obrigatório	string (RFC3339)	Data/hora da validação em UTC.
`type`Opcional	string	checkin \| checkout. Default: checkin.

Formato de data

Use sempre o padrão RFC 3339 / ISO 8601 em UTC (ex.: 2025-12-31T22:00:00Z). Veja Convenções da API.

Exemplo de requisição

cURL · POST

curl -X POST \
"https://<ACCESS_CONTROL_PROD_HOST>/v1/events/:event_id/sessions/:session_id/validation" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "operator_id": "{operator_UUID}",
    "validations": [
      {
        "code": "ABC123DEF",
        "date": "2025-12-31T22:00:00Z",
        "type": "checkin"
      },
      {
        "code": "XYZ987",
        "date": "2025-12-31T19:00:00Z",
        "type": "checkin"
      }
    ]
  }'

Respostas

Status	Descrição
200OK	Lote processado. Veja success e errors no corpo.
400Bad Request	Recusa do lote inteiro: array vazio ou ausente, array com mais de 1000 itens, ou algum item com code ausente, date ausente, date em formato não reconhecido ou type diferente de checkin/checkout.
401Unauthorized	Token ausente ou inválido.
403Forbidden	Sem permissão para o recurso.
404Not Found	Evento ou sessão inexistente (conforme o contrato; não medido em produção).
422Unprocessable Entity	Regra de negócio bloqueia a ação.
429Too Many Requests	Rate limit excedido (Retry-After).
500Internal Server Error	Erro interno do serviço.
502Bad Gateway	Dependência upstream indisponível — trate como transitório e retente.

Exemplo de resposta

JSON

{
  "data": {
    "success": [
      {
        "code": "ABC123DEF"
      }
    ],
    "errors": [
      {
        "code": "XYZ987",
        "message": "code already used"
      }
    ]
  }
}

success e errors vivem em data

A resposta não tem message no topo. Os arrays success e errors ficam dentro de data — quem ler a raiz do JSON procurando success/errors direto não encontra nada, e pode concluir erradamente que a validação passou.

A resposta é parcial: cada código é processado individualmente. Os validados com sucesso aparecem em data.success e as falhas em data.errors, ambos referenciando o code original.

Item de data.success[]

Campo	Tipo	Descrição
`code`	string	Código validado.

Item de data.errors[]

Campo	Tipo	Descrição
`code`	string	Código que falhou.
`message`	string	Mensagem literal do erro (texto livre, sem enum), ex.: "code already used", "duplicate code found in request", "Invalid operator ID format".

Reenvio / idempotência

Reenviar um code já validado não gera um novo check-in: a requisição volta 200, mas o item aparece em data.errors com a mensagem "code already used". É o comportamento esperado de um retry após perder a resposta de um envio anterior bem-sucedido.

Corpo de erro (400)

Hoje o corpo de um 400 de recusa de lote não segue o envelope { code, message } usado em outras rotas — é { "data": { "error": "<mensagem>" } }, por exemplo:

JSON

{"data":{"error":"operator_id is required"}}