VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Indicadores e relatórios

Análises por período

Indicadores com comparativos, receita por dia, produtos mais vendidos e pedidos por status do seller.

As análises alimentam os gráficos do painel. Diferente do resumo da conta, elas excluem da receita e do total os pedidos cancelados, reembolsados, recusados, estornados e anulados. Exigem o privilégio financeiro e o módulo analytics ligado na loja.

Indicadores do período

Devolve os indicadores do período pedido, já com a comparação contra o período imediatamente anterior (de mesma duração) e contra o mesmo período do ano passado.

GET/api/v1/vendor/analytics/statsSeller

Indicadores do período

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

periodstringpadrão: 30days
today7days30days90daysall
Janela de tempo.

Exemplo de requisição

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

Resposta

200Indicadores
json
{
  "total_orders": 4,
  "total_revenue": 380377,
  "pending_orders": 3,
  "completed_orders": 0,
  "cancelled_orders": 3,
  "avg_order_value": 95094,
  "unique_customers": 4,
  "period": "30days",
  "previous_total_orders": 1633,
  "previous_total_revenue": 103680436,
  "previous_avg_order_value": 63491,
  "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 do período, sem cancelados, reembolsados, recusados, estornados e anulados.
total_revenueinteger
Receita dos mesmos pedidos, em centavos.
pending_ordersinteger
Pedidos pendentes (status inicial).
completed_ordersinteger
Pedidos concluídos, conforme os status de cada loja.
cancelled_ordersinteger
Pedidos cancelados. Estes não entram em total_orders.
avg_order_valueinteger
Ticket médio em centavos.
unique_customersinteger
Clientes distintos.
periodstring
O período usado.
previous_*integer
previous_total_orders, previous_total_revenue, previous_avg_order_value, previous_unique_customers: os mesmos quatro números na janela anterior de mesma duração.
year_ago_*integer
year_ago_total_orders, year_ago_total_revenue, year_ago_avg_order_value, year_ago_unique_customers: os mesmos quatro números um ano antes.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller (por exemplo, um token de administrador), a loja ainda está em análise de cadastro, ou o usuário não tem o privilégio exigido.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial","vendor_request_payouts","vendor_view_commissions","vendor_view_debts","vendor_view_referrals"]}
400period desconhecido.{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}
403O módulo analytics está desligado nesta loja.{"error":"module_disabled","module":"analytics"}
Com `period=all`

Não há janela anterior para comparar: os campos previous_* e year_ago_* vêm zerados.

Receita por dia

Devolve uma linha por dia do intervalo, com receita, número de pedidos e ticket médio. Dias sem venda aparecem com zeros.

GET/api/v1/vendor/analytics/daily-revenueSeller

Receita por dia

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

startstringobrigatório
Primeiro dia, YYYY-MM-DD.
endstringobrigatório
Último dia, YYYY-MM-DD. A janela é de no máximo 366 dias.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/analytics/daily-revenue?start=2026-10-08&end=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Série diária
json
{
  "daily_revenue": [
    {
      "date": "2026-10-09",
      "revenue": 13587,
      "orders": 1,
      "avg_order_value": 13587
    },
    {
      "date": "2026-10-10",
      "revenue": 45000,
      "orders": 2,
      "avg_order_value": 22500
    }
  ]
}

Campos da resposta

daily_revenueobject[]

Um item por dia, em ordem crescente.

daily_revenue[].datestring
Dia, YYYY-MM-DD.
daily_revenue[].revenueinteger
Receita do dia em centavos.
daily_revenue[].ordersinteger
Pedidos do dia.
daily_revenue[].avg_order_valueinteger
Ticket médio do dia em centavos.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller (por exemplo, um token de administrador), a loja ainda está em análise de cadastro, ou o usuário não tem o privilégio exigido.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial","vendor_request_payouts","vendor_view_commissions","vendor_view_debts","vendor_view_referrals"]}
400start ou end ausentes.{"error":"start and end query parameters are required (format: 2006-01-02)"}
400Data fora do formato YYYY-MM-DD, início depois do fim, ou janela maior que 1 ano.{"error":"date range must not exceed 1 year"}
403O módulo analytics está desligado nesta loja.{"error":"module_disabled","module":"analytics"}
Dia é dia de Brasília

Cada pedido cai no dia em que foi criado no horário de Brasília, não em UTC. Um pedido feito às 22h de Brasília pertence àquele dia, mesmo já sendo o dia seguinte em UTC.

Produtos mais vendidos

Ranking dos produtos do seller no intervalo, ordenado pela receita.

GET/api/v1/vendor/analytics/top-productsSeller

Produtos mais vendidos

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

startstringobrigatório
Primeiro dia, YYYY-MM-DD.
endstringobrigatório
Último dia, YYYY-MM-DD. Janela de no máximo 366 dias.
limitintegerpadrão: 10
Quantos produtos devolver, de 1 a 100. Valor inválido ou menor que 1 volta ao padrão. Acima de 100 também volta ao padrão (10), não é limitado a 100.

Exemplo de requisição

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

Resposta

200Ranking
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_productsobject[]

Produtos, do que mais faturou para o que menos faturou.

top_products[].product_iduuid
Id do produto (UUID).
top_products[].product_namestring
Nome do produto.
top_products[].quantityinteger
Unidades vendidas.
top_products[].revenueinteger
Receita em centavos.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller (por exemplo, um token de administrador), a loja ainda está em análise de cadastro, ou o usuário não tem o privilégio exigido.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial","vendor_request_payouts","vendor_view_commissions","vendor_view_debts","vendor_view_referrals"]}
400start ou end ausentes.{"error":"start and end query parameters are required (format: 2006-01-02)"}
400Data fora do formato YYYY-MM-DD, início depois do fim, ou janela maior que 1 ano.{"error":"date range must not exceed 1 year"}
403O módulo analytics está desligado nesta loja.{"error":"module_disabled","module":"analytics"}
`limit` acima de 100

Se você pedir limit=500, recebe 10 produtos, não 100. Fique entre 1 e 100.

Pedidos por status

Conta os sub-pedidos do seller agrupados por status. Sem period, conta tudo desde sempre.

GET/api/v1/vendor/analytics/orders-by-statusSeller

Pedidos por status

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

periodstring
today7days30days90daysall
Janela de tempo. Omitido: todo o histórico.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/analytics/orders-by-status?period=7days" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contagem por status
json
{
  "statuses": [
    {
      "status": "I",
      "code": "cancelled",
      "name": "Cancelado",
      "type": "cancelled",
      "count": 3
    },
    {
      "status": "O",
      "code": "pending",
      "name": "Pendente",
      "type": "initial",
      "count": 2
    },
    {
      "status": "P",
      "code": "processing",
      "name": "Processando",
      "type": "processing",
      "count": 1
    }
  ]
}

Campos da resposta

statusesobject[]

Um item por status que tem pedidos, do mais frequente para o menos.

statuses[].statusstring
Letra do status.
statuses[].codestring
Código interno do status.
statuses[].namestring
Nome para exibição (em português, como configurado na loja).
statuses[].typestring
initialprocessingshippedcompletecancelledrefunded
Grupo do status.
statuses[].countinteger
Quantidade de sub-pedidos.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller (por exemplo, um token de administrador), a loja ainda está em análise de cadastro, ou o usuário não tem o privilégio exigido.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial","vendor_request_payouts","vendor_view_commissions","vendor_view_debts","vendor_view_referrals"]}
403O módulo analytics está desligado nesta loja.{"error":"module_disabled","module":"analytics"}
Valor de `period` inválido

Diferente de analytics/stats, esta rota não valida period: um valor desconhecido é tratado como se não tivesse sido enviado.

Veja também

  • Resumo da conta
  • Relatórios
Anterior
Resumo da conta
Próxima
Relatórios de vendas
Nesta página
  • Indicadores do período
  • Exemplo de requisição
  • Resposta
  • Erros
  • Receita por dia
  • Exemplo de requisição
  • Resposta
  • Erros
  • Produtos mais vendidos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pedidos por status
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também