Referência da API

Uma chamada devolve CST, cClassTrib, alíquotas vigentes, reduções e a fonte de cada regra. Outra confere a DPS antes de você transmitir. Toda resposta diz qual versão de tabela foi usada.

Começar em três passos

1. Crie a chave grátis: 200 chamadas por mês, sem cartão. Criar chave.
2. Guarde a chave em variável de ambiente. Ela é de servidor; não use no navegador.
3. Faça a primeira chamada.

npm i kalvi-nfse

import { Kalvi } from "kalvi-nfse";
const nfse = new Kalvi({ apiKey: process.env.KALVI_API_KEY });
const r = await nfse.classify({
  service_code: "04.01",
  tax_regime: "LUCRO_PRESUMIDO",
  municipality_code: "4113700",
  competence_date: "2026-11-10",
});
console.log(r.candidates[0].cClassTrib, r.tables_version); // 200029 2026-11-03

pip install requests

import os, requests
r = requests.post(
    "https://api.kalvi.com.br/v1/classify",
    headers={"Authorization": f"Bearer {os.environ['KALVI_API_KEY']}"},
    json={"service_code": "04.01", "tax_regime": "LUCRO_PRESUMIDO",
          "municipality_code": "4113700", "competence_date": "2026-11-10"},
)
print(r.json()["candidates"][0]["cClassTrib"])  # 200029

curl -s -X POST https://api.kalvi.com.br/v1/classify   -H "Authorization: Bearer $KALVI_API_KEY"   -H "Content-Type: application/json"   -d '{"service_code":"04.01","tax_regime":"LUCRO_PRESUMIDO","municipality_code":"4113700","competence_date":"2026-11-10"}'

Endpoints

• /v1/classify Classificar um serviço
• /v1/validate Validar uma DPS antes de transmitir
• /v1/account/usage Chave, limites e extrato
• /v1/tables Versões de tabela e o que mudou
• Erros formato único, lista de códigos e o que fazer com cada um

Autenticação

Chave no cabeçalho Authorization: Bearer kv_live_.... A chave completa aparece uma única vez, na criação; guardamos só o prefixo e um resumo criptográfico dela. Revogar é imediato: a chamada seguinte já recebe 401. Até três chaves ativas por conta.

Limites

Plano grátis: 200 chamadas por mês, sem cartão. Só chamada bem-sucedida conta; falha nossa não conta e aparece numa coluna separada do extrato. A partir de 80% toda resposta traz X-Plan-Usage; em 100% vem 429 QUOTA_EXCEEDED com o link para assinar. Existe também um limite de rajada, de 120 chamadas por minuto por chave, que devolve 429 RATE_LIMITED com Retry-After — esse o SDK repete sozinho.

Versionamento

A versão do contrato está na URL (/v1) e em api_version. As tabelas seguem data de vigência e aparecem em tables_version em toda resposta. Mudança de tabela não quebra o seu código; mudança de contrato ganharia /v2. Veja Tabelas e changelog.

Apoio técnico, não consultoria tributária. A responsabilidade pela nota é do emissor.