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

Relatórios por dimensão

Cinco relatórios de período fechado: receita por seller, por categoria e por dia, clientes e frete.

Estes relatórios respondem a perguntas pontuais sobre um intervalo: quem vendeu mais, que categoria rendeu mais, como foi cada dia, quantos clientes são novos e quanto custou o frete por modalidade. Todos exigem from e to (YYYY-MM-DD, no máximo 366 dias) e devolvem dinheiro em centavos. Todos exigem o privilégio view_reports.

Receita por seller

GET/api/v1/admin/reports/revenue-by-vendorAdmin

Receita e comissão por seller

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD, inclusive. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD, inclusive (o dia inteiro entra). Obrigatório. Não pode ser antes de from e o intervalo não pode passar de 366 dias.

Exemplo de requisição

Resposta

200Relatório

Campos da resposta

vendorsarray
Um item por seller com venda no período.
vendors[].vendor_iduuid
Id do seller.
vendors[].vendor_namestring
Nome do seller.
vendors[].order_countinteger
Pedidos do seller.
vendors[].revenueinteger
Receita bruta, em centavos.
vendors[].commission_amountinteger
Comissão retida pela loja, em centavos.
vendors[].net_revenueinteger
Receita menos comissão, em centavos: o que fica com o seller.
vendors[].avg_order_valueinteger
Ticket médio do seller, em centavos.
vendors[].percentageinteger
Participação na receita total, em pontos-base (2500 = 25,00%).

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)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}
400from depois de to.{"error":"from date must be before or equal to to date"}
400Intervalo maior que um ano.{"error":"date range must not exceed 1 year"}
500Falha ao consultar o banco.{"error":"failed to get revenue by vendor","detail":"..."}
Porcentagens em pontos-base

percentage usa pontos-base: divida por 100 para obter a porcentagem. Os percentuais de todos os sellers somam cerca de 10000.

Receita por categoria

GET/api/v1/admin/reports/revenue-by-categoryAdmin

Receita por categoria de produto

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD, inclusive. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD, inclusive (o dia inteiro entra). Obrigatório. Não pode ser antes de from e o intervalo não pode passar de 366 dias.

Exemplo de requisição

Resposta

200Relatório

Campos da resposta

categoriesarray
Do maior para o menor faturamento.
categories[].category_idstring
Id da categoria (UUID) ou uncategorized para produtos sem categoria.
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.

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)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}
400from depois de to.{"error":"from date must be before or equal to to date"}
400Intervalo maior que um ano.{"error":"date range must not exceed 1 year"}
500Falha ao consultar o banco.{"error":"failed to get revenue by category","detail":"..."}

Receita diária

GET/api/v1/admin/reports/daily-revenueAdmin

Receita dia a dia

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD, inclusive. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD, inclusive (o dia inteiro entra). Obrigatório. Não pode ser antes de from e o intervalo não pode passar de 366 dias.

Exemplo de requisição

Resposta

200Relatório

Campos da resposta

daily_revenuearray
Um item por dia do intervalo, inclusive dias sem venda (valores 0).
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

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)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}
400from depois de to.{"error":"from date must be before or equal to to date"}
400Intervalo maior que um ano.{"error":"date range must not exceed 1 year"}
500Falha ao consultar o banco.{"error":"failed to get daily revenue","detail":"..."}

Clientes

GET/api/v1/admin/reports/customersAdmin

Clientes novos, recorrentes e maiores compradores

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD, inclusive. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD, inclusive (o dia inteiro entra). Obrigatório. Não pode ser antes de from e o intervalo não pode passar de 366 dias.

Exemplo de requisição

Resposta

200Relatório

Campos da resposta

new_customersinteger
Clientes cuja primeira compra caiu no período.
returning_customersinteger
Clientes que compraram no período e já tinham comprado antes.
total_customersinteger
Clientes distintos que compraram no período.
avg_order_valueinteger
Ticket médio, em centavos.
avg_lifetime_valueinteger
Gasto médio por cliente ao longo da vida, em centavos.
top_customersarray
Maiores compradores: customer_id (UUID), customer_name (vazio se o cliente não tem nome), email, order_count, total_spent (centavos).

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)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}
400from depois de to.{"error":"from date must be before or equal to to date"}
400Intervalo maior que um ano.{"error":"date range must not exceed 1 year"}
500Falha ao consultar o banco.{"error":"failed to get customer stats","detail":"..."}
Exportação

Os mesmos dados saem em CSV por Exportar em CSV com type=customers.

Frete

GET/api/v1/admin/reports/shippingAdmin

Uso e custo por forma de envio

Parâmetros de consulta

fromstringobrigatório
Início do período, YYYY-MM-DD, inclusive. Obrigatório.
tostringobrigatório
Fim do período, YYYY-MM-DD, inclusive (o dia inteiro entra). Obrigatório. Não pode ser antes de from e o intervalo não pode passar de 366 dias.

Exemplo de requisição

Resposta

200Relatório

Campos da resposta

shippingarray
Um item por forma de envio usada. Pedidos sem forma registrada aparecem como Unknown.
shipping[].method_namestring
Nome da forma de envio.
shipping[].order_countinteger
Pedidos que usaram a forma.
shipping[].total_shipping_costinteger
Frete total cobrado, em centavos.
shipping[].avg_shipping_costinteger
Frete médio por pedido, em centavos.
shipping[].avg_delivery_daysinteger
Dias médios entre envio e entrega. 0 quando não há entrega registrada.

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)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}
400from depois de to.{"error":"from date must be before or equal to to date"}
400Intervalo maior que um ano.{"error":"date range must not exceed 1 year"}
500Falha ao consultar o banco.{"error":"failed to get shipping report","detail":"..."}

Veja também

  • Exportar em CSV
  • Vendas, pedidos e produtos
  • Dinheiro, ids e datas
Anterior
Vendas, pedidos e produtos
Próxima
Exportar em CSV
Nesta página
  • Receita por seller
  • Exemplo de requisição
  • Resposta
  • Erros
  • Receita por categoria
  • Exemplo de requisição
  • Resposta
  • Erros
  • Receita diária
  • Exemplo de requisição
  • Resposta
  • Erros
  • Clientes
  • Exemplo de requisição
  • Resposta
  • Erros
  • Frete
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/reports/revenue-by-vendor?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/reports/revenue-by-category?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/reports/daily-revenue?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/reports/customers?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/reports/shipping?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "vendors": [
    {
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "order_count": 400,
      "revenue": 28008796,
      "commission_amount": 2968334,
      "net_revenue": 25040462,
      "avg_order_value": 70022,
      "percentage": 9998
    }
  ]
}
json
{
  "categories": [
    {
      "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
      "category_name": "Cafeteiras",
      "product_count": 19,
      "products_sold": 33,
      "revenue": 1570670,
      "avg_price": 47596
    }
  ]
}
json
{
  "daily_revenue": [
    {
      "date": "2026-09-01",
      "revenue": 4480463,
      "orders": 65,
      "avg_order_value": 68930
    },
    {
      "date": "2026-09-07",
      "revenue": 0,
      "orders": 0,
      "avg_order_value": 0
    }
  ]
}
json
{
  "new_customers": 4,
  "returning_customers": 280,
  "total_customers": 284,
  "avg_order_value": 69606,
  "avg_lifetime_value": 380797,
  "top_customers": [
    {
      "customer_id": "b2495fbb-8e8d-4d18-b370-b30f880bfd71",
      "customer_name": "Bruno Gomes",
      "email": "bruno.gomes@example.com",
      "order_count": 26,
      "total_spent": 1229701
    }
  ]
}
json
{
  "shipping": [
    {
      "method_name": "SEDEX",
      "order_count": 101,
      "total_shipping_cost": 79720,
      "avg_shipping_cost": 789,
      "avg_delivery_days": 5
    }
  ]
}