Mudanças no Layout de Integração da NF-e/NFC-e (v3)

Objetivo

Este documento detalha as principais mudanças introduzidas na versão 3 do layout de integração da nota fiscal de produto (NF-e) e consumidor (NFC-e). A atualização incorpora os novos campos exigidos pela Reforma Tributária (IBS e CBS) e adiciona outros grupos e campos para maior detalhamento das operações, alinhando-se aos padrões mais recentes.

info

• Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de Perguntas e Respostas sobre a Reforma Tributária. Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
• Se você quer uma visão geral rápida, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página Visão geral da Reforma Tributária na NFE.io

Público-Alvo

Desenvolvedores e usuários já familiarizados com o layout de integração anterior (v2).

1. Principais Mudanças: Novos Grupos de Tributos nos Itens

A mudança mais significativa ocorre dentro de cada item da nota (items). A estrutura de tributos (tax) foi expandida para acomodar os novos impostos. Enquanto os grupos icms, ipi, pis e cofins permanecem para operações no regime antigo, foi adicionado o grupo IBSCBS para o novo modelo. O grupo do Imposto Seletivo (IS) ainda não é aceito pela API.

1.1. Grupo: IS (Imposto Seletivo)

Este grupo ainda não é aceito pela API: valores enviados na requisição são ignorados. A plataforma ainda não apura o Imposto Seletivo, e o grupo ISTot não é gerado no XML.

1.2. Grupo: IBSCBS (IBS e CBS)

Este é o principal grupo adicionado e será obrigatório para as operações sob o novo regime tributário. Ele centraliza as informações do IBS (que unifica ICMS e ISS) e da CBS (que unifica PIS e COFINS).

Motivo da Inclusão

Alinhar a emissão de documentos fiscais ao novo modelo de tributação sobre o consumo, detalhando o cálculo e a distribuição dos novos impostos.

Campos-chave

• situationCode: Código de Situação Tributária unificado para IBS/CBS.
• classCode: Código de Classificação Tributária, que define o regime de tributação do item.
• basis: Base de cálculo unificada para os novos tributos.

Subgrupos de Cálculo (dentro de IBSCBS)

• state e municipal: Detalham o cálculo do IBS, que é um imposto de competência compartilhada. A estrutura é similar para ambos e contém campos como rate, amount, deferment e reduction.
• cbs: Detalha o cálculo da CBS (tributo federal), com campos como rate e amount.

Outros Subgrupos Opcionais em IBSCBS

• regularTaxation: Usado para informar a tributação que seria aplicável caso uma condição especial (suspensiva/resolutória) não fosse atendida.
• governmentPurchase: Detalha a composição do IBS/CBS em operações de compra por entidades governamentais.
• monophase: Contém informações específicas para produtos com tributação monofásica sob o novo regime.
• creditTransfer: Para casos de transferência de créditos de IBS/CBS.
• operationalPresumedCredit: Detalha créditos presumidos da operação (basis, classificationCode, ibs, cbs).
• creditReversal: Para informar o estorno de créditos de IBS/CBS.
• zfmPresumedCredit: Crédito presumido aplicável à Zona Franca de Manaus (ZFM).

Além desses, o grupo IBSCBS possui os campos calculationMode (modo de cálculo) e donationIndicator (indicador de doação), e o subgrupo ibsTotalAmount.

2. Outras Mudanças Relevantes

Além dos novos grupos de tributos, outros campos foram adicionados para dar suporte ao novo sistema.

2.1. Novos Campos e Grupos na Raiz do Documento

• purposeType (enum): Finalidade da emissão (Normal, Complement, Adjustment, Devolution, CreditInvoice ou DebitInvoice). A Nota de Crédito usa purposeType = CreditInvoice (finNFe 5) e a Nota de Débito, purposeType = DebitInvoice (finNFe 6).
• debitType / creditType (enum): Subtipo da Nota de Débito (tpNFDebito) ou de Crédito (tpNFCredito). É obrigatório com a finalidade correspondente e só é aceito com ela: fora disso, a API responde 400 com [V-DN-01] ou [V-CN-01].
• purchaseInformation: Grupo para informar dados da nota de empenho, pedido de compra e contrato.

Campos do layout que a API ainda não aceita. A data prevista de entrega (dPrevEntrega), o município do fato gerador do IBS/CBS (cMunFGIBS), o grupo de compras governamentais da nota (gCompraGov) e o Imposto Seletivo (IS e ISTot) não fazem parte da requisição: valores enviados são ignorados. O município do fato gerador (cMunFG) e o total vNFTot são preenchidos pela plataforma.

Documentos e processos referenciados: o processo judicial/administrativo que ampara a operação é informado em additionalInformation.referencedProcess; documentos fiscais referenciados são informados por item em items[].referencedDFe (e, quando aplicável, em additionalInformation.taxDocumentsReference). Informações do comprador estrangeiro são tratadas em buyer (endereço no exterior) e no grupo export.

2.2. Novos Campos nos Itens (items)

• usedMovableGood: Indica fornecimento de bem móvel usado (indBemMovelUsado). A tag só é emitida no XML quando true; com false ou ausente ela não é enviada.
• itemAmount (vItem), presumedCredit (gCred) e ibsZfmPresumedCreditClassification (tpCredPresIBSZFM): não são aceitos pela API no item; valores enviados são ignorados. A classificação do crédito presumido da ZFM vai em items[].tax.IBSCBS.zfmPresumedCredit.classificationCode.
• referencedDFe: Documento Fiscal Eletrônico referenciado no item.

O crédito presumido operacional (com sua alíquota) é informado dentro de items[].tax.IBSCBS.operationalPresumedCredit, e não como um campo de alíquota na raiz do item.

2.3. Novos Grupos de Totais (totals)

No grupo totals, foi adicionado um novo objeto para consolidar os valores totais do IBS e da CBS:

• ibsCbs: Agrupa os totais de IBS e CBS da nota, incluindo valores de base de cálculo, diferimento, devolução e créditos presumidos.

O valor total da NF-e com IBS/CBS (vNFTot) não faz parte da requisição: a plataforma o preenche. Em 2025 e 2026 ele equivale a icms.invoiceAmount (vNF); a partir de 2027, IBS, CBS e IS passam a compor o total (NT 2025.002, regras VB01-10 e W60-10).

3. Resumo das Principais Diferenças

Característica	Layout Antigo (v2)	Novo Layout (v3)
Estrutura Tributária	Grupos separados para ICMS, IPI, PIS, COFINS.	Mantém os grupos antigos e adiciona o novo grupo IBSCBS dentro de cada item.
Novos Impostos	Não aplicável.	Suporte à dupla IBS/CBS. O Imposto Seletivo (IS) ainda não é aceito pela API.
Finalidade da NF-e	Não explícito no layout.	Campo purposeType para indicar a finalidade da emissão.
Cálculo de Impostos	Baseado nas regras individuais de cada tributo antigo.	Cálculo mais complexo e interligado, com alíquotas efetivas, diferimentos e reduções dentro dos novos grupos.
Totalizadores	Grupo icms dentro de totals.	Adiciona o grupo ibsCbs para os totais de IBS e CBS.
Cenários Específicos	Tratados com CFOPs e CSTs.	Novos grupos no item (tax.IBSCBS.governmentPurchase, monophase, creditTransfer, etc.) e referências em additionalInformation.referencedProcess / items[].referencedDFe.

Conclusão

A transição para o layout v3 é focada na adaptação ao novo sistema tributário nacional. O principal esforço de integração será mapear as operações para os novos situationCode e classCode, e preencher corretamente o grupo IBSCBS quando aplicável. A estrutura para o regime antigo de tributação foi mantida para garantir a coexistência dos dois modelos durante o período de transição.