kalvi-nfse
v0.1.1
Published
SDK TypeScript para a API Kalvi: classificação e pré-validação de NFS-e para IBS/CBS (CST, cClassTrib, alíquotas, rejeições). Plano gratuito de 200 chamadas/mês, sem cartão.
Maintainers
Readme
kalvi-nfse
CST, cClassTrib, alíquotas e pré-validação de NFS-e para IBS/CBS, em cinco linhas.
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);
// 200029 200 2026-10-11Crie sua chave grátis: 200 chamadas por mês, sem cartão. Criar chave · Documentação
Sem programar? Cole ou envie as notas (.xml, .json ou .zip) no verificador: 3 por dia sem cadastro, 20 por mês com a conta grátis.
npm i kalvi-nfseNode 18 ou mais novo. Sem dependências. Use no servidor: a chave não deve ir para o navegador.
O que ele faz
| Método | Para quê |
| -------------------------------------- | -------------------------------------------------------------------------------------- |
| classify(input) | candidatos de CST e cClassTrib com justificativa, cIndOp, alíquotas, reduções e fontes |
| validate(xmlOuObjeto) | confere uma DPS antes de transmitir e devolve os problemas por severidade |
| validateMany(notas) | o mesmo para um lote de até 50 notas |
| tables.list() · tables.changelog() | versões de tabela servidas e o que mudou em cada uma |
| account.usage() | extrato do mês: quantas contaram e quantas não foram cobradas |
O SDK não tem regra tributária dentro: tudo vem da API, e toda resposta traz tables_version, a data de vigência da tabela usada. Quando as tabelas oficiais mudam, seu código não muda.
Validar antes de transmitir
const r = await nfse.validate(xmlDaDps);
for (const issue of r.issues) {
console.log(issue.severity, issue.code, issue.message, "→", issue.fix);
}
// blocking E0958 cClassTrib para IBS/CBS incorreto... → Use /v1/classify para o candidato do seu item.severity é blocking (a nota não passa), likely_rejection (deve ser rejeitada) ou warning. code é o código oficial da NFS-e nacional quando existe (issue.official === true).
Erros
import { KalviError, KalviNetworkError } from "kalvi-nfse";
try {
await nfse.classify(entrada);
} catch (e) {
if (e instanceof KalviError && e.isQuotaExceeded) {
console.log("Limite do mês:", e.upgradeUrl, "zera em", e.resetsAt);
} else if (e instanceof KalviError) {
console.log(e.code, e.message, "request_id:", e.requestId);
} else if (e instanceof KalviNetworkError) {
console.log("A API não respondeu depois de", e.attempts, "tentativas");
}
}Guarde o request_id: ele identifica a chamada nos nossos registros. Códigos usados com frequência: UNAUTHORIZED, INVALID_INPUT, PARSE_ERROR, PAYLOAD_TOO_LARGE, RATE_LIMITED, QUOTA_EXCEEDED.
Repetição automática
Falha nossa (5xx), rajada (RATE_LIMITED) e erro de rede são repetidos sozinhos, com espera crescente e respeitando o Retry-After. Erro de entrada (4xx) e limite do mês (QUOTA_EXCEEDED) não são repetidos: repetir não ajudaria. Ajuste com maxRetries no construtor ou por chamada.
Quanto já foi do plano
const nfse = new Kalvi({
onPlanUsage: (u) => console.warn(`${u.used}/${u.limit} chamadas; zera em ${u.resets}`),
});A API manda o aviso a partir de 80% do limite; o último valor fica em nfse.lastPlanUsage. Só classify, validate e validateMany consomem o plano, e só a chamada que devolveu resultado ou erro de entrada conta. Falha nossa não conta e aparece em account.usage() numa coluna separada.
Opções
| Opção | Padrão | Para quê |
| ------------- | ---------------- | --------------------------------------------- |
| apiKey | KALVI_API_KEY | sua chave |
| baseUrl | KALVI_BASE_URL | outra instância da API (staging, por exemplo) |
| timeoutMs | 20000 | tempo máximo por tentativa |
| maxRetries | 2 | tentativas extras |
| fetch | o fetch global | proxy ou cliente HTTP próprio |
| onPlanUsage | — | aviso de consumo do plano |
| userAgent | — | identifica sua aplicação nos nossos logs |
Tipos
ClassifyInput, ClassifyResult, Candidate, ValidateResult, Issue, ValidateManyResult, TablesListResult, ChangelogResult, UsageResult, PlanUsage, TaxRegime, OperationNature, Severity, Confidence, SourceRef — todos exportados. Campos próprios em snake_case; campos oficiais do padrão nacional mantêm o nome oficial (cClassTrib, cst, cIndOp, opSimpNac).
Aviso
Apoio técnico, não consultoria tributária. A responsabilidade pela nota é do emissor. Confira o resultado com seu contador ou departamento fiscal.
MIT.
