Partner Reports

Pedidos

A lista de pedidos do evento e o detalhe de um pedido individual — a fonte dos dados de venda, comprador e portadores.

Listar pedidos do evento

GET/v1/reports/organizations/{organizationId}/events/{eventId}/orders

Página da lista de pedidos, do mais recente para o mais antigo — um item por pedido, com os dados do comprador (buyer_*), as linhas de compra aninhadas em items e, em cada linha, os portadores (holders) dos ingressos emitidos. Aceita paginação por página (page/page_size) ou por cursor, e filtros de janela de data — veja Leitura incremental abaixo. Guarde o order_id: é a chave do endpoint de detalhe.

Objeto de pedido

Campo	Tipo	Descrição
`id`	string	Identificador do registro no relatório.
`event_title`	string	Nome do evento do pedido.
`order_created_at`	string	Criação do pedido — horário local do evento; o fuso está em timezone.
`order_updated_at`	string	Última atualização — horário local do evento; o fuso está em timezone.
`timezone`	string	Fuso IANA em que os dois timestamps estão expressos — ex.: America/Sao_Paulo. Nunca vem vazio.
`convenience_fee`	integer \| null	Taxa de conveniência do pedido, em centavos. null = taxa não aplicável ou desconhecida (pedido pago fora do gateway — bilheteria/venda offline, loja do parceiro, cortesia); 0 = o gateway registrou taxa zero de fato. Não trate null como 0.
`order_id`	string	Identificador único do pedido.
`order_status`	string	Status do pedido.
`payment_status`	string	Status do pagamento.
`payment_type`	string	Meio de pagamento utilizado.
`passkey`	string	Passkey utilizada na compra, quando houver.
`cupom_name`	string	Cupom de desconto utilizado, quando houver.
`buyer_name`	string	Nome do comprador.
`buyer_document`	string	CPF do comprador.
`buyer_email`	string	E-mail do comprador.
`buyer_phone`	string	Telefone do comprador.
`buyer_birthdate`	string	YYYY-MM-DD
`items[]`	array	Linhas de compra.

Dados pessoais (LGPD)

A listagem e o detalhe retornam comprador e portadores — cada página traz até 200 pedidos com esses dados. holders reflete o titular atual de cada ingresso, inclusive após transferências. Trate esses campos como dados pessoais: armazene e descarte conforme a LGPD.

Objeto items — linha de compra

Campo	Tipo	Descrição
`product_type`	string	ticket, bundle ou product — além dos tipos de baixo volume checkin e pack.
`group_id / group_name`	string	Setor do item.
`ticket_id / ticket_name`	string	Ingresso do item.
`ticket_tier_id / ticket_tier_name`	string	Lote do item.
`bundle_id / bundle_name`	string	Combo do item.
`bundle_tier_id / bundle_tier_name`	string	Lote do combo.
`product_id / product_name`	string	Produto do item.
`item_quantity`	integer	Quantidade comprada na linha.
`item_unit_value`	integer	Valor unitário em centavos.
`item_discount_value`	integer	Desconto aplicado à linha, em centavos.
`item_total_value`	integer	quantidade × unitário − desconto.
`holders[]`	array	Portadores atuais dos ingressos emitidos da linha — name, document, email. Vazio para linhas de combo/produto; pode ter menos entradas que item_quantity enquanto nem todos os ingressos foram emitidos.

Timestamps no fuso do evento

order_created_at e order_updated_at são emitidos no horário local do evento, sem offset embutido — o campo timezone diz em que fuso IANA eles estão. Para derivar o instante absoluto: TIMESTAMP(order_created_at, timezone). Não os converta assumindo UTC.

Leitura incremental e cursor

Seis parâmetros opcionais permitem sincronizar só o que mudou, em vez de varrer todas as páginas a cada ciclo. Sem eles, a resposta é idêntica à de antes (mesma ordenação e mesmo envelope).

Parâmetro	Tipo	Descrição
`updated_after / updated_before`	string	Janela sobre a data de atualização. Limites inclusivos.
`created_after / created_before`	string	Janela sobre a data de criação. Limites inclusivos.
`limit`	integer	Liga o modo cursor — default 20, teto 200 (acima é clampado). Não numérico ou ≤ 0 → 400.
`cursor`	string	Retoma a travessia. Token opaco: devolva o next_cursor que recebeu.

Formatos de data aceitos: YYYY-MM-DD, YYYY-MM-DD HH:MM:SS[.ffffff] ou a variante ISO com T. Data pura abre à meia-noite e fecha no último microssegundo do dia. Em /orders os valores são interpretados no horário local do evento e offset de fuso é recusado (400) — use o campo timezone para converter o seu watermark.

No modo cursor a resposta muda para o envelope abaixo, ordenada por atualização crescente (o modo legado ordena por criação, decrescente) — pedido antigo que muda de status reaparece no fim da fila. Não há total; use has_more. Misturar page/page_size com limit/cursor → 400.

Modo cursor — envelope

GET .../orders?updated_after=2026-08-26 14:32:10&limit=200

{
  "items": [ ... ],
  "next_cursor": "eyJ0cyI6...",
  "has_more": true
}

Orientação para o integrador

Watermark = maior data de atualização recebida, nunca o relógio local. Aplique margem de sobreposição (ex.: updated_after = watermark − 15 min): a linha só aparece no relatório depois do ETL, e sem margem um pedido atualizado antes da leitura mas materializado depois é perdido em silêncio. Seja idempotente por order_id — no modo legado a lista cresce pela cabeça e um pedido pode aparecer em duas páginas; o cursor não tem esse problema.

Detalhar pedido

GET/v1/reports/organizations/{organizationId}/events/{eventId}/orders/{orderId}

Um único pedido, com exatamente a mesma estrutura do objeto de pedido da listagem (sem envelope de paginação) — incluindo comprador, portadores e timezone. Um orderId inexistente ou que não pertença ao evento informado retorna 404 — os dois casos são intencionalmente indistinguíveis.