API atual/Referência completa/Utilidades da vitrine

Estatísticas do cliente

Devolve o resumo de pedidos e gasto do cliente logado.

Devolve os números da conta do cliente: quantos pedidos fez, quantos foram pagos, quanto gastou, o ticket médio, as datas do primeiro e do último pedido e há quantos dias a conta existe. É a fonte do cartão "Meu resumo" da área do cliente.

GET/api/v1/storefront/statsCliente

Resumo de pedidos do cliente logado

Exige o token de um cliente logado (Authorization: Bearer) com o escopo customer:read. O resumo é sempre o do dono do token.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo do cliente

json

{
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "total_orders": 7,
  "total_paid_orders": 3,
  "total_spend_centavos": 128900,
  "average_order_value": 42966,
  "first_order_at": "2026-03-24T14:50:11.922414Z",
  "last_order_at": "2026-10-09T06:30:10.932191Z",
  "total_addresses": 1,
  "account_age_days": 219,
  "payment_punctuality": {
    "email": "maria.souza@example.com",
    "orders_4_months": 1,
    "late_payments_4_months": 0,
    "orders_5_years": 1,
    "late_payments_5_years": 0,
    "overdue_letter": "Y"
  }
}

Campos da resposta

user_iduuid

Id do cliente (o dono do token).

total_ordersinteger

Todos os pedidos do cliente, em qualquer status.

total_paid_ordersinteger

Pedidos considerados pagos (pago, enviado ou entregue na instalação padrão). Cada loja pode redefinir o que conta como pago.

total_spend_centavosinteger

Soma, em centavos, dos pedidos pagos. 128900 = R$ 1.289,00.

average_order_valueinteger

Ticket médio em centavos: gasto dividido pelos pedidos pagos. 0 sem pedidos pagos.

first_order_atstring

RFC 3339. Ausente se o cliente nunca comprou.

last_order_atstring

RFC 3339. Ausente se o cliente nunca comprou.

total_addressesinteger

Endereços salvos.

account_age_daysinteger

Dias desde a criação da conta.

payment_punctualityobject

Histórico de pontualidade de pagamento, contado pelo e-mail (pedidos de visitante com o mesmo e-mail entram na conta). Ausente quando o cliente não tem e-mail ou a leitura falhou.

payment_punctuality.emailstring

E-mail usado na contagem.

payment_punctuality.orders_4_monthsinteger

Pedidos nos últimos 4 meses.

payment_punctuality.late_payments_4_monthsinteger

Pagamentos em atraso nos últimos 4 meses.

payment_punctuality.orders_5_yearsinteger

Pedidos nos últimos 5 anos.

payment_punctuality.late_payments_5_yearsinteger

Pagamentos em atraso nos últimos 5 anos.

payment_punctuality.overdue_letterstring

Letra do status de atraso usada na conta.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido. O corpo é JSON, mas o `Content-Type` vem como `text/plain`.	`{"error":"missing authorization header"}`
401	Chamada com chave de API da vitrine (sem cliente logado): a rota exige um cliente.	`{"error":"authentication required"}`
403	Chave de API da vitrine sem o escopo `customer:read`.	`{"error":"missing_scope","required":"customer:read"}`
500	Falha ao calcular as estatísticas.	`{"error":"failed to get statistics","detail":"..."}`

Veja também

Estatísticas do cliente

Devolve o resumo de pedidos e gasto do cliente logado.

GET/api/v1/storefront/statsCliente

Resumo de pedidos do cliente logado

Exige o token de um cliente logado (Authorization: Bearer) com o escopo customer:read. O resumo é sempre o do dono do token.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo do cliente

json

{
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "total_orders": 7,
  "total_paid_orders": 3,
  "total_spend_centavos": 128900,
  "average_order_value": 42966,
  "first_order_at": "2026-03-24T14:50:11.922414Z",
  "last_order_at": "2026-10-09T06:30:10.932191Z",
  "total_addresses": 1,
  "account_age_days": 219,
  "payment_punctuality": {
    "email": "maria.souza@example.com",
    "orders_4_months": 1,
    "late_payments_4_months": 0,
    "orders_5_years": 1,
    "late_payments_5_years": 0,
    "overdue_letter": "Y"
  }
}

Campos da resposta

user_iduuid

Id do cliente (o dono do token).

total_ordersinteger

Todos os pedidos do cliente, em qualquer status.

total_paid_ordersinteger

Pedidos considerados pagos (pago, enviado ou entregue na instalação padrão). Cada loja pode redefinir o que conta como pago.

total_spend_centavosinteger

Soma, em centavos, dos pedidos pagos. 128900 = R$ 1.289,00.

average_order_valueinteger

Ticket médio em centavos: gasto dividido pelos pedidos pagos. 0 sem pedidos pagos.

first_order_atstring

RFC 3339. Ausente se o cliente nunca comprou.

last_order_atstring

RFC 3339. Ausente se o cliente nunca comprou.

total_addressesinteger

Endereços salvos.

account_age_daysinteger

Dias desde a criação da conta.

payment_punctualityobject

Histórico de pontualidade de pagamento, contado pelo e-mail (pedidos de visitante com o mesmo e-mail entram na conta). Ausente quando o cliente não tem e-mail ou a leitura falhou.

payment_punctuality.emailstring

E-mail usado na contagem.

payment_punctuality.orders_4_monthsinteger

Pedidos nos últimos 4 meses.

payment_punctuality.late_payments_4_monthsinteger

Pagamentos em atraso nos últimos 4 meses.

payment_punctuality.orders_5_yearsinteger

Pedidos nos últimos 5 anos.

payment_punctuality.late_payments_5_yearsinteger

Pagamentos em atraso nos últimos 5 anos.

payment_punctuality.overdue_letterstring

Letra do status de atraso usada na conta.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido. O corpo é JSON, mas o `Content-Type` vem como `text/plain`.	`{"error":"missing authorization header"}`
401	Chamada com chave de API da vitrine (sem cliente logado): a rota exige um cliente.	`{"error":"authentication required"}`
403	Chave de API da vitrine sem o escopo `customer:read`.	`{"error":"missing_scope","required":"customer:read"}`
500	Falha ao calcular as estatísticas.	`{"error":"failed to get statistics","detail":"..."}`