fiscalspec

Fiscal CI — a especificação fiscal que roda no seu pipeline.

Valida XMLs de NF-e/NFC-e contra um ruleset fiscal versionado (regras de validação da NT 2025.002-RTC — Reforma Tributária, IBS/CBS) e diz, antes da homologação, qual regra quebra, com o código provável de rejeição e link para o trecho da fonte oficial.

• Processamento local: o conteúdo dos seus XMLs nunca sai da sua máquina, e nada é transmitido por padrão. Duas coisas usam rede e são separadas disso: o download do ruleset na primeira execução (exige chave, fica em cache local) e a telemetria de uso, que é opt-in (--telemetry) e envia só contagens agregadas.
• Ruleset imutável e fixável: [email protected] produz o mesmo resultado hoje e em seis meses.
• Toda violação vem com ruleId, código de rejeição, versão da NT, vigência e página da fonte — nada sem evidência.
• O default é avisar, não quebrar o build: só regra revisada (confidence: reviewed) pode falhar o pipeline, e só com --fail-on reviewed.

Uso

npx fiscalspec check "notas/*.xml" --ruleset [email protected]

Saídas para CI:

npx fiscalspec check "notas/*.xml" --ruleset [email protected] --format junit --output resultado.xml
npx fiscalspec check "notas/*.xml" --ruleset [email protected] --format sarif --output resultado.sarif

Exit codes: 0 ok (mesmo com violações) · 1 só com --fail-on reviewed · 2 erro de uso.

O que ele responde

| Pergunta | Campo no relatório | |---|---| | Qual regra quebrou? | ruleId (ex.: VC02-14) | | Qual rejeição a SEFAZ deve dar? | rejectionCode (ex.: 321) | | Em qual versão da norma? | provenance.ntVersion, vigenciaInicio | | Onde está escrito? | provenance.source (documento + página) | | Dá para confiar? | confidence (extracted avisa · reviewed pode bloquear) e class (deterministic-offline · needs-external-data · sefaz-observable-only) |

Regra que depende de dado externo (cadastro SEFAZ, tabela não publicada) reporta cannot-decide — o relatório declara o limite em vez de chutar.

Uso programático

import { loadRuleset, evaluateXml, buildReport } from "@fiscalspec/core";

Ver @fiscalspec/core.

Escopo desta versão

NF-e/NFC-e (modelos 55/65), regras de validação da NT 2025.002-RTC v1.50. Requer Node.js 24 LTS.

Licença

Source-available, uso permitido inclusive comercial; redistribuição e derivação do corpus proibidas — ver LICENSE.md.

https://fiscalspec.com.br