VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Análises

Lucro real

Relatório de lucro por pedido, produto, categoria, seller ou dia, com exportação em CSV e carga do histórico.

Receita não é lucro. Este relatório desconta da receita o custo do produto, a comissão, a taxa do meio de pagamento, a diferença de frete, impostos e descontos, e mostra o lucro e a margem. Os custos são gravados como uma fotografia no momento em que cada pedido é criado e nunca mudam depois, então relatórios de meses atrás continuam batendo. Pedidos antigos, anteriores ao recurso, não têm fotografia: a rota backfill cria essas fotografias em lotes.

Relatório de lucro

GET/api/v1/admin/analytics/profitAdmin

Relatório de lucro

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Padrão: 30 dias atrás. Valor inválido é ignorado em silêncio.
tostring
Último dia, YYYY-MM-DD, inclusive. Padrão: agora. Valor inválido é ignorado em silêncio.
group_bystringpadrão: order
orderproductcategoryvendorday
Como agrupar as linhas. Valor desconhecido vira order.

Exemplo de requisição (profit)

bash
curl "$BASE_URL/api/v1/admin/analytics/profit?group_by=day&from=2026-10-01&to=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (profit)

200Relatório retornado
json
{
  "rows": [
    {
      "key": "2026-10-10",
      "label": "2026-10-10",
      "revenue_cents": 22500,
      "cogs_cents": 0,
      "commission_cents": 0,
      "gateway_fee_cents": 0,
      "shipping_gap_cents": 0,
      "tax_cents": 0,
      "discount_cents": 7500,
      "net_profit_cents": 15000,
      "margin_bps": 6666,
      "orders_count": 1
    }
  ],
  "totals": {
    "key": "total",
    "label": "Total",
    "revenue_cents": 22500,
    "cogs_cents": 0,
    "commission_cents": 0,
    "gateway_fee_cents": 0,
    "shipping_gap_cents": 0,
    "tax_cents": 0,
    "discount_cents": 7500,
    "net_profit_cents": 15000,
    "margin_bps": 6666,
    "orders_count": 1
  },
  "cogs_missing_pct": 16.67,
  "has_fee_config": true
}

Campos da resposta

rowsarray
Linhas do grupo escolhido, da maior receita para a menor.
rows[].keystring
Chave do grupo (id, dia ou total).
rows[].labelstring
Nome do grupo (número do pedido, nome do produto, categoria, seller ou o dia).
rows[].revenue_centsinteger
Receita dos itens, em centavos.
rows[].cogs_centsinteger
Custo dos produtos vendidos (preço de custo do cadastro), em centavos.
rows[].commission_centsinteger
Comissão da loja sobre o seller, em centavos.
rows[].gateway_fee_centsinteger
Taxa do meio de pagamento, em centavos. Fica em zero se a loja não configurou taxas por meio de pagamento.
rows[].shipping_gap_centsinteger
Reservado para a diferença de frete. Hoje é sempre 0.
rows[].tax_centsinteger
Impostos, em centavos.
rows[].discount_centsinteger
Descontos concedidos, em centavos.
rows[].net_profit_centsinteger
Lucro: receita menos todos os custos acima, em centavos.
rows[].margin_bpsinteger
Margem em pontos-base (6666 = 66,66%). 0 se a receita for zero.
rows[].orders_countinteger
Pedidos no grupo.
totalsobject
Soma de todas as linhas, com os mesmos campos de rows[].
cogs_missing_pctnumber
Porcentagem (0 a 100) dos itens do período sem preço de custo cadastrado. Quanto maior, menos confiável o lucro.
has_fee_configboolean
true se a loja já configurou taxas por meio de pagamento. Sem isso gateway_fee_cents fica zerado.

Erros (profit)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Exportar CSV

GET/api/v1/admin/analytics/profit/export.csvAdmin

Exportar o lucro em CSV

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Padrão: 30 dias atrás. Valor inválido é ignorado em silêncio.
tostring
Último dia, YYYY-MM-DD, inclusive. Padrão: agora. Valor inválido é ignorado em silêncio.
group_bystringpadrão: category
orderproductcategoryvendorday
Como agrupar as linhas. Aqui o padrão é category, diferente da rota JSON.

Exemplo de requisição (export)

bash
curl "$BASE_URL/api/v1/admin/analytics/profit/export.csv?group_by=day&from=2026-10-01&to=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (export)

200Arquivo CSV
text
key;label;revenue_brl;cogs_brl;commission_brl;gateway_fee_brl;shipping_gap_brl;tax_brl;discount_brl;net_profit_brl;margin_pct;orders
2026-10-10;2026-10-10;450,00;0,00;0,00;0,00;0,00;0,00;150,00;300,00;66.66%;2
total;TOTAL;450,00;0,00;0,00;0,00;0,00;0,00;150,00;300,00;66.66%;2

Campos da resposta

(corpo)text/csv
Arquivo text/csv; charset=utf-8 com BOM UTF-8, separador ; e valores em reais com vírgula decimal (450,00). A margem sai em porcentagem com ponto (66.66%). A última linha é o total. O nome do arquivo vem em Content-Disposition e muda com o idioma enviado em Accept-Language (português por padrão).

Erros (export)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Carga do histórico

POST/api/v1/admin/analytics/profit/backfillAdmin

Calcular o lucro de pedidos antigos, em lotes

Exemplo de requisição (backfill)

bash
curl -X POST "$BASE_URL/api/v1/admin/analytics/profit/backfill" \
  -H "Authorization: Bearer $TOKEN"

Resposta (backfill)

200Lote processado
json
{
  "processed": 500,
  "remaining": 1830
}

Campos da resposta

processedinteger
Pedidos processados nesta chamada (no máximo 500).
remaininginteger
Pedidos que ainda não têm fotografia de custos. Repita a chamada até chegar a 0.

Erros (backfill)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}
O backfill grava dados

Cada chamada a backfill processa até 500 pedidos, do mais novo para o mais antigo, e grava as fotografias de custo deles. Chame em laço até remaining ser 0. Os custos usam o preço de custo atual do produto, não o da época do pedido.

Só entra pedido que conta como venda

Pedidos cancelados, reembolsados, falhos, chargeback e anulados ficam fora. Os dias seguem o fuso America/Sao_Paulo. As taxas por meio de pagamento são configuradas em outra rota (/api/v1/admin/payment-fees), que não faz parte desta seção.

Veja também

  • Canais
  • Relatório de vendas
  • Ids, dinheiro e datas
Anterior
Coortes de retenção
Próxima
Canais de aquisição
Nesta página
  • Relatório de lucro
  • Exemplo de requisição (profit)
  • Resposta (profit)
  • Erros (profit)
  • Exportar CSV
  • Exemplo de requisição (export)
  • Resposta (export)
  • Erros (export)
  • Carga do histórico
  • Exemplo de requisição (backfill)
  • Resposta (backfill)
  • Erros (backfill)
  • Veja também