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

Clientes, estoque e comissões

Relatórios avançados de clientes (com LTV e geografia), estoque (giro e baixo estoque) e comissões por seller.

Três relatórios para gestão do marketplace: de onde vêm e quanto valem os clientes, o que está parado ou acabando no estoque e quanto a loja ganhou de comissão de cada seller. Cliente e comissão exigem from e to; estoque é uma fotografia de hoje e aceita só o filtro vendor_id (e a janela do giro). Privilégio exigido: view_reports.

Clientes

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

Clientes, LTV e geografia

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/customers?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório de clientes
json
{
  "new_customers": 4,
  "returning_customers": 276,
  "total_customers": 280,
  "avg_order_value": 68922,
  "avg_lifetime_value": 380797,
  "acquisition_series": [
    {
      "date": "2026-10-09",
      "revenue": 1,
      "orders": 0,
      "aov": 0
    }
  ],
  "geo_breakdown": [
    {
      "state": "SP",
      "customers": 120,
      "revenue": 8200000,
      "orders": 160
    }
  ],
  "ltv_distribution": [
    {
      "label": "R$0-100",
      "min_value": 0,
      "max_value": 10000,
      "count": 406
    },
    {
      "label": "R$5.000+",
      "min_value": 500000,
      "max_value": 0,
      "count": 1890
    }
  ],
  "top_customers": [
    {
      "customer_id": "b2495fbb-8e8d-4d18-b370-b30f880bfd71",
      "customer_name": "Bruno Gomes",
      "email": "bruno.gomes@example.com",
      "order_count": 26,
      "total_spent": 1229701
    }
  ],
  "generated_at": "2026-10-11T21:03:12Z"
}

Campos da resposta

new_customers / returning_customers / total_customersinteger
Clientes novos, recorrentes e total 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.
acquisition_seriesarray
Cadastros novos ao longo do tempo. Em revenue vem o número de clientes novos do ponto, não dinheiro.
geo_breakdownarray
Por estado (UF): state, customers, revenue (centavos), orders. Vazio quando os pedidos não têm estado de entrega.
ltv_distributionarray
Faixas de gasto total por cliente: label, min_value e max_value em centavos (max_value 0 = sem teto) e count de clientes. As faixas cobrem toda a base, não só o período.
top_customersarray
Maiores compradores: customer_id, customer_name, email, order_count, total_spent (centavos).
generated_atstring
Momento da geração.

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 customer report","detail":"..."}
Não filtra por seller

O relatório de clientes ignora vendor_id: ele sempre agrega a base do marketplace inteiro. Por isso relatórios agendados de seller não podem usar o tipo customers.

Estoque

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

Estoque, giro e produtos com pouco saldo

Parâmetros de consulta

vendor_iduuid
Limita ao seller. category_id é aceito mas ignorado neste relatório.
fromstring
Início da janela usada para contar as unidades vendidas (giro), YYYY-MM-DD. Padrão: 30 dias atrás.
tostring
Fim da janela do giro. Padrão: hoje.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/advanced-reports/inventory" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório de estoque
json
{
  "total_products": 4983,
  "total_value": 5131097470,
  "low_stock_count": 3095,
  "out_of_stock_count": 3,
  "top_movers": [
    {
      "product_id": "60554c37-45e9-4a08-a2ce-6d30d6cb3d0b",
      "product_name": "Notebook Deluxe Vermelho 00069",
      "sku": "SD-000069",
      "current_stock": 1,
      "units_sold": 5,
      "turnover_rate": 50000,
      "revenue": 19950
    }
  ],
  "slow_movers": [],
  "low_stock_items": [
    {
      "id": "9b0a5d1e-3c52-4f0e-8a58-6a1d7c2f0b11",
      "name": "Caneca Esmaltada 350 ml",
      "sku": "CAN-350",
      "quantity": 1,
      "threshold": 5
    }
  ],
  "stock_by_category": [
    {
      "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
      "category_name": "Cafeteiras",
      "product_count": 19,
      "total_stock": 340,
      "total_value": 15200000
    }
  ],
  "generated_at": "2026-10-11T21:03:12Z"
}

Campos da resposta

total_productsinteger
Produtos considerados.
total_valueinteger
Valor do estoque: preço vezes quantidade, em centavos.
low_stock_count / out_of_stock_countinteger
Produtos com saldo abaixo do limite e produtos sem saldo.
top_movers / slow_moversarray
Maior e menor giro: product_id, product_name, sku, current_stock, units_sold (no período), turnover_rate (vendidas dividido pelo estoque, em pontos-base: 50000 = 5 vezes o saldo) e revenue (centavos).
low_stock_itemsarray
Produtos abaixo do limite: id, name, sku, quantity, threshold.
stock_by_categoryarray
Por categoria: category_id, category_name, product_count, total_stock e total_value (centavos).
generated_atstring
Momento da geração.

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"]}
500Falha ao gerar o relatório.{"error":"failed to generate inventory report","detail":"..."}
Datas opcionais

É o único relatório avançado que não exige from e to. O saldo é sempre o de agora; as datas só definem a janela das unidades vendidas.

Comissões

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

Comissões por seller

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/commissions?from=2026-09-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório de comissões
json
{
  "total_commission": 1184740,
  "total_vendor_earnings": 10662665,
  "pending_amount": 1184740,
  "paid_amount": 0,
  "by_vendor": [
    {
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "order_count": 196,
      "gross_amount": 11847405,
      "commission_amount": 1184740,
      "vendor_amount": 10662665,
      "status": "pending"
    }
  ],
  "time_series": [
    {
      "date": "2026-09-01",
      "commission": 178136,
      "vendor": 1603224,
      "orders": 35
    }
  ],
  "generated_at": "2026-10-11T21:02:40Z"
}

Campos da resposta

total_commissioninteger
Comissão total da loja, em centavos.
total_vendor_earningsinteger
Total que fica com os sellers, em centavos.
pending_amount / paid_amountinteger
Parcela da comissão ainda pendente e já paga, em centavos.
by_vendorarray
Por seller: vendor_id, vendor_name, order_count, gross_amount, commission_amount, vendor_amount (centavos) e status (pending, partial ou paid).
time_seriesarray
Por dia: date, commission, vendor (centavos) e orders.
generated_atstring
Momento da geração.

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 commission report","detail":"..."}

Veja também

  • Relatórios avançados de vendas
  • Exportar em CSV
  • Dinheiro, ids e datas
Anterior
Relatórios avançados de vendas
Próxima
Agendar relatórios
Nesta página
  • Clientes
  • Exemplo de requisição
  • Resposta
  • Erros
  • Estoque
  • Exemplo de requisição
  • Resposta
  • Erros
  • Comissões
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também