Análises e relatórios

Esta seção reúne as rotas de análise da loja, as mesmas que alimentam as telas de relatórios do painel de administração. Elas respondem perguntas como quanto a loja vendeu, quem compra, quando compra, de onde vêm os clientes e quanto sobra de lucro. Todas são de leitura, exceto a gravação de custos de mídia, a adesão à comparação com o mercado, a carga do histórico de lucro e a criação de audiências.

Como funciona

Nenhuma rota guarda estado de relatório: cada chamada recalcula a partir dos pedidos. O fluxo típico de um painel é:

1. Mostrar a visão geral

   Chame Resumo de vendas para os cartões de topo e Pedidos por status para o funil.

2. Desenhar as séries

   Use Relatório de vendas para o gráfico por dia e Padrões de tempo para dia da semana e hora.

3. Entender quem compra

   Clientes, métricas de clientes e coortes.

4. Medir o retorno

   Lance os custos de mídia em Canais e acompanhe o lucro real.

As três famílias de períodos:

profit, channels, campaigns e search usam from/to com padrão de 30 dias.

Conceitos-chave

Pedido pai e sub-pedido

Uma compra com produtos de vários sellers (lojistas) vira um pedido pai e um sub-pedido por seller. Os relatórios da loja olham o pedido pai, para não contar a mesma compra duas vezes. A receita por seller usa os sub-pedidos.

Centavos e pontos-base

4990 é R$ 49,90. Taxas e participações vêm em pontos-base, a centésima parte de um ponto percentual: 2500 é 25,00%. Veja Ids, dinheiro e datas.

Letra de status

O status do pedido é uma letra definida por loja. Os relatórios resolvem a letra para code, name e type pelo cadastro de status da loja; agrupe por type.

Quem pode ver

São rotas do administrador da loja. O seller (lojista) tem as próprias rotas de análise, fora desta seção. Sem o privilégio view_reports a resposta é 403 insufficient privileges; com o módulo analytics desligado, 403 module_disabled.

Endpoints

Erros comuns

• Esquecer start e end nas rotas que os exigem: a resposta é 400, não um padrão de 30 dias.
• Pedir mais de 1 ano com start/end sem period=all.
• Somar pending_orders + completed_orders + cancelled_orders esperando chegar a total_orders: o total ignora cancelados.
• Tratar a letra do status como universal; ela muda por loja.
• Mandar limit acima de 100 em top-products esperando 100: volta 10.
• Dividir centavos por 100 duas vezes ou exibir pontos-base como se fossem porcentagem.
• Gravar custos de mídia com o rótulo do painel em vez da chave do canal.
• Chamar o lucro sem ter preço de custo nos produtos: cogs_missing_pct alto significa lucro inflado.

Próximos passos