Estrutura Básica de um XML de NF-e: Guia Completo

Introdução

O XML é o formato de dados fundamental para a Nota Fiscal Eletrônica. Cada NF-e é representada por um documento XML que segue uma estrutura padronizada definida pela SEFAZ.

Neste guia, vamos detalhar cada parte da estrutura do XML de NF-e, explicando as tags obrigatórias, opcionais e suas finalidades.

Estrutura Geral

<?xml version="1.0" encoding="UTF-8"?>
<NFe xmlns="http://www.portalfiscal.inf.br/nfe">
  <infNFe Id="NFe12345678901234567890123456789012345678901234">
    <ide>...</ide>
    <emit>...</emit>
    <dest>...</dest>
    <det NItem="1">...</det>
    <total>...</total>
    <transp>...</transp>
    <infAdic>...</infAdic>
  </infNFe>
  <Signature>...</Signature>
</NFe>

Tags Principais

<NFe>

Tag raiz que contém todo o documento.

Atributos:

• xmlns: Namespace do XML (obrigatório)

<infNFe>

Informações da NF-e.

Atributos:

• Id: Chave de acesso (44 dígitos) + dígito verificador

<ide>

Identificação da NF-e.

Campos obrigatórios:

• cUF: Código da UF (2 dígitos)
• cNF: Código numérico aleatório (8 dígitos)
• natOp: Natureza da operação
• mod: Modelo do documento (55 para NF-e, 65 para NFC-e)
• serie: Série do documento
• nNF: Número do documento
• tpEmis: Forma de emissão
• dhEmi: Data e hora de emissão
• tpAmb: Ambiente (1=Produção, 2=Homologação)
• finNF: Finalidade (1=Normal, 2=Complementar, 3=Ajuste)
• procEmi: Processo de emissão
• verProc: Versão do processo

<emit>

Dados do emitente.

Campos obrigatórios:

• CNPJ: CNPJ do emitente
• xNome: Razão social
• xFant: Nome fantasia
• enderEmit: Endereço do emitente
• IE: Inscrição Estadual
• CRT: Código de Regime Tributário

<dest>

Dados do destinatário.

Campos obrigatórios (para NF-e):

• CNPJ ou CPF: CNPJ ou CPF do destinatário
• xNome: Razão social ou nome
• enderDest: Endereço do destinatário
• IE: Inscrição Estadual (obrigatório para CNPJ)

<det>

Detalhamento dos produtos/serviços.

Atributos:

• NItem: Número do item (1, 2, 3, ...)

Subtags:

• prod: Dados do produto
• imposto: Dados do imposto

<prod>

Dados do produto.

Campos obrigatórios:

• cProd: Código do produto
• cEAN: Código de barras (GTIN)
• xProd: Descrição do produto
• NCM: Código NCM
• CFOP: Código CFOP
• uCom: Unidade de comercialização
• qCom: Quantidade
• vUnCom: Valor unitário
• vProd: Valor total do produto

<imposto>

Dados dos impostos.

Subtags comuns:

• ICMS: Imposto sobre Circulação de Mercadorias
• IPI: Imposto sobre Produtos Industrializados
• PIS: Programa de Integração Social
• COFINS: Contribuição para Financiamento da Seguridade Social

<total>

Totais da NF-e.

Campos obrigatórios:

• ICMSTot: Totais do ICMS
• vProd: Valor total dos produtos
• vFrete: Valor total do frete
• vSeg: Valor total do seguro
• vDesc: Valor total do desconto
• vII: Valor total do II
• vIPI: Valor total do IPI
• vPIS: Valor total do PIS
• vCOFINS: Valor total do COFINS
• vNF: Valor total da NF-e

<transp>

Dados do transporte.

Campos obrigatórios:

• modFrete: Modalidade do frete (0=Por conta do emitente, 1=Por conta do destinatário)

<infAdic>

Informações adicionais.

Campos comuns:

• infAdFisco: Informações ao fisco
• infCpl: Informações complementares ao contribuinte

Campos Opcionais Importantes

Dados do Destinatário Opcional

Para operações com consumidor final, o destinatário pode ser omitido ou conter apenas o CPF.

Informações de Transporte

• modFrete: Obrigatório apenas para operações com transporte
• transporta: Dados da transportadora
• vol: Dados dos volumes transportados

Dados Adicionais

• infAdFisco: Informações relevantes para o fisco
• infCpl: Informações complementares (até 5000 caracteres)

Validação do XML

Validação de Schema

Sempre valide o XML contra o schema XSD oficial:

# Usando xmllint
xmllint --schema nfe_v4.00.xsd nfe.xml --noout

Validação de Regras de Negócio

Além do schema, valide:

1. Tipos de dados: Datas, valores, CNPJ/CPF
2. Regras de cálculo: Totais, impostos
3. Combinações: CFOP com UF de origem/destino
4. Obrigatoriedades: Campos condicionais

Exemplo Completo

<?xml version="1.0" encoding="UTF-8"?>
<NFe xmlns="http://www.portalfiscal.inf.br/nfe">
  <infNFe Id="NFe352404123456780001955500100000012312345678901234">
    <ide>
      <cUF>35</cUF>
      <cNF>12345678</cNF>
      <natOp>VENDA</natOp>
      <mod>55</mod>
      <serie>1</serie>
      <nNF>123</nNF>
      <tpEmis>1</tpEmis>
      <dhEmi>2024-02-18T10:30:00-03:00</dhEmi>
      <tpAmb>1</tpAmb>
      <finNF>1</finNF>
      <procEmi>0</procEmi>
      <verProc>1.0</verProc>
    </ide>
    <emit>
      <CNPJ>12345678000195</CNPJ>
      <xNome>Empresa Teste LTDA</xNome>
      <enderEmit>
        <xLgr>Rua Teste</xLgr>
        <nro>123</nro>
        <xCpl>Sala 1</xCpl>
        <xBairro>Centro</xBairro>
        <cMun>3550308</cMun>
        <xMun>São Paulo</xMun>
        <UF>SP</UF>
        <CEP>01001000</CEP>
      </enderEmit>
      <IE>123456789012</IE>
      <CRT>1</CRT>
    </emit>
    <dest>
      <CNPJ>98765432000110</CNPJ>
      <xNome>Cliente Teste LTDA</xNome>
      <enderDest>
        <xLgr>Rua Cliente</xLgr>
        <nro>456</nro>
        <xBairro>Jardim</xBairro>
        <cMun>3550308</cMun>
        <xMun>São Paulo</xMun>
        <UF>SP</UF>
        <CEP>01002000</CEP>
      </enderDest>
      <IE>987654321098</IE>
    </dest>
    <det NItem="1">
      <prod>
        <cProd>001</cProd>
        <cEAN>SEM GTIN</cEAN>
        <xProd>Produto Teste</xProd>
        <NCM>12345678</NCM>
        <CFOP>5102</CFOP>
        <uCom>UN</uCom>
        <qCom>10.0000</qCom>
        <vUnCom>100.00</vUnCom>
        <vProd>1000.00</vProd>
      </prod>
      <imposto>
        <ICMS>
          <ICMS00>
            <orig>0</orig>
            <CST>00</CST>
            <vBC>1000.00</vBC>
            <pICMS>18.00</pICMS>
            <vICMS>180.00</vICMS>
          </ICMS00>
        </ICMS>
      </imposto>
    </det>
    <total>
      <ICMSTot>
        <vProd>1000.00</vProd>
        <vFrete>0.00</vFrete>
        <vSeg>0.00</vSeg>
        <vDesc>0.00</vDesc>
        <vII>0.00</vII>
        <vIPI>0.00</vIPI>
        <vPIS>16.50</vPIS>
        <vCOFINS>76.00</vCOFINS>
        <vNF>1000.00</vNF>
      </ICMSTot>
    </total>
    <transp>
      <modFrete>0</modFrete>
    </transp>
  </infNFe>
</NFe>

Boas Práticas

1. Valide sempre: Use nosso Validador XML antes de enviar
2. Mantenha o schema atualizado: Verifique versões na SEFAZ
3. Use codificação UTF-8: Evite problemas de caracteres
4. Documente campos customizados: Use <infAdic> adequadamente
5. Teste em homologação: Nunca envie XMLs de teste para produção

Conclusão

Conhecer a estrutura do XML de NF-e é fundamental para desenvolvedores fiscais. Com essa compreensão, você pode criar, validar e depurar XMLs de forma eficiente.

Use nossas ferramentas para validar, formatar e assinar XMLs, economizando tempo e evitando erros.