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

Relatórios avançados de vendas

Vendas com comparação entre períodos, formas de pagamento e categorias, com filtro por seller e categoria.

Os relatórios avançados aceitam filtros por seller e categoria e, no de vendas, comparação com outro período. Todos exigem from e to (YYYY-MM-DD) e o privilégio view_reports. Valores em dinheiro vêm em centavos e porcentagens em pontos-base (5115 = 51,15%).

Vendas avançado

GET/api/v1/admin/advanced-reports/salesAdmin

Vendas com comparação de períodos

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD. Obrigatório.
vendor_iduuid
Limita ao seller (lojista) informado.
category_iduuid
Aceito, mas ignorado neste relatório: só o relatório de categorias filtra por categoria.
group_bystringpadrão: day
dayweekmonth
Agrupamento da série: por dia, semana ou mês.
compare_fromstring
Início do período de comparação, YYYY-MM-DD.
compare_tostring
Fim do período de comparação. Os dois campos de comparação precisam vir juntos, senão a comparação é ignorada.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/advanced-reports/sales?from=2026-10-01&to=2026-10-11&group_by=week&compare_from=2026-09-01&compare_to=2026-09-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório com comparação
json
{
  "total_revenue": 63853,
  "total_orders": 4,
  "avg_order_value": 15963,
  "completed_orders": 0,
  "cancelled_orders": 3,
  "time_series": [
    {
      "date": "2026-10-05",
      "revenue": 63853,
      "orders": 4,
      "aov": 15963
    }
  ],
  "compare_revenue": 26990408,
  "compare_orders": 387,
  "compare_series": [
    {
      "date": "2026-08-31",
      "revenue": 26990408,
      "orders": 387,
      "aov": 69743
    }
  ],
  "revenue_change": -9976,
  "order_change": -9896,
  "top_products": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "product_name": "Camisa do Flamengo Masculina I 26 Adidas",
      "quantity": 2,
      "revenue": 45000
    }
  ],
  "generated_at": "2026-10-11T21:03:12Z"
}

Os campos são os mesmos de Vendas. Aqui revenue_change e order_change são o quanto o período atual ficou acima ou abaixo do de comparação, em pontos-base.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_reports"]}
400from ou to ausente.{"error":"from and to query parameters are required (format: 2006-01-02)"}
500Falha ao gerar o relatório.{"error":"failed to generate sales report","detail":"..."}
Semanas e meses

Com group_by=week a data de cada ponto é a segunda-feira da semana; com month, o dia 1 do mês. A comparação é agrupada do mesmo jeito.

Formas de pagamento

GET/api/v1/admin/advanced-reports/paymentsAdmin

Receita por forma de pagamento

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD. Obrigatório.
vendor_iduuid
Limita ao seller (lojista) informado.
category_iduuid
Aceito, mas ignorado neste relatório: só o relatório de categorias filtra por categoria.
group_bystringpadrão: day
dayweekmonth
Agrupamento da série: por dia, semana ou mês.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/advanced-reports/payments?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório de pagamentos
json
{
  "methods": [
    {
      "method": "pix",
      "order_count": 186,
      "revenue": 14059560,
      "percentage": 5115
    },
    {
      "method": "credit_card",
      "order_count": 135,
      "revenue": 9401439,
      "percentage": 3420
    }
  ],
  "time_series": [
    {
      "date": "2026-09-01",
      "methods": {
        "boleto": 533785,
        "credit_card": 1955243,
        "pix": 1991435
      }
    }
  ],
  "generated_at": "2026-10-11T21:03:12Z"
}

Campos da resposta

methodsarray
Um item por forma de pagamento usada.
methods[].methodstring
Código (slug) da forma de pagamento, como pix, credit_card, boleto. Pode ser um código customizado da loja.
methods[].order_countinteger
Pedidos pagos com a forma.
methods[].revenueinteger
Receita da forma, em centavos.
methods[].percentageinteger
Participação na receita total, em pontos-base.
time_seriesarray
Por dia (ou semana/mês): date e methods, um mapa de código da forma para receita em centavos.
generated_atstring
Momento da geração (RFC 3339).

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_reports"]}
400from ou to ausente.{"error":"from and to query parameters are required"}
500Falha ao gerar o relatório.{"error":"failed to generate payment report","detail":"..."}

Categorias

GET/api/v1/admin/advanced-reports/categoriesAdmin

Desempenho por categoria

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD. Obrigatório.
vendor_iduuid
Limita ao seller (lojista) informado.
category_iduuid
Limita à categoria informada.
group_bystringpadrão: day
dayweekmonth
Agrupamento da série: por dia, semana ou mês.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/advanced-reports/categories?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desempenho por categoria
json
{
  "categories": [
    {
      "category_id": "254960a6-8b83-4cbf-8ca0-5e9edfa2539d",
      "category_name": "Garrafas",
      "product_count": 17,
      "products_sold": 26,
      "revenue": 1490740,
      "avg_price": 57336,
      "order_count": 18,
      "percentage": 545
    }
  ],
  "time_series": [
    {
      "date": "2026-09-01",
      "categories": {
        "Garrafas": 120000,
        "Cafeteiras": 98000
      }
    }
  ],
  "generated_at": "2026-10-11T21:03:12Z"
}

Campos da resposta

categoriesarray
Do maior para o menor faturamento.
categories[].category_idstring
UUID da categoria ou uncategorized.
categories[].category_namestring
Nome da categoria.
categories[].product_countinteger
Produtos distintos vendidos.
categories[].products_soldinteger
Unidades vendidas.
categories[].revenueinteger
Receita, em centavos.
categories[].avg_priceinteger
Preço médio por unidade, em centavos.
categories[].order_countinteger
Pedidos que tiveram a categoria.
categories[].percentageinteger
Participação na receita total, em pontos-base.
time_seriesarray
Por dia: date e categories, mapa de nome da categoria para receita em centavos, só para as 5 maiores categorias.
generated_atstring
Momento da geração (RFC 3339).

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_reports"]}
400from ou to ausente.{"error":"from and to query parameters are required"}
500Falha ao gerar o relatório.{"error":"failed to generate category report","detail":"..."}

Veja também

  • Clientes, estoque e comissões
  • Exportar em CSV
  • Relatórios agendados
Anterior
Exportar em CSV
Próxima
Clientes, estoque e comissões
Nesta página
  • Vendas avançado
  • Exemplo de requisição
  • Resposta
  • Erros
  • Formas de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Categorias
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também