Guia do Usuário — Motor de Cálculo Tributário e Cadastro de Produtos NFE.io

Produto: NFE.io — Motor de Cálculo Tributário Versão: 1.0 Data: 2026-03-19 Audiência: Usuários e clientes do sistema NFE.io

---

O que é o Motor de Cálculo Tributário da NFE.io?

Quando você emite uma Nota Fiscal Eletrônica (NF-e), a legislação brasileira exige que você informe corretamente os tributos de cada produto: ICMS, PIS, COFINS, IPI e, em alguns casos, o DIFAL (diferencial de alíquota interestadual). Calcular esses tributos manualmente é extremamente complexo, pois as regras variam conforme:

• O estado de origem e destino da mercadoria
• O regime tributário do emitente (Lucro Real, Presumido, Simples Nacional, MEI…)
• O tipo de destinatário (consumidor final, revendedor, indústria…)
• A classificação fiscal do produto (NCM, CEST, origem)
• O tipo de operação (venda, devolução, transferência…)

O Motor de Cálculo Tributário da NFE.io faz tudo isso por você. Você informa os dados da operação e da mercadoria, e o sistema retorna automaticamente todos os tributos calculados e prontos para compor o XML da NF-e.

Cálculo de impostos é cobrado à parte

O Motor de Cálculo de Tributos é um serviço cobrado separadamente da emissão da nota fiscal. Não há etapa de ativação: o consumo é registrado sempre que você:

• emite uma NF-e ou NFC-e com o grupo taxDetermination preenchido em pelo menos um item;
• chama diretamente a API de Cálculo de Impostos ou o método calculate dos SDKs;
• cadastra ou atualiza produtos com regras tributárias no Cadastro de Produto.

Para emitir sem o motor, informe os impostos no grupo tax e não envie taxDetermination.

O valor e a forma de cobrança são definidos no seu plano comercial. Confirme com o time comercial antes de usar o motor em produção.

---

Modelo de Utilização do Motor de Cálculo

Para garantir o sucesso da sua integração e na utilização da nossa API, é importante alinhar o modelo de utilização do motor de cálculo. Atualmente, oferecemos dois cenários principais:

1. Utilização de Regras Padrão (Standard)

Neste cenário, você utiliza a inteligência tributária nativa do nosso motor.

• Ação: Não é necessário realizar o cadastro prévio de produtos.
• Integração: Basta enviar as propriedades perfeitamente preenchidas no grupo TaxDetermination via API. Com base nesses dados, o sistema processa e monta automaticamente o grupo Tax com os impostos do item.

2. Regras Customizadas

Indicado caso a sua operação possua particularidades fiscais ou benefícios específicos que fogem à regra geral.

• Ação: É necessário realizar o cadastro do produto e a configuração de cenários customizados.
• Análise Necessária: Nossa equipe de atendimento precisará validar se a customização desejada já existe em nossa base ou se será necessário desenvolver um novo cenário.

Informações necessárias para o Onboarding:

Para definir quais campos serão utilizados na configuração de regras customizadas, é fundamental mapear as seguintes variáveis do seu negócio:

• Natureza das Operações: Venda, transferência, entrada, simples remessa, etc.
• Perfil dos Envolvidos: Regime tributário, localização do emitente e do destinatário, entre outras características.
• Especificidades do Produto: NCM, tipo de item e a definição exata da regra que se deseja customizar.

Para garantir agilidade na configuração e na análise do seu cenário, pedimos que encaminhe ao nosso suporte as respostas do questionário de onboarding abaixo. Ele está dividido no contexto geral da sua operação e nas especificidades da regra customizada:

Parte 1: Perfil da Empresa (Contexto Geral)

Este mapeamento é feito apenas uma vez para entendermos o seu negócio.

1. Atuação: Possui operação e venda no território nacional de produtos/mercadorias? Realiza operações com múltiplos produtos?
2. Segmento e Perfil: Qual seu segmento de atuação (ex: Bebidas, eCommerce) e perfil do emitente (ex: Indústria, Varejista, Atacadista)?
3. Regime Tributário: Qual o regime de operação da empresa emitente? (Lucro Real, Lucro Presumido ou Simples Nacional)
4. Volume e Abrangência:
   • Qual a volumetria mensal de NF-es e média de itens por nota?
   • Em quais estados (UFs) sua empresa possui matriz/filiais e quais os principais estados de destino das vendas?
   • Quantos NCMs diferentes costuma operar e quais os principais capítulos?
5. Operações Frequentes: No seu dia a dia, quais operações são mais comuns? (Ex: Venda, Revenda, Devolução, Transferência, etc.)
6. Automação e Particularidades: Existe algum processo automatizado para os cálculos hoje? Sua empresa possui operações com regimes especiais (benefícios, isenções específicas do Estado)?

Parte 2: Mapeamento da Regra Customizada (Cenário Específico)

Para cada regra customizada que você precisar criar no nosso motor (para atender os regimes especiais ou particularidades citadas no item 6 da Parte 1), precisaremos das informações pontuais abaixo:

1. Operação Alvo: Dentre as operações que sua empresa realiza, para qual delas esta regra específica será aplicada? (Ex: Somente para Transferência entre filiais)
2. CFOP Esperado: Qual é o CFOP de saída exato que deseja para esta regra?
3. CST de ICMS Esperado: Qual o CST do ICMS que deve ser forçado/aplicado?
4. UF Origem vs. UF Destino da Regra: Em qual cruzamento de estados essa regra deve ser disparada? (Ex: Somente saídas de SP para RJ)
5. Origem da Mercadoria: Essa regra se aplica a produtos com qual origem? (Ex: Somente Importados)
6. Classificação Fiscal (NCMs Afetados): Quais são os NCMs exatos que devem obedecer a esta regra específica?
7. Escopo da Customização: A intenção é customizar apenas os valores de ICMS ou também outros impostos (PIS, COFINS)?

---

1. Visão Geral dos Dois Recursos Principais

1.1 Motor de Cálculo

O motor de cálculo é o coração do sistema. Você envia:

• Quem está emitindo (regime tributário, perfil fiscal, estado)
• Para quem está enviando (estado do destinatário, tipo de destinatário)
• Quais produtos (NCM, origem, quantidade, valor)

E recebe de volta:

• CFOP correto para cada produto
• CST ou CSOSN do ICMS
• Valores de base de cálculo, alíquotas e tributos calculados
• DIFAL (quando aplicável em operações interestaduais para consumidor final)
• PIS, COFINS, IPI

1.2 Cadastro de Produto

O cadastro de produto é um recurso opcional que permite "pré-configurar" produtos com regras tributárias específicas. Quando um produto cadastrado é identificado em uma operação de cálculo, suas regras customizadas substituem (total ou parcialmente) o resultado padrão do motor.

Por que cadastrar um produto?

• Seu produto tem tributação especial que o motor padrão não conhece (ex: benefício fiscal estadual, código de redução de base)
• Você trabalha no regime de Substituição Tributária e precisa fixar o CST 60 para o produto (os valores de ICMS-ST retido vão no item da NF-e, na emissão)
• Você quer garantir que sempre seja utilizado o CST correto para um produto específico
• Sua empresa tem acordos ou regimes diferenciados que precisam ser refletidos na NF-e

Sem cadastro de produto: o sistema calcula normalmente — você só não terá as customizações aplicadas.

---

2. O Motor de Cálculo em Detalhes

2.1 O Que Você Precisa Informar

Para calcular os tributos de uma operação, você precisa fornecer:

Sobre o Emitente:

• Estado (ex: São Paulo → SP)
• Regime tributário (Lucro Real, Lucro Presumido, Simples Nacional, MEI...)
• Perfil fiscal (varejo, atacado, indústria, importador)

Sobre o Destinatário:

• Estado (ex: Rio de Janeiro → RJ)
• Regime tributário (opcional, se conhecido)
• Tipo de destinatário (consumidor final, filial, revendedor...)

Sobre a Operação:

• Tipo: saída (venda) ou entrada (compra/devolução)
• Código de operação (define a natureza: venda, devolução, transferência, etc.)

Sobre cada Produto:

• NCM (Nomenclatura Comum do Mercosul — 8 dígitos)
• Origem da mercadoria (nacional ou estrangeira e em qual grau)
• CEST (quando o produto está sujeito à Substituição Tributária)
• Quantidade e valor unitário
• Valor de frete, seguro e desconto (quando aplicável)

2.2 O Que Você Recebe

Para cada produto informado, o sistema retorna:

CFOP: Código Fiscal de Operações — define a natureza da operação para fins fiscais (ex: 5102 para venda de mercadoria adquirida de terceiros no estado)

ICMS: Todos os campos necessários para o XML da NF-e:

• CST (Código de Situação Tributária) ou CSOSN (para Simples Nacional)
• Modalidade de cálculo da base (modBC)
• Base de cálculo (vBC) e alíquota (pICMS)
• Valor do ICMS (vICMS)
• Campos de ST quando aplicável (vBCST, pICMSST, vICMSST, etc.)
• Campos de ST retido anteriormente (vBCSTRet, vICMSSTRet, pST, etc.)
• Fundo de Combate à Pobreza (FCP) quando aplicável
• Desoneração (quando aplicável)

DIFAL (Diferencial de Alíquota): Calculado automaticamente em operações interestaduais para consumidor final (EC 87/2015 e LC 190/2022)

• Base de cálculo na UF de destino
• Alíquota interna e interestadual
• Partilha entre UF remetente e destinatário
• FCP da UF de destino

PIS e COFINS:

• CST
• Base de cálculo e alíquota
• Valor calculado
• Suporte a cálculo por quantidade (alíquota específica)

IPI:

• CST e código de enquadramento
• Base de cálculo (por dentro — gross-up)
• Alíquota e valor

Imposto de Importação (II): quando aplicável a produtos estrangeiros

Informações Adicionais: texto informativo sobre tributos para a NF-e

2.3 Como os Regimes Tributários Influenciam o Cálculo

O regime tributário do emitente é um dos fatores mais importantes:

Simples Nacional / MEI:

• ICMS: usa CSOSN (3 dígitos) em vez de CST (2 dígitos)
• ICMS: em vendas de optante do Simples Nacional para destinatário contribuinte do ICMS, pode haver indicação de crédito para o destinatário (pCredSN, vCredICMSSN). Não se aplica ao MEI nem a vendas para consumidor final
• Cálculo é simplificado em relação ao regime normal

Lucro Real / Lucro Presumido / Simples Nacional com sublimite excedido:

• ICMS: usa CST (2 dígitos)
• PIS/COFINS: calculados normalmente
• DIFAL: aplicável em vendas interestaduais para consumidor final não contribuinte
• Benefícios como redução de base de cálculo são considerados

2.4 Diferencial de Alíquota (DIFAL)

O DIFAL é calculado automaticamente quando:

• A operação é interestadual (estados emitente e destinatário diferentes)
• O destinatário é consumidor final não contribuinte do ICMS

O sistema implementa a base dupla prevista na LC 190/2022 para produtos com redução de base de cálculo (CST 20), garantindo conformidade com a legislação vigente.

---

3. Cadastro de Produto em Detalhes

3.1 Dados Cadastrais do Produto

Além das regras tributárias, você pode registrar informações complementares do produto:

Identificação:

• SKU: código interno do produto na sua empresa (obrigatório)
• Descrição: nome/descrição do produto (mínimo 3 caracteres, obrigatório)
• GTIN: código de barras EAN/GTIN (quando disponível)
• Categoria, Unidade de Medida, Preço Unitário

Classificação Fiscal:

• NCM: Nomenclatura Comum do Mercosul — 8 dígitos numéricos (obrigatório)
• CEST: Código Especificador da Substituição Tributária, 7 dígitos, que deve existir na tabela CEST oficial (quando o produto é sujeito à ST)
• ExTipi: código EX da TIPI (2 ou 3 dígitos) para produtos industrializados com tributação diferenciada. Atenção: produtos com exTipi informado não aceitam regras customizadas (customTax)
• Origem: código de origem da mercadoria (nacional ou estrangeira) (obrigatório)

Empresa (collectionId): identificador da empresa emissora à qual o produto pertence. Informe sempre: é por ele (junto com SKU e origem) que o produto é localizado no cálculo.

Detalhes Físicos (opcionais):

• Peso líquido e bruto
• Dimensões (altura, largura, profundidade)
• Unidade de medida das dimensões

3.2 O Que São as Regras Customizadas (customTax)

As regras customizadas permitem que você defina, para cada combinação específica de:

• Regime tributário do emitente
• Perfil fiscal do emitente (indústria, varejo, atacado, importador)
• Tipo de destinatário
• Código de operação

...quais valores devem ser usados ao invés do retorno padrão do motor.

O que a regra customizada sobrepõe no cálculo:

• CFOP: quando diferente do retornado pelo motor
• CST/CSOSN do ICMS: quando diferente do retornado pelo motor (ou quando a alíquota pICMS cadastrada difere da do motor). Só nesse caso os demais campos de ICMS do cadastro são aplicados
• pICMS e modBC: aplicados nos CST 00, 20, 40, 41 e 60
• pRedBC, pFCP, motDesICMS e indDeduzDeson: aplicados apenas no CST 20
• Alíquotas pPIS e pCOFINS: aplicadas quando cadastradas, junto com a sobreposição do ICMS nos CST 00, 20, 40, 41 e 60 (o CST de PIS e COFINS continua o do motor)
• benefitCode (cBenef): também só junto com a sobreposição do ICMS; aplicado nos CST 20, 40 e 41 quando cadastrado; nos CST 00 e 60 só a literal SEM CBENEF é aceita e qualquer código herdado do motor é removido. Com CST 40 ou 41 cadastrado sem benefitCode, se o motor devolveu um código de benefício para o item, o cálculo é recusado (422) com a orientação de cadastrar o código
• additionalInformation: aplicado sempre que cadastrado

Os campos de ICMS-ST próprio (modBCST, pMVAST, pRedBCST, pICMSST, pFCPST) são aceitos na entrada, mas não são gravados no cadastro: são ignorados e não voltam na consulta. Os campos de ST retido anteriormente (vBCSTRet, vICMSSTRet, pST etc.) e o grupo IPI são gravados no cadastro, mas não sobrepõem o resultado do cálculo.

Exemplo de situações onde customTax é útil:

• Produto com benefício fiscal estadual (ex: redução de base com isenção parcial)
• Produto sujeito a ST onde você precisa informar o ICMS já recolhido anteriormente
• Produto com CST específico acordado com a SEFAZ do seu estado
• Produto com informações adicionais obrigatórias na NF-e

3.3 Operações Intraestadual e Interestadual

Para cada regra customizada, você pode definir configurações diferentes para:

• Intrastate (Intraestadual): operações onde emitente e destinatário estão no mesmo estado. É aqui que geralmente se configura o CST 60 para produtos com ST, por exemplo.
• Interstate (Interestadual): operações onde emitente e destinatário estão em estados diferentes. As alíquotas e CFOPs interestaduais são diferentes das internas.

É possível informar apenas um dos dois (intraestadual OU interestadual) ou ambos.

3.4 Campos ICMS Disponíveis nas Regras Customizadas

Campo	Descrição
cst	Código de Situação Tributária (ex: "00", "20", "40", "60")
pICMS	Alíquota do ICMS (%)
modBC	Modalidade de determinação da BC
pRedBC	Percentual de redução da base de cálculo
pFCP	Percentual do Fundo de Combate à Pobreza
modBCST	Modalidade de determinação da BC do ICMS ST (aceito, mas não gravado: ignorado)
pMVAST	Margem de valor agregado do ICMS ST (aceito, mas não gravado: ignorado)
pRedBCST	Percentual de redução da BC do ICMS ST (aceito, mas não gravado: ignorado)
pICMSST	Alíquota do ICMS ST (aceito, mas não gravado: ignorado)
pFCPST	Percentual do FCP ST (aceito, mas não gravado: ignorado)
motDesICMS	Motivo da desoneração do ICMS
indDeduzDeson	Indica se ICMS desonerado deduz do valor do produto
vBCSTRet	Valor da BC do ICMS ST retido anteriormente
pST	Alíquota suportada pelo consumidor final
vICMSSubstituto	Valor do ICMS próprio do substituto
vICMSSTRet	Valor do ICMS ST retido anteriormente
vBCFCPSTRet	Base de cálculo do FCP ST retido anteriormente
pFCPSTRet	Percentual do FCP ST retido anteriormente
vFCPSTRet	Valor do FCP ST retido anteriormente

Os campos de ST retido anteriormente (vBCSTRet a vFCPSTRet) ficam armazenados no cadastro apenas como referência. Na emissão da NF-e, esses valores devem ser informados no item da nota (ver seção 7.3).

3.5 Campos PIS, COFINS e IPI nas Regras Customizadas

PIS:

• cst — Código de Situação Tributária do PIS
• pPIS — Alíquota do PIS

COFINS:

• cst — Código de Situação Tributária do COFINS
• pCOFINS — Alíquota do COFINS

IPI:

• cst — Código de Situação Tributária do IPI
• pIPI — Alíquota do IPI

No cálculo, das regras de PIS e COFINS só as alíquotas (pPIS, pCOFINS) sobrepõem o retorno do motor; o cst de PIS/COFINS e o grupo IPI ficam armazenados no cadastro. A exceção é o uso da regra cadastrada como contingência (ver FAQ sobre indisponibilidade), em que o CST de PIS e COFINS do cadastro é utilizado.

---

4. Ciclo de Vida do Cadastro de Produto

Após criar ou atualizar um produto, ele passa por um processo automático de validação. Acompanhe o status pelo campo status na consulta do produto:

Status e Significados

Status	Descrição	O que acontece
Pendente de Criação (Created)	Produto recém-criado, aguardando processamento	O sistema inicia automaticamente a validação em segundos
Regras Pendentes (CustomTaxPending)	Regras customizadas divergem do retorno padrão do motor e aguardam configuração	O produto é registrado no motor de regras tributárias e as regras são conferidas periodicamente (ver abaixo). Não há prazo máximo garantido
Ativo (Active)	Produto validado e pronto para uso	As regras serão aplicadas automaticamente em todas as operações de cálculo
Erro (Error)	Falha na validação	Verifique o campo errorMessage para entender o problema. Corrija e envie o cadastro novamente com PUT (um produto em erro sempre reinicia a validação)
Inativo (Inactive)	Produto desativado	Não é aplicado no cálculo

Atenção: se o item de uma operação de cálculo referenciar um produto cadastrado (mesmo SKU, origem e collectionId) que não esteja Active, o cálculo inteiro é recusado com 400 (Product id '...' with sku '...' is not 'Active'). Ele não é ignorado.

Quanto Tempo Leva a Ativação?

Após o POST ou PUT, o sistema:

1. Identifica os cenários fiscais configurados para a sua conta que correspondem a cada regra customizada (regime e perfil do emitente e do destinatário, código de operação, operações intraestaduais e/ou interestaduais)
2. Valida cada cenário consultando o motor de cálculo e comparando CFOP, CST/CSOSN e CEST com o que foi cadastrado
3. Se tudo coincide (ou o emitente é do Simples Nacional), o produto é ativado em segundos
4. Se há divergência, o produto fica em CustomTaxPending e é registrado no motor de regras tributárias. A primeira conferência automática ocorre cerca de 3 horas depois do registro (ou 10 minutos, se o produto já estava registrado); se as regras ainda não estiverem disponíveis, uma nova conferência é agendada a cada 3 horas
5. Se algum cenário é inválido, o produto vai para Error com o motivo em errorMessage

---

5. Notificações via Webhook

Configure um webhook para receber notificações automáticas quando o status de um produto muda:

Evento	Quando ocorre
product_tax.created_successfully	Produto foi validado e ativado com sucesso
product_tax.custom_rules_requested	Regras customizadas identificadas, aguardando configuração no motor de regras tributárias
product_tax.creation_failed	Falha na validação — verifique o errorMessage

O payload do webhook contém todos os dados do produto, incluindo o status atual e as regras tributárias configuradas. A notificação só é enviada se houver webhook cadastrado para o evento, e pode se repetir para o mesmo status (por exemplo, após uma revalidação ou um PUT).

---

6. Regras e Restrições Importantes

6.1 Unicidade do Produto

Não podem existir dois produtos com o mesmo collectionId + SKU + Origem dentro da mesma conta. Se tentar criar um produto duplicado, o sistema responde 409 com o ID do produto já existente.

6.2 Regras Customizadas Únicas por Cenário

Dentro do customTax, cada combinação de regime do emitente + perfil do emitente + regime do destinatário + perfil do destinatário + código de operação deve ser única. O sistema valida isso na criação e atualização.

6.3 Atualização Completa vs. Parcial

Ao atualizar um produto (PUT), envie o produto completo. A resposta de sucesso é 204, sem corpo, mas a atualização não substitui tudo:

• os dados do produto (sku, origem, descrição, informações adicionais, GTIN, GTIN tributável, unidade, preço, categoria, details, volume e tax) são sempre regravados com o valor enviado; campo não enviado é apagado;
• o collectionId não pode ser alterado: o valor gravado na criação é mantido;
• os cenários de customTax só são substituídos quando o produto está em Error ou quando há mudança tributária (veja 6.4). Caso contrário, os cenários gravados são mantidos;
• o EX TIPI (tax.exTipi) precisa ir com 2 ou 3 dígitos: na criação, 1 dígito é completado com zero, mas no PUT ele é recusado com 400.

Não há atualização parcial nem exclusão de produto pela API pública. Para reprocessar a validação de um produto já gravado, use POST /{tenantId}/products/{productId}/revalidate.

6.4 Impacto de Mudanças Tributárias

O sistema considera mudança tributária: origem, GTIN, NCM, EX TIPI ou CEST diferentes; quantidade de cenários de customTax diferente; ou, comparando os cenários pela posição na lista, diferença no emitente, no destinatário, no código de operação, na presença dos grupos intraestadual/interestadual ou, dentro deles, em CFOP, benefitCode ou nos campos gravados de ICMS. Com mudança tributária (ou com o produto em Error), o sistema:

1. Desfaz o registro existente no motor de regras tributárias, se houver
2. Substitui os cenários de customTax pelos enviados e reinicia o ciclo de validação do zero
3. O produto voltará ao status Created e precisará passar pelo processo de ativação novamente

Atualizações em campos não tributários (descrição, preço, dimensões, GTIN tributável etc.) não reiniciam o ciclo, exceto quando o produto está em Error: nesse caso qualquer PUT reinicia a validação.

⚠️ Limitação: alterar em customTax apenas PIS, COFINS, IPI ou additionalInformation não conta como mudança tributária. Com o produto fora de Error, o PUT responde 204, mas essa alteração não é aplicada e os cenários anteriores continuam valendo. Confira o resultado consultando o produto.

⚠️ Limitação conhecida: se um grupo intraestadual ou interestadual gravado no produto não tem ICMS (icms), e o PUT mantém nesse grupo o mesmo CFOP, o mesmo benefitCode e nenhum CST de ICMS, o PUT pode responder 500. Para evitar, envie o grupo icms, com cst, em todo grupo intraestadual/interestadual, tanto na criação quanto na atualização.

---

7. Cálculo de Impostos — Exemplos Práticos

7.1 Venda de produto nacional para consumidor final — mesmo estado

Situação: Loja em SP vende produto doméstico para consumidor final em SP

Dados da operação:

• Emitente: regime Lucro Real, perfil "varejo" (retail), estado SP
• Destinatário: consumidor final (não contribuinte), estado SP
• Produto: NCM 64021200 (calçados), origem 0 (nacional), valor R$ 120,00

O sistema calcula e retorna (valores ilustrativos):

• CFOP: 5102 (venda de mercadoria adquirida de terceiros — intraestadual)
• ICMS: CST "00", alíquota 18% (alíquota interna de SP), vBC R$ 120,00, vICMS R$ 21,60
• PIS: CST "01", alíquota 1,65%, base R$ 98,40 (valor da operação menos o ICMS destacado), vPIS R$ 1,62
• COFINS: CST "01", alíquota 7,6%, base R$ 98,40, vCOFINS R$ 7,48

7.2 Venda interestadual para consumidor final — com DIFAL

Situação: Loja em SP vende para consumidor final no RJ

O sistema calcula e retorna:

• CFOP: 6108 (venda interestadual de mercadoria de terceiros a não contribuinte)
• ICMS: CST "00", alíquota 12% (interestadual SP→RJ), vICMS R$ 14,40
• DIFAL: pICMSUFDest 20% (interna RJ), pICMSInter 12%, diferença partilhada entre SP e RJ
• PIS/COFINS: calculados normalmente

7.3 Venda de produto com Substituição Tributária (produto já com ST retida)

Situação: Supermercado em SP vende refrigerante com ICMS-ST já pago pelo distribuidor

Configuração do produto (customTax):

• CST intraestadual: "60" (ST cobrado anteriormente)
• CFOP intraestadual: 5405

Na emissão (item da NF-e):

• Valores da retenção anterior do lote vendido: base do ST retido (baseSTRetentionAmount), ICMS-ST retido (stRetentionAmount), alíquota suportada pelo consumidor final (stFinalConsumerRate) e ICMS próprio do substituto (substituteAmount). Esses valores são encaminhados ao motor de cálculo; os que estiverem no cadastro do produto não são usados

O sistema retorna:

• CFOP: 5405 (venda de produto adquirido com ST)
• ICMS: CST "60"
• Nenhum novo ICMS é calculado sobre a venda (já foi recolhido)

7.4 Emitente no Simples Nacional

Situação: MEI vende produto artesanal para consumidor final

O sistema retorna:

• ICMS com CSOSN em vez de CST
• Sem indicação de crédito de ICMS para o destinatário (o MEI recolhe o ICMS em valor fixo e a venda é para consumidor final)
• PIS/COFINS com o CST aplicável ao regime do emitente, conforme determinado pelo motor

---

8. Perfis Fiscais — O Que São e Como Usar

O perfil fiscal classifica o tipo de contribuinte dentro do sistema tributário brasileiro, influenciando quais alíquotas e regras se aplicam.

Perfis do Emitente

Perfil	Quando usar
retail (varejo)	Empresas que compram e revendem mercadorias ao varejo
wholesale (atacado)	Distribuidores e atacadistas
industry (indústria)	Fabricantes que produzem mercadorias próprias
wholesale_industry (atacado + indústria)	Empresas que tanto fabricam quanto distribuem
importer (importador)	Empresas que importam diretamente do exterior

Atenção: o perfil deve ser compatível com a origem do produto. industry e wholesale_industry só são aceitos para produtos nacionais (origem 0, 3, 4, 5 ou 8); retail e wholesale, para as origens 0, 2, 3, 4, 5, 7 e 8; importer é exclusivo para importação direta (origem 1 ou 6). Qualquer outro valor é recusado no cadastro.

Perfis do Destinatário

Perfil	Quando usar
final_consumer_non_icms_contributor	Consumidor final que não é contribuinte do ICMS (pessoa física ou empresa não contribuinte)
retail_branch	Filial varejista da mesma empresa
closed_warehouse	Depósito fechado (armazém próprio)

---

9. Códigos de Operação — O Que São

O código de operação (operationCode) define a natureza da operação fiscal. Os mais comuns são:

Código	Descrição
120	Venda de produção do próprio estabelecimento (indústria)
121	Venda de mercadoria adquirida ou recebida de terceiros (comércio)
466	Devolução de venda
727, 784, 802	Cenários de remessa e retorno envolvendo armazém ou depósito fechado (destinatário closed_warehouse, CFOP 5949 ou 1949). São acrescentados automaticamente ao cadastro de produto em algumas situações (ver Cadastro de produtos)
1108	Transferência entre estabelecimentos
2108	Transferência entre estabelecimentos com transferência de crédito de ICMS (CST 90)
3108	Transferência entre estabelecimentos sem transferência de crédito de ICMS (CST 90)

Use GET /tax-codes/operation-code para consultar a lista completa com as descrições oficiais.

---

10. Perguntas Frequentes (FAQ)

O uso do motor de cálculo é cobrado? Sim. O Motor de Cálculo de Tributos é cobrado separadamente da emissão da nota fiscal, e não depende de ativação: o consumo é registrado quando você emite NF-e ou NFC-e com taxDetermination, chama a API de Cálculo de Impostos ou cadastra e atualiza produtos com regras tributárias. Para emitir sem o motor, informe os impostos no grupo tax e não envie taxDetermination. O valor e a forma de cobrança são definidos no seu plano comercial — confirme com o time comercial.

Preciso cadastrar todos os produtos para usar o motor de cálculo? Não. O motor de cálculo funciona sem cadastro de produto. O cadastro é necessário apenas quando você precisa de regras tributárias customizadas que divergem do padrão calculado pelo motor.

O que acontece se o produto não for encontrado no cadastro durante o cálculo? O sistema calcula normalmente usando apenas o NCM, a origem e os dados da operação — sem aplicar nenhuma customização. O resultado é o retorno padrão do motor. Nesse caso o NCM do item é obrigatório; sem ele o cálculo é recusado com 400.

Posso ter regras diferentes para clientes do Simples Nacional e Lucro Real? Sim. É exatamente para isso que serve o array customTax. Você pode ter várias entradas, cada uma com issuer.taxRegime diferente, e o sistema aplica automaticamente a regra correta conforme o regime informado na chamada de cálculo.

Qual a diferença entre CST e CSOSN?

• CST (2 dígitos): usado por contribuintes fora do Simples Nacional (Lucro Real, Lucro Presumido) e por optantes do Simples Nacional com sublimite excedido
• CSOSN (3 dígitos): Código de Situação da Operação no Simples Nacional — usado por empresas optantes do Simples Nacional, inclusive MEI

O motor determina automaticamente qual usar com base no taxRegime do emitente.

Meu produto tem benefício fiscal com redução de base de cálculo. Como configurar? Use cst "20" com o campo pRedBC no customTax.intrastate.icms e/ou customTax.interstate.icms. Informe o percentual de redução (ex: "40.00" para 40% de redução). O sistema recalcula a base e o valor do ICMS automaticamente. O pRedBC só é aplicado no cálculo com CST 20.

O DIFAL é calculado automaticamente? Sim. Para operações interestaduais destinadas a consumidor final não contribuinte, o DIFAL é calculado automaticamente e retornado no campo icmsUfDest do response. Você não precisa configurar nada extra.

Quanto tempo demora para ativar um produto com regras customizadas? Depende. Se as regras cadastradas coincidem com o retorno padrão do motor, a ativação ocorre em segundos. Se divergem, o produto é registrado no motor de regras tributárias e a primeira conferência automática ocorre cerca de 3 horas depois, com novas conferências a cada 3 horas enquanto as regras não estiverem disponíveis; não há prazo máximo garantido. Você receberá um webhook quando o produto for ativado.

Posso usar os campos de ICMS ST retido (vBCSTRet, vICMSSTRet, etc.) sem ser CST 60? O cadastro aceita os campos em qualquer configuração, mas eles ficam apenas armazenados: não são usados no cálculo. Os valores de ST retido que valem para a nota devem ser informados no item da NF-e na emissão. Semanticamente, eles se aplicam ao CST 60 (ICMS cobrado anteriormente por ST) e ao CSOSN 500 (Simples Nacional com ST). Para outros CSTs, consulte sua assessoria fiscal.

Quem mantém as regras tributárias do motor? A NFE.io utiliza um motor de regras tributárias especializado, com base atualizada das legislações estaduais e federais. A NFE.io orquestra a comunicação com esse motor e aplica as customizações do seu cadastro de produto sobre o resultado dele.

Se o motor de regras tributárias ficar indisponível, minha emissão de NF-e para? Depende do cenário. Em falha do motor, a API usa, quando disponível: (1) o último resultado armazenado em cache para o mesmo cenário, mesmo que expirado, desde que todos os itens pendentes da operação tenham resultado em cache; ou (2) para produtos cadastrados com regra ICMS CST 40 completa (CFOP e CST de PIS e COFINS), a própria regra cadastrada. O cache só é mantido para alguns casos (por exemplo, emitentes do Simples Nacional) e é válido por 500 horas. Fora desses casos o cálculo retorna erro; na emissão de NF-e pela NFE.io, falhas temporárias do motor são tratadas com novas tentativas.

Posso atualizar o customTax sem reiniciar o ciclo de validação? Não. Toda alteração que conta como mudança tributária (ver 6.4), como CFOP, CST e demais campos gravados de ICMS, benefitCode, emitente, destinatário, código de operação ou os campos ncm, cest, exTipi, origin e gtin, reinicia o ciclo completo de validação. Atenção: alterar apenas PIS, COFINS, IPI ou additionalInformation do customTax não reinicia o ciclo e, com o produto fora de Error, não é aplicado. Nesses casos, confira o produto após o PUT.

---

11. Glossário

Termo	Significado
NCM	Nomenclatura Comum do Mercosul — código de 8 dígitos que classifica todos os produtos para fins fiscais e aduaneiros
CEST	Código Especificador da Substituição Tributária — código de 7 dígitos que identifica mercadorias sujeitas à ST
CST	Código de Situação Tributária do ICMS — 2 dígitos para empresas fora do Simples Nacional
CSOSN	Código de Situação da Operação no Simples Nacional — 3 dígitos para optantes do Simples
CFOP	Código Fiscal de Operações e Prestações — código de 4 dígitos que define a natureza da operação (venda, devolução, transferência...)
DIFAL	Diferencial de Alíquota — imposto sobre a diferença entre a alíquota interna do estado de destino e a alíquota interestadual, em operações para consumidor final
FCP	Fundo de Combate à Pobreza — adicional de até 2% do ICMS cobrado em alguns estados para determinados produtos
Substituição Tributária (ST)	Regime onde um contribuinte anterior na cadeia (substituto) recolhe o ICMS por todos os que virão depois
CustomTax	Regra tributária customizada cadastrada no produto, que sobrepõe o resultado padrão do motor
Motor de regras tributárias	Base de regras fiscais brasileiras utilizada pela NFE.io no cálculo de impostos
TaxRegime	Regime tributário do contribuinte (Simples Nacional, Lucro Real, Lucro Presumido, MEI...)
TaxProfile	Perfil fiscal do contribuinte (varejo, indústria, atacado, importador...)
OperationCode	Código interno da NFE.io que define a natureza da operação fiscal
SKU	Stock Keeping Unit — código interno do produto na empresa
CollectionId	Identificador de uma coleção/empresa dentro de uma conta NFE.io — usado para organizar e separar produtos de diferentes CNPJs