Produtos mais vendidos

Os produtos que mais faturaram em um intervalo de datas.

Lista os produtos por receita, do maior para o menor, considerando só pedidos que contam como venda (sem cancelados, reembolsados, falhos, chargeback ou anulados). A rota top-products exige as datas e responde em top_products. A rota products é um atalho para a mesma consulta: as datas são opcionais (o padrão são os últimos 30 dias) e a resposta repete o intervalo usado.

Top de produtos

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

Produtos mais vendidos 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.

limitintegerpadrão: 10

Quantos produtos devolver, de 1 a 100.

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 (top-products)

bash

curl "$BASE_URL/api/v1/admin/analytics/top-products?start=2026-09-01&end=2026-10-10&limit=2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (top-products)

200Produtos retornados

json

{
  "top_products": [
    { "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46", "product_name": "Cafeteira Elétrica Lumina 900W", "quantity": 9, "revenue": 2691000 },
    { "product_id": "f00b151f-498a-4c27-adfb-774ac5ac6c89", "product_name": "Garrafa Vintage Verde 02477", "quantity": 3, "revenue": 392970 }
  ]
}

Campos da resposta

top_productsarray

Produtos em ordem decrescente de receita.

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.

Erros (top-products)

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

Atalho `products`

GET/api/v1/admin/analytics/productsAdmin

Atalho de produtos mais vendidos (padrão 30 dias)

Parâmetros de consulta

startstring

Primeiro dia, YYYY-MM-DD. Se start ou end faltar, os dois são ignorados e vale os últimos 30 dias.

endstring

Último dia, YYYY-MM-DD.

limitintegerpadrão: 10

Quantos produtos devolver, de 1 a 100.

Exemplo de requisição (products)

bash

curl "$BASE_URL/api/v1/admin/analytics/products?limit=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta (products)

200Produtos retornados

json

{
  "start": "2026-09-11",
  "end": "2026-10-11",
  "limit": 1,
  "products": [
    { "product_id": "b63d9fb4-aef7-4294-9109-8e7219d5c746", "product_name": "Notebook Vintage Vermelho 04018 - ESPECIAL", "quantity": 2, "revenue": 319800 }
  ]
}

Campos da resposta

startstring

Primeiro dia usado.

endstring

Último dia usado.

limitinteger

Limite aplicado.

productsarray

Produtos, no mesmo formato de top_products[] da rota irmã.

Erros (products)

Status	Quando	Corpo
400	Data fora do formato `YYYY-MM-DD`.	`{"error":"invalid start date format; expected YYYY-MM-DD"}`
400	`start` depois de `end`.	`{"error":"start date must be before or equal to end date"}`
400	Intervalo maior que 1 ano sem `period=all`.	`{"error":"date range must not exceed 1 year"}`
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

Produtos mais vendidos

Os produtos que mais faturaram em um intervalo de datas.

Top de produtos

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

Produtos mais vendidos 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.

limitintegerpadrão: 10

Quantos produtos devolver, de 1 a 100.

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 (top-products)

bash

curl "$BASE_URL/api/v1/admin/analytics/top-products?start=2026-09-01&end=2026-10-10&limit=2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (top-products)

200Produtos retornados

json

{
  "top_products": [
    { "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46", "product_name": "Cafeteira Elétrica Lumina 900W", "quantity": 9, "revenue": 2691000 },
    { "product_id": "f00b151f-498a-4c27-adfb-774ac5ac6c89", "product_name": "Garrafa Vintage Verde 02477", "quantity": 3, "revenue": 392970 }
  ]
}

Campos da resposta

top_productsarray

Produtos em ordem decrescente de receita.

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.

Erros (top-products)

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

Atalho `products`

GET/api/v1/admin/analytics/productsAdmin

Atalho de produtos mais vendidos (padrão 30 dias)

Parâmetros de consulta

startstring

Primeiro dia, YYYY-MM-DD. Se start ou end faltar, os dois são ignorados e vale os últimos 30 dias.

endstring

Último dia, YYYY-MM-DD.

limitintegerpadrão: 10

Quantos produtos devolver, de 1 a 100.

Exemplo de requisição (products)

bash

curl "$BASE_URL/api/v1/admin/analytics/products?limit=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta (products)

200Produtos retornados

json

{
  "start": "2026-09-11",
  "end": "2026-10-11",
  "limit": 1,
  "products": [
    { "product_id": "b63d9fb4-aef7-4294-9109-8e7219d5c746", "product_name": "Notebook Vintage Vermelho 04018 - ESPECIAL", "quantity": 2, "revenue": 319800 }
  ]
}

Campos da resposta

startstring

Primeiro dia usado.

endstring

Último dia usado.

limitinteger

Limite aplicado.

productsarray

Produtos, no mesmo formato de top_products[] da rota irmã.

Erros (products)

Status	Quando	Corpo
400	Data fora do formato `YYYY-MM-DD`.	`{"error":"invalid start date format; expected YYYY-MM-DD"}`
400	`start` depois de `end`.	`{"error":"start date must be before or equal to end date"}`
400	Intervalo maior que 1 ano sem `period=all`.	`{"error":"date range must not exceed 1 year"}`
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 ..."}`