Como Emitir NF-e e NFC-e com IPI (IPITrib / IPINT) e Valor Aproximado de Tributos (vTotTrib / Lei 12.741) via API

Qualquer desenvolvedor que já construiu um motor de faturamento de mercadorias sabe que o teste real de uma integração de NF-e Modelo 55 ou NFC-e Modelo 65 começa quando o seu primeiro cliente sai do comércio varejista simples e passa a operar como indústria, importadora ou atacadista equiparado a industrial.

No segundo em que essa empresa tenta emitir uma nota de saída ou devolução de mercadoria industrializada, entram em cena duas exigências do Manual de Orientação do Contribuinte (MOC 7.0) da SEFAZ que derrubam a maioria das integrações feitas às pressas:

1. O Grupo O (<IPI>) — Imposto sobre Produtos Industrializados — que divide sua estrutura XML em dois subgrupos mutuamente exclusivos (<IPITrib> e <IPINT>), exige um Código de Enquadramento Legal (cEnq) compatível com o CST e altera diretamente a equação matemática do valor total da nota (<vNF>).
2. A Tag <vTotTrib> — exigida pela Lei Federal nº 12.741/2012 (Lei da Transparência Fiscal / De Olho no Imposto) com base na tabela do IBPT — que precisa ser informada em cada item (<det><imposto><vTotTrib>) e somada de forma consistente no bloco totalizador (<total><ICMSTot><vTotTrib>).

Nas releases v0.56.74 e v0.56.76 da engine fiscal da Notaas, nós redesenhamos tanto o builder do Grupo O (<IPI>) quanto a agregação automática do valorTributos (<vTotTrib>) e a renderização do DANFE em PDF. A seguir, vou abrir como essa engenharia funciona por baixo do capô e como você envia ambos via API REST em JSON sem tocar em uma única linha de XML.

Dissecanado o Grupo O (<IPI>) no Schema XML da NF-e (Modelo 55)

A primeira regra que costuma confundir quem está migrando de NFS-e Nacional de serviços para a NF-e de produtos é que o schema XSD da SEFAZ (enviNFe_v4.00.xsd) não usa uma tag única para todos os Códigos de Situação Tributária (CST) do IPI.

Dentro do bloco <imposto> de cada item (<det nItem="...">), o nó <IPI> exige primeiro o elemento <cEnq> (Código de Enquadramento Legal do IPI, com 3 posições) e, logo abaixo, força uma escolha binária (xs:choice) entre <IPITrib> (para operações com cálculo de imposto, mesmo que a alíquota seja zero em casos específicos de outros CSTs tributados) ou <IPINT> (para operações não tributadas, isentas, imunes, suspensas ou com alíquota zero tabelada).

Se o seu código colocar um CST 53 (Saída não-tributada) dentro de uma tag <IPITrib>, o validador de schema da SEFAZ rejeita o lote imediatamente com erro de falha de schema XML (Rejeição 215 / 225).

Matriz Completa de CSTs do IPI: <IPITrib> vs. <IPINT>

Na release v0.56.74 da Notaas, você não precisa escolher manualmente entre os nós XML: basta informar o cst no objeto ipi do item e o nosso builder resolve o subgrupo estrutural correto:

As Duas Modalidades de Cálculo no <IPITrib>: Ad Valorem vs. Unidade Tributável

Quando a operação utiliza os CSTs 00, 49, 50 ou 99, o IPI pode ser calculado de duas maneiras diferentes segundo a legislação do RIPI (Regulamento do IPI):

1. Cálculo por Alíquota Percentual (Ad Valorem): É o cenário de 95% das indústrias e importadoras. Informam-se a Base de Cálculo (vBC) e a Alíquota percentual (pIPI). O valor do imposto é calculado por: vIPI = round(vBC * (pIPI / 100), 2)
2. Cálculo Específico por Unidade (qUnid + vUnid): Comum no setor de bebidas, cigarros e produtos sujeitos a selo de controle ou pauta específica por litro/unidade. Em vez de percentual sobre o preço, o fisco cobra um valor fixo em reais (vUnid, com até 4 casas decimais) multiplicado pela quantidade na unidade tributável (qUnid, com até 4 casas decimais): vIPI = round(qUnid * vUnid, 2)

A Regra de Validação do Código de Enquadramento (cEnq)

Outro detalhe que implementamos na v0.56.74 é a proteção contra a Rejeição 387 / 388 (Código de Enquadramento Legal do IPI inválido). No MOC da SEFAZ:

• Se o CST for tributado normal (00, 49, 50, 99) ou não-tributado/alíquota zero (01, 03, 51, 53), o código de enquadramento padrão é "999" (Tributação normal IPI; Outros). Se você omitir o campo codigoEnquadramento no JSON da Notaas, nosso motor preenche "999" automaticamente.
• Porém, se você usar um CST de Imunidade (04 ou 54), a SEFAZ exige um cEnq na faixa 001 a 099.
• Para Suspensão (05 ou 55), exige um cEnq na faixa 101 a 199.
• Para Isenção (02 ou 52), exige um cEnq na faixa 301 a 399.

Por Que o IPI Quebra o <vNF> se Você Não Somar Corretamente (Rejeição 604 / W16-10)

Diferente do ICMS próprio, do PIS e da COFINS — que são impostos calculados "por dentro" (já embutidos no valor do produto vProd) —, o IPI é um imposto calculado "por fora".

Isso significa que o valor do IPI (vIPI) é cobrado além do preço do produto, somando diretamente no Valor Total da Nota Fiscal (<vNF>). A equação estrita validada pela SEFAZ na regra W16-10 é:

vNF = vProd - vDesc + vICMSST + vFrete + vSeg + vOutro + vII + vIPI + vServ

Se um item custa R$ 1.000,00 (vProd = 1000.00) e tem 10% de IPI (vIPI = 100.00), o totalizador <ICMSTot> terá <vProd>1000.00</vProd>, <vIPI>100.00</vIPI> e obrigatoriamente <vNF>1100.00</vNF>. Se o seu sistema enviar vNF = 1000.00, a SEFAZ rejeitará a nota na hora com a Rejeição 604: Total do vNF difere do somatório dos valores que compõem o valor total da NF-e.

Na Notaas, você não precisa fazer essa conta manualmente no cliente: ao enviar o bloco ipi nos itens do payload JSON, nossa engine calcula o vIPI de cada item, soma no <ICMSTot><vIPI>, adiciona automaticamente ao <vNF> e ainda renderiza as colunas V. IPI e ALIQ. IPI no PDF do DANFE gerado localmente.

A Lei da Transparência Fiscal (Lei 12.741/2012) e a Tag <vTotTrib>

Enquanto o IPI afeta indústrias e atacadistas, a Lei Federal nº 12.741/2012 (conhecida como Lei De Olho no Imposto) afeta qualquer empresa que venda mercadorias ou serviços ao consumidor final. Ela determina que todo documento fiscal deve exibir o valor aproximado dos tributos federais, estaduais e municipais que influenciam a formação do preço de venda, calculado tipicamente a partir da tabela semestral do IBPT (Instituto Brasileiro de Planejamento e Tributação) por código NCM ou NBS.

Na release v0.56.76, adicionamos suporte completo ao campo amigável valorTributos tanto em cada item quanto no bloco opcional de totais (para NF-e Modelo 55 e NFC-e Modelo 65).

Veja o fluxo de processamento de impostos e totalizadores na engine da Notaas:

⚡ Fluxo Arquitetural: Cálculo de <IPI> e Agregação de <vTotTrib> na Notaas (v0.56.74 / v0.56.76):

• 1. Recebimento do Payload JSON: Sua aplicação envia POST /api/v1/nfe/emitir ou POST /api/v1/nfce/emitir informando o objeto ipi (para NF-e Mod 55) e o campo valorTributos em cada item.
• 2. Resolução de <IPITrib> ou <IPINT>: O builder analisa o cst do IPI, aplica o cEnq (com fallback seguro para "999"), calcula o vIPI (por alíquota aliquota ou por unidade quantidadeUnidade * valorUnidade) e injeta o nó XML correspondente.
• 3. População de <vTotTrib> por Item e Soma Automática: Para cada item que contém valorTributos > 0, a engine gera <vTotTrib> dentro de <det><imposto> e acumula o somatório exato em <total><ICMSTot><vTotTrib> (permitindo override explícito caso você envie totais.valorTributos).
• 4. Fechamento Matemático do <vNF> e Renderização do DANFE: O motor soma vIPI na composição do <vNF>, assina o XML com o Certificado A1 do projeto e gera o PDF do DANFE / DANFE-NFC-e exibindo a coluna de IPI e o quadro de Valor Aproximado dos Tributos (Lei 12.741/2012).

Exemplo Completo: Payload JSON com IPI Tributado, IPI Não-Tributado e valorTributos

Se você desenvolve usando fluxos modernos de Vibe Coding com Cursor, Lovable, v0 e Next.js ou gerencia dezenas de clientes via nossa Org API para múltiplos CNPJs, veja como é limpo o payload JSON enviado para POST https://api.notaas.com.br/api/v1/nfe/emitir:

{
  "ambiente": "homologacao",
  "referencia": "pedido_ind_2026_8841",
  "naturezaOperacao": "VENDA DE PRODUCAO DO ESTABELECIMENTO",
  "finalidade": "1",
  "consumidorFinal": true,
  "presencaComprador": "1",
  "destinatario": {
    "cpfCnpj": "12345678000195",
    "razaoSocial": "METALURGICA HORIZONTE LTDA",
    "indicadorIe": "1",
    "inscricaoEstadual": "110042490114",
    "endereco": {
      "logradouro": "Avenida das Nações Unidas",
      "numero": "12901",
      "bairro": "Brooklin Paulista",
      "codigoMunicipio": "3550308",
      "uf": "SP",
      "cep": "04578910"
    }
  },
  "itens": [
    {
      "codigo": "VALV-INOX-01",
      "descricao": "VALVULA ESFERA EM ACO INOX 316 1 POLEGADA",
      "ncm": "84818095",
      "cfop": "5101",
      "unidade": "UN",
      "quantidade": 2,
      "valorUnitario": 500.00,
      "valorTotal": 1000.00,
      "valorTributos": 314.50,
      "icms": {
        "origem": "0",
        "cst": "00",
        "modalidadeBc": "3",
        "baseCalculo": 1000.00,
        "aliquota": 18.00,
        "valor": 180.00
      },
      "ipi": {
        "cst": "50",
        "codigoEnquadramento": "999",
        "baseCalculo": 1000.00,
        "aliquota": 9.75,
        "valor": 97.50
      },
      "pis": {
        "cst": "01",
        "baseCalculo": 820.00,
        "aliquota": 1.65,
        "valor": 13.53
      },
      "cofins": {
        "cst": "01",
        "baseCalculo": 820.00,
        "aliquota": 7.60,
        "valor": 62.32
      }
    },
    {
      "codigo": "KIT-VEDACAO-NT",
      "descricao": "AMOSTRA GRATIS DE ANEL DE VEDACAO PTFE",
      "ncm": "39269090",
      "cfop": "5911",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 50.00,
      "valorTotal": 50.00,
      "valorTributos": 12.10,
      "icms": {
        "origem": "0",
        "cst": "40"
      },
      "ipi": {
        "cst": "52",
        "codigoEnquadramento": "304"
      },
      "pis": {
        "cst": "08"
      },
      "cofins": {
        "cst": "08"
      }
    }
  ],
  "pagamento": {
    "formas": [
      {
        "meio": "15",
        "valor": 1147.50
      }
    ]
  }
}

O XML Oficial Gerado pela Engine da Notaas

Ao processar o JSON acima, o motor da Notaas gera exatamente a estrutura exigida pelo schema v4.00 da SEFAZ (note o <vTotTrib> em cada item, a diferença entre <IPITrib> no item 1 e <IPINT> no item 2, e os totalizadores <vIPI>, <vTotTrib> e <vNF> fechados ao centavo):

<!-- Trecho do Item 1 (Saída Tributada com IPI 9,75% e vTotTrib) -->
<det nItem="1">
  <prod>
    <cProd>VALV-INOX-01</cProd>
    <xProd>VALVULA ESFERA EM ACO INOX 316 1 POLEGADA</xProd>
    <NCM>84818095</NCM>
    <CFOP>5101</CFOP>
    <uCom>UN</uCom>
    <qCom>2.0000</qCom>
    <vUnCom>500.0000</vUnCom>
    <vProd>1000.00</vProd>
    <uTrib>UN</uTrib>
    <qTrib>2.0000</qTrib>
    <vUnTrib>500.0000</vUnTrib>
    <indTot>1</indTot>
  </prod>
  <imposto>
    <vTotTrib>314.50</vTotTrib>
    <ICMS>
      <ICMS00>
        <orig>0</orig>
        <CST>00</CST>
        <modBC>3</modBC>
        <vBC>1000.00</vBC>
        <pICMS>18.0000</pICMS>
        <vICMS>180.00</vICMS>
      </ICMS00>
    </ICMS>
    <IPI>
      <cEnq>999</cEnq>
      <IPITrib>
        <CST>50</CST>
        <vBC>1000.00</vBC>
        <pIPI>9.7500</pIPI>
        <vIPI>97.50</vIPI>
      </IPITrib>
    </IPI>
    <PIS>
      <PISAliq>
        <CST>01</CST>
        <vBC>820.00</vBC>
        <pPIS>1.6500</pPIS>
        <vPIS>13.53</vPIS>
      </PISAliq>
    </PIS>
    <COFINS>
      <COFINSAliq>
        <CST>01</CST>
        <vBC>820.00</vBC>
        <pCOFINS>7.6000</pCOFINS>
        <vCOFINS>62.32</vCOFINS>
      </COFINSAliq>
    </COFINS>
  </imposto>
</det>

<!-- Trecho do Item 2 (Amostra Grátis Isenta com IPINT CST 52 e cEnq 304) -->
<det nItem="2">
  <imposto>
    <vTotTrib>12.10</vTotTrib>
    <ICMS>
      <ICMS40>
        <orig>0</orig>
        <CST>40</CST>
      </ICMS40>
    </ICMS>
    <IPI>
      <cEnq>304</cEnq>
      <IPINT>
        <CST>52</CST>
      </IPINT>
    </IPI>
    <!-- ... PISNT e COFINSNT ... -->
  </imposto>
</det>

<!-- Bloco Totalizador da Nota (<total><ICMSTot>) -->
<total>
  <ICMSTot>
    <vBC>1000.00</vBC>
    <vICMS>180.00</vICMS>
    <vICMSDeson>0.00</vICMSDeson>
    <vFCP>0.00</vFCP>
    <vBCST>0.00</vBCST>
    <vST>0.00</vST>
    <vFCPST>0.00</vFCPST>
    <vFCPSTRet>0.00</vFCPSTRet>
    <vProd>1050.00</vProd>
    <vFrete>0.00</vFrete>
    <vSeg>0.00</vSeg>
    <vDesc>0.00</vDesc>
    <vII>0.00</vII>
    <vIPI>97.50</vIPI>
    <vIPIDevol>0.00</vIPIDevol>
    <vPIS>13.53</vPIS>
    <vCOFINS>62.32</vCOFINS>
    <vOutro>0.00</vOutro>
    <vNF>1147.50</vNF>
    <vTotTrib>326.60</vTotTrib>
  </ICMSTot>
</total>

E à medida que a sua operação avança para o cronograma da Reforma Tributária (IBS e CBS), o mesmo payload já está preparado para conviver com as novas tags de transição sem quebrar contratos de API existentes.

Emita NF-e e NFC-e em Produção com 20 Notas Grátis por Mês

Integrar cálculos de IPI, substituição tributária, devoluções e transparência fiscal do IBPT não precisa custar meses de desenvolvimento nem mensalidades fixas pesadas antes do seu produto escalar.

• Crie sua Conta Gratuita na Notaas: Emita até 20 notas fiscais gratuitas por mês em produção real (para 1 CNPJ) e teste até 5 projetos simultâneos grátis em homologação via Org API, sem cartão de crédito, em platform.notaas.com.br/sign-up.
• Explore a Documentação Técnica: Confira todos os parâmetros de NF-e (Mod 55), NFC-e (Mod 65) e Webhooks em docs.notaas.com.br.