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://<ACCESS_CONTROL_PROD_HOST>/v1

Host de produção fornecido com as credenciais

O host de desenvolvimento (apigw-access-control.dev.ingresse.com) é público, mas o host de produção do Access Control não é publicado nesta documentação — ele é entregue junto com suas credenciais (client_id/client_secret) durante o onboarding, pelo seu account manager.

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.
`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 pelo Access Control seguem RFC 3339 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. Na última página, o campo next fica ausente do JSON — ele nunca vem como null. Um cursor inválido ou expirado não é rejeitado: a API responde 200 com a primeira página.

cURL

# 1ª página
curl "https://<ACCESS_CONTROL_PROD_HOST>/v1/events/{event_id}/sessions/{session_id}/guestlist?size=100" \
  -H "Authorization: Bearer {token}"

# resposta -> "pagination": { "next": "eyJwYWdlIjoyfQ==" }  (previous também é omitido quando não existe)

# próxima página: repasse o cursor "next" em "cursor"
curl "https://<ACCESS_CONTROL_PROD_HOST>/v1/events/{event_id}/sessions/{session_id}/guestlist?size=100&cursor=eyJwYWdlIjoyfQ==" \
  -H "Authorization: Bearer {token}"

# na última página, "pagination.next" fica AUSENTE do JSON (não vem como null)
# repita enquanto "pagination.next" existir na resposta

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).

Nunca compare next com null

Pagine checando se pagination.next existe na resposta, não se ele é igual a null — o campo é omitido, não zerado. Um loop que espera next === null para parar nunca termina e refaz a primeira página indefinidamente.

Limites de uso

Rate limit

O Access Control está sujeito a limites de requisições não publicados nesta documentação. Trate 429 Too Many Requests como um caso possível: reaplique com backoff e, se a resposta trouxer o header Retry-After, respeite-o. 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 de validação e de regra de negócio retornam o código HTTP apropriado e o corpo JSON abaixo, com data.code e data.message.

JSON

{
  "data": {
    "code": "BAD_REQUEST",
    "message": "size must be between 1 and 1000"
  }
}

Nem todo erro usa este envelope

Um 401 rejeitado antes de chegar à API (token ausente ou mal formado) vem do gateway com um corpo diferente: { "message": "Unauthorized" }. A Validation API usa um envelope próprio, sem o campo code — ver Validation API. A Partner Reports também tem convenções de erro próprias, descritas na sua Visão geral.

Status	Descrição
200OK	Requisição bem-sucedida.
400Bad Request	Parâmetros ausentes ou inválidos.
401Unauthorized	Token ausente, expirado ou inválido.
403Forbidden	Duas causas distintas: sem permissão para o recurso (403 ACL_FORBIDDEN, emitido pela própria API); ou, fora do prefixo /v1, token ausente/mal formado barrado pelo API Gateway antes de chegar à API, com corpo {"message":"Missing Authentication Token"}.
404Not Found	Recurso não encontrado. Não se aplica à listagem da guest list: evento ou sessão inexistente retorna 200 com lista vazia, não 404.
429Too Many Requests	Limite de requisições excedido (ver Retry-After, quando presente).
500Internal Server Error	Erro inesperado. Tente novamente; se persistir, contate o suporte informando host, rota, horário aproximado e o corpo da resposta recebida.
502Bad Gateway	Pode ocorrer quando um parâmetro de enum recebe um valor inválido (ex.: status, entrance_method ou code_type fora dos valores aceitos — confira a Referência antes de reenviar; a resposta pode vir sem JSON, como página HTML) ou quando um serviço upstream está temporariamente indisponível (no Partner Reports, com code ACL_CHECK_FAILED ou reports_gateway_error); nesse caso trate como transitório e retente.