← Blog

Cinco armadilhas ao transformar XML de NF-e em planilha

O total da nota não bate com a soma dos itens — e não é erro do arquivo. As cinco coisas que quebram uma conversão de XML de NF-e para Excel, e como conferir.

Pedro Scrignoli3 min
Diagrama mostrando que o total da nota é a soma dos itens mais frete, seguro, outras despesas e substituição tributária, menos o desconto.

Converter o XML de uma NF-e em planilha parece trivial: é um arquivo de texto estruturado, basta ler as tags. Na prática, cinco coisas quebram a conversão — e quase sempre em silêncio, produzindo um número plausível e errado, que é o pior tipo de erro para quem assina relatório.

Abaixo, as cinco, na ordem em que costumam aparecer.

1. O total da nota não é a soma dos itens

Esta é a que mais gera retrabalho, porque parece defeito do arquivo e não é.

O valor total da nota inclui mais coisas do que a soma dos produtos: frete, seguro, outras despesas acessórias, substituição tributária — e desconto, para baixo. Somar o valor de cada item e comparar com o total da nota vai dar diferente na maioria das notas que têm qualquer uma dessas parcelas.

Quem não sabe disso conclui que a nota está errada e vai procurar um problema que não existe. Quem sabe, confere na ordem certa: soma dos itens, mais acessórios, menos desconto, igual ao total.

2. Nem todo XML tem a mesma raiz

O arquivo que você baixa autorizado vem embrulhado: um nó externo que contém a nota e o protocolo de autorização. O arquivo que foi salvo antes da autorização, ou que veio de outro caminho, tem a nota como raiz, sem embrulho.

Código que assume uma das duas formas funciona com metade da sua pasta e falha com a outra metade. O conserto é checar as duas na leitura, não escolher uma.

3. O namespace

O XML da NF-e declara um namespace. Parser que ignora isso procura a tag pelo nome puro, não encontra nada e devolve vazio — sem erro, sem aviso, só uma planilha com menos linhas do que deveria.

É o tipo de falha mais perigosa que existe num processo de conferência: o resultado parece bom. Se a sua conversão trouxe menos notas do que a quantidade de arquivos na pasta, suspeite daqui primeiro.

4. Destinatário é CPF ou CNPJ, nunca os dois

Na nota, o destinatário tem um campo ou outro, dependendo de quem comprou. Código escrito pensando só em venda para empresa procura o CNPJ, não acha, e ou derruba a linha ou grava vazio.

Em quem vende para consumidor final, isso some com uma fatia relevante do faturamento — e some de um jeito que não aparece no total geral, porque as notas continuam lá: só o cliente fica em branco.

5. Precisão decimal e a diferença de centavos

O leiaute aceita mais casas decimais no valor unitário do que a planilha costuma mostrar. A conversão arredonda, a soma de muitos itens acumula a diferença, e no fim do mês aparece um desencontro de alguns centavos que ninguém consegue explicar.

Não é erro de ninguém: é arredondamento. Mas precisa ser previsto, porque conferência que não tolera centavo nenhum vai acusar divergência todo mês.

O ritual de conferência

A regra que eu uso, e que vale para qualquer conversão — feita por ferramenta pronta, por macro ou por código escrito com IA:

O que conferirContra o quê
Quantidade de notas lidasQuantidade de arquivos na pasta
Soma dos totaisUma âncora conhecida: o total que o sistema já te deu
Chaves de acesso distintasQuantidade de notas — se for menor, há arquivo duplicado
Notas canceladasPrecisam estar marcadas, não somadas
Destinatário em brancoDeveria ser zero

A âncora é a parte que não dá para pular. Converter sem ter contra o que comparar é produzir um número bonito que ninguém validou — e número não validado, numa controladoria, não vale nada.

Como eu resolvi isso

Eu escrevi uma ferramenta que faz essa leitura e já devolve a aba de conferência junto: notas, itens, serviços e duplicatas separados, mais uma aba que acusa o que não bateu. Ela roda no navegador e não envia os arquivos para lugar nenhum — tem uma regra interna que proíbe conexão com a internet, e dá para testar desligando o wi-fi.

É gratuita e está em iaparacontroller.com.br/ferramenta.

Sou controller e construo com IA os sistemas que uso no fechamento. Se isto foi útil, a ferramenta de notas é gratuita e roda no seu computador, sem enviar nada para lugar nenhum.