Pular para o conteúdo principal

Documentação Funcional: API de Cadastro de Produtos e Customização Tributária

Visão Geral​

Esta API permite o cadastro e atualização de produtos, incluindo suas classificações fiscais básicas (NCM, CEST) e, principalmente, a definição de cenários tributários customizados (customTax).

O recurso de customTax é fundamental para flexibilidade fiscal: ele permite que o usuário defina regras específicas que sobrescrevem o cálculo automático do motor de impostos. Se um campo for informado dentro de um cenário de customTax, esse valor será utilizado prioritariamente na emissão da nota fiscal para aquele produto, naquele cenário específico, atuando como um valor "default" ou forçado.

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)?

Estrutura do Produto (ProductInput)​

O objeto principal de entrada para cadastro/atualização contém os seguintes campos:

CampoTipoObrigatórioDescrição
tenantIdStringSimIdentificador do Tenant (AccountId do Marketplace).
collectionIdStringSimIdentificador da coleção (CompanyId do Seller) para isolar o produto.
skuStringSimCódigo único de identificação do produto (SKU).
originEnumSimOrigem da mercadoria (ex: national, foreignDirectImport). Ver tabela de Origem.
descriptionStringSimDescrição detalhada do produto.
gtinStringNãoGTIN (EAN) do produto.
taxGtinStringNãoGTIN da unidade tributável.
tax.ncmStringSimCódigo NCM (8 dígitos) ou Gênero (2 dígitos).
tax.cestStringNãoCódigo CEST.
customTaxArraySimLista de cenários tributários customizados.

Valores de Origem (origin)​

  • national: Nacional
  • foreignDirectImport: Estrangeira - Importação direta
  • foreignInternalMarket: Estrangeira - Adquirida no mercado interno
  • nationalWith40To70Import: Nacional, mercadoria ou bem com Conteúdo de Importação superior a 40% e inferior ou igual a 70%
  • nationalPpb: Nacional, cuja produção tenha sido feita em conformidade com os processos produtivos básicos
  • nationalWithLess40Import: Nacional, mercadoria ou bem com Conteúdo de Importação inferior ou igual a 40%
  • foreignDirectImportWithoutNationalSimilar: Estrangeira - Importação direta, sem similar nacional
  • foreignInternalMarketWithoutNationalSimilar: Estrangeira - Adquirida no mercado interno, sem similar nacional
  • nationalWithGreater70Import: Nacional, mercadoria ou bem com Conteúdo de Importação superior a 70%

Customização de Regras Tributárias (customTax)​

O array customTax permite definir regras específicas baseadas no perfil do emitente (issuer) e do destinatário (recipient).

Como funciona o "Match" do Cenário​

Para que uma regra customizada seja aplicada, o sistema verifica se a operação sendo realizada corresponde aos critérios definidos no cenário:

  1. Emitente (issuer): O Regime Tributário (taxRegime) e o Perfil Tributário (taxProfile) do emitente da nota correspondem à lista fornecida?
  2. Destinatário (recipient): O Perfil Tributário (taxProfile) do destinatário corresponde à lista fornecida?
  3. Operação (OperationCode): O código da operação corresponde?
  4. Origem (origin): A origem da mercadoria corresponde?

Se houver correspondência, os valores definidos em intraState (operações internas/estaduais) ou interState (operações interestaduais) serão utilizados para preencher a nota fiscal.

Grupos de Impostos (intraState / interState)​

Dentro de cada grupo (interno ou interestadual), é possível customizar:

  • cfop: Código Fiscal de Operações e Prestações.
  • icms: Grupo de ICMS.
  • pis: Grupo de PIS.
  • cofins: Grupo de COFINS.

Interação com a Emissão da Nota (taxDetermination)​

Para que o motor de cálculo utilize as regras definidas no customTax do produto, é necessário enviar o grupo taxDetermination na requisição de emissão da nota fiscal (endpoint de emissão).

Este grupo fornece os parâmetros de contexto que o sistema utiliza para buscar a regra correspondente no cadastro do produto:

  • operationCode: Corresponde ao OperationCode cadastrado na regra.
  • issuerTaxProfile: Corresponde ao taxProfile do emitente (issuer) na regra.
  • buyerTaxProfile: Corresponde ao taxProfile do destinatário (recipient) na regra.
  • origin: Corresponde à origem da mercadoria.

Exemplo de taxDetermination na emissão:

"taxDetermination": {
  "operationCode": 1,
  "origin": "0",
  "issuerTaxProfile": "retail",
  "buyerTaxProfile": "final_consumer_non_icms_contributor"
}

Customização do ICMS (customTax.intraState.icms)​

Este grupo é utilizado para definir valores fixos ou regras específicas para o ICMS. Qualquer valor informado aqui terá precedência sobre o cálculo automático. Isso permite, por exemplo, fixar uma alíquota reduzida ou uma base de cálculo específica que o motor genérico não contemplaria.

Campos Disponíveis​

CampoDescriçãoTag SEFAZ
cstCódigo da Situação Tributária do ICMS (ex: 00, 20, 60).CST
modBCModalidade de determinação da Base de Cálculo do ICMS.modBC
pICMSAlíquota do ICMS (%).pICMS
pRedBCPercentual de redução da Base de Cálculo do ICMS.pRedBC
modBCSTModalidade de determinação da BC do ICMS ST.modBCST
pMVASTPercentual da Margem de Valor Adicionado ICMS ST.pMVAST
pRedBCSTPercentual de redução da BC do ICMS ST.pRedBCST
pICMSSTAlíquota do ICMS ST (%).pICMSST
motDesICMSMotivo da desoneração do ICMS.motDesICMS
pFCPPercentual do Fundo de Combate à Pobreza (FCP).pFCP
pDifPercentual de Diferimento.pDif
...(Outros campos conforme schema)

Guia de Preenchimento: Customizando CST 20 (Redução de Base de Cálculo)​

O CST 20 ("Com redução de base de cálculo") é utilizado quando a operação é tributada, mas existe um benefício fiscal que reduz a base sobre a qual o imposto é calculado.

Para configurar este cenário corretamente no grupo customTax.intraState.icms (ou interState), preencha os seguintes campos obrigatórios para a regra:

  1. cst: Deve ser preenchido com o valor "20".
  2. modBC: Informe a modalidade de determinação da base. Geralmente utiliza-se "3" (Valor da operação).
  3. pRedBC: Informe o percentual de redução que deve ser aplicado à base.
    • Exemplo: Se a base deve ser reduzida em 20%, informe "20.00".
  4. pICMS: Informe a alíquota do ICMS aplicável à operação (alíquota cheia, antes da redução da base).
  5. pFCP: Informe o percentual do FCP (Fundo de Combate à Pobreza) aplicável à operação.

Exemplo de objeto icms para CST 20:

"icms": {
  "cst": "20",
  "modBC": "3",
  "pRedBC": "41.67",  // Exemplo: Redução de 41.67% na base
  "pICMS": "18.00",   // Alíquota de 18%
  "pFCP": "2.00"      // Alíquota de 2% do FCP
}

Exemplo Completo de Requisição (JSON)​

Abaixo, um exemplo de cadastro de produto com uma regra customizada para CST 20 em operações estaduais (Intrastate) para um emitente do Lucro Real vendendo para Consumidor Final.

{
  "tenantId": "ACCOUNT-123",
  "collectionId": "COMPANY-456",
  "sku": "PROD-001",
  "origin": "national",
  "description": "Produto Exemplo com Redução de Base",
  "gtin": "7891234567890",
  "tax": {
    "ncm": "94036000",
    "cest": "2806100"
  },
  "customTax": [
    {
      "OperationCode": 1,
      "issuer": [
        {
          "taxRegime": "RealProfit",
          "taxProfile": "retail"
        }
      ],
      "recipient": [
        {
          "taxProfile": "final_consumer_non_icms_contributor"
        }
      ],
      "intraState": {
        "cfop": 5102,
        "icms": {
          "cst": "20",
          "modBC": "3",
          "pRedBC": "33.33",
          "pICMS": "18.00"
        },
        "pis": {
          "cst": "01",
          "pPIS": "1.65"
        },
        "cofins": {
          "cst": "01",
          "pCOFINS": "7.60"
        }
      }
    }
  ]
}

Nota Importante: CST 60 (ICMS Cobrado Anteriormente por Substituição Tributária)​

Para operações com CST 60, existem informações referentes à retenção do imposto na fase anterior (pelo substituto tributário) que são variáveis a cada lote de compra e, portanto, não devem ser cadastradas no produto (via customTax).

Esses dados são específicos da transação e devem ser enviados diretamente na integração da Nota Fiscal (endpoint de emissão), dentro do objeto items[].tax.icms.

Campos que devem ser enviados na emissão da NF-e (e não no cadastro):

  • baseSTRetentionAmount (vBCSTRet): Valor da BC do ICMS ST retido na operação anterior.
  • stRetentionAmount (vICMSSTRet): Valor do ICMS ST retido na operação anterior.
  • substituteAmount (vICMSSubstituto): Valor do ICMS próprio do substituto.
  • stFinalConsumerRate (pST): Alíquota suportada pelo consumidor final.
  • fcpstRetAmount (vFCPSTRet): Valor do FCP retido anteriormente por ST.
  • fcpstRetRate (pFCPSTRet): Percentual do FCP retido anteriormente por ST.

Exemplo de JSON na emissão da NF-e (CST 60):

  ...
  "taxDetermination": {
      "operationCode": 121,
      "origin": "0",
      "issuerTaxProfile": "retail",
      "buyerTaxProfile": "final_consumer_non_icms_contributor",
      "acquisitionPurpose": null
  },
  "tax": {
      "icms": {
          "BaseSTRetentionAmount": "10.00",
          "STFinalConsumerRate": 18.00,
          "SubstituteAmount": 10.00,
          "STRetentionAmount": "10.00"
      }
  }
  ...

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.