Access Control API

Guest List API

Recupera a lista de convidados de uma sessão de evento. Aceita múltiplos filtros de busca e paginação por cursor.

GET/v1/events/:event_id/sessions/:session_id/guestlist

Headers obrigatórios

Parâmetro	Tipo	Descrição
`Authorization`Obrigatório	Bearer {token}	Token de acesso OAuth.

Parâmetros de URL

Todos são obrigatórios.

Parâmetro	Tipo
`event_id`	string (UUID)
`session_id`	string (UUID)

Parâmetros de query

Todos os parâmetros de busca são opcionais. Sem nenhum filtro, a requisição retorna a primeira página da lista completa da sessão.

Parâmetro	Tipo	Descrição
`user_id`	string (UUID)	Filtra pelo usuário.
`document`	string	Documento do titular (ex.: CPF).
`email`	string	E-mail do titular.
`code`	string	Código de acesso.
`size`	int	Itens por página. Padrão 100, máximo 1000.
`cursor`	string	Cursor da próxima página (pagination.next).
`status`	string	active \| cancelled \| refunded
`transferred`	boolean	Filtra códigos transferidos. Exige user_id na mesma requisição.
`updated_after`	string (RFC3339)	Atualizados após a data.
`updated_before`	string (RFC3339)	Atualizados antes da data.
`created_after`	string (RFC3339)	Criados após a data.
`created_before`	string (RFC3339)	Criados antes da data.
`code_id`	string (UUID)	UUID do código.
`ticket_id`	string (UUID)	UUID do ingresso.
`order_id`	string (UUID)	UUID do pedido.
`group_id`	string (UUID)	UUID do grupo de ingressos.
`code_type`	string	individual \| passport
`entrance_method`	string	face \| qrcode
`has_rfc`	boolean	Possui biometria (RFC).
`related_type`	string	Tipo de entidade relacionada retornada em code. Padrão ticket; product seleciona os codes vinculados a produtos.

Exemplo de requisição

cURL · GET

curl -X GET \
"https://<ACCESS_CONTROL_PROD_HOST>/v1/events/:event_id/sessions/:session_id/guestlist\
?user_id=99999999-9999-4999-8999-999999999999\
&document=12345678900\
&email=cliente%40exemplo.com\
&code=ABC123DEF\
&size=100\
&cursor=eyJwYWdlIjoyfQ%3D%3D\
&status=active\
&transferred=true\
&updated_after=2025-10-01T00:00:00Z\
&updated_before=2025-10-27T23:59:59Z\
&created_after=2025-09-01T00:00:00Z\
&created_before=2025-10-15T23:59:59Z\
&code_id=11111111-1111-4111-8111-111111111111\
&ticket_id=22222222-2222-4222-8222-222222222222\
&order_id=33333333-3333-4333-8333-333333333333\
&group_id=44444444-4444-4444-8444-444444444444\
&code_type=individual\
&entrance_method=qrcode\
&related_type=ticket\
&has_rfc=true" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

Respostas

Status	Descrição
200OK	Lista retornada com sucesso. Um event_id/session_id inexistente também retorna 200, com data vazio — nunca 404.
400Bad Request	Filtro com valor inválido (data fora de RFC3339, size fora de 1–1000).
401Unauthorized	Token ausente ou inválido.
403Forbidden	Sem permissão para o recurso.
429Too Many Requests	Rate limit excedido (Retry-After).
500Internal Server Error	Erro interno do serviço.
502Bad Gateway	Dependência upstream indisponível. Um valor de enum inválido em algum filtro (ex.: status, entrance_method) também pode retornar 502.

Exemplo de resposta

JSON

{
  "data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000000",
      "code": "ABC123DEF",
      "external_id": "ext-9087",
      "type": "individual",
      "status": "active",
      "order_id": "33333333-3333-4333-8333-333333333333",
      "user_id": "99999999-9999-4999-8999-999999999999",
      "event_id": "88888888-8888-4888-8888-888888888888",
      "ticket_id": "22222222-2222-4222-8222-222222222222",
      "can_transfer": true,
      "in_resale": false,
      "owner_id": "77777777-7777-4777-8777-777777777777",
      "ownership": "owner",
      "user": {
        "id": "99999999-9999-4999-8999-999999999999",
        "external_id": "ext-user-42",
        "name": "Maria Silva",
        "document": "12345678900",
        "document_type": "cpf",
        "phone": "+5511999990000",
        "email": "[email protected]"
      },
      "owner": {
        "id": "77777777-7777-4777-8777-777777777777",
        "external_id": "ext-user-42",
        "name": "Maria Silva",
        "document": "12345678900",
        "document_type": "cpf",
        "phone": "+5511999990000",
        "email": "[email protected]"
      },
      "event": {
        "id": "95a447c4-0000-4000-8000-000000000001",
        "external_id": "88888888-8888-4888-8888-888888888888",
        "name": "Show de Verão",
        "description": "Edição 2025"
      },
      "ticket": {
        "id": "22222222-2222-4222-8222-222222222222",
        "external_id": "ext-tkt-1",
        "group_id": "44444444-4444-4444-8444-444444444444",
        "name": "Pista",
        "allotment": "lote-1",
        "price": 150.0,
        "transferable": "always",
        "holder_type": "user_only",
        "order": 1,
        "group": {
          "id": "44444444-4444-4444-8444-444444444444",
          "name": "Pista",
          "entrance_name": "Portão A",
          "entrance_method": "qrcode",
          "entrance_mapping": "gate-a"
        }
      },
      "product": {
        "id": "55555555-5555-4555-8555-555555555555",
        "external_id": "ext-prd-1",
        "service_id": "66666666-6666-4666-8666-666666666666",
        "name": "Combo Bebida",
        "description": "Combo com 2 bebidas",
        "sku": "SKU-001",
        "price": 2500,
        "image_url": "https://cdn.exemplo.com/p.png",
        "status": "active",
        "created_at": "2025-09-01T12:00:00Z",
        "updated_at": "2025-09-01T12:00:00Z"
      },
      "attributes": {
        "locale": "pt-BR",
        "rfc": "a1b2c3d4e5f6",
        "rfc_provider": "ugo"
      },
      "entrances": [
        { "id": "ent_1", "type": "checkin", "date": "2025-12-20T22:15:00Z" }
      ],
      "created_at": "2025-09-01T12:00:00Z",
      "updated_at": "2025-10-15T08:30:00Z"
    }
  ],
  "pagination": {
    "next": "eyJwYWdlIjoyfQ=="
  }
}

Paginação

Repasse o valor de pagination.next no parâmetro cursor para obter a próxima página; repita enquanto pagination.next vier na resposta — na última página o campo vem ausente, não null. Um cursor inválido é ignorado e devolve a primeira página, em vez de um erro.

Limites de uso

A API está sujeita a limites de uso não publicados; se receber 429, respeite o header Retry-After quando presente e retente com backoff.

Corpo de erro

Um 400 desta rota vem como { "data": { "code": "BAD_REQUEST", "message": "<mensagem>" } }. Um 401 emitido pelo API Gateway (fora do BFF) vem só como { "message": "Unauthorized" }, sem o envelope data.

Campos de resposta

Cada item de data representa um código de acesso. Os campos abaixo descrevem o objeto completo retornado.

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.

Ingresso sem portador definido

Quando o code ainda não tem portador, os campos user, owner, owner_id, ownership, attributes e ticket.holder_type vêm ausentes (omitempty, não null e não vazios). Nesse caso can_transfer vem false e ticket.transferable vem "never". user_id é exceção: não é omitempty e vem como string vazia (""), não ausente. Isso é o caso comum, não a exceção — trate esses campos como condicionais.

Parâmetro	Tipo	Descrição
`id`	string (UUID)	UUID do código.
`code`	string	Código de acesso.
`external_id`	string	Identificador externo.
`type`	string	individual \| passport
`status`	string	active \| cancelled \| refunded
`order_id`	string (UUID)	UUID do pedido.
`user_id`	string (UUID)	UUID do usuário. Não é omitempty: quando não há portador, vem como string vazia (""), não ausente.
`event_id`	string (UUID)	UUID do evento.
`ticket_id`	string (UUID)	UUID do ingresso.
`can_transfer`	boolean	Indica se pode ser transferido.
`in_resale`	boolean	Indica se o code está em revenda. Sempre presente, sem omitempty.
`owner_id`	string (UUID)	UUID do titular. Ausente quando não há portador (ver aviso acima).
`ownership`	string	owner \| dependent \| other
`user`	object	Dados do usuário (ver abaixo).
`owner`	object	Dados do titular (mesma estrutura de user).
`event`	object	Dados do evento (ver abaixo).
`ticket`	object	Dados do ingresso (ver abaixo).
`product`	object	Produto associado (ver abaixo).
`attributes`	object	Atributos adicionais (chave-valor). Ausente quando não há portador (ver aviso acima).
`entrances`	array \| null	Registros de entrada (ver abaixo). Vem null quando não há entrada registrada.
`created_at`	string (RFC3339)	Data de criação.
`updated_at`	string (RFC3339)	Data da última atualização.

Objeto user / owner

Parâmetro	Tipo	Descrição
`id`	string (UUID)
`external_id`	string
`name`	string
`document`	string
`document_type`	string	Pode vir vazio ("") quando o tipo não é conhecido.
`phone`	string
`email`	string

Objeto event

Parâmetro	Tipo	Descrição
`id`	string (UUID)	ID interno do evento — não é o UUID usado na URL da requisição.
`external_id`	string (UUID)	UUID do evento — o mesmo valor usado como :event_id na URL.
`name`	string
`description`	string	Opcional, costuma vir ausente.

Objeto ticket

Parâmetro	Tipo	Descrição
`id`	string (UUID)
`external_id`	string
`group_id`	string (UUID)
`name`	string
`allotment`	string	Lote.
`price`	number	Preço em reais (ex.: 150.0). Diferente de product.price, que é em centavos.
`transferable`	string	always \| on_purchase \| on_wallet \| never
`holder_type`	string	dependent \| user_only — ausente quando não há portador definido.
`order`	int
`group`	object	Dados do grupo (ver abaixo).
`event_dates`	array	Datas do evento. Este contrato não preenche o array — o campo vem ausente. As datas e os UUIDs de sessão são fornecidos pela Ingresse no onboarding.

Objeto ticket.group

Parâmetro	Tipo
`id`	string (UUID)
`name`	string
`entrance_name`	string
`entrance_method`	string
`entrance_mapping`	string

Objeto ticket.event_dates[]

Parâmetro	Tipo
`id`	string (UUID)
`external_id`	string
`date`	string (RFC3339)

Objeto product

Parâmetro	Tipo	Descrição
`id`	string (UUID)
`external_id`	string
`service_id`	string (UUID)
`name`	string
`description`	string
`sku`	string
`price`	int	Preço em centavos.
`image_url`	string
`status`	string
`created_at`	string (RFC3339)
`updated_at`	string (RFC3339)

Objeto attributes

Chave-valor livre; entre as chaves observadas em produção estão locale, rfc e rfc_provider.

Objeto entrances[]

O campo entrances no item pai vem null quando não há registro de entrada — não um array vazio.

Parâmetro	Tipo	Descrição
`id`	string (UUID)
`type`	string	checkin \| checkout
`date`	string (RFC3339)

Objeto pagination

Parâmetro	Tipo	Descrição
`previous`	string (ausente quando não há página)	Cursor para a página anterior. Ausente na primeira página (nunca null).
`next`	string (ausente quando não há página)	Cursor para a próxima página. Ausente na última página (nunca null).

Outras rotas

Rotas irmãs no mesmo BFF, úteis ao integrar com a Guest List:

Parâmetro	Tipo	Descrição
`GET /v1/events/{eventId}`		No momento devolve um objeto vazio (medido em 03/09). Os UUIDs de sessão (:session_id) vêm da própria Ingresse, não desta rota.
`GET /v1/events/{eventId}/guestlist`		Variante da Guest List sem filtrar por sessão.
`GET /v1/events/{eventId}/products`		Lista os produtos associados ao evento.
`GET /v1/events/{eventId}/members/{document}/eligibility-cashless`		Consulta elegibilidade cashless de um membro pelo documento.