ICMS em detalhe · TF Fiscal API

O ICMS é o tributo mais pesado e mais intrincado do Brasil: cada um dos 27 estados legisla sua versão sobre mercadorias, transporte interestadual/intermunicipal e comunicação. É não cumulativo (crédito nas entradas), calculado por dentro (o imposto integra a própria base) e com muitas exceções estaduais: substituição tributária (ST), redução de base, diferimento, isenções e o diferencial de alíquotas (DIFAL).

Cálculo e alíquotas

Cálculo por dentro: base = preço (que já contém o ICMS) + frete + seguro + outras despesas − descontos; o IPI integra a base na venda a consumidor final. Uma alíquota nominal de 18% equivale a cerca de 21,95% sobre o preço líquido.
Alíquotas internas: fixadas por cada estado, em geral 17%–20% (SP 18%, RJ 20% mais 2% de FCP, MG 18%…); supérfluos como fumo, bebidas e cosméticos chegam a 25%–35%.
Alíquotas interestaduais: 12% em geral; 7% do Sul e Sudeste (exceto ES) para Norte, Nordeste, Centro-Oeste e ES; mercadoria importada (origem 1, 2, 3, 8) sempre 4%.
DIFAL: na venda interestadual a não contribuinte (pessoa física, empresa sem inscrição estadual), a diferença entre a alíquota interna do destino e a interestadual vai para o estado de destino, paga pelo vendedor; Simples (CRT 1 / 4) é dispensado (ADI 5469), CRT 2 / 3 deve calcular.
FCP (Fundo de Combate à Pobreza): alguns estados adicionam 1%–2% em certos produtos; na interestadual segue o DIFAL para o destino.
Substituição tributária (ST): para mercadorias listadas (identificadas pelo CEST), o ICMS de toda a cadeia é retido uma vez pelo fabricante ou importador sobre a base com MVA; a revenda usa CST 60 / CSOSN 500 e não destaca imposto.
Redução de base, isenção, diferimento, suspensão: concedidos por estado e produto, mapeados em CST 20 / 40 / 51 / 50 no regime normal; o Simples não tem esse detalhamento e usa CSOSN 400 / 300 para não tributada e imune.

O regime define CSOSN ou CST

CRT	Regime	Código ICMS	invoice_type da empresa	DIFAL
`1`	Simples Nacional	CSOSN · 3	`simples_nacional` / `1`	Dispensado
`2`	Simples Nacional, excesso de sublimite	CST · 2	`simples_nacional_excesso` / `2`	Devido
`3`	Regime normal (Lucro Real / Presumido)	CST · 2	`tributacao_normal` / `lucro_normal` / `3`	Devido
`4`	MEI	CSOSN · 3	`simples` / `4`	Dispensado

A plataforma valida localmente se o tamanho do código bate com o regime: CRT 1 / 4 enviando CST, ou CRT 2 / 3 enviando CSOSN, é recusado com o motivo e não é encaminhado (seria rejeitado com 590 / 591 e consumiria a cota do CNPJ). Sem validação quando invoice_type não está na tabela.

Simples Nacional: tabela de CSOSN

CRT 1 e 4. Envie 3 dígitos em icms.situacao_tributaria; os 10 são suportados.

CSOSN	Significado	Quando usar
`101`	Tributada pelo Simples com permissão de crédito	Venda a contribuinte do regime normal com transferência de crédito; informe `aliquota_credito` (1,25%–3,95% conforme a faixa).
`102`	Tributada pelo Simples sem permissão de crédito	Mais comum: venda a consumidor, não contribuinte, ou qualquer venda sem transferir crédito.
`103`	Isenção do ICMS para faixa de receita bruta	Quando o estado isenta as faixas iniciais de receita.
`201`	Com permissão de crédito e com cobrança do ICMS por ST	Venda com ST como substituto, transferindo crédito.
`202`	Sem permissão de crédito e com cobrança do ICMS por ST	Venda com ST como substituto; o caso mais comum.
`203`	Isenção para faixa de receita e com cobrança do ICMS por ST	103 combinado com ST.
`300`	Imune	Imunidade constitucional: livros, jornais, periódicos e seu papel; exportação.
`400`	Não tributada pelo Simples	Fora do ICMS: remessas sem venda (brinde, amostra, conserto).
`500`	ICMS cobrado anteriormente por ST ou por antecipação	Revenda de mercadoria com ST; com CFOP 5405 / 6404, opcionalmente os valores retidos (`v_bc_st_ret`, `v_icms_st_ret`).
`900`	Outros	Quando nada acima se aplica: importação, operações que exigem base e valor.

Regime normal: tabela de CST

CRT 2 e 3. Envie 2 dígitos em icms.situacao_tributaria; no XML a origem é prefixada. Os 15 são suportados.

CST	Significado	Quando usar
`00`	Tributada integralmente	Venda comum, a mais usada; informe `aliquota`.
`10`	Tributada e com cobrança do ICMS por ST	Venda com ST como substituto; informe `aliquota_mva`, `aliquota_icms_st`.
`20`	Com redução de base de cálculo	Redução de base concedida pelo estado; informe `aliquota_reducao` (% de redução).
`30`	Isenta ou não tributada e com cobrança do ICMS por ST	Operação própria isenta, com retenção do ST para a etapa seguinte.
`40`	Isenta	Isenta por lei estadual; pode levar `motivo_desoneracao` e `valor_desoneracao`.
`41`	Não tributada	Fora do campo do ICMS; usual em exportação.
`50`	Suspensão	Remessas temporárias: conserto, demonstração, industrialização por encomenda.
`51`	Diferimento	Imposto diferido; informe `aliquota_diferimento`.
`60`	ICMS cobrado anteriormente por substituição tributária	Revenda de mercadoria com ST; com CFOP 5405 / 6404.
`70`	Com redução de base e cobrança do ICMS por ST	20 combinado com 10.
`90`	Outras	Quando nada acima se aplica.
`02` · `15` · `53` · `61`	Série de tributação monofásica sobre combustíveis	Só combustíveis (02 própria, 15 com retenção, 53 diferido, 61 cobrado anteriormente); informe `ad_rem_icms`.

Origem da mercadoria

Campo products[].origem, obrigatório nos dois regimes. Define a alíquota interestadual (4% para importados) e é o primeiro dígito do CST/CSOSN no XML.

Valor	Significado
`0`	Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8
`1`	Estrangeira, importação direta, exceto código 6
`2`	Estrangeira, adquirida no mercado interno, exceto código 7
`3`	Nacional, conteúdo de importação superior a 40% e até 70%
`4`	Nacional, produção conforme processos produtivos básicos
`5`	Nacional, conteúdo de importação até 40%
`6`	Estrangeira, importação direta, sem similar nacional (lista CAMEX)
`7`	Estrangeira, adquirida no mercado interno, sem similar nacional (lista CAMEX)
`8`	Nacional, conteúdo de importação superior a 70%

Campos da plataforma (linha icms[] da categoria / impostos.icms inline)

Campo	Finalidade
`cenario` · `tipo_pessoa`	Chaves da linha: cenário e tipo de pessoa, veja abaixo.
`codigo_cfop` · `situacao_tributaria`	CFOP e CST/CSOSN; obrigatórios.
`aliquota`	Alíquota do ICMS (%).
`aliquota_reducao`	% de redução de base (CST 20 / 70).
`aliquota_fcp`	Alíquota do FCP (%).
`aliquota_mva` · `aliquota_icms_st` · `aliquota_reducao_st` · `aliquota_fcp_st`	Ao reter ST como substituto: MVA, alíquota do ST, redução de base do ST, FCP-ST (CST 10 / 30 / 70, CSOSN 201 / 202 / 203).
`v_bc_st_ret` · `v_icms_st_ret` · `v_icms_substituto` · `p_fcp_st_ret` · `v_bc_fcp_st_ret` · `v_fcp_st_ret`	Na revenda com ST (CST 60 / CSOSN 500): base e valores retidos anteriormente.
`aliquota_credito`	Alíquota de crédito transferida ao comprador no Simples (CSOSN 101 / 201).
`aliquota_diferimento`	% de diferimento (CST 51).
`motivo_desoneracao` · `valor_desoneracao`	Motivo da desoneração e valor desonerado (CST 40 / 41 / 50 / 90).
`beneficio_fiscal[]`	Códigos de benefício fiscal por estado: `[{"estado":"SP","codigo":"SP800001"}]`, gravados em cBenef no XML.
`disable_difal` · `difal_desconta_icms_inter` · `difal_base_por_dentro` · `v_bc_uf_dest`	Controles do DIFAL: desligar; base dupla “por dentro” descontando o ICMS interestadual (método da maioria dos estados); ou informar a base do destino diretamente.
`desconta_icms_pis_cofins`	Se true, subtrai o ICMS do item da base de PIS/COFINS (STF, Tema 69).

Cenários e tipo de pessoa na categoria

cenario	Significado
`saida_dentro_estado`	Saída, destinatário no mesmo estado
`saida_fora_estado`	Saída, destinatário em outro estado
`entrada_dentro_estado`	Entrada, outra parte no mesmo estado
`entrada_fora_estado`	Entrada, outra parte em outro estado
`padrao`	Linha padrão quando nenhum cenário bate

Ordem: cenário atual → padrao → legado saida_dentro_estado / saida_fora_estado; cada passo filtra antes por tipo_pessoa (fisica / juridica).
Venda interestadual a pessoa física exige a linha saida_fora_estado + fisica com CFOP 6108 e códigos; senão usa a linha de pessoa jurídica.
Importação (transaction_type = 2) ignora cenário, usa o primeiro registro e prefere CFOP 3.xxx; exportação (= 3) ignora tipo_pessoa.
Sem linha compatível a emissão falha e o erro indica o cenario e o tipo_pessoa faltantes.

Combinações recomendadas

Operação	Simples Nacional (CRT 1 / 4)	Regime normal (CRT 3)
Venda comum	CSOSN `102`（`101` + `aliquota_credito`）	CST `00` + `aliquota`
Revenda com ST retida	CSOSN `500` · CFOP 5405 / 6404	CST `60` · CFOP 5405 / 6404
Retenção de ST como substituto	CSOSN `202` / `201` · MVA	CST `10` · MVA
Venda interestadual a pessoa física (B2C)	CSOSN `102` · CFOP 6108 · 免 DIFAL	CST `00` · CFOP 6108 · DIFAL + FCP
Remessa sem venda (brinde, amostra, conserto…)	CSOSN `400`	CST `41`（送修 `50`）
Exportação	CSOSN `300` · CFOP 7101 / 7102	CST `41` · CFOP 7101 / 7102
Entrada de importação	CSOSN `900` · CFOP 3102	CST `00` · CFOP 3102

Alíquotas, benefícios e listas de ST são definidos por cada estado e mudam com frequência; os valores aqui são os usuais, prevalecendo o contador e a legislação do estado. Para o CFOP veja “CFOP por cenário”.