Documentação — Fiscum Developers

Início rápido

Faça a primeira chamada à API em menos de 5 minutos. Exemplos em cURL, Node.js, Python e PHP.

Começar →

API Reference

Referência completa de todos os endpoints, parâmetros, tipos de retorno e exemplos de requisição.

Ver endpoints →

Guias temáticos

Configurando webhooks, processando batches grandes, compatibilidade com a Reforma Tributária.

Ver guias →

Início rápido

Para fazer a primeira chamada você precisa de: 1) uma conta Fiscum (trial gratuito de 7 dias sem cartão) e 2) sua API Key no painel em Configurações → API Keys.

Sandbox disponível gratuitamente. Todas as consultas no ambiente de homologação usam dados reais sem cobrança. Acesse em https://sandbox.api.fiscum.com.br/v1.

Primeira requisição — cURL

CURL

curl -X POST https://api.fiscum.com.br/v1/regras-fiscais \
  -H "X-API-Key: fsc_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "cabecalho": {
      "cnpj": "12345678000190",
      "cnae": "4711302",
      "crt": 3,
      "regimeTrib": "R",
      "amb": 1,
      "contribuinte": 1,
      "ufOrigem": "SP"
    },
    "uf": ["SP", "MG"],
    "produto": [
      {
        "codigo": "7891000315507",
        "descricao": "NESCAFE CAFE SOLUVEL 100G",
        "ncm": "21011110",
        "tipoCodigo": 0
      }
    ]
  }'
          

Resposta esperada

JSON · 200 OK · 45ms

{
  "cabecalho": {
    "cnpj": "12345678000190",
    "regimeTrib": "R",
    "crt": 3,
    "mensagem": "OK",
    "versao": "1.0.0"
  },
  "grupo": [{
    "ncm": "21011110",
    "descricaoNcm": "Café solúvel, mesmo descafeinado",
    "piscofins": {
      "cstEnt": "50", "cstSai": "01",
      "aliqPIS": 1.65, "aliqCOFINS": 7.6
    },
    "ipi": { "aliqIPI": 0, "ex": "", "codenq": "999" },
    "cbs": { "aliquota": 0, "pAliqEfetiva": 0 },
    "ibs": { "ibsUF": 0, "ibsMun": 0 },
    "ibptax": {
      "federal_nacional": 16.00, "federal_importados": 20.48,
      "estadual": 18.00, "municipal": 0, "carga_total": 34.00
    },
    "regra": [{
      "uf": "SP", "cst": "00",
      "aliqicms": 18, "reducaobcicms": 0,
      "cfopCompra": "1102", "cfopVenda": "5102",
      "cestId": "1700100", "fcp": 0,
      "antecipado": "N", "desonerado": "N"
    }],
    "produto": [{
      "codigo": "7891000315507",
      "descricao": "NESCAFE CAFE SOLUVEL 100G"
    }]
  }],
  "baixaSimilaridade": [],
  "_fiscum": {
    "versao": "1.0.0",
    "totalGrupos": 1,
    "totalProdutos": 1,
    "latencia_ms": 45,
    "requestId": "req-abc123"
  }
}
          

Primeira requisição — Node.js

Node.js

const response = await fetch('https://api.fiscum.com.br/v1/regras-fiscais', {
  method: 'POST',
  headers: {
    'X-API-Key': 'fsc_live_SUA_CHAVE_AQUI',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cabecalho: {
      cnpj: '12345678000190',
      crt: 3,
      regimeTrib: 'R',
      amb: 1,
      contribuinte: 1
    },
    uf: ['SP'],
    produto: [{
      codigo: '7891000315507',
      descricao: 'NESCAFE CAFE SOLUVEL 100G',
      tipoCodigo: 0
    }]
  })
})

const data = await response.json()
console.log(data.grupo[0].regra)
          

Primeira requisição — Python

Python

import requests

response = requests.post(
    'https://api.fiscum.com.br/v1/regras-fiscais',
    headers={
        'X-API-Key': 'fsc_live_SUA_CHAVE_AQUI',
        'Content-Type': 'application/json'
    },
    json={
        'cabecalho': {
            'cnpj': '12345678000190',
            'crt': 3,
            'regimeTrib': 'R',
            'amb': 1,
            'contribuinte': 1
        },
        'uf': ['SP'],
        'produto': [{
            'codigo': '7891000315507',
            'descricao': 'NESCAFE CAFE SOLUVEL 100G',
            'tipoCodigo': 0
        }]
    }
)

data = response.json()
print(data['grupo'][0]['regra'])
          

Autenticação

Todas as requisições (exceto Health Check) exigem autenticação via API Key. Envie sua chave por um dos dois métodos abaixo.

Opção 1 — Header X-API-Key

Inclua sua API Key no header X-API-Key. Chaves de produção têm prefixo fsc_live_ e de sandbox fsc_test_.

HTTP HEADER

X-API-Key: fsc_live_SuaChaveDeProducaoAqui
// ou para sandbox:
X-API-Key: fsc_test_SuaChaveDeSandboxAqui

Opção 2 — Authorization Bearer

Alternativamente, envie a API Key no header Authorization com o prefixo Bearer.

HTTP HEADER

Authorization: Bearer fsc_live_SuaChaveDeProducaoAqui

Gerenciamento de chaves

Gere uma nova API Key via POST /v1/auth/api-key/gerar. A chave completa é exibida apenas uma vez na resposta. Para revogar, use DELETE /v1/auth/api-key/{id}.

Nunca exponha sua API Key no frontend. Todas as chamadas à API devem ser feitas no backend. Se sua chave for comprometida, rotacione imediatamente via POST /v1/auth/api-key/gerar (invalida a anterior automaticamente).

Base URL

Todas as URLs da API seguem o padrão https://{host}/v1/{recurso}.

Ambiente	Base URL	Prefixo da chave
Produção	`https://api.fiscum.com.br`	`fsc_live_`
Sandbox	`https://sandbox.api.fiscum.com.br`	`fsc_test_`

Sandbox

O ambiente de sandbox é idêntico ao de produção, com as seguintes diferenças:

Base URL: https://sandbox.api.fiscum.com.br
Use chaves com prefixo fsc_test_
Dados reais de regras fiscais, mas sem cobrança
Limites de rate limiting mais generosos para testes
No campo cabecalho.amb, envie 2 (homologação)

Sandbox gratuito. Não é necessário informar cartão de crédito. Crie sua conta e comece a testar imediatamente.

Rate limiting

A API utiliza token bucket por parceiro. O limite depende do plano contratado. Quando excedido, a API retorna HTTP 429 com o código RATE_LIMIT_EXCEEDED.

Dicas para lidar com rate limiting:

Implemente retry com backoff exponencial
Agrupe produtos na mesma requisição (até 500 por chamada)
Use o endpoint POST /v1/alterados para sincronização incremental em vez de reconsultar tudo
Aproveite o cache — respostas idênticas são cacheadas automaticamente

Endpoints — Classifica API

Base URL: https://api.fiscum.com.br/v1 · Sandbox: https://sandbox.api.fiscum.com.br/v1

Endpoints disponíveis

Autenticação

POST /v1/auth/api-key/gerar Rotaciona a API Key do parceiro. A chave anterior é invalidada.

DELETE /v1/auth/api-key/{id} Revoga a API Key do parceiro pelo ID (UUID).

Regras Fiscais

POST /v1/regras-fiscais Consulta principal. Até 500 produtos por chamada, todas as UFs. ICMS, PIS/COFINS, IPI, CBS e IBS.

POST /v1/alterados Produtos com regras alteradas desde a última consulta do CNPJ. Sincronização incremental.

NCM

GET /v1/ncm/{ncm} Informações completas de um NCM, incluindo TIPI e CEST vinculados.

GET /v1/ncm/{ncm}/validar Verifica se o NCM existe na base de dados atualizada.

POST /v1/ncm/sugerir Sugere NCMs a partir de descrição de produto, ordenados por relevância.

GET /v1/ncm/{ncm}/historico Histórico de mudanças regulatórias que afetaram as regras do NCM.

GET /v1/ncm/{ncm}/reforma Timeline CBS/IBS da Reforma Tributária 2026–2033 para o NCM.

GTIN

GET /v1/gtin/{gtin}/validar Valida o dígito verificador (check digit) de um GTIN/EAN.

GET /v1/gtin/{gtin}/enriquecer Busca NCM vinculado a um GTIN/EAN na base de dados.

POST /v1/gtin/bulk Enriquecimento GTIN para NCM em lote. Até 500 GTINs por chamada.

Calculadora

POST /v1/calcular/difal Cálculo de DIFAL para operações interestaduais a consumidor final.

POST /v1/calcular/icms-st Cálculo de ICMS-ST com MVA ajustado, base de cálculo e FCP-ST.

POST /v1/calcular/transparencia-fiscal Carga tributária detalhada conforme Lei 12.741/2012 (Lei de Olho no Imposto).

POST /v1/calcular/municipio Cálculo tributário por município (código IBGE), incluindo ICMS, FCP e ISS.

Changelog e Webhooks

GET /v1/changelog Alterações regulatórias paginadas (DOU, CONFAZ, SEFAZs). Filtros por UF, tipo, data e fonte.

POST /v1/webhooks/subscribe Inscreve endpoint para receber notificações push de mudanças regulatórias.

GET /v1/webhooks Lista todas as inscrições de webhook ativas da conta.

DELETE /v1/webhooks/{id} Remove uma inscrição de webhook.

Produto e Regime Especial

POST /v1/produto/classificar Classificação ABC de produto com carga tributária e sugestões de markup.

POST /v1/regime-especial/buscar Busca regimes especiais tributários por UF, com filtros por CNAE e tipo.

IBPT

GET /v1/ibpt/{ncm} Carga tributária IBPT por NCM. Com ?uf=XX retorna UF específica; sem filtro retorna todas as UFs.

Conta

GET /v1/status-cliente/{cnpj} Verifica se o cliente (parceiro) está ativo no sistema.

GET /v1/minha-conta/uso Métricas de uso da conta: requisições, limites e percentual utilizado.

Sistema

GET /v1/health Verificação de saúde do sistema. Não requer autenticação.

GET /v1/metrics Métricas operacionais: latência, cache hit rate, contadores e uptime.

POST /v1/regras-fiscais

Endpoint principal do Fiscum Classifica. Recebe uma lista de produtos (até 500) e UFs, e retorna as regras fiscais completas para emissão de NF-e/NFC-e: ICMS por UF, PIS/COFINS, IPI, CBS e IBS. Os produtos são agrupados por NCM na resposta.

Parâmetros do body (JSON)

O body JSON contém 3 campos obrigatórios: cabecalho, uf e produto.

cabecalho (object) — obrigatório

Campo	Tipo	Req.	Descrição
cnpj	string	required	CNPJ da empresa consulente (14 dígitos numéricos).
crt	integer	required	Código de Regime Tributário: 1 (Simples Nacional), 2 (excesso sublimite), 3 (Normal), 4 (MEI).
regimeTrib	string	required	Regime de tributação: "R" (Lucro Real), "P" (Lucro Presumido), "S" (Simples Nacional).
amb	integer	required	Ambiente: 1 (Produção), 2 (Homologação).
contribuinte	integer	required	Contribuinte ICMS do destinatário: 0 (Não), 1 (Sim).
cnae	string	optional	CNAE principal da empresa (7 dígitos).
ufOrigem	string	optional	UF de origem da mercadoria (2 letras).
dthr	string	optional	Data/hora da operação (ISO 8601). Default: data atual.
codFaixa	integer	optional	Código da faixa do Simples Nacional.
indicPresenca	integer	optional	Indicador de presença do comprador (campo indPres NF-e, 0 a 9).
finalidade	integer	optional	Finalidade da operação: 1 (Normal), 2 (Complementar), 3 (Ajuste), 4 (Devolução).
cnaeSecundario	string	optional	CNAE secundário da empresa (7 dígitos).
fabricacaoPropria	boolean	optional	Indica se o produto é de fabricação própria. Default: false.
regimeEspecial	string	optional	Código ou nome do regime especial aplicável (máx. 60 caracteres).
municipio	string	optional	Código IBGE do município (7 dígitos).
dia	integer	optional	Dia da operação (se informado separadamente de dthr).
mes	integer	optional	Mês da operação (se informado separadamente de dthr).
ano	integer	optional	Ano da operação (se informado separadamente de dthr).

uf (string[]) — obrigatório

Lista de UFs para consulta (siglas de 2 letras). Ex: ["SP", "MG"]. Mínimo 1 UF.

produto (object[]) — obrigatório (máx. 500)

Campo	Tipo	Req.	Descrição
codigo	string	required	Código do produto: GTIN/EAN, código interno ou NCM conforme tipoCodigo. Máx. 20 caracteres.
descricao	string	required	Descrição do produto (máx. 60 caracteres).
ncm	string	optional	NCM do produto (8 dígitos). Obrigatório se tipoCodigo = 2.
tipoCodigo	integer	optional	0 = GTIN/EAN (padrão), 1 = código interno (busca por descrição), 2 = NCM direto no campo ncm.
cest	string	optional	CEST do produto (7 dígitos), se conhecido.
curva	string	optional	Classificação ABC do produto: "A", "B" ou "C".
refeicao	string	optional	Indica se o produto é refeição: "S" ou "N" (padrão: "N").

Exemplo cURL

CURL

curl -X POST https://api.fiscum.com.br/v1/regras-fiscais \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "cabecalho": {
      "cnpj": "12345678000190",
      "cnae": "4711302",
      "crt": 3,
      "regimeTrib": "R",
      "amb": 1,
      "contribuinte": 1,
      "ufOrigem": "SP"
    },
    "uf": ["SP", "MG"],
    "produto": [
      {
        "codigo": "7891000315507",
        "descricao": "NESCAFE CAFE SOLUVEL 100G",
        "ncm": "21011110",
        "tipoCodigo": 0
      }
    ]
  }'
          

Códigos de retorno

Status	Descrição
`200`	Regras fiscais retornadas com sucesso.
`400`	Requisição inválida — dados de entrada não passaram na validação.
`401`	Credenciais ausentes ou inválidas.
`422`	Erro de validação com campo `detalhes` listando cada campo e mensagem.
`429`	Limite de requisições excedido.
`500`	Erro interno do servidor.

NCM

GET /v1/ncm/{ncm}

Retorna informações detalhadas do NCM, incluindo dados da TIPI (IPI) e CEST vinculados.

Parâmetro	Local	Tipo	Req.	Descrição
ncm	path	string	required	Código NCM (8 dígitos). Ex: 10063021

CURL

curl https://api.fiscum.com.br/v1/ncm/21011110 \ -H "X-API-Key: fsc_live_SUA_CHAVE"

GET /v1/ncm/{ncm}/validar

Verifica se o código NCM existe na base de dados atualizada.

JSON · 200 OK

{
  "ncm": "10063021",
  "valido": true,
  "descricao": "Arroz semibranqueado ou branqueado, parboilizado, polido ou brunido"
}
          

POST /v1/ncm/sugerir

Recebe uma descrição de produto e retorna sugestões de NCM ordenadas por relevância (busca por similaridade).

Campo	Tipo	Req.	Descrição
descricao	string	required	Descrição do produto para sugestão de NCM.

CURL

curl -X POST https://api.fiscum.com.br/v1/ncm/sugerir \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "descricao": "Arroz branco tipo 1 pacote 5kg" }'
          

JSON · 200 OK

{
  "descricao_pesquisada": "Arroz branco tipo 1",
  "total": 2,
  "sugestoes": [
    { "ncm": "10063021", "descricao": "Arroz semibranqueado ou branqueado...", "relevancia": 0.85 },
    { "ncm": "10063029", "descricao": "Outros arrozes semibranqueados...", "relevancia": 0.72 }
  ]
}
          

GET /v1/ncm/{ncm}/historico

Retorna o histórico de mudanças regulatórias que afetaram as regras fiscais deste NCM.

Parâmetro	Local	Tipo	Req.	Descrição
ncm	path	string	required	Código NCM (8 dígitos).
uf	query	string	required	UF para filtrar histórico de regras (2 letras).

CURL

curl "https://api.fiscum.com.br/v1/ncm/21011110/historico?uf=SP" \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

GET /v1/ncm/{ncm}/reforma

Retorna o cronograma de transição CBS/IBS (Reforma Tributária EC 132/2023) aplicável a este NCM, com alíquotas previstas por ano (2026–2033).

Parâmetro	Local	Tipo	Req.	Descrição
ncm	path	string	required	Código NCM (8 dígitos).
uf	query	string	required	UF para regras estaduais na timeline.

CURL

curl "https://api.fiscum.com.br/v1/ncm/21011110/reforma?uf=SP" \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

GTIN

GET /v1/gtin/{gtin}/validar

Verifica se o código GTIN/EAN possui dígito verificador válido. Aceita EAN-8, UPC-A, EAN-13 e GTIN-14.

CURL

curl https://api.fiscum.com.br/v1/gtin/7891000315507/validar \ -H "X-API-Key: fsc_live_SUA_CHAVE"

JSON · 200 OK

{ "gtin": "7891000315507", "valido": true, "formato": "EAN-13" }

GET /v1/gtin/{gtin}/enriquecer

Busca o NCM vinculado a um GTIN/EAN na base de dados, retornando informações do produto e da classificação fiscal.

CURL

curl https://api.fiscum.com.br/v1/gtin/7891000315507/enriquecer \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

POST /v1/gtin/bulk

Recebe uma lista de GTINs (até 500) e retorna o enriquecimento com NCM para cada um, em uma única requisição.

Campo	Tipo	Req.	Descrição
gtins	string[]	required	Lista de códigos GTIN/EAN (mín. 1, máx. 500).

CURL

curl -X POST https://api.fiscum.com.br/v1/gtin/bulk \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "gtins": ["7891000315507", "7894900011517", "7891234567890"]
  }'
          

Cálculos tributários

POST /v1/calcular/difal

Calcula o Diferencial de Alíquota (DIFAL) para operações interestaduais destinadas a consumidor final não contribuinte.

Campo	Tipo	Req.	Descrição
ncm	string	required	NCM do produto (8 dígitos).
uf_origem	string	required	UF de origem (2 letras).
uf_destino	string	required	UF de destino (2 letras).
valor	number	required	Valor da operação em R$.
crt	integer	required	Código de Regime Tributário (1, 2, 3 ou 4).
contribuinte	integer	required	Indicador de contribuinte ICMS (0=não, 1=sim).
importado	boolean	optional	Se o produto é importado (alíquota interestadual 4%). Default: false.

CURL

curl -X POST https://api.fiscum.com.br/v1/calcular/difal \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "ncm": "21011110",
    "uf_origem": "SP",
    "uf_destino": "MG",
    "valor": 1000.00,
    "crt": 3,
    "contribuinte": 0
  }'
          

POST /v1/calcular/icms-st

Calcula o ICMS Substituição Tributária para um produto, incluindo MVA ajustado, base de cálculo e valores de ST e FCP-ST.

Campo	Tipo	Req.	Descrição
ncm	string	required	NCM do produto (8 dígitos).
uf	string	required	UF (2 letras).
valor	number	required	Valor do produto em R$.
iva	number	required	IVA/MVA (%).

CURL

curl -X POST https://api.fiscum.com.br/v1/calcular/icms-st \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "ncm": "22021000", "uf": "SP", "valor": 500.00, "iva": 40.0 }'
          

POST /v1/calcular/transparencia-fiscal

Calcula o detalhamento da carga tributária conforme Lei 12.741/2012 (Lei de Olho no Imposto), retornando tributos federais, estaduais e municipais separadamente.

Campo	Tipo	Req.	Descrição
ncm	string	required	NCM do produto (8 dígitos).
uf	string	required	UF (2 letras).
valor	number	required	Valor do produto em R$.

CURL

curl -X POST https://api.fiscum.com.br/v1/calcular/transparencia-fiscal \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "ncm": "10063021", "uf": "SP", "valor": 25.90 }'
          

POST /v1/calcular/municipio

Calcula tributos aplicáveis em um município específico, incluindo ICMS, FCP e opcionalmente ISS (quando tipo_servico é informado). Utiliza o código IBGE do município.

Campo	Tipo	Req.	Descrição
ncm	string	required	NCM do produto (8 dígitos).
uf	string	required	UF (2 letras).
municipio_ibge	string	required	Código IBGE do município (7 dígitos).
valor	number	required	Valor da operação em R$.
tipo_servico	string	optional	Tipo do serviço (se informado, calcula ISS).

CURL

curl -X POST https://api.fiscum.com.br/v1/calcular/municipio \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "ncm": "10063021", "uf": "SP", "municipio_ibge": "3550308", "valor": 1000.00 }'
          

POST /v1/produto/classificar

Classifica um produto na Curva ABC com base no faturamento mensal (valor unitário x volume de vendas). Retorna a curva, sugestões de markup e frequência de reposição, além de dados de carga tributária do NCM informado.

Campo	Tipo	Req.	Descrição
codigo	string	required	Código do produto (máx. 60 caracteres).
descricao	string	required	Descrição do produto (máx. 500 caracteres).
ncm	string	required	NCM do produto (8 dígitos).
valor_unitario	number	required	Valor unitário em R$ (maior que 0).
volume_vendas_mensal	integer	required	Volume de vendas mensal (unidades).

CURL

curl -X POST https://api.fiscum.com.br/v1/produto/classificar \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "codigo": "PROD-001",
    "descricao": "ARROZ BRANCO TIPO 1 5KG",
    "ncm": "10063021",
    "valor_unitario": 25.90,
    "volume_vendas_mensal": 3000
  }'
          

POST /v1/regime-especial/buscar

Busca regimes especiais tributários disponíveis por UF, com filtros opcionais por CNAE e tipo de regime. Retorna benefícios fiscais, amparo legal e período de vigência.

Campo	Tipo	Req.	Descrição
uf	string	required	UF para buscar regimes especiais (2 letras).
cnae	string	optional	CNAE para filtrar regimes (7 dígitos).
tipo	string	optional	Tipo de regime para filtrar (máx. 100 caracteres).

CURL

curl -X POST https://api.fiscum.com.br/v1/regime-especial/buscar \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "uf": "SP", "cnae": "4711302" }'
          

GET /v1/changelog

Retorna a lista paginada de alterações regulatórias monitoradas pelo sistema (DOU, CONFAZ, SEFAZs, etc.), ordenadas da mais recente para a mais antiga.

Parâmetro	Local	Tipo	Req.	Descrição
page	query	integer	optional	Número da página. Default: 1.
limit	query	integer	optional	Itens por página (máx. 100). Default: 20.
uf	query	string	optional	Filtrar por UF (2 letras).
desde	query	string	optional	Data inicial (YYYY-MM-DD).
tipo	query	string	optional	Filtrar por tipo: icms, piscofins, ipi, cbs, ibs, cest.
fonte	query	string	optional	Filtrar por fonte: dou, confaz, nfe, ibpt.

CURL

curl "https://api.fiscum.com.br/v1/changelog?page=1&limit=20&uf=SP" \ -H "X-API-Key: fsc_live_SUA_CHAVE"

POST /v1/alterados

Retorna os produtos cujas regras fiscais foram alteradas desde a última consulta registrada para o CNPJ informado. Útil para sincronização incremental de regras no ERP do parceiro.

Campo	Tipo	Req.	Descrição
nomeServico	string	required	Deve ser "ALTERADOS".
dados	string	required	String no formato "CNPJ\|UF\|LIMITE". Ex: "12345678000190\|SP\|100".

CURL

curl -X POST https://api.fiscum.com.br/v1/alterados \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "nomeServico": "ALTERADOS", "dados": "12345678000190|SP|100" }'
          

Auth

POST /v1/auth/api-key/gerar

Gera uma nova API Key para o parceiro autenticado, invalidando a anterior. A chave completa é exibida apenas uma vez na resposta.

CURL

curl -X POST https://api.fiscum.com.br/v1/auth/api-key/gerar \
  -H "X-API-Key: fsc_live_SUA_CHAVE_ATUAL"
          

JSON · 201 Created

{
  "api_key": "fsc_live_YOUR_API_KEY_HERE",
  "prefix": "fsc_live_",
  "aviso": "Guarde esta chave com segurança. Ela não será exibida novamente."
}
          

DELETE /v1/auth/api-key/{id}

Revoga a API Key do parceiro. O parceiro só pode revogar sua própria chave. Após revogar, nenhuma requisição será possível até gerar uma nova chave.

Parâmetro	Local	Tipo	Req.	Descrição
id	path	string (UUID)	required	ID do parceiro cuja API key será revogada.

CURL

curl -X DELETE https://api.fiscum.com.br/v1/auth/api-key/00000000-0000-0000-0000-000000000000 \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

JSON · 200 OK

{ "mensagem": "API key revogada com sucesso" }

GET /v1/ibpt/{ncm}

Retorna a carga tributária estimada conforme tabela IBPT (Instituto Brasileiro de Planejamento e Tributação), utilizada para cumprimento da Lei da Transparência Fiscal (Lei n.o 12.741/2012). Possui dois modos de operação:

Com ?uf=SP — retorna os dados de carga tributária para a UF informada (objeto único).
Sem parâmetro uf — retorna os dados de todas as UFs disponíveis para o NCM.

Parâmetro	Local	Tipo	Req.	Descrição
ncm	path	string	required	Código NCM (8 dígitos).
uf	query	string	optional	UF para filtrar (2 letras). Se omitido, retorna todas as UFs.

Exemplo — consulta por UF

CURL

curl "https://api.fiscum.com.br/v1/ibpt/21011110?uf=SP" \ -H "X-API-Key: fsc_live_SUA_CHAVE"

JSON · 200 OK

{
  "ncm": "21011110",
  "uf": "SP",
  "descricao": "Café solúvel, mesmo descafeinado",
  "federal_nacional": 16.00,
  "federal_importados": 20.48,
  "estadual": 18.00,
  "municipal": 0.00,
  "carga_total_nacional": 34.00,
  "carga_total_importados": 38.48,
  "vigencia_ini": "2026-01-01",
  "vigencia_fin": "2026-06-30",
  "versao": "26.1.A",
  "fonte": "IBPT"
}
          

Exemplo — consulta todas as UFs

CURL

curl "https://api.fiscum.com.br/v1/ibpt/21011110" \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

JSON · 200 OK

{
  "ncm": "21011110",
  "total_ufs": 27,
  "dados": [
    {
      "uf": "SP",
      "federal_nacional": 16.00,
      "federal_importados": 20.48,
      "estadual": 18.00,
      "municipal": 0.00,
      "carga_total_nacional": 34.00,
      "carga_total_importados": 38.48,
      "vigencia_ini": "2026-01-01",
      "vigencia_fin": "2026-06-30",
      "versao": "26.1.A",
      "fonte": "IBPT"
    }
  ]
}
          

Conta

GET /v1/status-cliente/{cnpj}

Verifica se o cliente (parceiro) está ativo no sistema. Retorna sucesso: true se o CNPJ está cadastrado e ativo.

Parâmetro	Local	Tipo	Req.	Descrição
cnpj	path	string	required	CNPJ do cliente (14 dígitos).

CURL

curl https://api.fiscum.com.br/v1/status-cliente/12345678000190 \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

JSON · 200 OK

{ "sucesso": true, "mensagem": "OK" }

GET /v1/minha-conta/uso

Retorna as métricas de utilização da API no período corrente, incluindo total de requisições, limite do plano e percentual de uso.

CURL

curl https://api.fiscum.com.br/v1/minha-conta/uso \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

Sistema

GET /v1/health

Retorna o status dos componentes do sistema. Não requer autenticação. Retorna HTTP 200 se tudo estiver operacional, ou HTTP 503 se algum componente estiver degradado.

CURL

curl https://api.fiscum.com.br/v1/health

JSON · 200 OK

{
  "status": "ok",
  "version": "1.0.0",
  "db": "ok",
  "cache": "ok",
  "timestamp": "2026-04-15T13:00:00.000Z"
}
          

GET /v1/metrics

Retorna métricas operacionais do sistema: contadores de requisições, latência (avg/max/min/p95), taxa de cache hit e uptime. Requer autenticação.

CURL

curl https://api.fiscum.com.br/v1/metrics \
  -H "X-API-Key: fsc_live_SUA_CHAVE"
          

Objeto de resposta — POST /v1/regras-fiscais

A resposta do endpoint principal contém 4 campos de primeiro nível:

Campo	Tipo	Descrição
cabecalho	object	Metadados da consulta (CNPJ, regime, data, quantidade de produtos, versão, mensagem).
grupo	array	Grupos de regras fiscais agrupados por NCM. Cada grupo contém: ncm, descricaoNcm, piscofins, ipi, cbs, ibs, is, ibptax, regra (ICMS por UF) e produto.
baixaSimilaridade	array	Produtos cujo NCM não foi identificado, com o motivo da falha.
_fiscum	object	Metadados do Fiscum: versão, totais, latência, cache hits/misses, requestId.

Estrutura de grupo[].regra[] (ICMS por UF)

Campo	Tipo	Descrição
codigo	integer	Índice sequencial da regra no grupo.
uf	string	Sigla da UF.
cst	string	CST ICMS (Regime Normal).
cstDescr	string	Descrição do CST ICMS.
csosn	string	CSOSN (Simples Nacional).
csosnDescr	string	Descrição do CSOSN.
aliqicms	number	Alíquota ICMS (%).
baseCalculo	string	Base de cálculo.
reducaobcicms	number	Redução da base de cálculo ICMS (%).
aliqicmsst	number	Alíquota ICMS-ST (%).
reducaobcicmsst	number	Redução da base de cálculo ICMS-ST (%).
iva	number	MVA/IVA-ST (%).
fcp	number	Fundo de Combate à Pobreza (%).
cestId	string	Código CEST vinculado.
codBenef	string	Código do benefício fiscal.
pDifer	number	Percentual de diferimento (%).
antecipado	string	Indicador de antecipação tributária: "S" ou "N".
cfopCompra	string	CFOP sugerido para entrada.
cfopVenda	string	CFOP sugerido para saída.
desonerado	string	Indicador de desoneração ICMS: "S" ou "N".
icmsdeson	number	Valor do ICMS desonerado.
pICMSEfet	number	Percentual ICMS efetivo (%).
pRedBCEfet	number	Percentual de redução da BC efetiva (%).
percIsencao	number	Percentual de isenção (%).
estd_finalidade	string	Finalidade específica do estado.
excecao	number	Número da exceção aplicada.
adRemICMS	number	ICMS ad rem (monofásico) em R$.
motivoDesoneracao	string \| null	Motivo da desoneração.
IndicDeduzDesonerado	string	Indicador de dedução do ICMS desonerado.
pICMSPDV	number	Percentual ICMS para PDV.
simbPDV	string	Simbologia PDV (T=tributado, I=isento, F=substituído, N=nenhum).
ampLegal	string	Amparo legal da regra ICMS.
creditoIndicador	string	Indicador de crédito ICMS.
creditoCstEnt	string	CST de entrada para crédito.
creditoPercentual	number	Percentual de crédito.
dtVigIni	string \| null	Data de início da vigência.
dtVigFin	string \| null	Data de fim da vigência.
dtAtualizacao	string \| null	Data da última atualização (YYYY-MM-DD).

Estrutura de grupo[].piscofins

Campo	Tipo	Descrição
cstEnt	string	CST PIS/COFINS na entrada.
cstEntDescr	string	Descrição do CST de entrada.
cstSai	string	CST PIS/COFINS na saída.
cstSaiDescr	string	Descrição do CST de saída.
aliqPIS	number	Alíquota PIS (%).
aliqCOFINS	number	Alíquota COFINS (%).
baseCalculo	string	Base de cálculo.
nri	string	Natureza da receita (NRI).
ampLegal	string	Amparo legal.
creditoIndicadorPIS	string	Indicador de crédito PIS.
creditoCstEntPIS	string	CST de entrada para crédito PIS.
creditoPercentualPIS	number	Percentual de crédito PIS.
creditoIndicadorCOFINS	string	Indicador de crédito COFINS.
creditoCstEntCOFINS	string	CST de entrada para crédito COFINS.
creditoPercentualCOFINS	number	Percentual de crédito COFINS.
dtVigIni	string \| null	Data de início da vigência.
dtVigFin	string \| null	Data de fim da vigência.
dtAtualizacao	string \| null	Data da última atualização (YYYY-MM-DD).
refeicao	boolean	Indica se o tratamento monofásico de refeição foi aplicado.

Estrutura de grupo[].ipi

Campo	Tipo	Descrição
cstEnt	string	CST IPI na entrada.
cstEntDescr	string	Descrição do CST de entrada.
cstSai	string	CST IPI na saída.
cstSaiDescr	string	Descrição do CST de saída.
aliqIPI	number	Alíquota IPI (%).
baseCalculo	string	Base de cálculo.
codenq	string	Código de enquadramento IPI.
ex	string	Código EX da TIPI.
ampLegal	string	Amparo legal.
creditoIndicador	string	Indicador de crédito IPI.
creditoCstEnt	string	CST de entrada para crédito.
creditoPercentual	number	Percentual de crédito.
dtAtualizacao	string \| null	Data da última atualização (YYYY-MM-DD).

Estrutura de grupo[].cbs (Reforma Tributária)

Campo	Tipo	Descrição
cClassTrib	string	Código de classificação tributária CBS.
descrClassTrib	string	Descrição da classificação tributária.
cst	string	CST da CBS.
descrCST	string	Descrição do CST.
aliquota	number	Alíquota CBS (%).
pAliqEfetiva	number	Alíquota efetiva CBS (%).
reducao	number	Percentual de redução (%).
reducaoBcCBS	number	Redução da base de cálculo CBS (%).
ampLegal	string	Amparo legal.
dtVigIni	string \| null	Data de início da vigência.
dtVigFin	string \| null	Data de fim da vigência.
dtAtualizacao	string \| null	Data da última atualização (YYYY-MM-DD).

Estrutura de grupo[].ibs (Reforma Tributária)

Campo	Tipo	Descrição
cClassTrib	string	Código de classificação tributária IBS.
descrClassTrib	string	Descrição da classificação tributária.
cst	string	CST do IBS.
descrCST	string	Descrição do CST.
ibsUF	number	Alíquota IBS estadual (%).
ibsMun	number	Alíquota IBS municipal (%).
pAliqEfetivaUF	number	Alíquota efetiva IBS UF (%).
pAliqEfetivaMun	number	Alíquota efetiva IBS municipal (%).
reducaoAliqIBS	number	Redução da alíquota IBS (%).
reducaoBcIbs	number	Redução da base de cálculo IBS (%).
ampLegal	string	Amparo legal.
dtVigIni	string \| null	Data de início da vigência.
dtVigFin	string \| null	Data de fim da vigência.
dtAtualizacao	string \| null	Data da última atualização (YYYY-MM-DD).

Estrutura de grupo[].is (Imposto Seletivo)

O Imposto Seletivo (IS) incide sobre bens prejudiciais à saúde ou ao meio ambiente, conforme definido na Reforma Tributária (EC 132/2023).

Campo	Tipo	Descrição
cClassTrib	string	Código de classificação tributária IS.
descrClassTrib	string	Descrição da classificação tributária.
cst	string	CST do IS.
descrCST	string	Descrição do CST.
aliquota	number	Alíquota IS (%).
ampLegal	string	Amparo legal.
dtVigIni	string \| null	Data de início da vigência.
dtVigFin	string \| null	Data de fim da vigência.

Estrutura de grupo[].ibptax (Carga tributária IBPT)

Carga tributária estimada conforme tabela IBPT (Lei da Transparência Fiscal 12.741/2012), retornada automaticamente para cada grupo NCM.

Campo	Tipo	Descrição
federal_nacional	number	Carga tributária federal para produtos nacionais (%).
federal_importados	number	Carga tributária federal para produtos importados (%).
estadual	number	Carga tributária estadual (%).
municipal	number	Carga tributária municipal (%).
carga_total	number	Carga tributária total (%).

Webhooks

O Fiscum dispara webhooks em tempo real quando regras fiscais de NCMs monitorados são alteradas. Configure um endpoint HTTPS e receba o payload via POST.

Tipos de evento

Ao criar a inscrição via POST /v1/webhooks/subscribe, informe os tipos de evento desejados no campo eventos e, opcionalmente, filtre por UFs no campo ufs. O payload enviado é assinado com HMAC-SHA256.

regra_atualizada

Qualquer regra fiscal foi atualizada (evento genérico)

regra.icms.alterada

Regra de ICMS foi alterada (alíquota, CST, ST, benefício, etc.)

regra.piscofins.alterada

Regra de PIS/COFINS foi alterada

regra.ipi.alterada

Regra de IPI foi alterada

regra.cbs.alterada

Regra de CBS (Reforma Tributária) foi alterada

regra.ibs.alterada

Regra de IBS (Reforma Tributária) foi alterada

regra.cest.alterada

CEST vinculado foi alterado

ncm.adicionado

Novo NCM foi adicionado à base de dados

ncm.removido

NCM foi removido da base de dados

Inscrever webhook — exemplo

CURL

curl -X POST https://api.fiscum.com.br/v1/webhooks/subscribe \
  -H "X-API-Key: fsc_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhook/fiscum",
    "eventos": ["regra.icms.alterada", "ncm.adicionado"],
    "ufs": ["SP", "MG"]
  }'
          

JSON · 201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://meusite.com.br/webhook/fiscum",
  "eventos": ["regra.icms.alterada", "ncm.adicionado"],
  "ufs": ["SP", "MG"],
  "ativo": true,
  "mensagem": "Webhook criado com sucesso"
}
          

Payload de webhook recebido

Quando uma alteração regulatória ocorre, o Fiscum envia um POST para sua URL registrada com o payload abaixo. O header X-Fiscum-Signature contém o HMAC-SHA256 do body.

JSON · Webhook Payload

{
  "evento": "regra.icms.alterada",
  "data": "2026-04-15",
  "ncm": "22021000",
  "uf": "SP",
  "descricao": "Alíquota ICMS alterada de 18% para 20%",
  "fonte": "CONFAZ"
}
          

Verificação de assinatura HMAC

Cada webhook inclui o header X-Fiscum-Signature com HMAC-SHA256 do body usando seu webhook secret. Valide antes de processar.

Node.js · Verificação HMAC

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}
          

Python · Verificação HMAC

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
          

Códigos de erro

A API usa códigos HTTP convencionais. Erros retornam um objeto JSON com os campos erro (mensagem), codigo (código da aplicação) e requestId (para rastreamento junto ao suporte).

JSON · Exemplo de erro

{
  "erro": "Dados de entrada inválidos",
  "codigo": "VALIDATION_ERROR",
  "detalhes": [
    {
      "campo": "cabecalho.cnpj",
      "mensagem": "CNPJ deve conter exatamente 14 dígitos numéricos",
      "codigo": "invalid_string"
    }
  ],
  "requestId": "req-abc123"
}
          

400

Bad Request

Dados de entrada inválidos ou payload malformado. Código: VALIDATION_ERROR.

401

Unauthorized

API Key ausente ou inválida. Verifique o header X-API-Key ou Authorization Bearer. Código: AUTH_REQUIRED.

403

Forbidden

Conta desativada ou sem permissão para o recurso. Código: ACCOUNT_DISABLED.

404

Not Found

Recurso não encontrado (NCM inexistente, webhook inválido, etc.). Código: NOT_FOUND.

422

Validation Error

Erro de validação com campo detalhes listando cada campo e mensagem. Código: VALIDATION_ERROR.

429

Rate Limited

Limite de requisições excedido. Aguarde antes de tentar novamente. Código: RATE_LIMIT_EXCEEDED.

500

Internal Error

Erro interno do servidor. Nosso time é alertado automaticamente. Código: INTERNAL_ERROR.

SDKs e ferramentas

SDK Node.js

npm install @fiscum/sdk

TypeScript nativo. Auto-complete completo. Disponível em breve.

SDK Python

pip install fiscum-sdk

Async/await nativo. Type hints completos. Disponível em breve.

Postman Collection

26 endpoints · Exemplos · Testes · Ambientes

Coleção completa com todos os endpoints, exemplos de request/response, testes automatizados e ambiente de produção pré-configurado.

Run in Postman

Collection JSON Environment Produção

Documentação técnica

Início rápido

Primeira requisição — cURL

Resposta esperada

Primeira requisição — Node.js

Primeira requisição — Python

Autenticação

Opção 1 — Header X-API-Key

Opção 2 — Authorization Bearer

Gerenciamento de chaves

Base URL

Sandbox

Rate limiting

Endpoints — Classifica API

POST /v1/regras-fiscais

Parâmetros do body (JSON)

cabecalho (object) — obrigatório

uf (string[]) — obrigatório

produto (object[]) — obrigatório (máx. 500)

Exemplo cURL

Códigos de retorno

NCM

GET /v1/ncm/{ncm}

GET /v1/ncm/{ncm}/validar

POST /v1/ncm/sugerir

GET /v1/ncm/{ncm}/historico

GET /v1/ncm/{ncm}/reforma

GTIN

GET /v1/gtin/{gtin}/validar

GET /v1/gtin/{gtin}/enriquecer

POST /v1/gtin/bulk

Cálculos tributários

POST /v1/calcular/difal

POST /v1/calcular/icms-st

POST /v1/calcular/transparencia-fiscal

POST /v1/calcular/municipio

POST /v1/produto/classificar

POST /v1/regime-especial/buscar

GET /v1/changelog

POST /v1/alterados

Auth

POST /v1/auth/api-key/gerar

DELETE /v1/auth/api-key/{id}

GET /v1/ibpt/{ncm}

Exemplo — consulta por UF

Exemplo — consulta todas as UFs

Conta

GET /v1/status-cliente/{cnpj}

GET /v1/minha-conta/uso

Sistema

GET /v1/health

GET /v1/metrics

Objeto de resposta — POST /v1/regras-fiscais

Estrutura de grupo[].regra[] (ICMS por UF)

Estrutura de grupo[].piscofins

Estrutura de grupo[].ipi

Estrutura de grupo[].cbs (Reforma Tributária)

Estrutura de grupo[].ibs (Reforma Tributária)

Estrutura de grupo[].is (Imposto Seletivo)

Estrutura de grupo[].ibptax (Carga tributária IBPT)

Webhooks

Tipos de evento

Inscrever webhook — exemplo

Payload de webhook recebido

Verificação de assinatura HMAC

Códigos de erro

SDKs e ferramentas