--- id: varejo/vendas-diarias-loja-erp industria: Varejo e e-commerce uso: muito usado esforco: médio grao: Loja x dia (e item de nota ou cupom para abrir por vendedor e produto) --- # Vendas diárias por loja e vendedor no ERP Faturamento líquido, ticket médio, cancelamentos e devoluções por loja, dia e vendedor, no dia comercial certo e batendo com o fechamento do ERP. ## Resumo executivo **Para quem:** Redes de varejo com várias lojas ou filiais que vendem pelo ERP ou PDV. **O que resolve** - O faturamento de cada loja cai no dia comercial certo, sem dia zerado ou deslocado por fuso. - Venda bruta, líquida, devolução e venda futura têm regra única e batem com o ERP. - Cada venda fica com a loja e o vendedor de quando ela aconteceu. **Por que importa:** É o número que a diretoria olha todo dia. Um dia zerado por erro de fuso ou uma nota casada com a loja errada derruba a confiança no painel inteiro. É a base para metas, comissão de vendedor e qualquer assistente de IA que responda quanto a loja vendeu. **Perguntas de negócio que responde** - Quanto cada loja vendeu ontem, líquido? - Qual o ticket médio por loja nesta semana e como está contra a semana passada? - Quanto foi de devolução e de cancelamento no mês, por loja? - Qual o faturamento por loja e vendedor nos últimos 14 meses? - Qual loja está em risco de não bater a meta do mês e quanto precisa vender por dia? **O que você precisa** - O ERP ou PDV conectado na Nekt (base Oracle, SAP ou ERP em nuvem) - Os códigos de operação do ERP: venda, venda futura, devolução, remessa - As metas por loja ou produto, se quiser meta x realizado **O que você recebe** - Uma tabela por loja e dia com bruta, líquida, tickets e cancelamentos - Uma tabela por item de nota com vendedor e produto - Dashboard da rede com meta, realizado e projeção por loja - Relatório diário de ontem por loja, no WhatsApp ou e-mail ## Detalhado ### O problema O ERP guarda a data da venda como meia-noite UTC e quem converte fuso joga a venda para o dia anterior ou zera o dia. O número da nota se repete entre lojas e o cruzamento só por ele mistura vendas de lojas e vendedores diferentes. Na mesma tabela convivem venda, venda futura, devolução negativa, cancelamento e remessa, e cada relatório soma de um jeito. ### Regras de negócio 1. **A data do ERP é o dia comercial.** Em muitos ERPs e PDVs o campo de data da venda é gravado como meia-noite UTC representando a data comercial, e a hora real fica em outro campo. Calcule hoje e ontem no fuso America/Sao_Paulo e compare direto com essa data, sem converter o campo. Converter para BRT joga meia-noite UTC para as 21h do dia anterior. (Evite: Aplicar AT TIME ZONE 'America/Sao_Paulo' no campo de data da venda.) 2. **Grave DATE, não TIMESTAMP, no destino.** Bancos de destino e ferramentas de BI reinterpretam um TIMESTAMP meia-noite UTC no fuso local e mostram o dia anterior. Converta para DATE antes de enviar. Confira fonte a fonte: algumas trazem data pura, outras trazem hora real em UTC (e-commerce costuma ter hora real e aí sim converte para BRT). (Evite: Mandar o TIMESTAMP do ERP para o Postgres do BI e confiar no fuso do servidor.) 3. **A nota é loja + número.** O número da nota é reutilizado entre estabelecimentos: o mesmo número em duas lojas são documentos diferentes. Todo cruzamento de nota com itens, carrinho, devolução ou comissão usa a chave composta (loja, número da nota). Conte notas com contagem distinta do par, não com contagem de linhas de item. (Evite: JOIN apenas pelo número da nota.) 4. **Diga se é bruta ou líquida.** Venda bruta é o valor dos cupons antes de desconto e cancelamento. Venda líquida = bruta menos descontos menos cancelamentos. As duas podem diferir em seis dígitos num único dia de uma loja. Todo número publicado diz qual é, e a pergunta "quanto vendeu" é respondida com a líquida. (Evite: Uma coluna "venda" sem dizer se é bruta ou líquida.) 5. **Cada tipo de operação tem um sinal.** Venda direta soma. Venda futura (faturada para entrega posterior) é faturamento válido e soma. Devolução vem com valor negativo e entra somada, reduzindo o total na data da devolução. Remessa, transferência e bonificação ficam fora: filtre pelos CFOPs de venda. Confirme a lista de códigos de operação com o financeiro. (Evite: Filtrar só venda direta e perder a venda futura, ou excluir devolução do líquido.) 6. **Ticket médio usa cupons válidos.** Ticket médio = venda líquida / tickets válidos. Ticket válido é cupom distinto (loja, PDV, número) que não foi cancelado. Ticket médio não é somável: o da rede e o do mês são recalculados a partir das somas, nunca média dos tickets diários. (Evite: Dividir pela contagem de linhas de item ou tirar a média dos tickets de cada loja.) 7. **Vendedor com a loja da época.** Vendedores mudam de loja ou apoiam outras unidades. A loja da venda é a do documento, e a relação vendedor x loja tem período de vigência; a loja atual do vendedor nunca é aplicada retroativamente. Normalize o nome (o ERP pode trazer sufixo " - 123" com o código) e mantenha vendedor nulo como "sem vendedor", sem descartar a venda. (Evite: Juntar vendedor à loja pelo cadastro atual e reescrever o histórico.) 8. **O grão está no nome e na chave de upsert.** A tabela diária tem uma linha por loja, por dia, e o nome diz isso. A chave de upsert é exatamente o grão (loja + dia). Cada execução reprocessa hoje e ontem para pegar ajustes tardios. Tabela mensal não recebe dado diário. (Evite: Merge por loja e mês numa tabela que recebe linhas diárias.) 9. **Meta x realizado com projeção.** Metas vêm de planilha por loja ou produto e competência. A carga substitui só os itens presentes na planilha para aquele mês e preserva os demais. Realizado é a venda líquida do mês. Gap = meta menos realizado; média diária necessária = gap / dias restantes; projeção = realizado / dias decorridos x dias do mês. (Evite: Recarregar a planilha inteira e apagar metas de meses anteriores.) ### Como cada operação entra no faturamento Confirme os códigos do seu ERP com o financeiro. - **Venda direta** → Soma (`valor positivo`) - **Venda futura (entrega posterior)** → Soma, é faturamento válido (`valor positivo`) - **Devolução** → Soma o valor negativo (`valor negativo, data da devolução`) - **Desconto** → Subtrai da bruta (`bruta - descontos`) - **Cupom cancelado** → Subtrai da bruta e sai dos tickets válidos (`bruta - cancelamentos`) - **Remessa, transferência, bonificação** → Fora do faturamento (`CFOP fora da lista de venda`) - **Matriz ou CD sem venda direta** → Sem venda é esperado (`não alertar`) ### Definições | Métrica | Definição | |---|---| | Venda bruta | soma do valor bruto dos cupons e notas de venda, por loja e dia comercial | | Venda líquida | venda bruta menos descontos menos cancelamentos, com venda futura somada e devolução negativa, por loja e dia comercial | | Tickets válidos | contagem distinta de cupons (loja, PDV, número) não cancelados, por loja e dia | | Ticket médio | venda líquida / tickets válidos no recorte pedido; não somável, recalculado em cada agregação | | Devoluções | soma do valor das operações de devolução (negativo), pela data da devolução, por loja e mês | | Taxa de cancelamento | cupons cancelados / cupons totais, por loja e período | | Notas emitidas | contagem distinta do par (loja, número da nota) no período | | % de atingimento | venda líquida do mês / meta do mês, por loja ou produto | | Média diária necessária | (meta menos realizado) / dias restantes do mês | ### Armadilhas - **Dia de venda alta zerado.** Uma consulta converteu para BRT o campo de data gravado como meia-noite UTC e respondeu zero venda para um dia que teve centenas de milhares de reais. Como evitar: Não converta o campo de data comercial; calcule só o hoje em BRT. - **Dia deslocado no BI.** O TIMESTAMP meia-noite UTC enviado ao Postgres do BI foi lido no fuso de São Paulo e todas as vendas apareceram no dia anterior. Como evitar: CAST para DATE antes do destino. - **Margem negativa por nota repetida.** O cruzamento só pelo número da nota casou um carrinho de uma loja com a nota de outra loja, com outro vendedor e outro cliente. Saíram margens negativas e acima de 100%. Como evitar: Chave composta (loja, número da nota) em todo JOIN. - **Matriz sem venda vira alerta.** A matriz ou o CD não tem venda direta e aparecia como loja zerada, levantando suspeita de falha de sincronização. Como evitar: Marque lojas sem venda direta na dimensão de loja e exclua do alerta de zero. - **Duplicação silenciosa.** Uma tabela com grão mensal no nome passou a receber linhas diárias, e uma merge key diferente do grão duplicou registros sem erro. Como evitar: Nome, grão e merge key iguais; teste de unicidade por loja e dia. - **Relatório acumulado do mês.** Algumas fontes exportam o acumulado do mês a cada dia. Somar os arquivos multiplicou a venda. Como evitar: Deduplique pelo dia inteiro e fique com o último arquivo de cada data. ### Teste de aceitação - [ ] Para três lojas e um dia fechado, venda bruta e líquida batem com o fechamento de caixa do ERP (diferença zero). - [ ] A soma das lojas é o total da rede do dia, e a soma dos dias de cada loja é igual ao valor da tabela mensal. - [ ] A tabela diária tem exatamente uma linha por loja e dia. - [ ] "Ontem" consultado às 22h e às 23h59 em São Paulo retorna o mesmo dia comercial e o mesmo valor. - [ ] A contagem de notas distintas por (loja, número) no mês é igual ao total de notas de venda emitidas no ERP. ### Context document ```text Vendas diárias por loja (ERP) - Grão: uma linha por loja, por dia comercial. Detalhe por vendedor e produto na tabela por item de nota. - A data da venda é gravada como meia-noite UTC e representa o dia comercial. Não aplique conversão de fuso nesse campo. Calcule hoje e ontem em America/Sao_Paulo e compare direto. - A nota fiscal é identificada por (loja, número da nota). Nunca faça JOIN só pelo número. - Venda líquida = bruta menos descontos menos cancelamentos. Quando perguntarem "quanto vendeu", responda a líquida e diga que é líquida. - Venda direta e venda futura somam. Devolução vem negativa e soma. Remessa e transferência ficam fora (CFOP de venda). - Ticket médio = venda líquida / cupons válidos (não cancelados). Não some nem tire média de ticket médio. - A loja da venda é a do documento. A loja atual do vendedor não é aplicada ao histórico. - A matriz e o CD não têm venda direta: ausência de venda neles é esperada. - Meta: % atingimento = líquida do mês / meta; média diária necessária = gap / dias restantes. Exceções por cliente: - : códigos de operação de venda ; venda futura = ; devolução = . - : lojas sem venda direta . - : fonte traz hora real em UTC e precisa de conversão para o fuso local. ``` ### Variações - **Uma instância de ERP por loja:** Mesma regra em cada instância, unificada com a coluna de loja antes de agregar. - **Rede em vários países:** Câmbio diário com repetição do último valor em fins de semana e regra de fuso por país. - **Histórico de ajustes:** Guardar versões do diário (SCD tipo 2) para saber quando um dia fechado foi alterado.