Kalvi: IBS/CBS para serviços, sem virar tributarista

Desde 2026 a NFS-e do padrão nacional carrega o grupo de IBS e CBS: CST, cClassTrib, alíquotas e reduções. Errar esse grupo é o motivo mais comum de nota de serviço fora de conformidade. Esta API responde, a partir do item da LC 116, do regime do prestador, do município e da data de competência, qual CST e cClassTrib a nota deve levar, com que alíquota e por qual artigo. E valida a DPS antes de você transmitir, apontando as regras do padrão nacional que ela quebraria.

Como vai funcionar

1. Crie uma chave gratuita (200 chamadas por mês, sem cartão). Disponível no Sprint 2.
2. Instale o SDK kalvi-nfse ou chame a API por HTTP.
3. Chame classify com o item da LC 116, o regime e a competência; ou validate com o XML da DPS.

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-03-15" });
console.log(r.candidates[0].cClassTrib, r.tables_version); // 200029, 2026-11-03

O que a API devolve (e o que não devolve)

• Candidatos de CST e cClassTrib com justificativa e fonte (artigo da LC 214, nota técnica, tabela oficial), alíquotas vigentes na data e reduções aplicáveis.
• Em toda resposta: api_version e tables_version. Você sabe exatamente com que tabela a resposta foi dada.
• Não devolve a tabela inteira nem guarda o conteúdo das suas notas. Processamento em memória; só metadados de uso ficam registrados.
• Quando a fonte oficial não cobre o caso, a resposta diz unknown. Nunca chuta.

Estado atual

Sprint 1 (motor): /v1/classify cobre 20 itens da LC 116 nos 4 regimes e /v1/validate aplica 19 regras oficiais do grupo IBS/CBS mais as checagens de schema e de correlação. Chaves e verificador web no Sprint 2; lançamento previsto para 2026-10-23.

Endpoints já disponíveis: POST /v1/classify, POST /v1/validate, GET /v1/health, GET /v1/tables, GET /v1/tables/:version/changelog, GET /v1/openapi.json.