Access Control API

Convenções da API

Regras comuns aos endpoints da Access Control API: URL base, headers, formatos, paginação, limites e tratamento de erros. A Partner Reports tem convenções próprias, descritas na sua Visão geral.

URL base e versão

Todas as requisições usam HTTPS e são prefixadas pela versão da API. O ambiente de produção é:

text

https://apigw-access-control.prod.ingresse.com/v1

Host de produção sob solicitação

O host de desenvolvimento (apigw-access-control.dev.ingresse.com) é público, mas o host de produção do Access Control não está publicado — solicite-o ao seu account manager antes de ir ao ar.

Os corpos de requisição e resposta usam JSON. Envie sempre o header Content-Type: application/json em requisições POST.

Headers comuns

Parâmetro	Tipo	Descrição
`Authorization`Obrigatório	string	Token de acesso no formato Bearer {token}, obtido via OAuth client credentials.
`X-Partner-ID`Obrigatório	string (UUID)	Identificador do parceiro. Validado pelo API Gateway (assinatura ECDSA) em todas as chamadas.
`Content-Type`Condicional	string	application/json. Obrigatório em requisições com corpo (POST).

Datas e horários

Todos os campos de data/hora retornados pela API seguem o padrão RFC 3339 / ISO 8601 em UTC, por exemplo 2025-12-20T22:00:00Z. Recomendamos enviar datas no mesmo formato nas requisições.

Paginação

Endpoints de listagem usam paginação por cursor. A resposta inclui um objeto pagination com next e previous. Para avançar, repasse o valor de next no parâmetro cursor. Quando next for null, não há mais páginas.

cURL

# 1ª página
curl "https://apigw-access-control.prod.ingresse.com/v1/events/{event_id}/sessions/{session_id}/guestlist?size=100" \
  -H "Authorization: Bearer {token}" \
  -H "X-Partner-ID: {partner_uuid}"

# resposta -> "pagination": { "next": "eyJwYWdlIjoyfQ==", "previous": null }

# próxima página: repasse o cursor "next" em "cursor"
curl "https://apigw-access-control.prod.ingresse.com/v1/events/{event_id}/sessions/{session_id}/guestlist?size=100&cursor=eyJwYWdlIjoyfQ==" \
  -H "Authorization: Bearer {token}" \
  -H "X-Partner-ID: {partner_uuid}"

# repita enquanto "next" != null

Parâmetro	Tipo	Descrição
`size`	int	Itens por página. Padrão 100, máximo 1000.
`cursor`	string	Cursor da página seguinte (valor de pagination.next).

Limites de uso

Rate limit

O limite padrão é de 100 requisições por minuto por parceiro. Ao exceder, a API responde 429 Too Many Requests com o header Retry-After indicando os segundos para nova tentativa. Para exportações em massa, use a paginação (size até 1000) ou consulte o time de integração sobre bulk export.

Tratamento de erros

Erros retornam o código HTTP apropriado e um corpo JSON com a estrutura abaixo. O campo request_id ajuda no rastreamento de chamadas junto ao suporte.

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "The 'operator_id' field is required.",
    "details": [
      { "field": "operator_id", "issue": "required" }
    ],
    "request_id": "req_01HXYZ..."
  }
}

Status	Descrição
200OK	Requisição bem-sucedida.
400Bad Request	Parâmetros ausentes ou inválidos.
401Unauthorized	Token ausente, expirado ou inválido.
403Forbidden	X-Partner-ID inválido ou sem permissão para o recurso.
404Not Found	Evento, sessão ou recurso não encontrado.
429Too Many Requests	Limite de requisições excedido (ver Retry-After).
500Internal Server Error	Erro inesperado. Tente novamente e contate o suporte com o request_id.