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

GETPainel de indicadores

Devolve em uma única chamada os indicadores, gráficos e listas da tela inicial do painel administrativo.

O painel inicial da loja mostra vendas de hoje e do mês, ticket médio, séries diárias, produtos mais vendidos e alertas de estoque baixo. Esta rota entrega tudo isso de uma vez, já comparado com o mês anterior e com o mesmo mês do ano passado. Use-a para montar um painel próprio ou um widget de acompanhamento. Os valores em dinheiro vêm em centavos. Dias e meses são contados no fuso de São Paulo (America/Sao_Paulo).

GET/api/v1/admin/dashboardAdmin

Indicadores consolidados do painel

Parâmetros de consulta

periodstringpadrão: 30days
7days30days90days
Janela dos gráficos e do ticket médio. Valor desconhecido volta ao padrão.
fromstring
Início de uma janela explícita, YYYY-MM-DD. Só vale se to também for enviado; sozinho é ignorado e vale period.
tostring
Fim da janela explícita, YYYY-MM-DD. Não pode ser antes de from nem passar de 366 dias de intervalo.

Exemplo de requisição

Resposta

200Painel carregado

Campos da resposta

revenue_todayinteger
Receita de hoje, em centavos (5266 = R$ 52,66).
revenue_monthinteger
Receita do mês corrente, em centavos.
orders_todayinteger
Pedidos de hoje.
orders_monthinteger
Pedidos do mês corrente.
avg_order_valueinteger
Ticket médio do período do gráfico, em centavos.
pending_ordersinteger
Pedidos ainda pendentes.
active_productsinteger
Produtos ativos no catálogo.
active_customersinteger
Clientes distintos que compraram no período.
active_vendorsinteger
Sellers (lojistas) ativos.
new_customers_monthinteger
Clientes novos no mês corrente.
previous_revenue_month / previous_orders_month / previous_new_customers_month / previous_avg_order_valueinteger
Os mesmos indicadores do mês calendário anterior, para comparação.
year_ago_revenue_month / year_ago_orders_month / year_ago_new_customers_month / year_ago_avg_order_valueinteger
Os mesmos indicadores do mesmo mês um ano atrás.
daily_revenuearray
Série diária do período: date (YYYY-MM-DD), revenue (centavos), orders e avg_order_value. Um ponto por dia, inclusive dias sem venda.
prev_daily_revenuearray
A mesma série para a janela imediatamente anterior, de igual tamanho.
top_productsarray
Até 10 produtos mais vendidos: product_id, product_name, quantity, revenue (centavos).
revenue_by_categoryarray
Receita por categoria: category_id, category_name, product_count, products_sold, revenue, avg_price.
recent_ordersarray
Últimos pedidos: id (UUID), order_number, customer_name, status (letra), total (centavos), created_at.
low_stockarray
Produtos abaixo do limite de estoque: id, name, sku, quantity, threshold.
generated_atstring
Quando o resultado foi montado (RFC 3339, UTC).
warningsarray
Nomes dos blocos que falharam ao carregar (por exemplo top_products). Lista vazia quando tudo carregou.

Erros

StatusQuandoExemplo de corpo
400from ou to fora do formato, to antes de from ou intervalo maior que 366 dias.{"error":"invalid date range","detail":"from/to must be YYYY-MM-DD"}
500Falha ao montar o painel.{"error":"failed to load dashboard data","detail":"..."}
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
Cache de 1 minuto

O resultado fica em cache por 1 minuto para cada combinação de loja, period, from e to. Chamar mais vezes dentro desse minuto não traz números mais novos. Qualquer administrador pode chamar a rota, sem privilégio específico.

Campos que podem vir zerados

Nesta rota, avg_order_value dentro de daily_revenue, e product_count e avg_price dentro de revenue_by_category, podem voltar 0 mesmo havendo vendas. Para o ticket médio diário e o preço médio por categoria use Relatórios por dimensão.

Veja também

  • Relatórios de vendas, pedidos e produtos
  • Dinheiro, ids e datas
Anterior
Relatórios e painel
Próxima
Vendas, pedidos e produtos
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/dashboard?period=7days" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "revenue_today": 5266,
  "revenue_month": 63853,
  "orders_today": 1,
  "orders_month": 4,
  "avg_order_value": 15963,
  "pending_orders": 3,
  "active_products": 4983,
  "active_customers": 3,
  "active_vendors": 12,
  "new_customers_month": 14,
  "previous_revenue_month": 27418842,
  "previous_orders_month": 391,
  "previous_new_customers_month": 33,
  "previous_avg_order_value": 107109,
  "year_ago_revenue_month": 67315796,
  "year_ago_orders_month": 1041,
  "year_ago_new_customers_month": 165,
  "year_ago_avg_order_value": 66017,
  "daily_revenue": [
    {
      "date": "2026-10-10",
      "revenue": 45000,
      "orders": 2,
      "avg_order_value": 0
    },
    {
      "date": "2026-10-11",
      "revenue": 5266,
      "orders": 1,
      "avg_order_value": 0
    }
  ],
  "prev_daily_revenue": [
    {
      "date": "2026-09-28",
      "revenue": 374956,
      "orders": 3,
      "avg_order_value": 0
    }
  ],
  "top_products": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "product_name": "Camisa do Flamengo Masculina I 26 Adidas",
      "quantity": 2,
      "revenue": 45000
    }
  ],
  "revenue_by_category": [
    {
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "category_name": "Camisetas",
      "product_count": 0,
      "products_sold": 2,
      "revenue": 45000,
      "avg_price": 0
    }
  ],
  "recent_orders": [
    {
      "id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "order_number": "PILOT-20261011-0009",
      "customer_name": "Maria Souza",
      "status": "O",
      "total": 5266,
      "created_at": "2026-10-11T17:55:25"
    }
  ],
  "low_stock": [
    {
      "id": "9b0a5d1e-3c52-4f0e-8a58-6a1d7c2f0b11",
      "name": "Caneca Esmaltada 350 ml",
      "sku": "CAN-350",
      "quantity": 1,
      "threshold": 5
    }
  ],
  "generated_at": "2026-10-11T21:03:01.305Z",
  "warnings": []
}