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

bash

curl "$BASE_URL/api/v1/admin/dashboard?period=7days" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Painel carregado

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": []
}

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

Status	Quando	Exemplo de corpo
400	`from` 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"}`
500	Falha ao montar o painel.	`{"error":"failed to load dashboard data","detail":"..."}`
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`

Veja também