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.

Parâmetro	Tipo	Descrição
`page`Opcional	integer	Página a retornar. Padrão 1. Valor acima de 10.000 é rebaixado para 10.000, sem erro. Não combine com limit/cursor — veja Leitura incremental abaixo.
`page_size`Opcional	integer	Itens por página. Padrão 20, máximo 200 (acima é rebaixado). Valor inválido (não numérico ou ≤ 0) cai para o padrão 20 em silêncio, sem erro — diferente de limit, que retorna 400.

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. Hoje vem sempre preenchido nos dados de origem (garantia dos dados, não do contrato do serviço) — trate um valor vazio como dado ausente e aplique um fallback (ex.: UTC) em vez de falhar.
`order_id`	string	Identificador único do pedido.
`order_status`	string	Status do pedido. Valores conhecidos: PARTIALLY_CANCELLED, COMPLETED, REFUND, PROCESSING, ERROR, REFUNDED, RESERVED, CANCELLED. A lista reflete os dados atuais de produção e pode ganhar valores novos — trate valores desconhecidos de forma tolerante.
`payment_status`	string	Status do pagamento. Valores conhecidos: PAID, GENERATED, MANUAL REVIEW, FREE, REFUNDED, DECLINED, CANCELED, STARTED, PARTIALLY PAID, AUTHORIZED — além de string vazia quando a fonte não tem status de pagamento para o pedido. Pode ganhar valores novos — trate valores desconhecidos de forma tolerante.
`payment_type`	string	Meio de pagamento, retornado literalmente como rótulo em português. Valores conhecidos: Pix, Cartão de Crédito, Dinheiro, Mbway, Grátis, Wallet, Não Identificado, -, Outros, Cartão de Débito, Google Pay, Bankbillet, Apple Pay, NuPay, Clicktopay. Novos meios de pagamento surgem com o tempo — trate valores desconhecidos de forma tolerante.
`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	Documento do comprador — CPF, passaporte ou CNPJ; o tipo está em buyer_document_type.
`buyer_document_type`	string	Tipo de buyer_document: cpf, passport ou cnpj, em minúsculas. String vazia quando o pedido não tem documento do comprador ou vem do sistema legado, que não registra o tipo — não trate vazio como cpf. Pode ganhar valores novos — trate valores desconhecidos de forma tolerante.
`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	Valor total da linha, conforme registrado na origem (não recalculado pelo serviço) — na prática, corresponde a quantidade × unitário − desconto.
`holders[]`	array	Portadores atuais dos ingressos emitidos da linha — name, document, email, document_type. document_type é o tipo de document (cpf ou passport, em minúsculas), vazio quando não há documento ou o pedido vem do sistema legado. 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, com fallback para a data de criação quando o pedido nunca foi atualizado (COALESCE(updated, created)) — um pedido nunca atualizado ainda entra na janela pela sua criaçã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. A simples presença do parâmetro (mesmo limit= vazio) já liga o modo cursor.
`cursor`	string	Retoma a travessia. Token opaco: devolva o next_cursor que recebeu. Um cursor não vazio também liga o modo cursor por si só, sem precisar de limit.

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-26T14: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.