Relatório de vendas
Escopo: reports:read
Escopo: reports:read
GET/api/reports/sales?from=2026-07-01&to=2026-07-31from e to são obrigatórios (AAAA-MM-DD), janela de no máximo 1 ano. A resposta cobre o
mesmo terreno da aba Vendas do CRM, um bloco por chave dentro de data:
| Chave | O que traz |
|---|---|
kpis |
os indicadores do topo |
funnel |
o funil por etapa (leia a regra abaixo) |
series |
a série temporal do período |
ticket_by_rep |
ticket por vendedor |
loss_reasons |
motivos de perda |
sales_by_origin |
vendas por origem |
sales_cycle |
ciclo de venda |
conversion_by_stage |
conversão de uma etapa para a seguinte |
deal_flow |
o movimento do período em cascata — cada passo com label, value e kind (start, delta ou total) |
rep_performance |
desempenho por vendedor — vendedor, ganhos, receita, ticket e conv (estes dois vêm null quando não houve fechamento, nunca 0) |
O que o funil conta — leia antes de integrar
Uma etapa aberta do funil responde quantos negócios estão nela agora (no fim da janela),
não quantos passaram por ela no período. Negócio que entrou na etapa há três meses e continua
parado ali conta, mesmo tendo nascido muito antes do from.
As etapas de Ganho e Perdido são o contrário: contam o movimento do período — o que
foi ganho ou perdido entre from e to.
⛔ Se você precisa de "quantos passaram pela etapa no período", o campo é outro: periodCount
(camelCase, ao contrário do resto do payload), que vem na mesma resposta e não muda de sentido
com esta regra. count e value são o retrato de agora; periodCount é o movimento.
periodCount é opcional: ele só vem quando a resposta tem os dois lados da janela. Trate a
ausência como "não medido", nunca como zero.
Pular etapa conta como ter passado pelas do meio (desde 06/10/2026). Negócio movido da 1ª etapa
direto pra 4ª — ou ganho direto da 1ª — conta em periodCount de cada etapa aberta entre as duas,
e a conversão por etapa (conversion_by_stage) usa a mesma regra. Assim cada etapa do funil nunca
passa da anterior, exceto quando o negócio já começa o período numa etapa mais à frente (nasceu
nela ou veio de antes). Perder o negócio não preenche nada, e voltar pra trás também não. A ordem
das etapas usada é a que valia no momento do movimento: criar ou reordenar etapa depois não
reescreve o passado.
effortCount é a ocupação real da etapa no período, sem esse preenchimento: só conta
quem esteve de fato na etapa. É o número de esforço (quem pulou a etapa não fez o trabalho dela).
Trate a ausência como "não medido", nunca como zero.
Ganho e Perdido contam quem entrou no desfecho dentro do período, pelo movimento: negócio ganho em setembro e passado pra Perdido em outubro aparece como Ganho em setembro e Perdido em outubro. O fim do período nunca passa de hoje — "este mês" é comparado com os dias equivalentes antes dele, igual à tela.
Essa distinção existe porque as duas perguntas são legítimas e dão números diferentes: um funil cheio de negócio antigo tem muita oportunidade aberta agora e pouco movimento na janela. Contar só o movimento faria o funil parecer vazio. A tela e esta rota passam pelo mesmo agregador, justamente para não poderem divergir:
O acesso tem duas camadas:
- O relatório de Vendas precisa estar liberado para o responsável pela chave (§2) em Configurações →
Membros (dono e administradores sempre têm), e ele precisa poder ver Negócios. Sem isso:
403 forbidden_module. - A permissão "Só o dele" em Negócios ou em Relatórios recorta os números para os próprios negócios dessa pessoa, não a conta inteira.
Consumo por produto
Escopo: reports:read + products:read + deals:read (receita por produto é número de negócio sobre o catálogo; faltando um, 403)
GET/api/reports/products?from=2026-07-01&to=2026-07-31Quanto de cada produto foi vendido no período. Só negócios ganhos, pela data de fechamento no
calendário de Brasília — o último dia do período entra, o dia seguinte não. from e to são
obrigatórios, janela de no máximo 366 dias. Os únicos parâmetros são from, to e group_by.
{
"data": {
"from": "2026-07-01",
"to": "2026-07-31",
"groupBy": "product",
"rows": [
{
"productId": "9f1e4b7a-…",
"productName": "Camiseta Básica",
"variantId": null,
"variantSku": null,
"variantLabel": null,
"quantity": 40,
"revenue": 1996,
"dealsCount": 12
}
]
}
}⛔ Esta resposta é camelCase, ao contrário do resto da API. revenue é o total das linhas, já
com desconto; dealsCount conta negócios distintos. As linhas vêm da maior receita para a menor.
Custo e imposto nunca saem.
group_by aceita product (padrão) ou variant. Como cada produto tem uma única variação
(ver §30), variant devolve os mesmos números, com variantId e variantSku
preenchidos — útil para casar pelo código (SKU) com o seu sistema. variantLabel vem sempre null.
A chave precisa ter o relatório de Vendas, Produtos e Negócios liberados para o responsável pela
chave; com "Só o dele" em Negócios ou em Relatórios, a soma é só dos negócios do responsável da
chave e dos sem responsável. Um período com produtos demais para somar de uma vez responde 500
pedindo um período menor.