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)

bash

curl "$BASE_URL/api/v1/admin/analytics/stats?period=30days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (stats)

200Estatísticas retornadas

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
}

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)

Status	Quando	Corpo
400	`period` fora da lista.	`{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha 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)

bash

curl "$BASE_URL/api/v1/admin/analytics/overview?period=30days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (overview)

200Visão geral retornada

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 }
  ]
}

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)

Status	Quando	Corpo
400	`period` fora da lista.	`{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`

Veja também

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.

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)

bash

curl "$BASE_URL/api/v1/admin/analytics/stats?period=30days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (stats)

200Estatísticas retornadas

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
}

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)

Status	Quando	Corpo
400	`period` fora da lista.	`{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha 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)

bash

curl "$BASE_URL/api/v1/admin/analytics/overview?period=30days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (overview)

200Visão geral retornada

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 }
  ]
}

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)

Status	Quando	Corpo
400	`period` fora da lista.	`{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`