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

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

Resposta

200Relatório
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
    }
  ]
}

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

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

Resposta

200Relatório
json
{
  "categories": [
    {
      "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
      "category_name": "Cafeteiras",
      "product_count": 19,
      "products_sold": 33,
      "revenue": 1570670,
      "avg_price": 47596
    }
  ]
}

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

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

Resposta

200Relatório
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
    }
  ]
}

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

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

Resposta

200Relatório
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
    }
  ]
}

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

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

Resposta

200Relatório
json
{
  "shipping": [
    {
      "method_name": "SEDEX",
      "order_count": 101,
      "total_shipping_cost": 79720,
      "avg_shipping_cost": 789,
      "avg_delivery_days": 5
    }
  ]
}

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