Guia Completo paraExtração de NF-e Brasileira

Todo XML de NF-e brasileira contém mais de 500 campos de dados estruturados — incluindo detalhamentos de impostos por item que determinam sua recuperação de créditos de ICMS e PIS/COFINS. No entanto, a maioria das equipes de AP extrai menos de 20. Este guia é uma referência completa para transformar XML de NF-e em dados de planilha que você realmente pode usar: tabelas de mapeamento de campos, validação de alíquota de ICMS por par de estados, referências de códigos CST e CFOP, tratamento de ICMS-ST e os passos práticos necessários para a transição de esquema duplo de 2026.

Pare de digitar dados — deixe a IA ler por você
Envie uma imagem ou PDF — dados estruturados em 10 segundos
Experimente agora →
Ilustração principal intitulada Extração de NF-e Brasileira: Mapeamento Completo de Campos XML e Guia Fiscal com três ícones vetoriais planos para caminhos de tags XML em português, quatro impostos por item e a chave de acesso de 44 dígitos.

Principais Conclusões

  1. Um XML de NF-e carrega mais de 500 campos de dados estruturados — mas a maioria das equipes de AP extrai menos de 20, deixando a recuperação de créditos de ICMS e o rastreamento de entradas de PIS/COFINS completamente invisíveis.
  2. O gargalo não é a disponibilidade de dados — o XML é validado pelo governo — é que cada item aninha quatro árvores fiscais separadas (ICMS, IPI, PIS, COFINS), cada uma com mais de 10 variantes de código CST que mudam o que um valor zero significa para sua posição de crédito.
  3. Um modelo de extração semântica que mapeia todos os quatro ramos fiscais em uma única passagem transforma cada NF-e de um arquivo XML opaco em uma ferramenta transparente de recuperação de créditos — uma única suposição incorreta de regime em uma fatura de BRL 100.000 custa BRL 9.250 em créditos perdidos.

Extrair dados de uma NF-e brasileira é fundamentalmente diferente de extrair dados de uma nota fiscal comum. Uma nota fiscal padrão em PDF exige OCR ou compreensão de documentos baseada em IA para ler campos de um layout visual. Uma NF-e chega como arquivo XML — legível por máquina por concepção — com uma estrutura validada contra mais de 400 regras automatizadas pela SEFAZ, a autoridade fiscal estadual do Brasil, antes mesmo de a mercadoria que ela descreve poder sair do armazém.

O desafio não é a disponibilidade dos dados. É a complexidade deles. Uma nota fiscal europeia Peppol BIS usa cerca de 100 elementos XML. Uma NF-e no layout versão 4.0 carrega mais de 500 grupos de elementos estruturados distribuídos em vários níveis aninhados, com quatro ramificações separadas de cálculo de tributos por item da linha, cada uma usando seu próprio código de situação tributária, cálculo da base de cálculo, alíquota e regra de crédito. Os dados estão completos — mas extraí-los corretamente exige entender o que cada campo significa e como ele se conecta aos demais.

Este guia foi elaborado como uma referência prática. Se você está configurando um fluxo de extração de NF-e pela primeira vez, comece pelo fluxo passo a passo da seção 2. Se você já tem um pipeline de extração em funcionamento e precisa validar uma alíquota específica de ICMS ou consultar um código CFOP, vá direto para as tabelas de referência das seções 3 a 6. Cada seção pode ser usada de forma independente, mas o valor completo está no panorama geral: saber quais campos extrair, como verificar se estão corretos e o que fazer quando a NF-e chega com um evento de cancelamento ou um indicador de contingência.

Se você é totalmente novo em NF-e, comece pelo nosso guia para iniciantes sobre a Nota Fiscal Eletrônica antes de se aprofundar nos detalhes da extração. Este guia pressupõe que você entende a distinção básica entre DANFE e XML, o processo de autorização da SEFAZ e os quatro tributos principais — e foca em extrair esses dados corretamente.

O Que Torna a Extração de NF-e Diferente da Extração de Notas Fiscais Comuns

Três diferenças estruturais definem como a extração de NF-e funciona e por que uma abordagem padrão de extração de notas fiscais — enviar um PDF, definir colunas, obter dados — resolve apenas parte do problema.

1. A fonte é XML, não um documento visual. A extração de notas fiscais comuns é um problema de leitura: o sistema de IA ou OCR precisa localizar o texto na página, reconhecer qual string é o número da nota e mapeá-la para a coluna correta. A extração de NF-e é um problema de análise e mapeamento: os dados já estão em tags legíveis por máquina, mas a estrutura XML usa nomes de tags em português (<emit> para emitente, <dest> para destinatário, <imposto> para impostos) e hierarquias profundamente aninhadas que variam conforme o regime tributário. O desafio da extração muda de "encontrar os dados" para "mapear o caminho XML correto para cada coluna de saída".

2. A estrutura tributária é multidimensional. Um único item de NF-e carrega até quatro cálculos tributários independentes — ICMS (estadual, com mais de 10 variantes dependendo do código CST), IPI (imposto federal sobre produtos industrializados, dependente do produto), PIS e COFINS (contribuições sociais federais). Cada tributo tem sua própria base de cálculo, alíquota, CST (código de situação tributária) e regras de elegibilidade a crédito. Diferente de uma nota fiscal de IVA da UE, em que uma única alíquota se aplica a todo o item, um item de NF-e contém subgrupos separados de <ICMS>, <IPI>, <PIS> e <COFINS>, cada um potencialmente com bases tributáveis diferentes. Extrair apenas os totais deixa de fora o detalhe que determina se cada crédito tributário foi calculado corretamente.

3. O fluxo de extração deve considerar eventos após a emissão. Uma NF-e pode ser cancelada em até 24 horas. Pode receber uma Carta de Correção (CC-e) que altera campos específicos. Pode ser emitida em modos de contingência se a SEFAZ estiver inacessível. Ela dispara eventos do lado do destinatário chamados manifestação do destinatário — uma obrigação legal do comprador de confirmar o recebimento, reconhecer a transação ou rejeitá-la. Um pipeline de extração completo deve lidar com essas mudanças orientadas por eventos, não apenas extrair o XML inicial e considerar concluído. Para um olhar mais aprofundado sobre como as regras de cancelamento e contingência afetam os fluxos de contas a pagar, veja nossa análise da complexidade do processamento de NF-e.

Essas três diferenças significam que a extração de NF-e não é "extração de notas fiscais com nomes de campos em português". É uma categoria própria — mais próxima da análise de EDI do que do OCR de documentos, mas com uma complexidade tributária que supera a maioria dos padrões EDI em uma ordem de magnitude. Para conhecer o outro grande sistema latino-americano de notas fiscais eletrônicas com suas próprias complexidades estruturais, veja nosso guia completo de extração de CFDI mexicano.

O Fluxo Completo de Extração de NF-e: Passo a Passo

Um fluxo de extração de NF-e de ponta a ponta, seja manual, baseado em script ou orientado por IA, segue a mesma sequência lógica. Cada etapa produz uma saída específica que alimenta a próxima.

1

Colete o XML — não apenas o DANFE

Toda transação de NF-e gera um arquivo XML. Se o fornecedor enviou apenas o DANFE, use a chave de acesso de 44 dígitos impressa no DANFE para baixar o XML completo no portal da SEFAZ do estado emissor. A lei brasileira exige que os fornecedores forneçam o XML, e você precisa dele tanto para a extração quanto para o arquivo obrigatório de cinco anos. Armazene os XMLs originais exatamente como recebidos — modificá-los invalida a assinatura digital e quebra sua trilha de auditoria.

2

Verifique a Chave de Acesso e o Status na SEFAZ

Antes de processar qualquer dado, confirme que a NF-e é válida. Extraia a chave de acesso de 44 dígitos do elemento <chNFe> e consulte o web service ou portal da SEFAZ. Verifique se o status é "Autorizada" — não "Cancelada" ou "Denegada". Esta etapa deve ser automatizada em qualquer script ou fluxo de trabalho baseado em ferramentas, pois uma NF-e pode ser cancelada em até 24 horas após a emissão. Verificar a chave de acesso no momento da extração evita que você processe um documento que não tem mais validade legal.

3

Analise a Estrutura do XML em Grupos

Um XML de NF-e tem uma estrutura de nível superior previsível. Os principais grupos de elementos são: <ide> (identificação do documento), <emit> (emitente/fornecedor), <dest> (destinatário/você), <det> (itens da linha — repetidos por produto), <total> (totais da nota — um por tipo de tributo), <transp> (transporte/frete), <cobr> (pagamento/cobrança) e <infAdic> (informações adicionais). Seu script ou ferramenta de extração deve analisar cada grupo de forma independente e depois unir os resultados no nível do item da linha.

4

Mapeie os Campos para as Colunas de Saída Usando a Tabela de Referência

Para cada campo que você precisa na sua planilha ou arquivo de importação do ERP, identifique o caminho exato no XML, o tipo de dado esperado e a transformação necessária (datas para o formato ISO, valores para decimais com duas casas decimais, strings de CNPJ com preenchimento de zeros preservado). Use a referência de mapeamento de campos na seção 3 abaixo. A distinção crítica nesta etapa: separe os campos de nível de cabeçalho (extraídos uma vez por NF-e) dos campos de item da linha (extraídos para cada elemento <det>). Sua estrutura de saída deve refletir isso: uma tabela de cabeçalho com uma linha por nota, e uma tabela de itens da linha com várias linhas por nota.

5

Valide os cálculos tributários com dados de referência

Os XMLs de NF-e contêm os cálculos tributários do fornecedor, não os seus. Seu fluxo de extração deve incluir verificações de validação: a alíquota de ICMS corresponde à alíquota correta para o par de estados origem-destino? A alíquota de IPI corresponde à faixa de NCM do produto? O código CST é consistente com o tipo de transação descrito pelo CFOP? A Seção 4 deste guia traz as tabelas de referência necessárias para essas verificações. Sinalize qualquer divergência para revisão — não importe silenciosamente dados tributários inconsistentes para o seu ERP.

6

Exporte, arquive e monitore eventos

Exporte os dados estruturados para o seu ERP ou planilha. Arquive tanto o XML original (exatamente como recebido, sem modificações) quanto a saída da extração. Depois, configure um processo de monitoramento: consulte novamente o status na SEFAZ dos documentos NF-e extraídos 48 horas após a extração para capturar cancelamentos ou eventos de correção. Um fornecedor pode cancelar uma NF-e em até 24 horas sem avisar você. Se você extraiu dados de uma NF-e agora cancelada e os lançou no seu ERP, há um registro de estorno a criar. Ferramentas automatizadas podem cuidar dessa etapa de monitoramento — equipes humanas costumam esquecê-la.

Referência de Mapeamento de Campos do XML da NF-e

As tabelas a seguir mapeiam os caminhos essenciais do XML da NF-e para colunas da planilha. Os campos são classificados por criticidade: Crítico (necessário para o processamento básico), Importante (necessário para validação fiscal e recuperação de créditos) e Nicho (necessário para cenários específicos, como alfândega ou declarações do SPED). Todos os caminhos são relativos ao namespace padrão do XML da NF-e.

Campos do Cabeçalho (Uma Linha por Nota Fiscal)

Coluna de SaídaCaminho XML (relativo a <nfeProc>/<NFe>/<infNFe>)Valor de ExemploCriticidade
Chave de Acesso@Id (remover o prefixo "NFe") ou <ide>/<cNF> combinado com o prefixo35200600012345000106550010000012341012345678Crítico
Número da NF-e<ide>/<nNF>1234Crítico
Série da NF-e<ide>/<serie>1Crítico
Data de Emissão<ide>/<dhEmi>2026-06-15T14:30:00-03:00Crítico
Protocolo de Autorização da SEFAZ<ide>/<nProt>135260001234567Crítico
Tipo de Emissão<ide>/<tpEmis>1 (normal), 2-6 (contingência)Importante
CNPJ do Fornecedor<emit>/<CNPJ>00.000.000/0001-91Crítico
Razão Social do Fornecedor<emit>/<xNome>Fornecedor Exemplo LtdaCrítico
Inscrição Estadual do Fornecedor<emit>/<IE>123.456.789.110Importante
Estado do Fornecedor (Código IBGE)<emit>/<enderEmit>/<cUF>35 (São Paulo), 33 (Rio de Janeiro)Crítico
CNPJ do Comprador<dest>/<CNPJ>00.000.000/0002-82Crítico
Estado do Comprador (Código IBGE)<dest>/<enderDest>/<cUF>31 (Minas Gerais)Crítico
Valor Total da NF-e<total>/<ICMSTot>/<vNF>12500.00Crítico
Valor Total do ICMS<total>/<ICMSTot>/<vICMS>1500.00Importante
Valor Total do ICMS-ST<total>/<ICMSTot>/<vST>450.00Importante
Valor Total do IPI<total>/<ICMSTot>/<vIPI>625.00Importante
Valor Total do PIS<total>/<ICMSTot>/<vPIS>206.25Importante
Valor Total do COFINS<total>/<ICMSTot>/<vCOFINS>950.00Importante
Valor do Desconto<total>/<ICMSTot>/<vDesc>250.00Nicho
Valor do Frete<total>/<ICMSTot>/<vFrete>350.00Importante
Valor do Seguro<total>/<ICMSTot>/<vSeg>50.00Nicho
Informações de Pagamento/Cobrança<cobr>/<dup>/<dVenc> (data de vencimento) e <vDup> (valor)2026-07-15 / 12500.00Importante
CFOP (no nível do cabeçalho — geralmente do primeiro item da linha)<det>[1]/<prod>/<CFOP>2101Importante
Natureza da Operação<ide>/<natOp>Venda de mercadoria adquirida de terceirosNicho

Campos dos Itens da Linha (Uma Linha por Item do Produto)

Cada elemento <det> dentro de <infNFe> representa um item do produto. O atributo nItem fornece o número da linha (indexado em 1). Os campos a seguir se repetem para cada <det>:

Coluna de SaídaCaminho XML (por <det>)Criticidade
Número da Linha@nItemCrítico
Código do Produto (Código Interno do Fornecedor)<prod>/<cProd>Importante
Descrição do Produto<prod>/<xProd>Crítico
Código NCM (classificação de produto com 8 dígitos)<prod>/<NCM>Crítico
Código CFOP (operação fiscal com 4 dígitos)<prod>/<CFOP>Crítico
CST — Código de Situação Tributária do ICMS<imposto>/<ICMS>/<ICMS00>/<CST> (varia por subgrupo)Crítico
Quantidade<prod>/<qCom>Crítico
Preço Unitário<prod>/<vUnCom>Crítico
Total da Linha (Bruto)<prod>/<vProd>Crítico
Base de Cálculo do ICMS (BC ICMS)<imposto>/<ICMS>/<ICMS00>/<vBC>Importante
Alíquota do ICMS (%)<imposto>/<ICMS>/<ICMS00>/<pICMS>Importante
Valor do ICMS<imposto>/<ICMS>/<ICMS00>/<vICMS>Crítico
Base de Cálculo do ICMS-ST (se aplicável)<imposto>/<ICMS>/<ICMSST>/<vBCST>Importante
Valor do ICMS-ST (se aplicável)<imposto>/<ICMS>/<ICMSST>/<vICMSST>Importante
Base de Cálculo do IPI<imposto>/<IPI>/<IPITrib>/<vBC>Importante
Alíquota de IPI (%)<imposto>/<IPI>/<IPITrib>/<pIPI>Importante
Valor do IPI<imposto>/<IPI>/<IPITrib>/<vIPI>Importante
Base de Cálculo do PIS<imposto>/<PIS>/<PISAliq>/<vBC>Importante
Alíquota de PIS (%)<imposto>/<PIS>/<PISAliq>/<pPIS>Importante
Valor do PIS<imposto>/<PIS>/<PISAliq>/<vPIS>Importante
Base de Cálculo do COFINS<imposto>/<COFINS>/<COFINSAliq>/<vBC>Importante
Alíquota de COFINS (%)<imposto>/<COFINS>/<COFINSAliq>/<pCOFINS>Importante
Valor do COFINS<imposto>/<COFINS>/<COFINSAliq>/<vCOFINS>Importante
UOM (Unidade de Medida)<prod>/<uCom>Nicho
GTIN/EAN (Código de Barras do Produto)<prod>/<cEAN>Nicho
EX TIPI (código de isenção de IPI)<prod>/<EXTIPI>Nicho

Nota importante sobre os subgrupos do ICMS: O caminho do ICMS no XML dentro de <imposto> varia conforme o código CST. Um ICMS tributado normalmente usa o subgrupo <ICMS00>. Outros códigos CST usam <ICMS10> (tributado + ST), <ICMS20> (base reduzida), <ICMS30> (ST isento do ICMS regular), <ICMS40> (isento), <ICMS51> (diferido), <ICMS60> (já recolhido), <ICMS90> (outros), <ICMSPart> (DIFAL — diferencial de alíquota interestadual) e <ICMSST> (substituição tributária). Seu mapeamento de extração deve lidar com todas essas variantes, não apenas com <ICMS00>.

Validação de Impostos: Como Verificar os Números Extraídos

Um XML de NF-e carrega os próprios cálculos de impostos do fornecedor, que podem estar incorretos. A SEFAZ valida que a estrutura do XML está completa e que a aritmética básica é consistente, mas não verifica se a alíquota correta de ICMS foi usada para o par origem-destino, nem se a alíquota de IPI corresponde à alíquota oficial da TIPI para o código NCM. Isso é sua responsabilidade como comprador — e é a fonte mais comum de pagamentos indevidos recuperáveis no AP brasileiro.

Validação da Alíquota Interestadual de ICMS por Par de Estados

A alíquota de ICMS em uma operação interestadual depende do estado de origem (de onde o fornecedor envia) e do estado de destino (onde sua empresa está localizada). Use esta tabela para validar se a alíquota de ICMS na NF-e corresponde à alíquota correta para o par de estados:

Estado de OrigemEstado de DestinoAlíquota Padrão de ICMSObservação
Qualquer estado do Sul/Sudeste (SP, RJ, MG, ES, PR, SC, RS)Qualquer estado do Sul/Sudeste12%Alíquota interestadual padrão dentro da região Sul/Sudeste
Qualquer estado do Sul/SudesteQualquer estado do Norte/Nordeste/Centro-Oeste7%Alíquota reduzida para regiões menos desenvolvidas (Art. 2º, I, LC 87/96)
Qualquer estado do Norte/Nordeste/Centro-OesteQualquer estado (incluindo Sul/Sudeste)12%Alíquota padrão de saída das regiões em desenvolvimento
Qualquer estadoQualquer estado (mercadorias importadas com >40% de conteúdo estrangeiro)4%Resolução Senado 13/2012 — aplica-se a produtos com mais de 40% de conteúdo importado
Estado fornecedor = estado receptor (interestadual)Mesmo estado17%–22%Varia por estado: SP=18%, RJ=20%, MG=18%, PR=19%, RS=17%, etc.
Gráfico de barras intitulado Verifique a Alíquota de ICMS em Relação ao Par de Estados mostrando 4% para mercadorias com mais de 40% importadas, 7% do Sudeste para o Norte/Nordeste, 12% do Sudeste para o Sudeste e 18% dentro de São Paulo.

Se a alíquota de ICMS na NF-e não corresponder à alíquota esperada para o par origem-destino (de <emit>/<enderEmit>/<cUF> para <dest>/<enderDest>/<cUF>), sinalize o documento para revisão. Divergências de alíquota são um dos erros mais comuns em notas fiscais de fornecedores brasileiros e podem levar a cálculos incorretos de crédito tributário.

Códigos CST: os Códigos de Situação Tributária que mudam tudo

O CST (Código da Situação Tributária) é um código de três dígitos que informa como um tributo foi aplicado, não apenas a alíquota. Todo cálculo de ICMS, IPI, PIS e COFINS em uma NF-e carrega seu próprio CST. O primeiro dígito do CST indica a origem do regime tributário (0=nacional, 1=estrangeiro, 2=estrangeiro com conteúdo nacional — varia conforme o tributo). Para o ICMS especificamente, o CST determina se o ICMS é tributado, isento, diferido, substituído (ST) ou recolhido por regime especial. Os códigos CST de ICMS de três dígitos seguem uma lógica específica:

CST (ICMS)SignificadoCrédito disponível?Impacto na AP
00Tributado — alíquota integral de ICMS se aplicaSimCompra padrão. Extraia vBC, pICMS, vICMS normalmente.
10Tributado + Substituição Tributária (ICMS-ST)Sim (apenas ICMS regular)Dois valores de ICMS: regular e ST. Extraia ambos — o valor de ST não é seu crédito.
20Tributado com base de cálculo reduzidaSim (proporcional)A base tributável é reduzida (ex.: em 1/3). Os campos vBC refletem a base reduzida.
30Isento do ICMS regular + ST se aplicaNãoNenhum ICMS regular a extrair. Existem apenas campos de ST. Seu custo inclui o valor de ST.
40Isento — nenhum ICMS cobradoNãoNenhum valor de ICMS. O total da linha permanece o mesmo, mas nenhum crédito é gerado.
41Isento — não tributávelNãoSemelhante ao CST 40. Nenhum ICMS a extrair ou creditar.
51Diferido — pagamento do ICMS adiado para etapa posteriorDependeExtraia vBC e pICMS mesmo se vICMS for zero — o diferimento afeta eventos futuros.
60ICMS já recolhido pelo fornecedor (ou elo anterior da cadeia)NãoComum em combustível, energia, telecom. O ICMS não é um item da linha — foi pago anteriormente na cadeia.
70Tributado com base reduzida + STSim (proporcional)Híbrido: base reduzida no ICMS regular + valor de ST separado. Ambos devem ser extraídos.
90Outros — regime especial não coberto acimaDependeRevise manualmente. O <infAdic> da NF-e deve explicar o regime.

Seu fluxo de extração deve sempre capturar o código CST junto com o valor do tributo — um "ICMS zero" com CST 40 (isento) é uma situação muito diferente de um "ICMS zero" com CST 00 (erro). O CST determina se o zero é um tratamento fiscal legítimo ou uma lacuna de dados que você precisa investigar.

Validação de IPI, PIS e COFINS

Verificação do IPI: A alíquota de IPI é determinada pelo código NCM do produto. O Brasil publica a TIPI (Tabela de Incidência do IPI), uma tabela abrangente de alíquotas que mapeia cada código NCM para uma alíquota de IPI. Embora você não possa manter a planilha completa da TIPI internamente (ela contém milhares de entradas e é atualizada periodicamente pela Receita Federal), você pode fazer verificações pontuais em itens de alto valor: extraia o NCM, consulte a faixa de alíquota de IPI na TIPI e confirme se o campo pIPI está dentro da faixa esperada. O código CST do IPI também importa — CST 50 significa que o IPI é isento, enquanto 00 significa que é tributado.

Verificação de PIS e COFINS: Essas contribuições federais se aplicam no regime cumulativo ou não cumulativo. O regime é determinado pela classificação tributária do fornecedor e rege tanto a alíquota quanto a disponibilidade de créditos para você como comprador:

RegimeAlíquota de PISAlíquota de COFINSCombinadaComprador recebe créditos?
Não Cumulativo (Lucro Real)1,65%7,6%9,25%Sim — o comprador pode creditar PIS e COFINS contra suas próprias contribuições
Cumulativo (Lucro Presumido)0,65%3,0%3,65%Não — nenhum crédito de entrada é gerado no regime cumulativo

Se a alíquota de PIS na NF-e for 1,65% e a de COFINS for 7,6%, o fornecedor está no regime não cumulativo e você pode aproveitar créditos de entrada de PIS/COFINS. Se as alíquotas forem 0,65% e 3,0%, nenhum crédito está disponível. O CST do fornecedor (normalmente 01 = não cumulativo ou 02 = cumulativo) confirma o regime. Extrair e validar essas alíquotas afeta diretamente sua posição tributária recuperável.

Regra prática de validação: Para cada NF-e, extraia a alíquota de PIS e a alíquota de COFINS no nível do item. Se a alíquota combinada for 9,25%, sinalize para rastreamento de créditos. Se for 3,65%, confirme o regime do fornecedor e observe que nenhum crédito de PIS/COFINS se aplica. Uma única suposição incorreta de regime em uma fatura de BRL 100.000 representa BRL 9.250 em créditos perdidos — ou BRL 5.600 em créditos reivindicados incorretamente.

Substituição Tributária do ICMS (ICMS-ST): O Mecanismo Que Você Não Pode Ignorar

O ICMS-ST (Substituição Tributária) é um mecanismo em que a autoridade fiscal atribui a responsabilidade pela cobrança do ICMS de toda a cadeia de fornecimento ao primeiro elo — normalmente o fabricante ou importador. Em vez de cada comprador da cadeia (fabricante → distribuidor → varejista) pagar ICMS sobre sua própria margem, o fabricante recolhe o ICMS sobre o preço de venda final presumido ao consumidor no início da cadeia. Essa "substituição" do contribuinte desloca o ponto de cobrança do imposto para montante.

Comparação em duas colunas intitulada ICMS-ST É um Custo, Não um Crédito de Entrada, com um selo de check verde para o ICMS regular recuperável (CST 00) e um selo de X âmbar para o ICMS-ST (CST 10 ou CST 30) que nunca pode ser recuperado.

Para as equipes de Contas a Pagar que processam documentos NF-e, o ICMS-ST aparece em dois cenários:

Cenário 1 — Sua empresa está no meio da cadeia (comprando da parte substituída). Você compra mercadorias de um distribuidor que já as adquiriu sob ST do fabricante. A NF-e traz o ICMS regular (CST 00, tributado normalmente) e um valor separado de ICMS-ST (CST 10, sob <ICMS10> ou <ICMSST>). Sua extração deve capturar ambos: o ICMS regular é seu crédito de entrada; o ICMS-ST não é um crédito — é um encargo que já inclui o custo e que já foi recolhido à SEFAZ pelo fornecedor a montante. Você não pode recuperá-lo.

Cenário 2 — Sua empresa é o elo final (varejista ou consumidor direto). Você compra de um fornecedor que é a parte substituída pelo ST. A NF-e traz um único valor de ICMS-ST (CST 30 — isento do ICMS regular, aplica-se o ST). Todo o custo de ICMS da cadeia está embutido nesse único valor. Sua extração captura apenas os campos de ST, e nenhum crédito de ICMS regular está disponível.

Para distinguir entre esses dois cenários no seu fluxo de extração, verifique o código CST: CST 10 = ICMS regular + ST (você obtém créditos parciais), CST 30 = somente ST (sem créditos de ICMS regular). O caminho XML do ICMS-ST usa um subgrupo separado: <imposto>/<ICMS>/<ICMSST>/<vICMSST> para o valor do ST e <vBCST> para a base de cálculo do ST. Extraia-os como colunas separadas do ICMS regular — nunca os some em um único campo "ICMS total". Algumas equipes de Contas a Pagar somam o ICMS regular e o ST e lançam um valor combinado, o que superestima sua posição de crédito de ICMS e gera apontamentos em auditorias.

CFOP e NCM: extraindo os códigos de classificação que controlam a conformidade

Cada item de uma NF-e carrega dois códigos que, juntos, determinam o tratamento tributário daquele produto. Eles não são metadados opcionais — são as entradas da sua lógica de determinação de impostos.

Referência de códigos CFOP (classificação pelo primeiro dígito)

O CFOP (Código Fiscal de Operações e Prestações) é um código de quatro dígitos em que o primeiro dígito indica a direção e a natureza da operação. No processamento de NF-e de entrada (lado da compra), os códigos CFOP que você encontrará com mais frequência estão nas faixas 1xxx, 2xxx e 3xxx:

Primeiro dígitoClassificaçãoCódigos de entrada comuns
1Entrada — dentro do mesmo estado (interestadual não; operação interna)1102 = compra para revenda, 1101 = compra para industrialização, 1116 = compra para uso/consumo
2Entrada — de outro estado (interestadual)2101 = compra para industrialização, 2102 = compra para revenda, 2116 = compra para uso/consumo
3Entrada — do exterior (importação)3101 = importação para industrialização, 3102 = importação para revenda, 3126 = importação para uso/consumo
5Saída (venda) — raramente aparece em NF-e do lado da compra—
6Saída interestadual — relevante apenas se você emitir NF-e—
7Saída para o exterior — operações de exportação—

Por que o CFOP importa para a extração: o código CFOP determina quais regras de ICMS se aplicam à operação. Um CFOP iniciado por 1 (operação interna) significa que a alíquota de ICMS deve ser a alíquota interna do estado do fornecedor (17-22%), e não uma alíquota interestadual. Um CFOP iniciado por 2 (interestadual) significa que a alíquota deve corresponder à tabela de alíquotas interestaduais acima. Se o CFOP e a alíquota de ICMS forem inconsistentes — por exemplo, CFOP 1102 (operação interna) com alíquota de ICMS de 12% (que é uma alíquota interestadual) — a nota fiscal tem uma divergência estrutural que precisa ser corrigida. Seu fluxo de extração deve sinalizar isso automaticamente.

Código NCM: A Classificação de Produto Que Determina IPI e Impostos de Importação

NCM (Nomenclatura Comum do Mercosul) é um código de classificação de produto de oito dígitos baseado no Sistema Harmonizado (SH) com dois dígitos adicionais específicos do Mercosul. Formato: NNNN.NN.NN (onde os 6 primeiros dígitos são o código SH). O código NCM determina:

  • Alíquota de IPI: Mapeada pela tabela TIPI. Produtos com NCM iniciado em capítulos específicos enfrentam alíquotas de IPI maiores ou menores.
  • Aplicabilidade do ICMS-ST: Certos capítulos de NCM estão sujeitos a protocolos obrigatórios de ICMS-ST (convênios) entre estados.
  • Imposto de importação (II) para compras internacionais.
  • Alíquota do imposto substituto (ex.: cálculos simplificados de ICMS-ST por protocolo CONFAZ).

Para extração, o NCM deve sempre ser capturado como campo de texto, preservando os zeros à esquerda. Nunca o converta em número — o NCM 8471.30.00 (equipamento de informática) perderia sua estrutura inicial se tratado numericamente. O NCM também serve como chave primária para consultar alíquotas de IPI se seu fluxo de trabalho incluir validação automatizada de alíquotas.

Tratando Eventos Especiais da NF-e no Seu Fluxo de Extração

Uma NF-e não é um documento estático. Ela pode ser modificada, cancelada ou reemitida por meio de uma série de eventos legalmente definidos. Um fluxo de extração completo deve considerar esses eventos, pois eles podem alterar os dados que você já extraiu.

Cancelamento. O emitente pode cancelar uma NF-e em até 24 horas após o recebimento do protocolo de autorização, desde que a mercadoria não tenha circulado fisicamente. O evento de cancelamento é registrado na SEFAZ e vinculado à mesma chave de acesso. Após 24 horas, o cancelamento não é mais possível — o emitente deve solicitar um cancelamento especial junto à autoridade fiscal ou emitir uma nota de crédito (NF-e de devolução). Para seu fluxo de extração: a validação essencial é verificar o status da NF-e no momento da extração e novamente antes do pagamento. Se você processa documentos NF-e programaticamente, inclua uma etapa de verificação de status que consulte o web service ConsNFeDest da SEFAZ para obter a lista de status das NF-e recebidas pelo comprador.

Carta de Correção (CC-e). Se o fornecedor precisar corrigir um campo em uma NF-e já autorizada (ex.: corrigir a descrição do produto, corrigir o endereço de entrega, atualizar a data de vencimento do pagamento), ele emite uma CC-e — uma carta de correção eletrônica vinculada à chave de acesso da NF-e. A CC-e não substitui o XML; ela altera campos específicos. Seu fluxo de extração deve, ao processar documentos NF-e, consultar se existem eventos de CC-e para aquela chave de acesso. O processamento em lote do ImageToTable.ai inclui a opção de verificar eventos de correção nos documentos extraídos — porque se o fornecedor corrigiu a data de vencimento via CC-e e seu fluxo de trabalho usou a data de vencimento do XML original, você está pagando no prazo errado.

Modos de contingência. Se a SEFAZ estiver inacessível, os fornecedores podem emitir NF-e em modo de contingência. O tipo de emissão (<ide>/<tpEmis>) indica o método de contingência: 2 = FS-DA (DANFE digitado), 3 = EPEC (contingência pré-evento), 4 = DPEC (contingência eletrônica), 5 = FS-IA (contingência em formulário), 6 = SVC (SEFAZ Virtual de Contingência — um servidor de autorização de backup). No modo de contingência, a NF-e pode não ter o protocolo completo de autorização da SEFAZ no momento da extração. Seu fluxo de trabalho deve sinalizar documentos emitidos em contingência para acompanhamento: assim que o sistema se recuperar, o fornecedor transmitirá a NF-e completa, e você deve recuperar o XML final e reextrair se algum campo tiver mudado.

Manifestação do Destinatário. Este não é um evento do fornecedor — é uma obrigação do comprador. Pela lei brasileira, o comprador de mercadorias deve registrar a resposta do seu evento no portal da SEFAZ dentro de prazos específicos: confirmar o recebimento em até 10 dias da emissão e aceitar ou rejeitar a transação. Esse processo é chamado de manifestação do destinatário e é gerenciado pela plataforma DF-e da SEFAZ. Embora a manifestação seja uma etapa de conformidade separada da extração, seu fluxo de extração deve registrar a chave de acesso de cada NF-e processada em um sistema de acompanhamento de manifestação, para que a conformidade possa registrar os eventos exigidos dentro do prazo. Se você não registrar a manifestação, a SEFAZ presume que a transação não foi reconhecida, o que pode bloquear a emissão de NF-e futuras por parte desse fornecedor.

Para um olhar mais aprofundado sobre esses tipos de evento e como eles afetam as operações de AP, veja nossa análise da complexidade do processamento de NF-e.

Métodos de Extração Comparados: Qual Abordagem se Adequa ao Seu Volume

Existem quatro abordagens comuns para extrair dados de NF-e, e a correta depende do seu volume, dos seus recursos técnicos e se você precisa de detalhamento tributário por item ou apenas dos totais do cabeçalho.

MétodoComo FuncionaCampos ExtraídosVolume IdealPrincipal Limitação
Digitação Manual do DANFEO operador lê o DANFE impresso e digita no Excel ou ERP~20 campos do cabeçalho, sem detalhamento tributário por item< 10 por mêsPerde 90% dos dados, incluindo todos os detalhamentos tributários; alta taxa de erro
Scripts XML (Python, Power Query)Um script personalizado interpreta o XML da NF-e e extrai os campos para CSV/ExcelTodos os campos do cabeçalho + itens; exige mapeamento XPath predefinido10–100 por mêsExige conhecimento de programação; quebra quando o schema é atualizado (schema duplo em 2026); sem validação tributária integrada
Módulo de Localização do ERP (SAP/Oracle/Dynamics)Módulo de ERP específico para o Brasil que recebe o XML da NF-e e lança automaticamente no razãoConjunto completo de campos, mapeamento de contas tributárias, integração com o SPED100+ por mêsCusto elevado (licenciamento + implementação); só funciona se você tiver esse ERP; mapeamento de schema rígido
Extração com IAFaça upload de PDFs de DANFE ou XMLs de NF-e; a IA interpreta e mapeia para colunas definidas pelo usuárioTodos os campos visíveis no DANFE a partir de PDFs; campos completos a partir do XML10–500+ por mêsA interpretação de XML exige que a ferramenta aceite entrada de dados estruturados (não apenas PDFs visuais)

A distinção crítica para a NF-e é se o método de extração lida com o DANFE e o XML. Se seus fornecedores enviam uma mistura — alguns transmitem o XML diretamente, outros apenas imprimem e enviam o DANFE — você precisa de um método que trate ambas as fontes de forma consistente. O ImageToTable.ai suporta ambos: você pode fazer upload de arquivos XML brutos de NF-e junto com PDFs de DANFE no mesmo lote, definir um único modelo de coluna e obter uma planilha unificada. A ferramenta também lida com os caminhos variáveis dos subgrupos de ICMS descritos acima — uma vantagem significativa quando a complexidade do schema obriga as equipes de script a manter dezenas de variações de XPath. Para um passo a passo prático do processamento em lote de vários documentos NF-e, veja nosso guia de processamento em lote de NF-e.

XML / PDF / JPG Extração por IA

Os arquivos são processados com segurança e não são armazenados.

Preparando seu fluxo de extração para a Reforma Tributária de 2026

Linha do tempo de três nós intitulada O Esquema da NF-e Carrega Dois Sistemas Tributários Até 2033, mostrando campos de teste da CBS em 2026 a 0,9%, CBS ativa em 2027 com PIS e COFINS extintos, e CBS substituindo totalmente o PIS em 2033.

A Emenda Constitucional 132/2023 e a Lei Complementar 214/2025 do Brasil introduziram um sistema de IVA dual que substitui cinco tributos existentes por dois novos. Para a extração de NF-e, isso significa que o esquema XML que você analisa hoje carregará tanto os campos tributários antigos quanto os novos durante um período de transição que vai de agosto de 2026 até 2033. Veja o que muda no nível da extração e o que você precisa fazer a respeito.

O que permanece: A estrutura geral do XML (<ide>, <emit>, <det>, <total>) continua a mesma. Campos de cabeçalho, quantidades de itens, códigos NCM e códigos CFOP não são afetados.

O que muda: Novos grupos de elementos XML são adicionados à seção <imposto> de cada item e ao grupo de resumo <total>. Os novos grupos carregam cálculos de CBS (federal) e IBS (estadual/municipal) junto com os campos existentes de ICMS, IPI, PIS e COFINS. Durante o período de transição, você deve extrair ambos os conjuntos de campos e ter ambos disponíveis para os sistemas downstream.

Tributo AtualSubstituído PorImpacto na ExtraçãoCronograma de Transição
PIS (1,65% / 0,65%)CBS (federal, ~8,8%)Novos elementos <CBS> aparecem junto com <PIS>. Ambos devem ser extraídos durante a transição. A CBS substitui totalmente o PIS até 2033.2026: campos de teste da CBS (alíquota de 0,9%). 2027: CBS ativa, PIS extinto.
COFINS (7,6% / 3,0%)CBS (federal, ~8,8%)Igual ao PIS — os campos de COFINS coexistem com os campos de CBS. A extração combinada de PIS+COFINS deve considerar a alíquota unificada da CBS.2027: COFINS extinto, CBS em alíquota integral.
ICMS (estadual, 17-22% interno, 4-12% interestadual)IBS (estadual/municipal, ~17,7%)Novo grupo de elementos <IBS> com vBC, pIBS, vIBS. ICMS e IBS coexistem por item da linha. A extração deve capturar ambas as bases de cálculo — elas podem ser diferentes.2026: campos de teste do IBS (alíquota de 0,1%). 2029-2032: IBS entra em vigor estado por estado, substituindo o ICMS de forma incremental.
IPI (0-330% por NCM)IS (Imposto Seletivo, variável)O IS substitui o IPI gradualmente. IPI e IS podem coexistir durante a transição. O NCM continua sendo o classificador do produto.As alíquotas do IPI começam a ser zeradas em 2027. Substituição total até 2033.

Três passos práticos para preparar seu fluxo de extração:

1

Audite seu mapa de campos atual

Percorra seu modelo de extração e identifique cada campo que atualmente mapeia para ICMS, IPI, PIS ou COFINS. Para cada um, adicione um campo paralelo para o novo tributo correspondente (CBS para PIS/COFINS, IBS para ICMS, IS para IPI). Mesmo que você ainda não use os novos campos, o espaço do esquema precisa ser mapeado para que suas colunas de saída de extração existam e estejam prontas para receber dados quando os campos CBS/IBS forem preenchidos.

2

Teste com documentos NF-e de esquema duplo

Solicite aos seus fornecedores XMLs de NF-e de amostra que já incluam os novos campos CBS e IBS (todas as NF-e emitidas a partir de 1º de agosto de 2026 trarão ambos). Execute-os pelo seu pipeline de extração e verifique se os campos de tributos antigos e novos são extraídos corretamente. Se sua extração for baseada em script, confirme que as consultas XPath para ICMS não capturam acidentalmente valores de IBS — os grupos de elementos compartilham padrões de nomenclatura semelhantes.

3

Decida sua estratégia de campo duplo

Pelos próximos 7-8 anos, seus dados extraídos carregarão tanto campos de tributos legados quanto novos. Decida se (a) você mantém colunas paralelas na sua planilha de saída e deixa os usuários downstream escolherem qual usar, ou (b) você implementa um cronograma de migração em que certas colunas são introduzidas gradualmente e outras são descontinuadas em datas específicas. A maioria das equipes de AP preferirá a opção (a) durante os primeiros anos de transição — ela cria uma tabela de saída mais longa, mas evita o risco de descartar o único campo válido durante o período de regime misto.

Perguntas Frequentes

Preciso lidar com namespaces XML ao extrair campos da NF-e?

Sim. O XML da NF-e usa um namespace padrão declarado no elemento <nfeProc> (normalmente xmlns="http://www.portalfiscal.inf.br/nfe"). Qualquer consulta XPath deve registrar esse namespace (no lxml do Python: ns = {'nfe': 'http://www.portalfiscal.inf.br/nfe'}) ou usar local-name() para ignorá-lo. O conector XML do Power Query lida com namespaces automaticamente na maioria dos casos. Se sua ferramenta de extração exigir registro explícito de namespace, certifique-se de que ela use o URI correto — uma incompatibilidade produzirá conjuntos de resultados vazios silenciosamente.

Devo somar os valores de impostos dos itens de linha e comparar com os totais do cabeçalho?

Sim — esta é uma das verificações de validação mais valiosas que você pode implementar. O XML da NF-e carrega os totais de impostos em <total>/<ICMSTot> e o detalhamento dos itens de linha em cada <det>. Esses valores devem conciliar. Uma divergência entre a soma dos itens de linha e o total do cabeçalho é um sinal de alerta: pode indicar que um item de linha foi omitido na geração do XML, que um desconto foi aplicado de forma inconsistente ou que o ERP do fornecedor tem um erro de configuração. Reconcilie os valores de impostos dos itens de linha com os totais do cabeçalho como etapa padrão em cada lote de extração.

A extração de NF-e cobre os requisitos de declaração do SPED?

Não. O SPED (Sistema Público de Escrituração Digital) é o sistema brasileiro de escrituração digital — EFD-ICMS/IPI para impostos estaduais e EFD-Contribuições para contribuições federais — que exige que os dados sejam formatados em layouts específicos do SPED e enviados por meio de software credenciado. A extração de NF-e coloca os dados da nota fiscal em uma planilha; ela não gera registros compatíveis com o SPED. No entanto, os dados que você extrai da NF-e (ICMS, PIS, COFINS, CFOP, NCM, CST por item de linha) são os mesmos dados que alimentam as declarações do SPED. Se seu fluxo de trabalho de extração capturar corretamente o detalhamento de impostos no nível do item de linha, sua equipe de contabilidade brasileira poderá usar esses dados para preencher os registros do SPED exigidos, em vez de redigitar a partir dos documentos de origem. O mapeamento dos campos da NF-e para as posições do layout do SPED é uma etapa de transformação separada que alguns módulos de localização de ERP tratam automaticamente.

E se minha empresa tiver vários CNPJs em estados brasileiros diferentes?

Isso é comum em organizações maiores. Cada CNPJ (ou "estabelecimento") é uma pessoa jurídica separada para fins tributários, e o estado de destino na NF-e corresponde ao CNPJ que recebeu as mercadorias. Ao extrair dados de NF-e para uma organização com múltiplas entidades, filtre a saída da extração pelo CNPJ do destinatário (<dest>/<CNPJ>) e mantenha mapeamentos contábeis separados por entidade. A validação da alíquota de ICMS também difere por entidade — mercadorias enviadas para o seu CNPJ de São Paulo enfrentam alíquotas diferentes das enviadas para o seu CNPJ da Bahia, mesmo vindo do mesmo fornecedor. Para saber mais sobre como lidar com a complexidade estado a estado no Brasil, consulte nosso guia de extração acessível de NF-e.

O que acontece se o código NCM mudar enquanto tenho dados extraídos de um período anterior?

Os códigos NCM são atualizados periodicamente pela Receita Federal (normalmente anualmente, mas às vezes com ajustes no meio do ano por meio de Notas Técnicas). Se um código NCM mudar, a alíquota de IPI para essa classificação de produto também pode mudar. Para fins de extração, você deve capturar o código NCM conforme ele aparece na NF-e no momento da emissão — é o código que estava em vigor na data da nota e determina os tributos legalmente devidos. Se você estiver fazendo análises retrospectivas ou ajustes no SPED, use o NCM registrado no documento original, não a lista atual de NCM.

E se o XML da NF-e do fornecedor tiver elementos ausentes ou malformados?

Acontece. Os problemas mais comuns são: grupo <cobr> (cobrança) ausente, endereço incompleto em <enderEmit>, ou subgrupos de ICMS que não seguem a variante de schema esperada para o código CST declarado. Seu fluxo de extração deve lidar com isso de forma adequada — retornar null ou um placeholder para campos ausentes e registrar um aviso de validação. Nunca falhe de forma definitiva por elementos ausentes não críticos. Para campos críticos (chave de acesso, CNPJ, totais dos itens), um valor ausente deve acionar a rejeição dessa NF-e do lote com uma mensagem de erro clara. Um relatório resumo de validação é essencial: registre cada NF-e que teve campos ausentes ou anômalos para que sua equipe possa investigar antes de lançar no razão.

Como lidar com o DIFAL (diferencial de alíquota do ICMS entre estados)?

O DIFAL (Diferencial de Alíquota do ICMS) se aplica quando mercadorias são vendidas entre estados e a alíquota de ICMS no estado de destino é maior que a alíquota interestadual paga na origem. O comprador deve pagar a diferença de alíquota ao seu próprio estado. Na NF-e, o DIFAL é representado pelo subgrupo <ICMSPart> dentro de <imposto>/<ICMS>. Esse subgrupo contém vBC (a base de cálculo), pICMS (a alíquota interestadual já aplicada), pICMSUf (a alíquota interna do estado de destino) e vICMS (o valor do DIFAL = diferença entre as duas alíquotas sobre a base). Você deve extrair o valor do DIFAL separadamente e tratá-lo pelos seus fluxos de crédito de ICMS específicos do estado — ele não faz parte do crédito regular de ICMS.

Devo extrair frete e seguro separadamente dos valores dos produtos?

Sim. O XML da NF-e detalha a transação em valor do produto (vProd), frete (vFrete), seguro (vSeg) e outras despesas (vOutro). A base tributável do ICMS frequentemente inclui a soma de valor do produto + frete + seguro + outras despesas — mas nem sempre. Alguns produtos têm ICMS calculado apenas sobre o valor do produto. Extrair cada componente separadamente permite validar se a base tributável do ICMS corresponde ao seu entendimento da estrutura de preços. Se o frete está incluído na base do ICMS na NF-e, mas seu modelo de ERP espera o frete fora da base do ICMS, você tem um item de conciliação a resolver.

Ferramentas de extração com IA conseguem processar o XML completo da NF-e ou apenas o PDF do DANFE?

Depende da ferramenta. A extração com IA do ImageToTable.ai consegue processar tanto arquivos XML de NF-e (dados estruturados) quanto PDFs de DANFE (documento visual) no mesmo lote. Quando você envia um XML, a ferramenta lê os elementos estruturados diretamente — sem necessidade de OCR — e os mapeia para o seu modelo de colunas. Quando você envia um PDF de DANFE, a IA lê o conteúdo visual e extrai os campos visíveis. A principal vantagem de uma única plataforma para ambos é a consistência: você define um modelo de colunas para "Chave de Acesso da NF-e", "Valor do ICMS", "Código CFOP", e a ferramenta os preenche a partir do documento de origem que receber. Isso elimina a necessidade de manter fluxos separados para fornecedores baseados em XML vs. DANFE — um ponto comum de fragmentação nas operações de contas a pagar no Brasil.

Preciso arquivar a saída da extração junto com o XML?

A legislação brasileira exige que o XML original da NF-e seja arquivado por cinco anos a partir do fim do exercício fiscal em que ocorreu a transação. A saída da extração (sua planilha ou registros no ERP) não substitui o XML. No entanto, manter uma saída de extração estruturada junto ao arquivo de XML bruto é uma boa prática para conciliação interna e resposta a auditorias. Durante uma auditoria da SEFAZ, você provavelmente precisará apresentar ambos: os XMLs originais (para comprovar que os documentos existem e foram devidamente autorizados) e seus registros contábeis (para mostrar como os dados foram processados). Um fluxo de extração que arquiva automaticamente tanto o XML de origem quanto a saída extraída em uma estrutura vinculada — com a chave de acesso como chave de junção — economizará tempo significativo na preparação para auditorias. Para opções de conformidade com bom custo-benefício, consulte nosso guia de extração de NF-e para pequenas empresas.

Teste a Extração nos Seus Próprios Documentos de NF-e

A extração de NF-e não é um exercício teórico. Todo XML que você recebe carrega dados totalmente estruturados, validados pelo governo e prontos para uso. A única questão é se seu fluxo de trabalho extrai o suficiente deles — e os valida corretamente — antes que cheguem ao seu ERP ou registros financeiros. Os mapas de campos, tabelas de validação fiscal e referências de códigos deste guia fornecem a camada de referência. O motor de extração processa os documentos. A combinação transforma uma NF-e brasileira de um arquivo XML opaco que sua equipe tem dificuldade para analisar em uma fonte transparente de dados financeiros que você pode usar com confiança — para lançamento, para recuperação de créditos e para defesa em auditorias.

📮 contact email: [email protected]