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

Clientes e maiores compradores

Novos e recorrentes, gasto médio e ranking dos clientes que mais compram.

Três visões dos clientes no período. customer-stats resume quantos são novos e quantos já compravam, com o gasto médio. top-customers é o ranking de quem mais gastou. sales-by-customer devolve a receita por cliente já no formato de gráfico de pizza: os maiores clientes e uma fatia "Outros" com o resto.

Estatísticas de clientes

GET/api/v1/admin/analytics/customer-statsAdmin

Clientes novos e recorrentes

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 (customer-stats)

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

Resposta (customer-stats)

200Estatísticas retornadas
json
{
  "new_customers": 3,
  "returning_customers": 280,
  "total_customers": 283,
  "avg_order_value": 69883,
  "avg_lifetime_value": 380797,
  "top_customers": [
    { "customer_id": "b2495fbb-8e8d-4d18-b370-b30f880bfd71", "customer_name": "Bruno Gomes", "email": "bruno.gomes@example.com", "order_count": 26, "total_spent": 1229701 }
  ]
}

Campos da resposta

new_customersinteger
Clientes cuja primeira compra aconteceu dentro do intervalo.
returning_customersinteger
Clientes que compraram no intervalo mas já tinham comprado antes.
total_customersinteger
Soma dos dois grupos.
avg_order_valueinteger
Ticket médio em centavos.
avg_lifetime_valueinteger
Gasto médio de todos os tempos por cliente ativo, em centavos.
top_customersarray
Os maiores clientes do intervalo.
top_customers[].customer_idstring
Id do cliente (UUID).
top_customers[].customer_namestring
Nome; pode vir vazio.
top_customers[].emailstring
E-mail do cliente.
top_customers[].order_countinteger
Pedidos no intervalo.
top_customers[].total_spentinteger
Total gasto, em centavos.

Erros (customer-stats)

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 ..."}

Ranking de clientes

GET/api/v1/admin/analytics/top-customersAdmin

Ranking dos clientes que mais gastaram

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.
tostring
Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.
periodstringpadrão: 30days
today7days30days90daysthis_monthlast_monththis_year
Atalho de janela quando from/to não são enviados.
limitintegerpadrão: 10
Quantos clientes devolver. Máximo 50 (valores maiores são cortados em 50).

Exemplo de requisição (top-customers)

bash
curl "$BASE_URL/api/v1/admin/analytics/top-customers?period=90days&limit=2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (top-customers)

200Ranking retornado
json
{
  "customers": [
    { "user_id": "a0000000-0000-0000-0000-000000000002", "name": "João Santos", "email": "joao.santos@example.com", "order_count": 4, "total_spent_centavos": 428434, "avg_ticket_centavos": 107109 },
    { "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10", "name": "Maria Souza", "email": "maria.souza@example.com", "person_type": "F", "order_count": 2, "total_spent_centavos": 45000, "avg_ticket_centavos": 22500 }
  ]
}

Campos da resposta

customersarray
Clientes em ordem decrescente de gasto.
customers[].user_idstring
Id do cliente (UUID).
customers[].namestring
Nome do cliente.
customers[].emailstring
E-mail do cliente.
customers[].person_typestring
FJ
Tipo de pessoa: F física, J jurídica. Só aparece quando está preenchido.
customers[].order_countinteger
Pedidos no período.
customers[].total_spent_centavosinteger
Total gasto, em centavos.
customers[].avg_ticket_centavosinteger
Ticket médio do cliente, em centavos.

Erros (top-customers)

StatusQuandoCorpo
400period desconhecido.{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}
400from/to mal formatados, from depois de to, ou mais de 2 anos.{"error":"date range must not exceed 2 years"}
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 cliente

GET/api/v1/admin/analytics/sales-by-customerAdmin

Receita por cliente em fatias

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.
tostring
Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.
periodstringpadrão: 30days
today7days30days90daysthis_monthlast_monththis_year
Atalho de janela quando from/to não são enviados.
top_nintegerpadrão: 5
Quantos clientes aparecem com nome antes da fatia "Outros". Máximo 20 (valores maiores são cortados em 20).

Exemplo de requisição (sales-by-customer)

bash
curl "$BASE_URL/api/v1/admin/analytics/sales-by-customer?period=90days&top_n=2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (sales-by-customer)

200Fatias retornadas
json
{
  "slices": [
    { "label": "João Santos", "revenue_centavos": 428434 },
    { "label": "Maria Souza", "revenue_centavos": 45000 },
    { "label": "Outros", "revenue_centavos": 18853 }
  ]
}

Campos da resposta

slicesarray
Fatias em ordem decrescente; a última, Outros, soma os demais clientes.
slices[].labelstring
Nome do cliente, ou Outros.
slices[].revenue_centavosinteger
Receita da fatia, em centavos.

Erros (sales-by-customer)

StatusQuandoCorpo
400period desconhecido.{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}
400from/to mal formatados, from depois de to, ou mais de 2 anos.{"error":"date range must not exceed 2 years"}
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 ..."}
Cada rota recebe o período de um jeito

customer-stats usa start e end (obrigatórios). top-customers e sales-by-customer usam from/to ou period, e por padrão olham os últimos 30 dias. As rotas de Métricas de clientes seguem o segundo modelo.

Veja também

  • Métricas de clientes
  • Coortes de retenção
Anterior
Produtos mais vendidos
Próxima
Métricas de clientes
Nesta página
  • Estatísticas de clientes
  • Exemplo de requisição (customer-stats)
  • Resposta (customer-stats)
  • Erros (customer-stats)
  • Ranking de clientes
  • Exemplo de requisição (top-customers)
  • Resposta (top-customers)
  • Erros (top-customers)
  • Receita por cliente
  • Exemplo de requisição (sales-by-customer)
  • Resposta (sales-by-customer)
  • Erros (sales-by-customer)
  • Veja também