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 parte do cálculo automático do motor de impostos. Os campos sobrepostos, e em quais condições, estão descritos em Quando os valores são aplicados.

Cadastro de produto e cálculo de impostos são cobrados à parte

O Cadastro de Produto faz parte do 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ê:

• cria ou atualiza um produto com regras tributárias (inclusive cenários de customTax);
• 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.

O valor e a forma de cobrança são definidos no seu plano comercial. Confirme com o time comercial antes de cadastrar produtos ou 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)?

Operações da API

Operação	Método e rota	Resposta de sucesso
Criar produto	POST /{tenantId}/products	201 com { "id": "..." }
Consultar produto	GET /{tenantId}/products/{productId}	200 com o produto
Atualizar produto	PUT /{tenantId}/products/{productId}	204 sem corpo
Revalidar produto	POST /{tenantId}/products/{productId}/revalidate	200 com { "status": "...", "errorMessage": "..." }

Não há operação de exclusão de produto. O tenantId (conta) vai somente na rota, nunca no corpo.

Respostas de erro mais comuns:

• 400: o cadastro viola uma regra de validação. O corpo traz { "status": 400, "detail": "<primeira regra violada>" }.
• 404: produto não encontrado nesta conta (consulta, atualização e revalidação).
• 409: na criação, já existe produto com o mesmo collectionId + sku + origin. O corpo traz o id do produto existente: { "status": 409, "detail": "Product already exists", "id": "..." }.

O PUT atualiza o produto, mas não substitui tudo:

• sku, origin, description, additionalInformation, gtin, taxGtin, unit, unitPrice, category, details, volume e tax são sempre regravados com o valor enviado; campo omitido é apagado.
• collectionId não pode ser alterado: o valor gravado na criação é mantido.
• customTax só é substituído (pela lista inteira enviada) quando o produto está em Error ou quando há mudança tributária (veja abaixo). Caso contrário, os cenários gravados são mantidos.
• Os preenchimentos automáticos de customTax (veja "Valores preenchidos automaticamente") também valem no PUT. A exceção é tax.exTipi: no PUT ele não é completado com zero, e um valor de 1 dígito é recusado com 400 (ExTipi must have between 2 and 3 digits). Envie exTipi sempre com 2 ou 3 dígitos.

Status do produto

A criação e a atualização respondem assim que o cadastro é gravado. A validação tributária dos cenários acontece em segundo plano e aparece no campo status da consulta:

Status	Significado
Created	Cadastro gravado, aguardando a validação tributária.
CustomTaxPending	Regras customizadas em validação e registro no motor de cálculo. Pode levar algumas horas.
Active	Produto validado; as regras customizadas são aplicadas no cálculo.
Error	A validação falhou; o motivo está em errorMessage. Corrija com PUT.
Inactive	Produto inativo.

Mudança tributária é: origin, gtin, tax.ncm, tax.exTipi ou tax.cest diferentes; quantidade de cenários de customTax diferente; ou, comparando os cenários pela posição na lista, diferença no emitente (issuer.taxRegime, issuer.taxProfile), no destinatário (recipient.taxRegime, recipient.taxProfile), no operationCode, na presença de intrastate/interstate, ou, dentro desses grupos, em cfop, benefitCode ou nos campos gravados de icms. Com mudança tributária (ou com o produto em Error), o produto volta a Created, os cenários são substituídos e a validação recomeça. Mudanças só em campos descritivos (descrição, preço, dimensões, taxGtin etc.) são gravadas sem reiniciar o status.

⚠️ 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 com a consulta do produto.

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

A operação de revalidação executa a validação de novo, na hora, e devolve o status resultante.

Estrutura do Produto (ProductInput)

O objeto de entrada para criação e atualização contém os seguintes campos. Os nomes são camelCase (na entrada, maiúsculas e minúsculas são indiferentes).

Campo	Tipo	Obrigatório	Descrição
collectionId	String	Sim	ID da empresa emitente (companyId). Na emissão, o produto é localizado pela conta + collectionId + sku + origin. Não pode ser alterado pelo PUT.
sku	String	Sim	Código do produto. Deve ser igual ao código do item (cProd) enviado na emissão.
origin	Enum	Sim	Origem da mercadoria (ex.: National, ForeignDirectImport). Ver tabela de Origem.
description	String	Sim	Descrição do produto, com no mínimo 3 caracteres.
additionalInformation	String	Não	Informações adicionais do produto.
gtin	String	Não	GTIN (EAN) do produto.
taxGtin	String	Não	GTIN da unidade tributável.
unit	String	Não	Unidade comercial (ex.: UN).
unitPrice	Number	Não	Preço unitário de referência.
category	String	Não	Categoria do produto.
details	Objeto	Não	brand, manufacturing (Own ou ThirdParty) e condition (New ou Used).
volume	Objeto	Não	netWeight, grossWeight, height, width, depth e measurementUnit (Meters, Centimeters ou Millimeters).
tax.ncm	String	Sim	Código NCM com 8 dígitos numéricos.
tax.exTipi	String	Não	Código EX da TIPI com 2 ou 3 dígitos (na criação, 1 dígito é completado com zero; no PUT, é recusado). Com ele informado, a validação atual recusa os cenários de customTax.
tax.cest	String	Não	Código CEST com 7 dígitos. Precisa existir na tabela CEST.
tax.totalTaxRate	Number	Não	Percentual aproximado da carga tributária total.
customTax	Array	Sim	Lista de cenários tributários customizados (ao menos um).

Campos devolvidos apenas na consulta: id, status, errorMessage, createdAt e lastModified.

Valores de Origem (origin)

Enumerações trafegam pelo nome do valor. Na entrada o nome não diferencia maiúsculas de minúsculas (national também é aceito); a consulta devolve o nome como abaixo.

• National: 0 - Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8
• ForeignDirectImport: 1 - Estrangeira, importação direta, exceto a indicada no código 6
• ForeignInternalMarket: 2 - Estrangeira, adquirida no mercado interno, exceto a indicada no código 7
• NationalWith40To70Import: 3 - Nacional, com Conteúdo de Importação superior a 40% e inferior ou igual a 70%
• NationalPpb: 4 - Nacional, produzida conforme os processos produtivos básicos
• NationalWithLess40Import: 5 - Nacional, com Conteúdo de Importação inferior ou igual a 40%
• ForeignDirectImportWithoutNationalSimilar: 6 - Estrangeira, importação direta, sem similar nacional
• ForeignInternalMarketWithoutNationalSimilar: 7 - Estrangeira, adquirida no mercado interno, sem similar nacional
• NationalWithGreater70Import: 8 - Nacional, com Conteúdo de Importação superior a 70%

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

O array customTax define regras específicas por emitente (issuer), destinatário (recipient) e código de operação (operationCode). issuer e recipient são objetos (não listas):

{
  "issuer": { "taxRegime": "RealProfit", "taxProfile": "retail" },
  "recipient": { "taxProfile": "final_consumer_non_icms_contributor" },
  "operationCode": 121,
  "intrastate": { "cfop": 5102, "icms": { "cst": "00", "pICMS": "18.00" } }
}

Campo	Descrição
issuer.taxRegime	Regime tributário do emitente: NationalSimple, NationalSimpleSublimitExceeded, RealProfit, PresumedProfit, IndividualMicroEnterprise ou Exempt. Obrigatório; quando ausente, a API usa o regime da empresa informada em collectionId. ⚠️ Exempt é aceito no cadastro, mas o motor de cálculo não tem correspondência para emitente isento: a validação dos cenários falha (Unsupported issuer tax profile '...' with regime 'Exempt') e o produto fica em Error. Não use Exempt no emitente.
issuer.taxProfile	Perfil do emitente: retail, wholesale, industry, wholesale_industry ou importer (ver compatibilidade com a origem abaixo).
recipient.taxRegime	Regime tributário do destinatário (mesmos valores de issuer.taxRegime). Opcional.
recipient.taxProfile	Perfil do destinatário (ex.: final_consumer_non_icms_contributor, final_consumer_icms_contributor, retail, wholesale, industry, retail_branch, closed_warehouse). Quando ausente, a API usa final_consumer_non_icms_contributor.
operationCode	Código da operação (número inteiro). Quando ausente, a API usa 120 se issuer.taxProfile for industry e 121 nos demais casos.
intrastate	Valores para operação dentro do estado.
interstate	Valores para operação entre estados.

Regras de validação do cenário

Um cadastro que viola qualquer regra abaixo é recusado com 400:

1. Unicidade: cada combinação de issuer.taxRegime + issuer.taxProfile + recipient.taxRegime + recipient.taxProfile + operationCode aparece uma única vez.
2. Regime do emitente: issuer.taxRegime é obrigatório em todo cenário.
3. Perfil do emitente compatível com a origem:
   • retail e wholesale: origens National, ForeignInternalMarket, NationalWith40To70Import, NationalPpb, NationalWithLess40Import, ForeignInternalMarketWithoutNationalSimilar e NationalWithGreater70Import;
   • industry e wholesale_industry: origens nacionais National, NationalWith40To70Import, NationalPpb, NationalWithLess40Import e NationalWithGreater70Import;
   • importer: origens ForeignDirectImport e ForeignDirectImportWithoutNationalSimilar;
   • qualquer outro valor é recusado.
4. Grupo de operação: todo cenário tem ao menos intrastate ou interstate.
5. CST do ICMS: 3 dígitos (CSOSN) quando issuer.taxRegime é NationalSimple; 2 dígitos nos demais regimes.
6. CFOP compatível com o operationCode (quando o cfop é informado):

operationCode	CFOP em intrastate	CFOP em interstate
120 (venda de produção própria)	5101, 5103, 5105, 5106, 5111, 5113, 5118, 5122, 5401, 5402	6101, 6103, 6105, 6107, 6109, 6111, 6113, 6116, 6118, 6123
121 (venda de mercadoria de terceiros)	5102, 5104, 5106, 5110, 5112, 5114, 5115, 5117, 5119, 5120, 5123, 5403, 5405, 5409	6102, 6104, 6106, 6108, 6110, 6112, 6114, 6115, 6117, 6119, 6120, 6123, 6403
466 (devolução)	5202, 5411, 7202	6202, 6411, 7202
727, 784, 802 (remessa e retorno de armazém)	5949, 1949	não aceito
1108, 2108, 3108 (transferência com crédito de ICMS)	sem verificação	sem verificação (a API pode sobrescrever; veja abaixo)

Com cfop informado, um operationCode fora desta tabela é recusado.

Valores preenchidos automaticamente

A API aplica os ajustes abaixo em customTax, antes da validação, tanto na criação quanto no PUT.

• Cenários de remessa: a API acrescenta os cenários 727 (CFOP 5949), 784 (CFOP 1949) e 802 (CFOP 5949), só com intrastate e para o destinatário closed_warehouse, quando todas as condições valem: nenhum cenário tem emitente NationalSimple (os demais regimes, inclusive NationalSimpleSublimitExceeded, não impedem); há ao menos um cenário de venda (120 ou 121); e o produto tem um único cenário ou tem ao menos um cenário de transferência (1108, 2108 ou 3108) com interstate. Os cenários acrescentados copiam o emitente e o CST de ICMS do último cenário da lista que tem intrastate (sem nenhum intrastate, ficam sem emitente e a requisição falha). Eles são acrescentados mesmo que a lista já traga 727, 784 ou 802; se a combinação se repetir, o cadastro é recusado pela regra de unicidade.
• Transferência com crédito de ICMS (1108, 2108, 3108): em cada cenário de transferência que tenha interstate, a API sobrescreve o interstate.cfop (6151 quando o perfil do emitente é industry, 6152 nos demais) e troca o recipient por { "taxProfile": "retail_branch" } (um recipient.taxRegime enviado é descartado). Em 2108 e 3108 também define interstate.icms.cst = 90 (em 2108, ainda interstate.icms.modBC = 3), o que exige o grupo interstate.icms. Esse ajuste não acontece quando o produto tem um único cenário e ele é de transferência sem intrastate, nem, na ordem da lista, a partir do primeiro cenário com emitente NationalSimple (inclusive). Os cenários 2108 e 3108 são ativados sem a validação tributária em segundo plano.
• Customização de CST 20 (somente em contas com a customização habilitada): quando há um cenário de venda (120 ou 121) com intrastate.icms.cst = 20, a API, no primeiro cenário desse tipo, troca interstate.icms.cst por 00 e apaga interstate.icms.pICMS, modBC, pRedBC e pFCP (quando o grupo interstate.icms existe). Também copia pICMS, modBC, pRedBC e pFCP do intrastate.icms desse cenário para o intrastate.icms dos cenários 727, 784 e 802, inclusive os acrescentados automaticamente. Em contas sem a customização, nada disso acontece. Esse ajuste é pensado para operações cuja redução de base vale só dentro do estado; se a redução da sua operação também vale em operações interestaduais, não solicite a customização e envie o interstate com o CST e os valores corretos. A customização é habilitada pela NFE.io, a pedido do cliente; consulte o suporte para saber se está habilitada na sua conta.

Recomendação: nos cenários de transferência, envie cfop, recipient e icms explicitamente, com os valores que a sua operação exige. Assim o cadastro fica correto mesmo quando o ajuste automático não acontece; quando ele acontece, os valores acima prevalecem sobre os enviados.

Como funciona o "Match" do Cenário

Na emissão com o grupo taxDetermination, o sistema localiza o produto pela conta + collectionId (empresa emitente) + sku (código do item) + origin. Em seguida escolhe o cenário de customTax que corresponde à operação:

1. Emitente (issuer): o regime tributário e o perfil do emitente da nota correspondem a issuer.taxRegime e issuer.taxProfile?
2. Destinatário (recipient): o regime tributário e o perfil do destinatário correspondem a recipient.taxRegime e recipient.taxProfile?
3. Operação (operationCode): o código da operação corresponde?

Um critério não informado no cenário aceita qualquer valor. Vale o primeiro cenário da lista que corresponder.

Se houver correspondência, os valores de intrastate (operação dentro do estado) ou interstate (operação entre estados) são usados para preencher o item da nota, conforme Quando os valores são aplicados.

Se o produto for localizado mas não estiver com status Active, o cálculo é recusado com 400 (Product id '...' with sku '...' is not 'Active'). O produto não é ignorado.

Grupos de Impostos (intrastate / interstate)

Dentro de cada grupo é possível customizar:

• cfop: Código Fiscal de Operações e Prestações (número de 4 dígitos).
• icms: grupo de ICMS.
• pis: grupo de PIS (cst, pPIS). No cálculo, só a alíquota pPIS sobrepõe o motor, e apenas junto com a sobreposição do ICMS (veja Quando os valores são aplicados). O CST de PIS continua o do motor.
• cofins: grupo de COFINS (cst, pCOFINS). No cálculo, só a alíquota pCOFINS sobrepõe o motor, nas mesmas condições do PIS. O CST de COFINS continua o do motor.
• ipi: grupo de IPI (cst, pIPI). É gravado, mas não sobrepõe o cálculo.
• additionalInformation: informações adicionais do item (infAdProd) quando o cenário é usado.
• benefitCode: Código de Benefício Fiscal na UF (cBenef) do item neste cenário. É aplicado apenas junto com a sobreposição do ICMS: nos CST 20, 40 e 41, o código cadastrado substitui o sugerido pelo motor; nos CST 00 e 60, apenas a literal SEM CBENEF é aceita e o código herdado do motor é removido (um código real ali geraria a rejeição 928). Com CST 40 ou 41 cadastrado sem benefitCode, se o motor devolveu um código de benefício para o item, a API recusa o cálculo (422) com a instrução de preenchê-lo, em vez de deixar a nota consumir número e tomar a rejeição 930 ou 931 da SEFAZ. Nesse caso, cadastre o código da tabela da UF ou, se a UF não exigir código para o CST, a literal SEM CBENEF.

Os valores numéricos dos grupos de impostos são texto com ponto decimal (ex.: "18.00").

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 no cenário.
• issuerTaxProfile: corresponde ao issuer.taxProfile do cenário.
• buyerTaxProfile: corresponde ao recipient.taxProfile do cenário.
• origin: corresponde à origem da mercadoria.

Exemplo de taxDetermination na emissão:

"taxDetermination": {
  "operationCode": 121,
  "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. Os campos gravados compõem a regra customizada do cenário, e a forma como cada um entra no cálculo depende do CST. 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.

Quando os valores são aplicados

• CFOP: o CFOP do cenário substitui o do motor quando for diferente, exceto nos operationCode 783, 784, 9120 e 9121, em que o CFOP do motor é mantido.
• ICMS: os campos de ICMS só são aplicados quando o cst cadastrado difere do CST devolvido pelo motor, ou quando o pICMS cadastrado difere do devolvido (a sobreposição do ICMS). Nesse caso, conforme o CST final:
  • CST 00, 40, 41 e 60: pICMS e modBC;
  • CST 20: pICMS, modBC, pRedBC, pFCP, motDesICMS e indDeduzDeson;
  • demais CST: apenas o CST é trocado; os valores continuam os do motor;
  • no Simples Nacional, apenas o CSOSN é trocado.
• PIS e COFINS: nos CST 00, 20, 40, 41 e 60, as alíquotas pis.pPIS e cofins.pCOFINS cadastradas também são aplicadas.
• benefitCode: também só dentro da sobreposição do ICMS, conforme descrito em Grupos de Impostos.
• additionalInformation: aplicado sempre que cadastrado.

Se o CST e o pICMS cadastrados forem iguais aos do motor, os demais campos do cenário (inclusive benefitCode, pPIS e pCOFINS) não são aplicados.

⚠️ Os campos de ICMS ST próprio (modBCST, pMVAST, pRedBCST, pICMSST e pFCPST) são aceitos na entrada, mas não são gravados no cadastro: são ignorados e não voltam na consulta.

Campos Disponíveis

Campo	Descrição	Tag SEFAZ
cst	CST do ICMS com 2 dígitos (ex.: 00, 20, 60) ou CSOSN com 3 dígitos no Simples Nacional (ex.: 102, 500).	CST
modBC	Modalidade de determinação da Base de Cálculo do ICMS.	modBC
pICMS	Alíquota do ICMS (%).	pICMS
pRedBC	Percentual de redução da Base de Cálculo do ICMS.	pRedBC
pFCP	Percentual do Fundo de Combate à Pobreza (FCP).	pFCP
modBCST	Aceito, mas não gravado (ignorado). Modalidade de determinação da BC do ICMS ST.	modBCST
pMVAST	Aceito, mas não gravado (ignorado). Percentual da Margem de Valor Adicionado ICMS ST.	pMVAST
pRedBCST	Aceito, mas não gravado (ignorado). Percentual de redução da BC do ICMS ST.	pRedBCST
pICMSST	Aceito, mas não gravado (ignorado). Alíquota do ICMS ST (%).	pICMSST
pFCPST	Aceito, mas não gravado (ignorado). Percentual do FCP retido por ST.	pFCPST
motDesICMS	Motivo da desoneração do ICMS.	motDesICMS
indDeduzDeson	Indica se o ICMS desonerado é deduzido do valor do item.	indDeduzDeson
vBCSTRet, pST, vICMSSubstituto, vICMSSTRet, vBCFCPSTRet, pFCPSTRet, vFCPSTRet	Valores de ST retido anteriormente (veja a nota sobre CST 60 abaixo).	mesmas tags

Campos fora desta lista (ex.: pDif, pCredSN, pICMSEfet) também não fazem parte do cadastro e são ignorados.

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 (POST /{tenantId}/products) com uma regra customizada para CST 20 em operações internas (intrastate) para um emitente do Lucro Real, varejista, vendendo mercadoria de terceiros (operationCode 121) para consumidor final. Como há um único cenário de venda, a API acrescenta os cenários de remessa 727, 784 e 802.

{
  "collectionId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "sku": "PROD-001",
  "origin": "National",
  "description": "Produto Exemplo com Redução de Base",
  "gtin": "7891234567895",
  "tax": {
    "ncm": "94036000"
  },
  "customTax": [
    {
      "issuer": {
        "taxRegime": "RealProfit",
        "taxProfile": "retail"
      },
      "recipient": {
        "taxProfile": "final_consumer_non_icms_contributor"
      },
      "operationCode": 121,
      "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"
        }
      }
    }
  ]
}

Resposta 201:

{ "id": "0f8fad5bd9cb469fa165708167f5a1b2" }

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"
      }
  }
  ...