Tutorial de NF-e de dez anos atrás: como conferir o leiaute que vale hoje

O desenvolvedor seguiu um tutorial de 2011 para gerar a NF-e no sistema da distribuidora. O XML sai bonito, ele troca versao="2.00" por versao="4.00" e envia para homologação. Volta rejeição atrás de rejeição: grupo obrigatório ausente, campo que não existe mais, ordem de elementos inválida. Ele passa dois dias procurando bug no código. A resposta curta: o bug é a idade do tutorial. Um artigo escrito para o leiaute de 2011 não conhece o leiaute 4.00 nem as notas técnicas publicadas depois dele. A fonte da verdade é o Portal Nacional da NF-e, com o manual, os schemas e as notas técnicas em vigor.

Tutorial antigo ainda ajuda a entender o fluxo: montar o XML, assinar, transmitir, consultar o retorno, guardar. O que ele não pode é servir de especificação de campos. Este guia mostra como separar uma coisa da outra.

Isto não substitui o contador nem a consultoria fiscal da empresa. Regras de tributação, CST, CFOP e obrigatoriedade de campos para o seu caso precisam ser conferidas com quem responde por elas.

Por que a nota de hoje não é a nota do tutorial

A NF-e muda por dois caminhos, e o segundo é o que pega quem confia em tutorial:

• Troca de versão do leiaute. A NF-e passou pelas versões 2.00, 3.10 e 4.00. Cada troca muda estrutura, campos e serviços. A 4.00 tornou o grupo de pagamento obrigatório também na NF-e, trouxe campos do Fundo de Combate à Pobreza e mudou os nomes dos serviços web. Um tutorial da 2.00 está duas versões atrás.
• Notas técnicas dentro da mesma versão. A versão 4.00 está em vigor há anos, mas recebeu campos novos por notas técnicas: o grupo do responsável técnico, a indicação de intermediador em vendas por plataforma, ajustes de regras de validação e, com a reforma tributária do consumo, grupos para IBS e CBS. O atributo continua dizendo 4.00, e o XML de 2019 com 4.00 já não é o XML de hoje.

Além disso, cada nota técnica costuma ter data para entrar em homologação e data para valer em produção. Um campo pode ser opcional num mês e obrigatório no seguinte. Quem copia exemplo de blog não acompanha esse calendário.

Como conferir o leiaute que vale hoje

1. Date o material que você está seguindo. Veja o ano do artigo e procure no texto a versão que ele declara. Se o artigo não diz a versão, considere que é a do ano em que foi escrito.
2. Vá ao Portal Nacional da NF-e (www.nfe.fazenda.gov.br) e abra a seção de documentos. Ali estão o Manual de Orientação do Contribuinte, as notas técnicas e o pacote de schemas (XSD) em vigor.
3. Liste as notas técnicas publicadas desde a última vez que o seu emissor foi alinhado. Para cada uma, anote a data de produção e se ela afeta o seu tipo de operação.
4. Baixe o pacote de schemas atual e guarde no repositório, com a data do download. É contra ele que o seu XML será validado.
5. Confira o que o seu XML declara e compare com o pacote baixado.
6. Valide e homologue. Validação local contra o XSD pega estrutura; o ambiente de homologação da Sefaz pega as regras de negócio que o schema não expressa.

Exemplo: descobrindo a versão e validando o XML

Primeiro, a versão declarada nas notas que o sistema está gerando:

$ grep -o 'versao="[^"]*"' nota-35260112345678000195550010000012341000012345.xml
versao="4.00"

Depois, a validação contra o schema baixado do portal. Com xmllint, apontando para o arquivo principal do pacote de schemas da nota (no pacote da 4.00, o nfe_v4.00.xsd, que inclui os demais):

$ xmllint --noout --schema schemas/nfe_v4.00.xsd nota-assinada.xml
nota-assinada.xml:1: element infAdic: Schemas validity error : Element
'{http://www.portalfiscal.inf.br/nfe}infAdic': This element is not expected.
Expected is one of ( {http://www.portalfiscal.inf.br/nfe}cobr, {http://www.portalfiscal.inf.br/nfe}pag ).
nota-assinada.xml fails to validate

A mensagem diz qual elemento apareceu e o que era esperado no lugar. No caso da distribuidora, o XML gerado pelo tutorial não tinha o grupo pag, e o validador apontou isso localmente, em segundos, sem gastar uma tentativa na Sefaz. Repare que o schema da nota espera a assinatura, então valide o XML já assinado, logo antes de transmitir.

Uma ficha de alinhamento no repositório

Para não depender da memória de quem implementou, mantenha um arquivo curto junto do código fiscal:

# docs/fiscal-alinhamento.md
Documento: NF-e modelo 55
Versão do leiaute: 4.00
Pacote de schemas: baixado do Portal Nacional em 2026-09-14
Notas técnicas implementadas (com data de produção):
  - [número e versão da NT] - [data] - [o que mudou para nós]
Biblioteca de emissão: [nome] versão [x.y.z]
Último teste completo em homologação: 2026-09-20
Responsável: [nome]

Quando sair a próxima nota técnica, a pergunta "o que falta implementar" vira uma comparação entre essa ficha e a lista do portal.

O que aproveitar de um tutorial antigo

Não jogue tudo fora. O fluxo continua parecido: gerar a chave de acesso, montar o XML, assinar com o certificado da empresa, transmitir, consultar o recibo ou o retorno síncrono, guardar o XML autorizado com o protocolo. Conceitos como contingência, cancelamento, carta de correção e inutilização de numeração também se mantêm. Use o tutorial para entender o caminho e o portal para cada campo, regra e endereço de serviço. O guia sobre o que acontece antes do XML cobre esse fluxo com o olhar atual, e o de resposta de fórum antiga traz o mesmo método para qualquer outro assunto.

Erros comuns

• Trocar só o número da versão no XML. O atributo diz 4.00, o conteúdo é de outra versão, e a rejeição aponta campo que o tutorial nunca mencionou.
• Misturar exemplos de versões diferentes no mesmo arquivo. Um grupo de um artigo de 2014, outro de 2020: o XML não corresponde a nenhum leiaute.
• Usar endereços de serviço copiados do artigo. Os serviços mudaram de nome e de URL; o endereço certo está na documentação atual de cada autorizador.
• Ignorar a data de produção das notas técnicas. O sistema passa em homologação num mês e é rejeitado em produção no outro, quando o campo vira obrigatório.
• Tratar o XSD como validação completa. Ele pega estrutura e formato; regras como soma de valores e coerência entre campos só aparecem na homologação.
• Decidir tributação pelo exemplo do tutorial. CST, CFOP e alíquota do artigo são da operação de quem escreveu, não da sua empresa.

Checklist

• Você sabe a data e a versão de leiaute do material que está seguindo.
• O pacote de schemas usado na validação foi baixado do Portal Nacional, com data registrada.
• As notas técnicas posteriores ao último alinhamento estão listadas, com data de produção.
• O XML assinado passa no XSD local antes de ir para a Sefaz.
• O fluxo completo foi testado em homologação depois da última mudança.
• As regras de tributação foram conferidas com o contador, não com o tutorial.
• A ficha de alinhamento está no repositório e atualizada.

Abra o XML da última nota autorizada do seu sistema e o pacote de schemas que você usa para validar: os dois são do mesmo ano, e você sabe qual foi a última nota técnica implementada?