Começo
Qual API usar
O AWA expõe três interfaces com propósitos diferentes. Escolher a errada é o erro mais caro da integração: uma lista de convidados não tem preço, e uma API analítica não entrega tempo real. Comece por aqui.
As três interfaces
Partner Reports
apigw-partner-bffPainel de vendas, receita, ticket médio, mix de pagamento, cupom, conciliação de pedidos, catálogo de ingressos e lotes.
- Valores, descontos e totais
- Forma de pagamento, cupom, passkey
- Comprador e portadores
- Local, cidade, UF e sessões do evento
Access Control BFF
apigw-access-controlLista de acesso por sessão, consulta de códigos e registro de validações na portaria.
- Leitura incremental por cursor
- Filtros por titular, documento, e-mail, código
- Gravação de check-in em lote
Webhook de Acesso
awa-access-webhookReagir em tempo real ao ciclo de vida do ingresso, sem varredura.
- Emissão, alteração, transferência
- Cancelamento e reembolso
- Uso do código na portaria
Erro comum
Não monte um painel de vendas a partir do guestlist. Ele é um artefato de controle de acesso e não carrega preço, taxa, forma de pagamento nem pedido — registros vindos dele chegam com valor zero, o que leva painéis a classificá-los erroneamente como cortesia. Para dados de venda, use a Partner Reports.
Padrão recomendado para painel ao vivo
Assine o webhook para saber que algo mudou, e consulte a Partner Reports para saber o quê. O webhook entrega o order_id; o detalhe financeiro vem de GET /orders/{orderId}. Isso substitui a varredura completa da API a cada ciclo.
Comparativo
| Partner Reports | Access Control BFF | Webhook | |
|---|---|---|---|
| Modelo | pull, analítico | pull, operacional | push |
| Fonte do dado | data warehouse, cache ~1 min | transacional | transacional |
| Paginação | page / page_size ≤ 200 | cursor + size | — |
| Leitura incremental | não disponível | updated_after, created_after | nativa |
| Timestamps | local do evento, sem fuso | ISO-8601 com Z | RFC3339 UTC |
| Autenticação | OAuth2 + ACL events.reports | OAuth2 + X-Partner-ID | segredo HMAC por assinatura |
| Ambientes | produção | dev e produção | dev e produção |
| Granularidade | pedido e linha de compra | código de acesso | código de acesso |
Ambientes e hosts
| Interface | Ambiente | Base URL |
|---|---|---|
| Partner Reports | produção | https://apigw-partner-bff.prod.ingresse.com |
| Access Control | desenvolvimento | https://apigw-access-control.dev.ingresse.com |
| Access Control | produção | solicitar ao account manager |
| Webhook | desenvolvimento | https://awa-access-webhook.dev.ingresse.com |
| Webhook | produção | https://awa-access-webhook.prod.ingresse.com |
| Auth (Keycloak) | produção | https://auth.prod.ingresse.com |
| Auth (Keycloak) | desenvolvimento | https://auth.dev.ingresse.com |
Duas lacunas de ambiente
A Partner Reports não possui sandbox — só existe produção. E o host de produção do Access Control não está publicado; solicite ao seu account manager antes de ir ao ar.