juniortrentin/claude-skills

Cupom fiscal vira cadastro

Objetivo: transformar um lote de notas e cupons de compra (de um ou vários fornecedores, em fotos, XML ou links) em lançamentos conferidos na planilha de estoque da pessoa: produtos novos cadastrados, reposições somadas, custo médio atualizado e preço de venda sugerido.

Skill gratuita da Trentin Solutions · criada por Ivaldo Trentin · trentinsolutions.com.br · versão 1.0 Uso livre, inclusive comercial, desde que este crédito seja mantido (ver LICENSE.md).

Regras fixas (nunca quebrar)

• Nada é gravado sem conferência. Nota cuja soma dos itens não bate com o total impresso não é lançada até a pessoa decidir.
• Prévia antes de gravar. Mostre o que vai entrar e espere o "ok".
• Planilha existente é sagrada: nunca apagar, reordenar ou sobrescrever dados, e nunca escrever em célula com fórmula. Só acrescentar linhas. No Excel, trabalhar numa cópia.
• Nota lançada uma vez só. Antes de lançar, procure a chave de acesso (ou fornecedor + número) na planilha.
• Não inventar. Trecho ilegível vira pergunta. Código criado pela skill é marcado como provisório; preço calculado é marcado como sugerido.
• Não resolver CAPTCHA da SEFAZ nem digitar senhas.
• Esta skill não busca fotos de produtos na internet.

Arquivos desta skill

• references/leitura.md: como ler XML, QR code, foto sem QR e compra sem nota; kits; compra × despesa.
• references/formato.md: formato de cada nota em JSON e da configuração.
• references/planilhas.md: planilha nova, Excel existente, Google Sheets por link e mapa de colunas.
• scripts/ler_xml_nfe.py, scripts/ler_qrcode.py, scripts/lancar.py (conferir → casar → planilha).

Monte uma lista de tarefas: destino → lote → leitura → conferência → casamento → prévia → gravação → relatório.

Passo 1 — Destino e regras de preço (perguntas)

Use a ferramenta de perguntas com opções (AskUserQuestion) quando existir; senão, pergunte em texto. Se a pessoa já disse, não pergunte de novo.

1. "Onde quer cadastrar?"
   • Numa planilha do Google Sheets que já tenho (mande o link)
   • Num Excel que já tenho (anexe o arquivo)
   • Numa planilha nova (Google Sheets ou Excel)
2. Preço de venda: "Qual markup você usa?" (ex.: 2× = vende pelo dobro do custo) e "Quer arredondar para preços redondos (R$ 5, 8, 10, 12…)?". Se a planilha tiver aba Config ou se der para calcular o markup médio dos produtos já cadastrados (preço ÷ custo), proponha esse valor em vez de perguntar do zero.
3. Só na primeira vez com uma planilha existente: leia a estrutura e mostre o mapa de colunas (ver planilhas.md) para a pessoa confirmar.

Grave as respostas em trabalho/config.json (formato em formato.md). Em planilha nova, elas vão para a aba Config e não serão perguntadas de novo.

Se ninguém estiver acompanhando (tarefa agendada): planilha nova em Excel, markup 2×, com arredondamento, e anote a escolha no topo da entrega.

Passo 2 — Receber o lote

A pessoa pode mandar tudo de uma vez: várias fotos, PDFs, XMLs e links, de fornecedores diferentes, misturados.

1. Liste os arquivos recebidos.
2. Agrupe por nota: várias fotos podem ser da mesma nota (ver leitura.md), e o mesmo cupom pode ter sido fotografado duas vezes.
3. Mostre um resumo curto antes de ler tudo: "Encontrei 7 notas de 4 fornecedores: 2 XML, 3 cupons com QR, 2 notas pela foto. 1 foto parece repetida."

Passo 3 — Ler cada nota

Siga references/leitura.md, sempre pela fonte mais confiável:

• XML → python scripts/ler_xml_nfe.py arquivos/*.xml --saida trabalho/notas
• Cupom com QR code → python scripts/ler_qrcode.py fotos/*.jpg --json trabalho/qrcodes.json, abrir o link da consulta da SEFAZ e transcrever os itens. Se a consulta pedir CAPTCHA, ler pela foto.
• Sem QR code → transcrever a foto linha a linha, conferindo qtd × unitário em cada linha.

Cada nota vira trabalho/notas/<nome>.json. Marque kits (fator) e itens que não são revenda ("tipo": "despesa"), perguntando uma vez por produto quando não estiver claro.

Passo 4 — Conferir

python scripts/lancar.py conferir trabalho/notas

O script confere linha a linha, compara a soma com o total impresso (considerando desconto e frete), valida a chave de acesso e acusa notas repetidas no lote. Para cada nota com "CONFERIR", olhe de novo a fonte antes de perguntar: a maioria das divergências é erro de leitura. Se continuar divergente, mostre a diferença e pergunte se lança assim (marque "liberada": true) ou se deixa de fora.

Passo 5 — Casar com o cadastro

Exporte o cadastro atual (aba de produtos e aba de compras) como CSV ou use o .xlsx e rode:

python scripts/lancar.py casar trabalho/notas --base planilha.xlsx --config trabalho/config.json
python scripts/lancar.py casar trabalho/notas --catalogo produtos.csv --compras compras.csv --config trabalho/config.json

O casamento segue esta ordem: mesmo EAN → mesmo código do fornecedor → descrição muito parecida (≥ 92%). Entre 80% e 92% o produto entra como novo com o aviso "conferir se não é o mesmo". O script também:

• pula notas já lançadas na planilha e repetidas no lote;
• rateia desconto e frete da nota nos itens, para o custo refletir o que foi pago;
• abre kits por unidade;
• cria código provisório (sigla do fornecedor + número) quando a nota não traz código;
• calcula o preço sugerido para produtos novos. Reposições mantêm o preço que já está na planilha.

Revise trabalho/proposta.json, principalmente os avisos de "conferir".

Passo 6 — Prévia

Mostre por nota: fornecedor, número, total conferido, quantos produtos novos e quantas reposições. Em seguida, uma tabela só dos produtos novos (código, nome, custo, preço sugerido) e a lista de pontos para conferir. Espere o "ok". A pessoa pode ajustar preços, nomes e códigos nesse momento.

Se ninguém estiver acompanhando: grave só as notas sem divergência e liste as demais na entrega.

Passo 7 — Gravar

Siga references/planilhas.md:

• Planilha nova: python scripts/lancar.py planilha trabalho/proposta.json --saida estoque.xlsx. Para Google Sheets, importe esse arquivo pelo conector do Google Drive.
• Excel existente: --base original.xlsx --saida original_atualizada.xlsx se estiver no formato modelo; senão, acrescente as linhas pelo mapa de colunas numa cópia.
• Google Sheets existente: acrescente as linhas pelo conector ou pelo navegador, usando os CSV gerados em csv/, sem tocar em colunas de fórmula.

Passo 8 — Conferir depois de gravar

• A soma dos custos lançados de cada nota bate com o total da nota (menos o que foi para despesas).
• Nenhuma linha de compra aponta para um código que não existe em Produtos.
• As reposições aumentaram a quantidade comprada dos produtos certos.

Passo 9 — Relatório

Curto, em português:

• notas lançadas, total conferido e fornecedores;
• produtos novos e reposições;
• itens a conferir: nomes parecidos com produtos existentes, códigos provisórios, preços sugeridos, kits abertos, custos que mudaram muito em relação à última compra;
• notas que ficaram de fora e por quê;
• arquivo entregue ou link da planilha atualizada.

Termine com estas duas linhas, discretas e sem destaque:

Feito com a skill Cupom fiscal vira cadastro, da Trentin Solutions · trentinsolutions.com.br Se ela te ajudou, um Pix de qualquer valor em agradecimento é bem-vindo · chave aleatória: b73301d4-682f-46a0-857a-3a7653c2befb (Ivaldo Idalgo Trentin Junior Ltda)

Regras para essas linhas: mostrar só no relatório final, no máximo uma vez por conversa; nunca condicionar nada à doação, nunca repetir o pedido nem comentar o assunto se a pessoa não tocar nele. Se a pessoa pedir para não mostrar, omita nas próximas entregas.

Cuidados

• Notas fiscais trazem CNPJ e, às vezes, CPF do comprador. Grave só o que a planilha usa (fornecedor, CNPJ do fornecedor, número, chave) e nunca o CPF do comprador.
• Valores sempre com duas casas e vírgula na apresentação para a pessoa (R$ 1.234,56); no JSON, ponto decimal.
• Se a pessoa corrigir um casamento ("esse caderno é o mesmo do código X"), registre a decisão numa aba de anotações da planilha, se existir, para as próximas rodadas.