Documentação

API Finanseed

Motor tributário por API. Um endpoint de cálculo, doze tributos, e cada valor volta com o ID da regra aplicada e a citação legal que o sustenta.

Base URL

https://api.finanseed.com.br

Toda a superfície pública vive sob /v1. Dentro de /v1 o contrato só muda de forma aditiva: campos novos podem aparecer em respostas e payloads, mas nenhum campo existente muda de nome, tipo ou semântica. Qualquer mudança incompatível nasceria em /v2 — escreva seu cliente tolerando campos desconhecidos.

Autenticação em uma linha

Envie sua chave no header X-API-Key. Chaves fs_live_… são de produção (consomem cota); fs_test_… são de sandbox (não faturam, cortesia de 1.000 chamadas/mês). Detalhes em Autenticação.

Primeira chamada

Um ICMS-ST interestadual SP→MG. A resposta traz o valor devido, os componentes do cálculo em detalhes e a regra aplicada com citação legal:

Requisição

curl https://api.finanseed.com.br/v1/calculate \
  -H "X-API-Key: fs_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "tributo": "icms_st",
    "ncm": "22021000",
    "uf_origem": "SP",
    "uf_destino": "MG",
    "data_operacao": "2026-08-01",
    "valor_produto": "1000.00",
    "ipi": "100.00",
    "frete": "0",
    "despesas": "0"
  }'

Resposta · 200

{
  "tributo": "icms_st",
  "valor": "157.20",
  "regra": {
    "rule_id": "BR-MG-SP-NCM2202-ICMSST-v4.1",
    "citacao_legal": "Convênio ICMS 142/18; Decreto MG 48.xxx/2026",
    "vigente_de": "2026-01-01",
    "vigente_ate": null
  },
  "detalhes": {
    "base_calculo_st": "1540.00",
    "icms_proprio": "120.00",
    "icms_st": "157.20",
    "aliquota_interna": "18",
    "aliquota_interestadual": "12",
    "mva_aplicada": "40",
    "base_metodo": "mva"
  },
  "cached": false
}

Valores monetários e alíquotas trafegam como string decimal com ponto ("1000.00"), nunca como float — some com uma biblioteca decimal, não com aritmética binária.

Os três princípios do contrato

Fonte em cada campo. Toda resposta de cálculo carrega regra.rule_id, regra.citacao_legal e a vigência. A conferência é objetiva: ou o ato citado diz aquilo, ou não diz.
Vigência temporal. A data_operacao do payload decide qual versão da regra responde. Pergunte com a data da nota e receba a regra que valia naquele dia.
Sem resposta no chute (fail-inert). Regra inexistente responde 404; regra publicada cujo conteúdo não sustenta o cálculo, ou payload sem um campo material, responde 422 com o motivo. Alíquota nula jamais vira zero em silêncio.

Superfície da API

Endpoint	O que faz
POST /v1/calculate	Calcula um tributo — o dispatch é pelo campo `tributo` do payload. Referência
GET /v1/regras	Lista as regras aprovadas, com filtros e paginação. Referência
GET /v1/changelog	Publicações e supersessões recentes — inclusive retroativas. Referência
GET /v1/usage	Consumo da própria conta: totais, latência e chamadas recentes. Referência
GET /sandbox	Página pública para disparar chamadas reais com a sua chave, sem escrever código. Abrir

Além da API, o motor te avisa quando uma regra que você usa muda: webhook de mudança de regra com assinatura HMAC.

Latência

Meta de < 200 ms para o cálculo completo e < 5 ms em cache hit (resposta com cached: true). O cache respeita a vigência: a publicação de uma regra nova invalida as chaves do escopo afetado.