Indicadores e relatórios

Um seller (lojista) vende dentro do marketplace da loja e acompanha o próprio negócio no painel do seller. Esta seção documenta as rotas de leitura desse painel, sob /api/v1/vendor: o resumo da conta, o saldo financeiro, as análises por período, os relatórios de vendas (com exportação em CSV) e os relatórios agendados por e-mail. Todas as rotas devolvem somente os dados do próprio seller: o seller é identificado pelo token, nunca por um parâmetro.

Como funciona

Pense em três camadas, da mais simples para a mais detalhada:

1. Resumo da conta

   GET /vendor/dashboard (ou /vendor/stats, é o mesmo) devolve cinco números para o cabeçalho do painel. GET /vendor/revenue soma a receita de um intervalo e GET /vendor/balance mostra o que o seller tem a receber.

2. Análises por período

   /vendor/analytics/* devolve indicadores com comparação contra o período anterior e contra o mesmo período do ano passado, receita por dia, ranking de produtos e pedidos por status.

3. Relatórios e exportação

   /vendor/reports/* entrega relatórios mais completos (vendas com série temporal, produtos, pedidos, categorias) e /vendor/reports/export baixa o mesmo dado em CSV. Para receber o CSV por e-mail em dias fixos, crie um relatório agendado em /vendor/scheduled-reports.

Conceitos-chave

Período nomeado e janela de datas

Dois estilos de filtro convivem. Rotas de indicadores aceitam um período nomeado em period: today, 7days, 30days, 90days ou all. Rotas de séries e relatórios pedem uma janela explícita, com start/end ou from/to, em YYYY-MM-DD, e as duas pontas entram inteiras.

Status de pedido

Os pedidos têm um status de uma letra, e cada loja pode ter o seu alfabeto (por exemplo O pendente, P processando, C entregue, I cancelado, R reembolsado). As rotas de status devolvem status (a letra), code (nome interno), name (nome em português para exibir) e type (grupo: initial, processing, shipped, complete, cancelled, refunded).

Saldo do seller

O saldo é calculado a partir das comissões. A plataforma retém uma comissão sobre cada venda (definida pelo plano ou pelo acordo do seller) e o restante é do seller. Os campos de saldo separam o que já pode ser repassado do que ainda está em liquidação.

Endpoints

Erros comuns

• Somar /stats e /analytics/stats e esperar o mesmo número. O resumo da conta (/stats, /dashboard) conta todos os sub-pedidos do seller, inclusive cancelados; analytics/stats exclui cancelados, reembolsados, recusados, estornados e anulados da receita e do total.
• Esquecer o intervalo. daily-revenue, top-products, revenue e todos os reports/* exigem as duas datas. Sem elas a resposta é 400.
• Pedir mais de um ano. Janelas acima de 366 dias são recusadas com date range must not exceed 1 year. Divida a consulta em anos.
• Tratar centavos como reais. 380377 é R$ 3.803,77. Só o CSV usa reais.
• Chamar com token de administrador. Estas rotas pedem um token de usuário seller; o de administrador recebe 403.
• Achar que 403 é erro de token. Se o token está certo, olhe o privilégio do usuário e se o módulo analytics (ou metrics-config) está ligado na loja.
• Esperar o CSV como JSON. reports/export devolve um arquivo com separador ; e BOM UTF-8, não JSON.

Próximos passos