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

Relatório de vendas

Relatório de vendas entre duas datas, com a série diária, o top de produtos e a receita por dia.

Três rotas para o mesmo propósito: ver como as vendas se comportaram em um intervalo de datas. report entrega tudo de uma vez (totais, série diária e os 10 produtos mais vendidos). daily e daily-revenue entregam só a série por dia; a diferença é que daily pula os dias sem pedido e daily-revenue devolve todos os dias do intervalo, com zero onde não houve venda, o que é o que um gráfico de linha precisa.

Relatório completo

GET/api/v1/admin/analytics/reportAdmin

Relatório de vendas entre duas datas

Parâmetros de consulta

startstringobrigatório
Primeiro dia, formato YYYY-MM-DD, no fuso da loja (America/Sao_Paulo).
endstringobrigatório
Último dia, formato YYYY-MM-DD. O dia inteiro entra no cálculo.
periodstring
all
Só o valor all tem efeito aqui: remove o limite de 366 dias entre start e end. Qualquer outro valor é ignorado.

Exemplo de requisição (report)

bash
curl "$BASE_URL/api/v1/admin/analytics/report?start=2026-10-01&end=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (report)

200Relatório retornado
json
{
  "stats": {
    "total_orders": 6,
    "total_revenue": 58587,
    "pending_orders": 2,
    "completed_orders": 1,
    "cancelled_orders": 0,
    "avg_order_value": 9764,
    "unique_customers": 0,
    "period": "2026-10-01 \u2014 2026-10-10",
    "previous_total_orders": 0,
    "previous_total_revenue": 0,
    "previous_avg_order_value": 0,
    "previous_unique_customers": 0,
    "year_ago_total_orders": 0,
    "year_ago_total_revenue": 0,
    "year_ago_avg_order_value": 0,
    "year_ago_unique_customers": 0
  },
  "daily_sales": [
    { "date": "2026-10-09", "orders": 4, "revenue": 13587 },
    { "date": "2026-10-10", "orders": 2, "revenue": 45000 }
  ],
  "top_products": [
    { "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46", "product_name": "Cafeteira Elétrica Lumina 900W", "quantity": 9, "revenue": 2691000 }
  ],
  "generated_at": "2026-10-11T14:02:11.482Z"
}

Campos da resposta

statsobject
Totais do intervalo, com os mesmos campos de Resumo de vendas. Os campos previous_* e year_ago_* vêm sempre 0 neste relatório.
daily_salesarray
Série por dia, só dos dias com pelo menos um pedido.
daily_sales[].datestring
Dia, YYYY-MM-DD, no fuso da loja.
daily_sales[].ordersinteger
Pedidos do dia.
daily_sales[].revenueinteger
Receita do dia, em centavos.
top_productsarray
Os 10 produtos com mais receita no intervalo.
top_products[].product_idstring
Id do produto (UUID).
top_products[].product_namestring
Nome do produto.
top_products[].quantityinteger
Unidades vendidas.
top_products[].revenueinteger
Receita do produto, em centavos.
generated_atstring
Quando o relatório foi calculado (RFC 3339, UTC).

Erros (report)

StatusQuandoCorpo
400Falta start ou end.{"error":"start and end query parameters are required (format: 2006-01-02)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid start date format; expected YYYY-MM-DD"}
400start depois de end.{"error":"start date must be before or equal to end date"}
400Intervalo maior que 1 ano sem period=all.{"error":"date range must not exceed 1 year"}
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 ..."}

Vendas por dia

GET/api/v1/admin/analytics/dailyAdmin

Vendas por dia (só dias com pedido)

Parâmetros de consulta

startstringobrigatório
Primeiro dia, formato YYYY-MM-DD, no fuso da loja (America/Sao_Paulo).
endstringobrigatório
Último dia, formato YYYY-MM-DD. O dia inteiro entra no cálculo.
periodstring
all
Só o valor all tem efeito aqui: remove o limite de 366 dias entre start e end. Qualquer outro valor é ignorado.

Exemplo de requisição (daily)

bash
curl "$BASE_URL/api/v1/admin/analytics/daily?start=2026-10-01&end=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (daily)

200Série retornada
json
{
  "daily_sales": [
    { "date": "2026-10-09", "orders": 4, "revenue": 13587 },
    { "date": "2026-10-10", "orders": 2, "revenue": 45000 }
  ]
}

Campos da resposta

daily_salesarray
Um item por dia com pedidos, em ordem de data. Lista vazia ([]) se nenhum dia teve pedido.
daily_sales[].datestring
Dia, YYYY-MM-DD, no fuso da loja.
daily_sales[].ordersinteger
Pedidos do dia.
daily_sales[].revenueinteger
Receita do dia, em centavos.

Erros (daily)

StatusQuandoCorpo
400Falta start ou end.{"error":"start and end query parameters are required (format: 2006-01-02)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid start date format; expected YYYY-MM-DD"}
400start depois de end.{"error":"start date must be before or equal to end date"}
400Intervalo maior que 1 ano sem period=all.{"error":"date range must not exceed 1 year"}
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 ..."}

Receita por dia

GET/api/v1/admin/analytics/daily-revenueAdmin

Receita por dia (todos os dias do intervalo)

Parâmetros de consulta

startstringobrigatório
Primeiro dia, formato YYYY-MM-DD, no fuso da loja (America/Sao_Paulo).
endstringobrigatório
Último dia, formato YYYY-MM-DD. O dia inteiro entra no cálculo.
periodstring
all
Só o valor all tem efeito aqui: remove o limite de 366 dias entre start e end. Qualquer outro valor é ignorado.

Exemplo de requisição (daily-revenue)

bash
curl "$BASE_URL/api/v1/admin/analytics/daily-revenue?start=2026-10-01&end=2026-10-03" \
  -H "Authorization: Bearer $TOKEN"

Resposta (daily-revenue)

200Série retornada
json
{
  "daily_revenue": [
    { "date": "2026-10-01", "revenue": 0, "orders": 0, "avg_order_value": 0 },
    { "date": "2026-10-02", "revenue": 0, "orders": 0, "avg_order_value": 0 },
    { "date": "2026-10-03", "revenue": 0, "orders": 0, "avg_order_value": 0 }
  ]
}

Campos da resposta

daily_revenuearray
Um item para cada dia de start a end, inclusive, mesmo sem vendas.
daily_revenue[].datestring
Dia, YYYY-MM-DD.
daily_revenue[].revenueinteger
Receita do dia, em centavos.
daily_revenue[].ordersinteger
Pedidos do dia.
daily_revenue[].avg_order_valueinteger
Ticket médio do dia, em centavos (0 sem pedidos).

Erros (daily-revenue)

StatusQuandoCorpo
400Falta start ou end.{"error":"start and end query parameters are required (format: 2006-01-02)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid start date format; expected YYYY-MM-DD"}
400start depois de end.{"error":"start date must be before or equal to end date"}
400Intervalo maior que 1 ano sem period=all.{"error":"date range must not exceed 1 year"}
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 ..."}
Máximo de 1 ano, a menos que você peça `period=all`

Intervalos acima de 366 dias retornam 400. Para o histórico completo, envie também period=all junto com um start bem antigo. Datas são sempre dias de calendário no fuso da loja.

`orders` na série diária inclui cancelados

Em daily_sales (rotas report e daily) o campo orders conta todos os pedidos do dia, cancelados inclusive, enquanto revenue exclui cancelados, reembolsados, falhos, chargeback e anulados. É por isso que um dia pode ter orders maior que zero e revenue igual a zero. Já daily-revenue não conta esses pedidos em nenhum dos dois campos.

Veja também

  • Resumo de vendas
  • Produtos mais vendidos
  • Padrões de tempo
Anterior
Pedidos por status
Próxima
Receita por seller e categoria
Nesta página
  • Relatório completo
  • Exemplo de requisição (report)
  • Resposta (report)
  • Erros (report)
  • Vendas por dia
  • Exemplo de requisição (daily)
  • Resposta (daily)
  • Erros (daily)
  • Receita por dia
  • Exemplo de requisição (daily-revenue)
  • Resposta (daily-revenue)
  • Erros (daily-revenue)
  • Veja também