Referência da API

Cálculo

Um endpoint para todos os tributos: o dispatch é pelo campo `tributo` do payload. Tributo novo entra como payload novo — a rota e o envelope de resposta não mudam.

POST/v1/calculate

Envelope de resposta

Idêntico para todo tributo:

Campo	Tipo	Descrição
tributo	string	Eco do discriminador do payload.
valor	decimal (string)	Montante devido do tributo.
regra	objeto	A prova de auditabilidade: `rule_id` (ID semântico, ex.: `BR-MG-SP-NCM2202-ICMSST-v4.1`), `citacao_legal`, `vigente_de` e `vigente_ate` (`null` = vigente).
detalhes	objeto	Campos específicos do tributo — os componentes do cálculo, documentados em cada seção abaixo. Novos campos podem ser adicionados; tolere desconhecidos.
cached	boolean	true quando a resposta veio do cache (mesma regra, mesma vigência).

Erros possíveis: 404 quando não há regra aprovada e vigente para os parâmetros; 422 quando o payload é inválido ou o cálculo é recusado com motivo (fail-inert). Ver Erros e limites.

Payloads por tributo

O campo tributo aceita: icms_st, icms, ipva, itcmd, iss, iptu, itbi, ipi, pis/cofins, cbs/ibs.

icms_st — ICMS Substituição Tributária

ICMS-ST em operação interestadual ou interna: base por MVA ajustada ou por pauta fiscal/PMPF, conforme a regra vigente.

Campo	Tipo	Descrição
ncm*	string	NCM com 8 dígitos, ex.: `"22021000"`.
uf_origem*	string	UF de origem, ex.: "SP".
uf_destino*	string	UF de destino, ex.: "MG".
data_operacao*	date	Data da operação — define a regra vigente.
valor_produto*	decimal (string)	Valor do produto (> 0).
ipi	decimal (string)	IPI destacado. Default 0.
frete	decimal (string)	Frete. Default 0.
despesas	decimal (string)	Despesas acessórias. Default 0.
quantidade	decimal (string)	Quantidade na unidade da pauta (litro/kg/unidade). Exigida quando a regra aplicável usa pauta fiscal/PMPF (base = valor de pauta × quantidade); sem ela a chamada recusa com 422. Ignorada nas regras só-MVA.

Exemplo de payload

{
  "tributo": "icms_st",
  "ncm": "22021000",
  "uf_origem": "SP",
  "uf_destino": "MG",
  "data_operacao": "2026-08-01",
  "valor_produto": "1000.00",
  "ipi": "100.00"
}

Campos de detalhes

base_calculo_st, icms_proprio, icms_st, aliquota_interna, aliquota_interestadual, mva_aplicada, base_metodo ("mva" ou "pauta" — qual base venceu) e, quando a regra modela o adicional, fcp_st (parcela do Fundo de Combate à Pobreza dentro do total — paridade com vFCPST/vICMSST da NF-e).

icms — ICMS próprio

ICMS da operação própria, interna (uf_origem == uf_destino) ou interestadual (alíquota da Resolução do Senado, com tabela assinada como autoridade).

Campo	Tipo	Descrição
uf_origem*	string	UF de origem.
uf_destino*	string	UF de destino — igual à origem é operação interna.
ncm	string	NCM de 8 dígitos (opcional): regra específica do produto vence a geral da UF.
valor_produto*	decimal (string)	Valor da operação com o imposto por dentro (LC 87/1996, art. 13).
frete	decimal (string)	Frete que integra a base. Default 0.
despesas	decimal (string)	Seguros, juros e demais. Default 0.
data_operacao*	date	Data da operação.
origem_mercadoria	"nacional" \| "importada"	Default `"nacional"`. `"importada"` aciona os 4% da Res. SF 13/2012 na interestadual.
destinatario_contribuinte	boolean	Default `true` (B2B revenda). `false` é DIFAL — fora do escopo atual, recusa 422 nomeada.
destinatario_consumidor_final	boolean	Default `false`. `true` recusa 422 nomeada (fase 2).
regime_simples_nacional	boolean	Default `false`. Optante do Simples recusa 422 nomeada — o DAS não sai daqui.

Exemplo de payload

{
  "tributo": "icms",
  "uf_origem": "SP",
  "uf_destino": "SP",
  "ncm": "22021000",
  "valor_produto": "1000.00",
  "data_operacao": "2026-08-01"
}

Na interestadual sem regra publicada para o par de UFs, o motor pode casar a regra interna da UF de origem (fallback documentado). O envelope diz qual caminho valeu em detalhes.regra_casada — e uma isenção interna não é importada para a saída interestadual.

Campos de detalhes

tipo_operacao, base_calculo, aliquota_aplicada, split valor_icms / valor_fcp (paridade com vICMS/vFCP da NF-e), isento (+ isencao_base_legal), regra_casada, citacao_interestadual e divergencia_interestadual.

ipva — IPVA

IPVA anual. A base é o valor venal informado — o motor não consulta FIPE.

Campo	Tipo	Descrição
uf*	string	UF de licenciamento.
categoria_veiculo*	enum	`automovel`, `motocicleta`, `caminhao`, `caminhonete`, `onibus_micro_onibus`, `locadora`, `taxi`, `pcd`.
valor_venal*	decimal (string)	Valor venal do veículo (base de cálculo).
data_fato_gerador*	date	Fato gerador (1º/jan do exercício) — define a vigência.
combustivel	enum	Opcional: `gasolina`, `etanol`, `flex`, `diesel`, `gnv`, `eletrico`, `hibrido`. Desambigua alíquota diferenciada (ex.: SP 3%).

Exemplo de payload

{
  "tributo": "ipva",
  "uf": "SP",
  "categoria_veiculo": "automovel",
  "valor_venal": "80000.00",
  "data_fato_gerador": "2026-01-01"
}

Campos de detalhes

valor_venal, aliquota_aplicada, categoria_veiculo, combustivel, isento e motivo_isencao.

itcmd — ITCMD / ITCD

Transmissão causa mortis e doação. Em MG o imposto se chama ITCD — o discriminador é o mesmo.

Campo	Tipo	Descrição
uf*	string	UF competente.
fato_gerador*	"causa_mortis" \| "doacao"	Natureza da transmissão.
valor_base*	decimal (string)	Valor venal transmitido (um quinhão, ou a doação acumulada da janela legal).
data_fato_gerador*	date	Óbito (saisine) ou doação.
valor_unidade_fiscal	decimal (string)	R$ de 1 UFESP/UFEMG no ano. Exigido quando a regra tem isenção ou faixas em unidades fiscais.

Exemplo de payload

{
  "tributo": "itcmd",
  "uf": "SP",
  "fato_gerador": "doacao",
  "valor_base": "150000.00",
  "data_fato_gerador": "2026-08-01",
  "valor_unidade_fiscal": "37.02"
}

Campos de detalhes

base, aliquota_aplicada, fato_gerador, isento (+ isencao_base_legal, limite_isencao) e, na progressividade, o detalhamento por faixas.

iss — ISS

Municipal: informe o município onde o ISS é devido (na construção civil, o da obra — LC 116, § 3º).

Campo	Tipo	Descrição
uf*	string	UF do município (desambigua homônimos).
municipio*	string	Nome oficial IBGE, ex.: `"São Paulo"`.
item_lista_servico*	string	Item da LC 116 na grafia `"1.05"`.
preco_servico*	decimal (string)	Preço do serviço (base do percentual).
data*	date	Data da prestação.
regime	"normal" \| "sociedade_uniprofissional"	Default `"normal"`.
numero_profissionais	int	Obrigatório no regime fixo (sociedade uniprofissional).

Exemplo de payload

{
  "tributo": "iss",
  "uf": "SP",
  "municipio": "São Paulo",
  "item_lista_servico": "1.05",
  "preco_servico": "24000.00",
  "data": "2026-08-01"
}

Campos de detalhes

preco_servico, aliquota_aplicada, item_lista_servico, regime, retido_na_fonte e, no regime fixo, numero_profissionais / periodicidade.

iptu — IPTU

Base = valor venal informado (o motor não calcula planta genérica de valores).

Campo	Tipo	Descrição
uf*	string	UF do município.
municipio*	string	Nome oficial IBGE.
uso_imovel*	"residencial" \| "nao_residencial" \| "territorial"	Uso do imóvel.
valor_venal*	decimal (string)	Valor venal (base de cálculo).
exercicio*	int	Exercício — fato gerador em 1º/jan.

Exemplo de payload

{
  "tributo": "iptu",
  "uf": "SP",
  "municipio": "São Paulo",
  "uso_imovel": "residencial",
  "valor_venal": "450000.00",
  "exercicio": 2026
}

Campos de detalhes

valor_venal_tributavel, modelo_progressividade, faixa_aplicada (+ aliquota, parcela_deduzir), imposto_bruto, excecoes_aplicadas e excecoes_nao_avaliadas.

itbi — ITBI

Transmissão onerosa de imóveis. Base default = valor da transação declarado (STJ Tema 1113).

Campo	Tipo	Descrição
uf*	string	UF do município.
municipio*	string	Nome oficial IBGE.
valor_transacao*	decimal (string)	Valor declarado da transmissão.
valor_venal_referencia	decimal (string)	Valor de referência do cadastro municipal (regras históricas).
financiado_sfh	boolean	Aquisição via SFH/PAR/HIS. Default `false`; `true` exige `valor_financiado > 0`.
valor_financiado	decimal (string)	Parcela financiada (não pode exceder o valor da transação).
data*	date	Data do fato gerador.

Exemplo de payload

{
  "tributo": "itbi",
  "uf": "SP",
  "municipio": "São Paulo",
  "valor_transacao": "600000.00",
  "data": "2026-08-01"
}

Campos de detalhes

base aplicada, alíquota, tratamento SFH e observações da regra municipal.

ipi — IPI

Primeiro federal do contrato: sem UF nem município — a regra da TIPI é nacional e quem a identifica é o NCM e, quando existe, o Ex tarifário.

Campo	Tipo	Descrição
ncm*	string	NCM com 8 dígitos, na grafia da TIPI.
ex	string	Ex tarifário, ex.: `"01"` (canonizado: `"1"` → `"01"`). Omitido resolve a linha-mãe; declarado sem regra própria cai na linha-mãe com `ex_aplicado=false`.
valor_produto*	decimal (string)	Valor da operação de que decorre a saída (CTN, art. 47, II).
frete	decimal (string)	Frete cobrado do comprador (RIPI, art. 190, § 1º). Default 0.
despesas	decimal (string)	Demais despesas acessórias debitadas. Default 0.
data_operacao*	date	Define a edição vigente da TIPI.

Exemplo de payload

{
  "tributo": "ipi",
  "ncm": "22021000",
  "valor_produto": "1000.00",
  "data_operacao": "2026-08-01"
}

Campos de detalhes

situacao (tributado | nao_tributado | aliquota_zero), aliquota_aplicada, base_calculo, ex_aplicado / ex_declarado e tabela_versao.

pis / cofins — PIS/PASEP e COFINS

Dois discriminadores ("pis" e "cofins") com o mesmo corpo: o par custa duas chamadas, porque cada contribuição tem regra, alíquota e citação próprias — e o envelope é singular por contrato.

Campo	Tipo	Descrição
regime_apuracao*	enum	`cumulativo` \| `nao_cumulativo` \| `simples`. Fato do contribuinte — o motor não infere. `simples` é vocabulário válido e responde 422 nomeado (as contribuições vão dentro do DAS).
ncm	string	Opcional — discrimina os regimes especiais (monofásico, alíquota zero); a regra ordinária do regime não tem NCM.
ex	string	Ex tarifário (mesmo eixo do IPI) — o regime de bebidas frias alcança `2106.90.10 Ex 02`, não o código-pai.
papel_na_cadeia	"fabricante_importador" \| "revenda"	Opcional; exigido quando a regra que casa é monofásica — o mesmo NCM é 2,32% para o fabricante e 0% para a revenda.
venda_a	"varejista_consumidor_final" \| "demais"	Opcional; exigido quando a regra discrimina o comprador (Lei 13.097/2015, art. 25, § 1º reduz a alíquota em ~20% na venda a varejista/consumidor final).
destinacao_autopropulsado	boolean	Autopeças dos Anexos I/II da Lei 10.485/2002: quando o NCM tem regra-marcadora, `false` destrava o cálculo ordinário; `true` ou ausência respondem 422 nomeado.
valor_operacao*	decimal (string)	Receita da operação, líquida de desconto incondicional.
valor_icms_destacado*	decimal (string)	ICMS destacado no documento — excluído da base (Tema 69/Lei 14.592). Obrigatório; zero explícito é legítimo (serviço, exportação). Omitir inflaria a base.
data_operacao*	date	Define a regra vigente.

Exemplo de payload

{
  "tributo": "pis",
  "regime_apuracao": "nao_cumulativo",
  "ncm": "25232910",
  "papel_na_cadeia": "fabricante_importador",
  "valor_operacao": "10000.00",
  "valor_icms_destacado": "1800.00",
  "data_operacao": "2026-08-01"
}

Campos de detalhes

situacao (tributado | aliquota_zero | monofasico_revenda), regime_apuracao, papel_na_cadeia, venda_a, motivo_zero quando o zero é legítimo, e o eco dos eixos declarados (ex_aplicado, destinacao_autopropulsado).

cbs / ibs — Reforma tributária (ano-teste 2026)

CBS (0,9%) e IBS (0,1%) da LC 214/2025 em cálculo paralelo ao regime atual. Dois discriminadores, mesmo corpo, contrato estrito (campo desconhecido recusa) — sem UF nem município: em 2026 não há alíquota por ente.

Campo	Tipo	Descrição
valor_operacao*	decimal (string)	Valor com ICMS/ISS/PIS/COFINS por dentro e sem CBS/IBS (tributo "por fora" — art. 12 da LC 214/2025).
valor_icms*	decimal (string)	ICMS da operação, incluído o retido por ST. Se não incide, declare `0` — omitir recusa.
valor_iss*	decimal (string)	ISS da operação. Declare `0` se não incide.
valor_pis*	decimal (string)	PIS/Pasep da operação. Declare `0` se não incide.
valor_cofins*	decimal (string)	COFINS da operação. Declare `0` se não incide.
valor_ipi*	decimal (string)	IPI destacado — exclusão permanente da base (art. 12, § 2º, II).
cumpre_obrigacoes_acessorias*	boolean	Condição da dispensa do recolhimento (art. 348, § 1º). Sem default — fato do contribuinte.
optante_simples*	boolean	`true` recusa com 422 nomeado: a lei afasta o optante do ano-teste.
ncm	string	Opcional — endereça a lista de recusa de regimes diferenciados (ex.: alíquota zero, redução de 60%).
item_lista_servico	string	Opcional — mesmo papel do NCM para serviços.
data_operacao*	date	Fora de 2026 não há regra do ano-teste (404).

Exemplo de payload

{
  "tributo": "cbs",
  "valor_operacao": "1000.00",
  "valor_icms": "180.00",
  "valor_iss": "0",
  "valor_pis": "16.50",
  "valor_cofins": "76.00",
  "valor_ipi": "0",
  "cumpre_obrigacoes_acessorias": true,
  "optante_simples": false,
  "data_operacao": "2026-09-01"
}

valor é o montante devido — que pode ser R$ 0,00 quando há dispensa do recolhimento. O destaque no documento fiscal continua obrigatório: use detalhes.valor_destaque, sempre presente, e detalhes.motivo_dispensa nomeia o dispositivo.

Campos de detalhes

valor_destaque, valor_devido, dispensado, dispensa_presumida, motivo_dispensa, base_calculo e aliquota_aplicada.

Convenções que valem para todos

Decimais viajam como string com ponto ("1000.00"); datas em ISO 8601 ("2026-08-01"); UFs em sigla maiúscula.
Campos com default podem ser omitidos; zero explícito e ausência são coisas diferentes onde o contrato diz que são (PIS/COFINS, CBS/IBS).
A resposta de um payload idêntico é estável dentro da mesma vigência — mudança de resultado implica regra nova, visível no GET /v1/changelog e no webhook.