Relatórios e painel
Painel de indicadores, relatórios de vendas, clientes, estoque, comissões e pagamentos, exportação em CSV e relatórios agendados por e-mail.
Esta área reúne tudo o que mostra como a loja está indo: o painel inicial com os indicadores do dia e do mês, relatórios de vendas, clientes, estoque, comissões, pagamentos e frete, exportação em planilha e envio periódico por e-mail. São rotas de leitura (exceto os agendamentos), pensadas para alimentar BI, planilhas e painéis próprios.
Como funciona
O caminho típico é: (1) começar pelo painel para o retrato do momento; (2) aprofundar com os relatórios de vendas, pedidos e produtos ou com os por dimensão; (3) usar os avançados quando precisar comparar períodos ou filtrar por seller e categoria; (4) levar para a planilha via CSV ou pedir que a plataforma envie sozinha com os relatórios agendados.
Conceitos principais
Dinheiro e porcentagem
Valores monetários são inteiros em centavos (4990 = R$ 49,90). Porcentagens são pontos-base (1 ponto-base = 0,01%), então 5115 é 51,15%. Veja também Dinheiro, ids e datas.
Seller (lojista)
Em uma loja multi-seller, cada vendedor é um seller. Os relatórios do admin enxergam todos; vendor_id restringe a um deles.
Fuso horário
O dia de um pedido é o dia em São Paulo (America/Sao_Paulo), não em UTC. Um pedido feito às 22h de São Paulo conta no mesmo dia, mesmo já sendo o dia seguinte em UTC.
Status de pedido
Cada pedido guarda uma letra de status, e o significado da letra é definido por loja. Os relatórios de pedidos devolvem a letra junto com code, name e type (etapa do ciclo de vida) para você não depender da letra.
Endpoints
| Método | Caminho | Para que serve | Página |
|---|---|---|---|
| GET | /api/v1/admin/dashboard | Indicadores, gráficos e listas do painel inicial | Painel de indicadores |
| GET | /api/v1/admin/reports | Relatório de vendas (últimos 30 dias por padrão) com envelope | Vendas, pedidos e produtos |
| GET | /api/v1/admin/reports/sales | Relatório de vendas com série temporal e produtos mais vendidos | Vendas, pedidos e produtos |
| GET | /api/v1/admin/reports/orders | Contagem de pedidos por status | Vendas, pedidos e produtos |
| GET | /api/v1/admin/reports/products | Produtos mais vendidos | Vendas, pedidos e produtos |
| GET | /api/v1/admin/reports/revenue-by-vendor | Receita e comissão por seller | Relatórios por dimensão |
| GET | /api/v1/admin/reports/revenue-by-category | Receita por categoria de produto | Relatórios por dimensão |
| GET | /api/v1/admin/reports/daily-revenue | Receita dia a dia | Relatórios por dimensão |
| GET | /api/v1/admin/reports/customers | Clientes novos, recorrentes e maiores compradores | Relatórios por dimensão |
| GET | /api/v1/admin/reports/shipping | Uso e custo por forma de envio | Relatórios por dimensão |
| GET | /api/v1/admin/reports/export | CSV dos relatórios por dimensão | Exportar em CSV |
| GET | /api/v1/admin/advanced-reports/export | CSV dos relatórios avançados | Exportar em CSV |
| GET | /api/v1/admin/advanced-reports/sales | Vendas com série temporal e comparação entre períodos | Relatórios avançados de vendas |
| GET | /api/v1/admin/advanced-reports/payments | Receita por forma de pagamento | Relatórios avançados de vendas |
| GET | /api/v1/admin/advanced-reports/categories | Desempenho por categoria, com série das 5 maiores | Relatórios avançados de vendas |
| GET | /api/v1/admin/advanced-reports/customers | Clientes novos e recorrentes, LTV, geografia e maiores compradores | Clientes, estoque e comissões |
| GET | /api/v1/admin/advanced-reports/inventory | Fotografia do estoque: valor, giro, baixo estoque e ruptura | Clientes, estoque e comissões |
| GET | /api/v1/admin/advanced-reports/commissions | Comissão da loja e repasse por seller | Clientes, estoque e comissões |
| GET | /api/v1/admin/scheduled-reports | Lista os relatórios agendados | Agendar relatórios |
| POST | /api/v1/admin/scheduled-reports | Cria um relatório agendado | Agendar relatórios |
| POST | /api/v1/admin/scheduled-reports/{id}/toggle | Pausa ou reativa um agendamento | Agendar relatórios |
| DELETE | /api/v1/admin/scheduled-reports/{id} | Exclui um agendamento | Agendar relatórios |
| POST | /api/v1/admin/scheduled-reports/{id}/run | Executa um agendamento agora | Executar e consultar histórico |
| GET | /api/v1/admin/scheduled-reports/{id}/runs | Histórico das últimas 20 execuções | Executar e consultar histórico |
Erros comuns
- Enviar
from/toem outro formato (10/09/2026): o formato éYYYY-MM-DDe erro volta como 400. - Pedir mais de 366 dias de uma vez: divida o período em janelas.
- Tratar
percentageerevenue_changecomo porcentagem direta: divida por 100. - Comparar o resultado de
/admin/reports/orderssem datas com o de vendas: o primeiro cobre a tabela inteira. - Checar só o status HTTP do
/admin/reports/export: umtypeinválido volta 200 com erro no corpo. - Esperar que
filtersde um agendamento volte como objeto: vem como texto JSON.