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

Relatórios de vendas

Vendas com série temporal e comparação, desempenho de produtos, pedidos por status e receita por categoria do seller.

Os relatórios são mais completos que as análises e todos pedem uma janela de datas. Sempre restritos ao próprio seller. Exigem o privilégio de ajustes do seller; não dependem de módulo. Para baixar o mesmo dado em planilha, use Exportar CSV.

Relatório de vendas

Receita, pedidos e ticket médio do intervalo, uma série temporal agrupada por dia, semana ou mês, os produtos mais vendidos e, se pedir, a comparação com outro intervalo.

GET/api/v1/vendor/reports/salesSeller

Relatório de vendas

Cabeçalhos

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

Parâmetros de consulta

fromstringobrigatório
Primeiro dia, YYYY-MM-DD.
tostringobrigatório
Último dia, YYYY-MM-DD. Janela de no máximo 366 dias.
group_bystringpadrão: day
dayweekmonth
Agrupamento da série. Valor desconhecido vale day. Em week e month a data do ponto é o primeiro dia do grupo (segunda-feira ou dia 1).
compare_fromstring
Início do intervalo de comparação, YYYY-MM-DD. Use junto com compare_to.
compare_tostring
Fim do intervalo de comparação, YYYY-MM-DD.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/reports/sales?from=2026-10-09&to=2026-10-11&group_by=day" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório
json
{
  "total_revenue": 58587,
  "total_orders": 3,
  "avg_order_value": 19529,
  "completed_orders": 0,
  "cancelled_orders": 3,
  "time_series": [
    {
      "date": "2026-10-09",
      "revenue": 13587,
      "orders": 1,
      "aov": 13587
    },
    {
      "date": "2026-10-10",
      "revenue": 45000,
      "orders": 2,
      "aov": 22500
    }
  ],
  "compare_revenue": 0,
  "compare_orders": 0,
  "compare_series": [],
  "revenue_change": 0,
  "order_change": 0,
  "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:02:58.955447846Z"
}

Campos da resposta

total_revenueinteger
Receita do intervalo em centavos, sem cancelados, reembolsados, recusados, estornados e anulados.
total_ordersinteger
Pedidos no intervalo, com a mesma exclusão.
avg_order_valueinteger
Ticket médio em centavos.
completed_ordersinteger
Pedidos concluídos.
cancelled_ordersinteger
Pedidos cancelados (contados à parte).
time_seriesobject[]
Pontos da série: date, revenue (centavos), orders e aov (ticket médio, centavos).
compare_revenueinteger
Receita do intervalo de comparação, em centavos. 0 sem comparação.
compare_ordersinteger
Pedidos do intervalo de comparação.
compare_seriesobject[]
Série do intervalo de comparação, no mesmo formato de time_series.
revenue_changeinteger
Variação da receita contra a comparação, em pontos-base (10000 = +100%, -2500 = -25%). 0 quando não há comparação ou ela é zero.
order_changeinteger
Variação do número de pedidos, também em pontos-base.
top_productsobject[]
Produtos mais vendidos: product_id, product_name, quantity, revenue (centavos).
generated_atstring
Momento da geração, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
400from/to ausentes, data inválida, início depois do fim ou janela maior que 1 ano.{"error":"from and to query parameters are required (format: 2006-01-02)"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
500Falha ao montar o relatório.{"error":"failed to generate sales report","detail":"..."}
Comparação

A comparação só é calculada quando compare_from e compare_to vêm juntos e válidos. Para comparar com o período anterior de mesma duração, calcule você mesmo as duas datas.

Desempenho de produtos

Os produtos do seller que mais venderam no intervalo, ordenados pela receita. Não conta pedidos cancelados, reembolsados, recusados, estornados nem anulados.

GET/api/v1/vendor/reports/productsSeller

Desempenho de produtos

Cabeçalhos

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

Parâmetros de consulta

fromstringobrigatório
Primeiro dia, YYYY-MM-DD.
tostringobrigatório
Último dia, YYYY-MM-DD. Janela de no máximo 366 dias.
limitintegerpadrão: 20
Quantos produtos devolver, de 1 a 100. Valor inválido ou menor que 1 usa o padrão 20; acima de 100 o resultado volta para 10.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/reports/products?from=2026-10-01&to=2026-10-11&limit=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos
json
{
  "products": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "product_name": "Camisa do Flamengo Masculina I 26 Adidas",
      "quantity": 2,
      "revenue": 45000
    }
  ]
}

Campos da resposta

productsobject[]
Um item por produto: product_id (UUID), product_name, quantity (unidades) e revenue (centavos).

Erros

StatusQuandoCorpo de exemplo
400from/to ausentes, data inválida, início depois do fim ou janela maior que 1 ano.{"error":"from and to query parameters are required (format: 2006-01-02)"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
500Falha ao montar o relatório.{"error":"failed to get product performance","detail":"..."}

Pedidos por status e indicadores

Duas visões dos pedidos do seller na mesma resposta: a contagem por status e os indicadores do período. Aceita dois estilos de filtro: um período nomeado (period) ou uma janela explícita (from e to). Se você mandar from ou to, eles vencem period.

GET/api/v1/vendor/reports/ordersSeller

Pedidos por status e indicadores

Cabeçalhos

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

Parâmetros de consulta

periodstringpadrão: 30days
today7days30days90daysall
Período nomeado. Ignorado se from/to forem enviados.
fromstring
Primeiro dia, YYYY-MM-DD. Exige to.
tostring
Último dia, YYYY-MM-DD. Exige from.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/reports/orders?from=2026-10-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedidos
json
{
  "by_status": [
    {
      "status": "I",
      "code": "cancelled",
      "name": "Cancelado",
      "type": "cancelled",
      "count": 3
    },
    {
      "status": "O",
      "code": "pending",
      "name": "Pendente",
      "type": "initial",
      "count": 2
    }
  ],
  "stats": {
    "total_orders": 3,
    "total_revenue": 58587,
    "pending_orders": 2,
    "completed_orders": 0,
    "cancelled_orders": 3,
    "avg_order_value": 19529,
    "unique_customers": 3,
    "period": "2026-10-01..2026-10-11",
    "previous_total_orders": 1,
    "previous_total_revenue": 321790,
    "previous_avg_order_value": 321790,
    "previous_unique_customers": 1,
    "year_ago_total_orders": 383,
    "year_ago_total_revenue": 23862110,
    "year_ago_avg_order_value": 62303,
    "year_ago_unique_customers": 362
  }
}

Campos da resposta

by_statusobject[]
Contagem por status, no mesmo formato de analytics/orders-by-status.
statsobject
Indicadores, no mesmo formato de analytics/stats. Com from/to, o campo period vem como AAAA-MM-DD..AAAA-MM-DD.

Erros

StatusQuandoCorpo de exemplo
400period desconhecido (sem from/to), ou from/to inválidos: um só deles já aciona a validação das duas datas.{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
500Falha ao montar o relatório.{"error":"failed to get orders by status","detail":"..."}

Receita por categoria

Quanto cada categoria do catálogo do seller vendeu no intervalo, mais a receita por dia das 5 categorias que mais venderam.

GET/api/v1/vendor/reports/revenue-by-categorySeller

Receita por categoria

Cabeçalhos

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

Parâmetros de consulta

fromstringobrigatório
Primeiro dia, YYYY-MM-DD.
tostringobrigatório
Último dia, YYYY-MM-DD. Janela de no máximo 366 dias.
group_bystringpadrão: day
dayweekmonth
Agrupamento de time_series. Valor desconhecido vale day.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/reports/revenue-by-category?from=2026-10-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Categorias
json
{
  "categories": [
    {
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "category_name": "Camisetas",
      "product_count": 1,
      "products_sold": 2,
      "revenue": 45000,
      "avg_price": 22500,
      "order_count": 2,
      "percentage": 7814
    }
  ],
  "time_series": [
    {
      "date": "2026-10-10",
      "categories": {
        "Camisetas": 45000
      }
    }
  ],
  "generated_at": "2026-10-11T21:02:59.045213299Z"
}

Campos da resposta

categoriesobject[]

Uma linha por categoria.

categories[].category_iduuid
Id da categoria (UUID).
categories[].category_namestring
Nome da categoria.
categories[].product_countinteger
Produtos da categoria que venderam no intervalo.
categories[].products_soldinteger
Unidades vendidas.
categories[].revenueinteger
Receita em centavos.
categories[].avg_priceinteger
Preço médio em centavos.
categories[].order_countinteger
Pedidos com a categoria.
categories[].percentageinteger
Participação na receita total em pontos-base (7814 = 78,14%).
time_seriesobject[]
Por ponto: date e categories, um mapa nome da categoria para receita em centavos (5 maiores).
generated_atstring
Momento da geração, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
400from/to ausentes, data inválida, início depois do fim ou janela maior que 1 ano.{"error":"from and to query parameters are required (format: 2006-01-02)"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
500Falha ao montar o relatório.{"error":"failed to generate category report","detail":"..."}

Veja também

  • Exportar CSV
  • Relatórios agendados
  • Análises
Anterior
Análises por período
Próxima
Exportar relatório em CSV
Nesta página
  • Relatório de vendas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Desempenho de produtos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pedidos por status e indicadores
  • Exemplo de requisição
  • Resposta
  • Erros
  • Receita por categoria
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também