Relatório de vendas e faturamento: por dia/loja, dashboard, atribuição por campanha
Vendas/faturamento agregados por período, com quebra por dia, mês ou loja — a resposta para "quanto vendi ontem", "faturamento por loja neste mês", "ticket médio por período". Devolve os totais mais a quebra por status.
A receita é líquida de cancelamento por padrão (pedidos cancelados ficam
fora do total). O bloco byStatus traz sempre todos os status, inclusive o
cancelado, para o que ficou de fora continuar auditável.
Valores em centavos. O dia sai de order_date (a data do negócio)
convertida para o fuso da organização — a venda cai no dia em que aconteceu,
não no dia em que sincronizou. updatedThrough é o maior createAt que
entrou no cálculo: como o pedido chega depois da venda, "ontem" é um número
mutável; use-o para decidir se vale reconsultar.
Substitui o financeSumary, que somava cancelado, perdia o último dia do
período e agrupava em UTC.
Todo total traz mix, a receita decomposta do preço de tabela até o que
entrou de fato — a resposta para "qual é minha receita líquida", "quanto eu
dei de desconto", "quanto o programa de fidelidade me custou":
| campo | significado |
|---|---|
listRevenue |
preço de tabela — revenue + discounts |
discount |
o que a loja abriu mão |
incentive |
saldo que o programa pagou (null sem withAttribution) |
netRevenue |
o que entrou — revenue − incentive (null sem withAttribution) |
averageTicket |
ASP, preço médio efetivamente cobrado |
listAverageTicket |
OSP, preço médio de tabela, antes do desconto |
⚠️ revenue já é líquido do desconto comercial — o price do item é o
unitário depois do desconto. Então o preço de tabela é revenue mais
discounts, não menos. Subtrair o desconto de revenue conta duas vezes, e
é a forma mais comum de errar esse número.
⚠️ Não confunda mix com attribution.revenueGross / revenueNet: esses
são do recorte das vendas atribuídas, enquanto mix é do negócio inteiro.
⚠️ listRevenue e listAverageTicket valem o que valer total_discounts.
Onde a integração não manda "preço de tabela menos preço de venda" o número
não se sustenta — ordersDiscountOverRevenue, no mesmo total, conta os
pedidos com desconto maior que a própria venda.
Todo total e toda linha trazem também as contagens principais: orders,
revenue, averageTicket e customersIdentified — os
compradores únicos (clientes distintos, COUNT(DISTINCT client)): quantas
pessoas diferentes compraram — além de ordersIdentified / ordersAnonymous
(pedidos com e sem cliente identificado). Então "vendas por dia com ticket médio
e compradores únicos" é uma chamada só: este relatório com groupBy=day (some
membership=member para só membros). customersIdentified conta só comprador
identificado — pedido anônimo não tem cliente para contar.
Passe compareWith para comparar com outro período (previous = janela
de mesmo tamanho logo antes; previousYear = mesmas datas um ano atrás; ou um
intervalo YYYY-MM-DD..YYYY-MM-DD). A resposta ganha um bloco comparison
com o total do período-base e o delta (absoluto e %) — dá para responder
"vendeu X, +12% vs o mês passado".
Passe withAttribution para a receita atribuída a campanhas — o valor
total das vendas em que o cashback / saldo de uma campanha foi resgatado ou
cuja mensagem gerou a compra, e a mesma quebra por campanha (topCampaigns=N),
para responder "quanto o cashback da campanha X gerou" e o ticket por
campanha. É receita influenciada, não incremental. O bloco separa ainda
venda atribuída (resgatou saldo), influenciada (só recebeu a mensagem
e comprou) e impactada (a soma) em split. O bloco já traz as
derivadas sobre pedidos distintos: avgDiscount (redeemed / revenueGross),
averageTicketGross e averageTicketNet — a diferença entre os dois tickets é
o saldo médio aplicado por pedido.
Try-it values populated from environment ACME (Demo)
Autenticação
Token
Send your user token in the x-guper-authorization header.
Cabeçalhos
Parâmetros do caminho
Parâmetros de query
Respostas
Notas
Comparando períodos (compareWith)
Adiciona um bloco comparison ao lado do total. A comparação usa os mesmos
filtros store/status; só o total do período-base é calculado (sem
quebra por dia ou por loja no período-base).
| valor | período-base |
|---|---|
previous |
a janela de mesmo tamanho imediatamente antes — ex.: para 2026-08-01..2026-08-31 (31 dias) é 2026-07-01..2026-07-31 |
previousYear |
as mesmas datas um ano antes — ex.: 2025-08-01..2025-08-31 |
2026-06-01..2026-06-30 |
um intervalo explícito que você passa |
delta compara o total atual com o base, em orders, revenue e
averageTicket:
abs— a diferença (atual − base). Em centavos pararevenueeaverageTicket.pct— a variação como razão:0.0767= +7,67%,-0.0509= −5,09%. Énullquando o base é0(porcentagem contra zero não tem sentido).
No exemplo acima: faturamento +7,7% com −5,1% de pedidos — menos pedidos, ticket maior (+13,4%).
Atribuída, influenciada, impactada (split)
Com withAttribution=true, o bloco separa os dois caminhos pelos quais o
programa chega na venda, sempre em pedidos distintos:
| lado | o que é |
|---|---|
attributed |
o pedido resgatou saldo de uma campanha |
influenced |
o cliente só recebeu a mensagem da campanha e comprou, sem resgatar nada |
impacted |
os dois juntos — o total do próprio bloco |
cashback |
dos atribuídos, os que resgataram sem push |
push |
dos atribuídos, os que resgataram e receberam push (push vence o empate) |
O pedido cai num lado só: receber a mensagem e resgatar conta como
atribuído, então attributed e influenced nunca contam em dobro e sempre
fecham na soma (impacted). Dentro dos atribuídos, cashback + push =
attributed — a separação por canal, porque cashback-base e push custam
diferente e misturar subestima o retorno do push.
"attribution": {
"orders": 1558,
"revenueNet": 303065066,
"split": {
"attributed": { "orders": 1480, "revenueGross": 345645957, "redeemed": 62869038, "revenueNet": 282776919, "avgDiscount": 0.1819 },
"influenced": { "orders": 78, "revenueGross": 20288147, "redeemed": 0, "revenueNet": 20288147, "avgDiscount": 0 },
"impacted": { "orders": 1558, "revenueGross": 365934104, "redeemed": 62869038, "revenueNet": 303065066, "avgDiscount": 0.1718 },
"cashback": { "orders": 1432, "revenueGross": 332780112, "redeemed": 60667968, "revenueNet": 272112144, "avgDiscount": 0.1823 },
"push": { "orders": 48, "revenueGross": 12865845, "redeemed": 2201070, "revenueNet": 10664775, "avgDiscount": 0.1711 }
}
}
influenced só existe onde a campanha manda mensagem — campanha que só
emite saldo nunca cai ali. cashback/push também aparecem em byDay e nas
quebras byStore/byInterface (cashback vs push por canal e por mês). Reporte
revenueNet: é a base da fatura.
discounts e os pedidos em que ele não fecha
discounts é a soma de total_discounts, que as integrações deveriam mandar como
preço de tabela menos preço de venda. Algumas não mandam.
ordersDiscountOverRevenue conta os pedidos do recorte cujo desconto é maior
que a própria venda — o que aquela definição torna impossível.
Não é resíduo de arredondamento: numa organização são 27% dos pedidos, todos de
uma integração só, e com eles dentro a razão desconto/receita dá 67%. Confira esse
campo antes de publicar qualquer razão feita sobre discounts; acima de zero,
reporte o valor e diga que a razão não se sustenta, em vez de transformar dado sujo
em número de negócio. Consertar o dado é da integração, não do relatório.