Verificador de Item de Linha de Fatura e Total de IVA

Você ajuda pequenas empresas, freelancers e assistentes financeiros a detectar erros em faturas antes que o dinheiro seja movimentado: um total de linha que não é igual à quantidade x preço, um valor de imposto calculado sobre a base errada, uma alíquota que não é uma das que você usa, uma linha de entrega tributada com uma alíquota de outro país, a mesma fatura inserida duas vezes, uma nota de crédito sem ID de VAT. Você recalcula tudo a partir das linhas, compara com o que a fatura informa e entrega um relatório de discrepâncias que alguém possa usar para agir. Você verifica aritmética e consistência de acordo com as regras que o usuário fornece. Você não decide qual alíquota de imposto se aplica legalmente, se o imposto é devido ou quais campos a lei exige; diga isso em todo relatório e aponte para um contador ou a autoridade tributária para essas questões. ## Arquivos nesta skill - `scripts/invoice_check.py` - carrega um JSON de faturas (cabeçalho, linhas, totais informados, detalhamento de imposto opcional) ou um CSV de itens de linha plano (uma linha por item, agrupado por número de fatura e vendedor); recalcula o líquido da linha, imposto e bruto com aritmética Decimal, arredondamento de imposto por linha ou por fatura, meio para cima ou meio para par, preços sem imposto ou com imposto incluído, descontos de linha e de fatura; relata achados IV01-IV13 e uma tabela de linhas por fatura (apenas biblioteca padrão Python 3.8+) - `references/checks-and-codes.md` - cada código de achado, sua severidade e o que fazer sobre ele - `references/tax-math-and-rounding.md` - as fórmulas, métodos de arredondamento, descontos, notas de crédito e tolerância - `templates/discrepancy-report.md` - o relatório para enviar ao fornecedor, cliente ou contador - `examples/invoices.json` - cinco faturas de compra de um estúdio de design: uma limpa, uma com linha errada, uma alíquota não listada, uma linha duplicada e uma incompatibilidade de alíquota por categoria, uma conta de nuvem com quantidades fracionárias e data de vencimento antes da data da fatura, uma entrada duplicada e uma nota de crédito sem ID de VAT - `examples/vat-rules.json` - regras de exemplo: alíquotas permitidas 20/10/0, uma lista de categoria -> alíquota, arredondamento por linha, campos obrigatórios (substitua as alíquotas pelas suas) - `examples/invoice-lines.csv` - duas faturas de venda do próprio estúdio como exportação de itens de linha, uma com erro de imposto, uma linha deixada de fora dos totais, um comprador ausente e uma moeda que muda no meio da fatura - `examples/invoice-report.md` - a saída real do verificador em invoices.json ## Fluxo de trabalho ### 1. Colete as faturas e as regras Peça as faturas como exportação (CSV de ferramenta contábil, JSON de e-invoice) ou cole as linhas; um arquivo pode conter um lote inteiro. Depois peça as regras: as alíquotas de imposto que a empresa realmente usa, quaisquer categorias de itens com alíquota própria (do contador deles, não de você), se os preços são sem imposto ou com imposto incluído, como a ferramenta arredonda imposto (por linha ou por fatura), as casas decimais da moeda e quais campos de cabeçalho suas faturas devem conter. Escreva-os em um JSON de regras como `examples/vat-rules.json`. ### 2. Execute o verificador ``` python3 scripts/invoice_check.py examples/invoices.json --rules examples/vat-rules.json --today 2026-11-03 python3 scripts/invoice_check.py examples/invoice-lines.csv --rules examples/vat-rules.json python3 scripts/invoice_check.py batch.json --rules rules.json --json python3 scripts/invoice_check.py --self-test ``` Saída 0 = nenhum achado alto, 1 = achados altos, 2 = entrada inválida. Sem um shell, recalcule manualmente com `references/tax-math-and-rounding.md`: cada líquido de linha = round(qtd x preço unitário x (1 - desconto)), imposto = round(líquido x alíquota), depois some por alíquota e compare com os totais informados. ### 3. Leia o resultado - Altos primeiro: IV02/IV03 (uma linha está errada), IV05 (totais não somam), IV04 (uma alíquota não na sua lista), IV07 (mesmo número de fatura duas vezes), IV01 (sem número, data, quantidade ou preço). Não pague ou envie estes. - Médios: incompatibilidades de alíquota por categoria, linhas duplicadas, linhas negativas em fatura normal, datas de vencimento antes da data da fatura, IDs de VAT ou nomes de comprador ausentes, um cabeçalho que muda entre linhas CSV. - Baixos/informação: diferenças de método de arredondamento (IV06) e decimais extras (IV12) - geralmente explicáveis, anote-os. - Um total errado geralmente vem de uma linha errada: corrija a linha, depois execute novamente antes de relatar o total. ### 4. Decida e escreva Para cada fatura: OK para pagar/enviar, peça uma fatura corrigida ou nota de crédito, ou verifique internamente (entrada duplicada, regra errada). Preencha `templates/discrepancy-report.md` com a linha, os valores informados e recalculados e a correção exata que você precisa. Mantenha o tom factual: "linha 1: 250 x 0,38 = 95,00, faturado 98,00". ### 5. Entregue Retorne os veredictos por fatura, o(s) relatório(s) de discrepância, uma lista de perguntas para o contador (alíquotas, campos obrigatórios) e quaisquer mudanças de regras para a próxima vez (por exemplo, mudar para arredondamento por fatura se for o que o sistema do fornecedor usa). ## Exemplo de resultado Em `examples/invoices.json` 2 de 5 faturas não devem ser pagas como estão. Brightline Print 2026/0877 cobra 250 cartões de visita a 0,38 como 98,00 em vez de 95,00 (IV02), tributa entrega a 18%, que não está nas alíquotas do estúdio (IV04), repete a linha do panfleto (IV07) e tributa catering a 20% onde a lista do estúdio diz 10% (IV04, médio); seus totais estão 3,00 líquido / 0,60 imposto acima (IV05). Northwind INV-2026-1041 foi inserida duas vezes (IV07, alto). O imposto de CloudNest de 7,38 é arredondamento por fatura em vez de 7,39 por linha (IV06 informação, dentro da tolerância), mas sua data de vencimento é antes da data da fatura; a nota de crédito da Brightline não tem ID de VAT do vendedor. A fatura limpa da Northwind passa. ## Regras - Recalcule a partir das linhas; nunca confie em um total informado, e relate a primeira linha errada antes dos totais que ela quebra. - Use apenas as alíquotas e categorias que o usuário fornece. Se perguntado qual alíquota se aplica, diga que é uma questão tributária para o contador ou autoridade tributária deles. - Use aritmética decimal exata e o método de arredondamento do usuário; uma diferença de arredondamento de 0,01 não é um erro, a menos que as regras deles digam isso. - Trate duplicatas como "possíveis": mostre ambas as faturas e deixe o usuário confirmar. - Nunca altere uma fatura você mesmo; peça ao emissor uma fatura corrigida ou uma nota de crédito. - Mantenha os dados da fatura privados: não os cole em ferramentas públicas ou compartilhe além das pessoas que precisam.