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

Vendas, pedidos e produtos

Quatro relatórios de entrada: resumo de vendas, vendas, pedidos por status e produtos mais vendidos, com janela padrão de 30 dias.

Estas quatro rotas são o jeito mais curto de obter números de vendas: não exigem parâmetros, e sem datas usam os últimos 30 dias. GET /admin/reports e GET /admin/reports/sales devolvem o relatório de vendas (o primeiro dentro de um envelope report/period/data). GET /admin/reports/orders conta pedidos por status e GET /admin/reports/products lista os mais vendidos. Valores em dinheiro vêm em centavos. Para filtros por seller ou categoria e comparação entre períodos, use os relatórios avançados.

Resumo de relatórios

GET/api/v1/admin/reportsAdmin

Relatório de vendas dentro de um envelope

Parâmetros de consulta

fromstring
Início, YYYY-MM-DD. Sem from e to, vale os últimos 30 dias.
tostring
Fim, YYYY-MM-DD. Os dois precisam vir juntos, senão a janela padrão é usada.
compare_fromstring
Início do período de comparação, YYYY-MM-DD.
compare_tostring
Fim do período de comparação, YYYY-MM-DD. Precisa vir junto com compare_from.
vendor_iduuid
Limita ao seller 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/reports?from=2026-10-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório
json
{
  "report": "sales",
  "period": {
    "from": "2026-10-01",
    "to": "2026-10-11"
  },
  "data": {
    "total_revenue": 63853,
    "total_orders": 4,
    "avg_order_value": 15963,
    "completed_orders": 0,
    "cancelled_orders": 3,
    "time_series": [
      {
        "date": "2026-10-09",
        "revenue": 13587,
        "orders": 1,
        "aov": 13587
      },
      {
        "date": "2026-10-10",
        "revenue": 45000,
        "orders": 2,
        "aov": 22500
      }
    ],
    "compare_revenue": 0,
    "compare_orders": 0,
    "compare_series": [],
    "revenue_change": 0,
    "order_change": 0,
    "top_products": [
      {
        "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
        "product_name": "Camisa do Flamengo Masculina I 26 Adidas",
        "quantity": 2,
        "revenue": 45000
      }
    ],
    "generated_at": "2026-10-11T21:02:40.868Z"
  }
}

Campos da resposta

reportstring
Sempre sales.
periodobject
from e to efetivamente usados.
dataobject
O relatório de vendas. Campos em Vendas.

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 consultar o banco.{"error":"failed to generate report","detail":"..."}
Janela omitida

Aqui from e to são opcionais. Nos relatórios por dimensão e nos avançados eles são obrigatórios.

Vendas

GET/api/v1/admin/reports/salesAdmin

Relatório de vendas

Parâmetros de consulta

fromstring
Início, YYYY-MM-DD. Padrão: 30 dias atrás.
tostring
Fim, YYYY-MM-DD. Padrão: hoje (UTC).
compare_fromstring
Início do período de comparação.
compare_tostring
Fim do período de comparação.
vendor_iduuid
Limita ao seller.
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/reports/sales?from=2026-10-01&to=2026-10-11&group_by=week" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório de vendas
json
{
  "total_revenue": 63853,
  "total_orders": 4,
  "avg_order_value": 15963,
  "completed_orders": 0,
  "cancelled_orders": 3,
  "time_series": [
    {
      "date": "2026-10-09",
      "revenue": 13587,
      "orders": 1,
      "aov": 13587
    },
    {
      "date": "2026-10-10",
      "revenue": 45000,
      "orders": 2,
      "aov": 22500
    }
  ],
  "compare_revenue": 0,
  "compare_orders": 0,
  "compare_series": [],
  "revenue_change": 0,
  "order_change": 0,
  "top_products": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "product_name": "Camisa do Flamengo Masculina I 26 Adidas",
      "quantity": 2,
      "revenue": 45000
    }
  ],
  "generated_at": "2026-10-11T21:02:40.868Z"
}

Campos da resposta

total_revenueinteger
Receita total do período, em centavos.
total_ordersinteger
Quantidade de pedidos no período.
avg_order_valueinteger
Ticket médio, em centavos.
completed_ordersinteger
Pedidos em status final de concluído.
cancelled_ordersinteger
Pedidos cancelados.
time_seriesarray
Um ponto por dia (ou semana, ou mês, conforme group_by): date, revenue (centavos), orders, aov (ticket médio, centavos). Só aparecem os dias com pedido.
compare_revenue / compare_ordersinteger
Receita e pedidos do período de comparação. 0 quando nenhum período de comparação foi pedido.
compare_seriesarray
A série do período de comparação, no mesmo formato de time_series.
revenue_change / order_changeinteger
Variação em pontos-base (basis points) contra o período de comparação. -9976 = menos 99,76%; 1250 = mais 12,50%.
top_productsarray
Produtos mais vendidos do período: product_id, product_name, quantity, revenue.
generated_atstring
Momento em que o relatório foi gerado (RFC 3339, UTC).

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 consultar o banco.{"error":"failed to generate sales report","detail":"..."}

Pedidos por status

GET/api/v1/admin/reports/ordersAdmin

Quantidade de pedidos por status

Parâmetros de consulta

fromstring
Início, YYYY-MM-DD. Só vale junto com to.
tostring
Fim, YYYY-MM-DD. Se vier só um dos dois, a validação de datas é aplicada e a ausência do outro dá erro 400.

Exemplo de requisição

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

Resposta

200Contagem por status
json
{
  "orders_by_status": [
    {
      "status": "C",
      "code": "delivered",
      "name": "Entregue",
      "type": "complete",
      "count": 191
    },
    {
      "status": "O",
      "code": "pending",
      "name": "Pendente",
      "type": "initial",
      "count": 39
    },
    {
      "status": "I",
      "code": "cancelled",
      "name": "Cancelado",
      "type": "cancelled",
      "count": 4
    }
  ]
}

Campos da resposta

orders_by_statusarray
Um item por status existente.
orders_by_status[].statusstring
Letra do status guardada no pedido (a mesma letra pode ter outro significado em outra loja).
orders_by_status[].codestring
Código estável do status na loja (pending, delivered...). Vazio para letra sem cadastro.
orders_by_status[].namestring
Nome de exibição, em português.
orders_by_status[].typestring
Etapa do ciclo de vida: initial, processing, general, shipped, complete, cancelled, refunded ou final.
orders_by_status[].countinteger
Pedidos naquele status.

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"]}
400Datas inválidas (mesmas regras de Relatórios por dimensão).{"error":"from and to query parameters are required (format: 2006-01-02)"}
500Falha ao consultar o banco.{"error":"failed to get orders by status","detail":"..."}
Sem datas, é a tabela inteira

Sem from e to a contagem cobre todos os pedidos da loja desde sempre, não os últimos 30 dias como nos irmãos desta página. Isso é intencional, para compatibilidade com quem chama sem datas. Envie as datas quando quiser conferir contra o relatório de vendas.

Produtos mais vendidos

GET/api/v1/admin/reports/productsAdmin

Produtos mais vendidos do período

Parâmetros de consulta

fromstring
Início, YYYY-MM-DD. Padrão: 30 dias atrás. Não é validado: um texto inválido produz resultado vazio ou erro 500.
tostring
Fim, YYYY-MM-DD. Padrão: hoje (UTC).
limitintegerpadrão: 10
Quantos produtos devolver, de 1 a 100. Valor fora dessa faixa volta ao padrão.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/reports/products?limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos
json
{
  "period": {
    "from": "2026-09-11",
    "to": "2026-10-11"
  },
  "products": [
    {
      "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46",
      "product_name": "Cafeteira Elétrica Lumina 900W",
      "quantity": 9,
      "revenue": 2691000
    }
  ]
}

Campos da resposta

periodobject
from e to usados.
productsarray
Do mais para o menos vendido: product_id (UUID), product_name, quantity (unidades) e revenue (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"]}
500Falha ao consultar o banco.{"error":"failed to get top products","detail":"..."}

Veja também

  • Relatórios por dimensão
  • Relatórios avançados de vendas
  • Dinheiro, ids e datas
Anterior
Painel de indicadores
Próxima
Relatórios por dimensão
Nesta página
  • Resumo de relatórios
  • Exemplo de requisição
  • Resposta
  • Erros
  • Vendas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pedidos por status
  • Exemplo de requisição
  • Resposta
  • Erros
  • Produtos mais vendidos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também