Classificar um serviço

POST/v1/classify

A partir do item da LC 116, do regime, do município e da competência, devolve os candidatos de CST e cClassTrib com justificativa, alíquotas vigentes, reduções e a fonte de cada regra.

TypeScript

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.candidates[0].cst, r.tables_version);

Python

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",
    },
    timeout=20,
)
r.raise_for_status()
d = r.json()
print(d["candidates"][0]["cClassTrib"], d["candidates"][0]["cst"], d["tables_version"])

bash

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"
  }'

Resposta

Capturada da API, recortada para caber na tela.

JSON

{
  "api_version": "1",
  "tables_version": "2026-11-03",
  "service_code": "04.01",
  "service_description": "Medicina e biomedicina.",
  "confidence": "high",
  "candidates": [
    {
      "cst": "200",
      "cClassTrib": "200029",
      "short_name": "Fornecimento dos serviços de saúde humana (Anexo III)",
      "confidence": "high",
      "reduction": { "ibs_pct": 60, "cbs_pct": 60, "article": "art. 130" },
      "rates_status": "applied",
      "rates": {
        "ibs_uf_pct": 0.1, "ibs_mun_pct": 0, "cbs_pct": 0.9,
        "effective": { "ibs_uf_pct": 0.04, "ibs_mun_pct": 0, "cbs_pct": 0.36 },
        "year": 2026, "test_phase": true
      }
    }
  ],
  "calendar": {
    "mandatory_from": "2026-10-01",
    "simples_mandatory_from": "2027-01-01",
    "mandatory_now": true
  }
}

O que saber antes de usar

service_code aceita o item da LC 116 (04.01) ou o código nacional de seis dígitos (040101).
tax_regime é SIMPLES_UNIFICADO, SIMPLES_REGIME_REGULAR, LUCRO_PRESUMIDO ou LUCRO_REAL.
Quando o item admite mais de um código, os outros vêm na mesma lista com confiança menor e a justificativa diz em que situação cada um vale.
Profissão regulamentada muda o resultado: mande provider_profile.regulated_profession para receber a redução do art. 127.
rates_status pode vir pending_regulation: em 2027 e 2028 ainda não há alíquota definida em lei para tudo, e nós não chutamos.

Lista de erros · Voltar à referência

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