Estrutura do XML da NF-e: o mapa dos grupos, do ide ao protocolo
Publicado em · Atualizado em · Por Equipe PegaXML
Resumo
O XML da NF-e é dividido em grupos: identificação (ide), emitente (emit), destinatário (dest), itens (det), totais (total), transporte (transp), cobrança (cobr), pagamento (pag) e informações adicionais (infAdic), todos dentro de infNFe. Depois vêm a assinatura digital e, no arquivo de distribuição, o protocolo de autorização (protNFe). Conhecer esse mapa permite conferir uma nota recebida e localizar a causa de uma rejeição.
O XML em uma frase
O XML da NF-e é um arquivo de texto organizado em grupos aninhados, como pastas dentro de pastas. Cada grupo reúne um tipo de informação, e cada campo tem nome, tamanho e formato definidos no Manual de Orientação do Contribuinte (MOC). A versão do schema em uso é a 4.00, e as notas técnicas acrescentam ou ajustam campos dentro dela.
O arquivo que você recebe: nfeProc
Quando um fornecedor envia "o XML da nota", o arquivo certo tem esta forma geral:
| Nível | Grupo | Conteúdo |
|---|---|---|
| Raiz | nfeProc | Envelope de distribuição |
| 1 | NFe | A nota como foi transmitida |
| 2 | infNFe | Todas as informações da nota, com o atributo Id (chave de acesso) e versao |
| 2 | infNFeSupl | Informações suplementares (usado na NFC-e para o QR Code) |
| 2 | Signature | Assinatura digital do emitente |
| 1 | protNFe | Protocolo de autorização devolvido pela Sefaz |
Um arquivo que tem só NFe, sem protNFe, mostra a nota mas não prova que ela foi autorizada. Para o destinatário, o que vale guardar é o conjunto completo.
Os grupos dentro de infNFe
A ordem abaixo é a ordem do schema. Grupos marcados como opcionais só aparecem quando a operação exige.
| Grupo | Nome | Obrigatório? | O que traz |
|---|---|---|---|
ide | Identificação | Sim | UF, número, série, modelo, datas, tipo de operação, finalidade, ambiente, forma de emissão, notas referenciadas |
emit | Emitente | Sim | CNPJ ou CPF, razão social, endereço, inscrição estadual, regime tributário (CRT) |
avulsa | Nota avulsa | Não | Dados do órgão fiscal, usado só em nota avulsa |
dest | Destinatário | Em regra, sim | CNPJ, CPF ou identificação de estrangeiro, endereço, indicador de contribuinte, IE |
retirada | Local de retirada | Não | Quando a mercadoria sai de endereço diferente do emitente |
entrega | Local de entrega | Não | Quando a entrega é em endereço diferente do destinatário |
autXML | Autorizados a baixar | Não | CNPJ ou CPF de terceiros que podem obter o XML (por exemplo, o contador) |
det | Detalhamento | Sim (1 a 990) | Um grupo por item: produto e impostos |
total | Totais | Sim | Somatórios de produtos, impostos, frete, descontos e valor da nota |
transp | Transporte | Sim | Modalidade do frete, transportadora, veículo, volumes |
cobr | Cobrança | Não | Fatura e duplicatas |
pag | Pagamento | Sim | Formas de pagamento, valores, dados de cartão, troco |
infIntermed | Intermediador | Não | Plataforma de terceiros que intermediou a venda |
infAdic | Informações adicionais | Não | Texto de interesse do fisco e do contribuinte, processos referenciados |
exporta | Exportação | Não | UF e local de embarque |
compra | Compra | Não | Nota de empenho, pedido, contrato |
cana | Cana-de-açúcar | Não | Registro de aquisição de cana |
infRespTec | Responsável técnico | Conforme a UF | Empresa que desenvolveu o sistema emissor |
Cada um desses grupos tem um artigo próprio nesta seção:
- Grupo ide: identificação da NF-e
- Emitente e destinatário no XML
- Itens da NF-e: o grupo det
- Impostos do item e IBS e CBS no XML
- Totais da NF-e
- Transporte na NF-e
- Pagamento e cobrança
- Informações adicionais
O grupo det por dentro
O det é o coração da nota. Cada item tem o atributo nItem (de 1 a 990) e três subgrupos:
prod: código, descrição, NCM, CFOP, unidades, quantidades, valores, frete, seguro e desconto do item;imposto: ICMS, IPI, PIS, Cofins, II, ISSQN quando houver, e os grupos da reforma (IBS, CBS e Imposto Seletivo);infAdProd: texto livre sobre o item.
Há ainda impostoDevol, usado em devoluções para informar o IPI devolvido.
A assinatura e o protocolo
A assinatura digital (Signature) segue o padrão XMLDSig. Ela aponta para o Id do infNFe, ou seja, assina todo o conteúdo da nota. Se um único caractere do infNFe mudar depois da assinatura, a verificação falha. Veja assinatura digital do XML.
O protNFe traz, no subgrupo infProt, os dados da autorização:
| Campo | O que é |
|---|---|
tpAmb | Ambiente (produção ou homologação) |
verAplic | Versão do aplicativo do autorizador |
chNFe | Chave de acesso da nota |
dhRecbto | Data e hora do processamento |
nProt | Número do protocolo |
digVal | Digest da nota recebida, que liga o protocolo àquele XML |
cStat | Código do resultado (100 significa autorizado o uso) |
xMotivo | Descrição do resultado |
Conferir o cStat e o chNFe do protocolo é o jeito mais rápido de saber se um XML recebido corresponde a uma nota autorizada.
Como ler um XML sem ferramentas
- Abra o arquivo no navegador. Ele mostra a árvore de grupos.
- Procure
infNFe Id="NFe...: os 44 dígitos depois de "NFe" são a chave de acesso. - Em
ide, confira número, série, data (dhEmi) e natureza da operação (natOp). - Em
emitedest, confira CNPJ e inscrição estadual das partes. - Percorra cada
dete veja NCM, CFOP e o grupo de ICMS. - Em
total/ICMSTot, comparevNFcom o valor cobrado. - No fim, em
protNFe, confirmecStat100 e o número do protocolo.
Regras de formato que valem para todos os grupos
- Datas e horas seguem o padrão AAAA-MM-DDThh:mm:ss com o fuso horário (por exemplo, -03:00).
- Valores usam ponto como separador decimal e não têm separador de milhar. Cada campo tem um número máximo de casas decimais.
- Campos vazios não devem ser enviados. Um campo opcional sem conteúdo deve ser omitido, e não preenchido com espaços.
- Caracteres especiais como o "e comercial" precisam ser escapados conforme as regras do XML. Texto colado de planilhas e sites é fonte frequente de rejeição de schema.
- Ordem dos campos importa: o schema define a sequência, e um campo fora de ordem invalida o arquivo.
O que muda com as notas técnicas de 2026
O leiaute recebeu muitos campos em 2026 por causa da reforma tributária:
- NT 2025.002-RTC (v1.53, publicada em 30/10/2026): grupos de IBS, CBS e Imposto Seletivo e as regras de validação.
- NT 2026.005 v1.00 (30/10/2026): campos do Simples Nacional na reforma, com produção em 16/11/2026.
- NT 2026.006 v1.01 (30/10/2026): vínculo da nota com a transação de pagamento, de caráter preparatório, com produção em 16/11/2026.
- NT 2026.008 v1.01 (30/10/2026): valor líquido do item e da nota, com produção em 16/11/2026 para parte das regras.
- NT 2026.004 v1.01 (08/06/2026): CNPJ alfanumérico nos schemas, em produção desde 01/07/2026.
Sistemas que leem XML de entrada precisam aceitar esses grupos novos sem quebrar. Uma rotina de importação que trava ao encontrar um campo desconhecido vai falhar com notas de fornecedores que já atualizaram o emissor.
Perguntas frequentes
Qual a versão do leiaute da NF-e?
A versão do schema é a 4.00, indicada no atributo versao do grupo infNFe. Os campos novos, como os da reforma tributária, entram por notas técnicas que alteram esse leiaute sem trocar o número da versão.
Qual a diferença entre o arquivo NFe e o nfeProc?
O NFe é a nota assinada, como foi transmitida. O nfeProc é o arquivo de distribuição, que junta a nota e o protocolo de autorização (protNFe). É o nfeProc que deve ser enviado ao destinatário e guardado.
Quantos itens cabem numa NF-e?
O grupo det pode se repetir até 990 vezes, cada um com o seu número de item (nItem). Acima disso, a operação precisa ser dividida em mais de uma nota.
Posso abrir o XML para conferir?
Sim. É um arquivo de texto e abre em qualquer navegador ou editor. Só não altere nada: qualquer mudança invalida a assinatura digital.