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

Resumo de vendas

Pedidos, receita, ticket médio e clientes de um período, com comparação com o período anterior e com o ano anterior.

Estas duas rotas respondem à pergunta "como a loja está indo?". stats devolve os números de um período. overview devolve os mesmos números mais a contagem de pedidos por status, numa chamada só, para montar uma tela inicial. Os dois comparam com o período anterior de mesma duração e com o mesmo intervalo um ano antes, o que dá a variação sem uma segunda chamada.

Estatísticas do período

GET/api/v1/admin/analytics/statsAdmin

Estatísticas de pedidos de um período

Parâmetros de consulta

periodstringpadrão: 30days
today7days30days90daysall
Janela de tempo, contada de agora para trás.

Exemplo de requisição (stats)

Resposta (stats)

200Estatísticas retornadas

Campos da resposta

total_ordersinteger
Pedidos que contam como venda: todos menos cancelados, reembolsados, falhos, chargeback e anulados.
total_revenueinteger
Receita desses pedidos, em centavos.
pending_ordersinteger
Pedidos pendentes (status O) no período, contados à parte.
completed_ordersinteger
Pedidos concluídos segundo o cadastro de status da loja.
cancelled_ordersinteger
Pedidos cancelados (status I).
avg_order_valueinteger
Ticket médio em centavos (receita dividida por total_orders).
unique_customersinteger
Clientes distintos no período. Em /analytics/report o valor vem sempre 0.
periodstring
O período pedido. No relatório por datas, start, um travessão longo e end.
previous_total_ordersinteger
Mesmo número do período imediatamente anterior, com a mesma duração. 0 quando period=all.
previous_total_revenueinteger
Receita do período anterior, em centavos.
previous_avg_order_valueinteger
Ticket médio do período anterior, em centavos.
previous_unique_customersinteger
Clientes distintos no período anterior.
year_ago_total_ordersinteger
Pedidos na mesma janela, um ano antes.
year_ago_total_revenueinteger
Receita na mesma janela, um ano antes, em centavos.
year_ago_avg_order_valueinteger
Ticket médio um ano antes, em centavos.
year_ago_unique_customersinteger
Clientes distintos um ano antes.

Erros (stats)

StatusQuandoCorpo
400period fora da lista.{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}
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 ..."}

Visão geral

GET/api/v1/admin/analytics/overviewAdmin

Estatísticas mais pedidos por status

Parâmetros de consulta

periodstringpadrão: 30days
today7days30days90daysall
Janela de tempo, contada de agora para trás.

Exemplo de requisição (overview)

Resposta (overview)

200Visão geral retornada

Campos da resposta

periodstring
O período usado.
statsobject
O mesmo objeto de /analytics/stats (o exemplo mostra só alguns campos).
orders_by_statusarray
Pedidos por status, igual a Pedidos por status. Se essa parte falhar, a rota ainda responde 200 com a lista vazia.

Erros (overview)

StatusQuandoCorpo
400period fora da lista.{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}
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 ..."}
Os números não são o total de pedidos da loja

total_orders e total_revenue ignoram pedidos cancelados, reembolsados, falhos, com chargeback e anulados, e só olham pedidos "pai" (a compra inteira, não os sub-pedidos de cada seller). Já pending_orders, completed_orders e cancelled_orders são contagens por status e não somam com total_orders.

Janelas e fuso

today começa à meia-noite do fuso da loja; 7days, 30days e 90days contam 7, 30 e 90 dias para trás a partir de agora, não dias de calendário. Com period=all os campos previous_* e year_ago_* vêm zerados.

Veja também

  • Pedidos por status
  • Relatório de vendas por datas
  • Ids, dinheiro e datas
Anterior
Análises e relatórios
Próxima
Pedidos por status
Nesta página
  • Estatísticas do período
  • Exemplo de requisição (stats)
  • Resposta (stats)
  • Erros (stats)
  • Visão geral
  • Exemplo de requisição (overview)
  • Resposta (overview)
  • Erros (overview)
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/analytics/stats?period=30days" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/analytics/overview?period=30days" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "total_orders": 8,
  "total_revenue": 492287,
  "pending_orders": 6,
  "completed_orders": 0,
  "cancelled_orders": 3,
  "avg_order_value": 61536,
  "unique_customers": 5,
  "period": "30days",
  "previous_total_orders": 1634,
  "previous_total_revenue": 103685186,
  "previous_avg_order_value": 63455,
  "previous_unique_customers": 1024,
  "year_ago_total_orders": 1146,
  "year_ago_total_revenue": 73426509,
  "year_ago_avg_order_value": 64072,
  "year_ago_unique_customers": 950
}
json
{
  "period": "30days",
  "stats": {
    "total_orders": 8,
    "total_revenue": 492287,
    "avg_order_value": 61536,
    "period": "30days"
  },
  "orders_by_status": [
    { "status": "O", "code": "pending", "name": "Pendente", "type": "initial", "count": 146 },
    { "status": "C", "code": "delivered", "name": "Entregue", "type": "complete", "count": 36900 }
  ]
}