Partner Reports

Partner Reports — visão geral

Consulta integrada de eventos publicados, tipos de ingresso, combos, produtos e pedidos. Os dados são servidos a partir do data warehouse da Ingresse com cache de curta duração.

Fluxo

Obter token → reutilizar por ~5 min
GET /v1/reports/organizations/{organizationId}/events → o id de cada evento é o eventId dos demais endpoints
Consultar /tickets, /bundles, /products, /orders e /ecommerce-items do evento

Valores monetários

Todos os campos de valor — price, item_unit_value, item_discount_value e item_total_value — são inteiros em centavos. R$ 150,00 = 15000. Exceção: no relatório de e-commerce (GA4), price e event_value são decimais na moeda de currency — veja a página E-commerce.

Endpoints

Endpoint	Descrição	Página
GET /events	Eventos da organização, sessões, local e link de venda	Eventos
GET /tickets · /bundles · /products	Catálogo — ingressos e combos por lote, produtos por item —, preço e estoque	Catálogo
GET /orders · /orders/{orderId}	Pedidos, linhas de compra, comprador e portadores	Pedidos
GET /ecommerce-items	Funil de e-commerce do GA4 — view_item a purchase, 1 linha por item, com origem de tráfego	E-commerce (GA4)

Erros

Status	Quando ocorre
400Bad Request	Parâmetros inválidos — misturar page/page_size com limit/cursor, limit não numérico ou ≤ 0, data em formato inválido, ou offset de fuso nos filtros de /orders. Em /ecommerce-items: limit/cursor (endpoint sem modo cursor) ou event_name fora da lista aceita. Path sem organizationId ou (em rotas de evento) sem eventId retorna ACL_MISSING_ORGANIZATION ou ACL_MISSING_EVENT.
401unauthorized	Token ausente, expirado, malformado ou com assinatura inválida. O token também precisa das claims email e sub (UUID) — um token client_credentials sem email recebe 401 com a mensagem invalid token: invalid authentication token: missing email.
403ACL_FORBIDDEN	Sem a permissão events.reports na organização ou no evento.
404Not Found	orderId inexistente ou de outro evento — indistinguíveis, de propósito.
500Internal Server Error	Falha ao consultar o data warehouse. Reenvie com backoff.
502ACL_CHECK_FAILED · reports_gateway_error	ACL_CHECK_FAILED: o serviço de permissões está indisponível. reports_gateway_error: o backend de relatórios está fora do ar.
503reports_gateway_not_configured	O backend de relatórios não está configurado neste ambiente.
504Gateway Timeout	Corpo vazio. Pode vir do gateway na frente da API quando a consulta demora além do timeout interno do serviço (30 s) — condicional, não emitido pelo código de aplicação. Reenvie com backoff.

Erros emitidos pelo BFF — autenticação (401), controle de acesso (403, os 400 do ACL, 502 ACL_CHECK_FAILED) e proxy (502 reports_gateway_error, 503 reports_gateway_not_configured) — retornam { "code": "...", "message": "..." }. Só o que vem do serviço de relatórios devolve { "error": "..." } — mensagem genérica em 404 e 500, mensagem específica em 400 de validação de parâmetros. Hoje a resposta não traz trace_id; se o API Gateway devolver x-amzn-RequestId, informe-o ao suporte junto com os parâmetros da requisição e o horário aproximado.

Limites e boas práticas

Tema	Regra
Token	Renove quando restarem menos de 60 s. Mantenha o anterior em cache como fallback.
Retry	Apenas em 5xx e timeout, com backoff exponencial e no máximo 3 tentativas — exceto 503 reports_gateway_not_configured, que não se resolve com retry (o backend não está configurado no ambiente); contate o suporte. Erros 4xx são definitivos.
Timeout do cliente	35 segundos — o serviço tem timeout interno de 30 s.
Cache	Respostas são cacheadas no servidor por ~1 minuto, exceto o detalhe de pedido (GET /orders/{orderId}), que não é cacheado. Nos demais endpoints, requisições em intervalos menores retornam os mesmos dados.
Paginação	Em /events, /orders e /ecommerce-items, itere até acumular total. Para sincronização incremental, /orders, /tickets e /bundles aceitam janelas de data (updated_after etc.) e paginação por cursor (limit/cursor) — veja as páginas de Pedidos e Catálogo. /ecommerce-items não tem modo cursor: o incremental é pela janela date_from/date_to.
Limite de requisições	Não publicado — consulte o account manager.