Biblioteca e ferramenta de linha de comando para localizar, validar e classificar chaves de acesso de NF-e (modelo 55) e NFC-e (modelo 65) em documentos PDF, JPEG e PNG. As entradas podem ser caminhos locais, URLs HTTP(S), bytes em memória, Readable do Node.js ou qualquer AsyncIterable<Uint8Array>; o processamento usa CPU e combina texto nativo de PDF, Code 128, QR Code e OCR.
O pacote atual é cerne-fiscal versão 0.6.0, requer Node.js 20 ou superior e publica interfaces ESM, CommonJS e TypeScript.
O Cerne Fiscal:
- detecta o formato pelo conteúdo do arquivo, sem confiar na extensão;
- extrai chaves contíguas ou separadas no texto nativo do PDF;
- reconstrói linhas visuais de PDFs quando a ordem do stream não representa a leitura humana;
- renderiza páginas para procurar Code 128 e QR Code;
- usa OCR como fallback ou de forma obrigatória, conforme a configuração;
- aceita o formato numérico tradicional e o segmento de emitente alfanumérico previsto pelo validador;
- valida UF, mês, modelo, identificador do emitente, número da nota e dígito verificador;
- retorna resultados estruturados, fontes da evidência, páginas, confiança, métricas, avisos e erros estáveis.
O pacote não consulta SEFAZ, não verifica autorização ou situação atual de uma nota, não lê XML fiscal e não inicia servidor. Uma chave retornada é estrutural e semanticamente válida de acordo com as regras implementadas; isso não comprova a existência ou a validade jurídica do documento.
Em um projeto consumidor:
npm install cerne-fiscalO runtime exige Node.js >=20. Consulte Instalação e desenvolvimento para uso a partir do código-fonte, build, distribuição e dependências nativas.
import { extractNFeAccessKeys } from "cerne-fiscal";
const extraction = await extractNFeAccessKeys("./danfe.pdf", {
performance: "balanced",
stopAfterFirst: true,
});
if (extraction.success) {
console.log(extraction.bestMatch?.accessKey);
} else {
console.error(extraction.error ?? extraction.status);
}Para NFC-e, use extractNFCeAccessKeys. As duas funções aceitam caminho, URL HTTP(S), ArrayBuffer, Uint8Array, Buffer (por herança), Readable e qualquer AsyncIterable<Uint8Array>.
const result = await extractNFeAccessKeys(readable, {
streamStorage: "auto",
streamMemoryThresholdBytes: 1024 * 1024,
maxFileSizeBytes: 25 * 1024 * 1024,
signal,
});streamStorage decide onde os bytes ficam enquanto o stream é consumido: memory acumula na memória do processo, file grava cada bloco em um temporário do extrator e auto (padrão) começa na memória e migra para um temporário ao ultrapassar streamMemoryThresholdBytes. A política vale apenas para streams; Buffer, Uint8Array e ArrayBuffer já estão na memória e nunca vão para disco. Temporários criados pelo extrator são removidos ao fim da chamada, inclusive em erro, timeout, aborto e not_found. Detalhes em API.
cerne-fiscal ./nota.pdf --document-type nfe --pretty
cerne-fiscal ./cupom.jpg --document-type nfce --performance accurate --firstA CLI escreve exatamente um documento JSON em stdout. O código de saída é 0 quando há resultado (ou na ajuda), 2 quando a extração termina sem encontrar chave e 1 nos demais erros. Veja todas as opções em CLI.
O fluxo percorre, nesta ordem:
- validação das opções;
- leitura limitada da entrada e detecção de assinatura;
- abertura como PDF ou imagem de página única;
- busca no texto nativo e nas linhas reconstruídas do PDF;
- renderização e leitura de Code 128/QR Code nas páginas ainda relevantes;
- OCR conforme
ocr: "never" | "fallback" | "always"; - revalidação fiscal, deduplicação, cálculo de confiança e ordenação.
Somente chaves válidas do modelo solicitado chegam a results. Recursos de página, canvas, worker de OCR, documento e timeout são liberados ao final da chamada, inclusive em falhas.
| Perfil | Passes padrão | OCR padrão | Páginas padrão | Pixels por página | Pixels da imagem-fonte | Timeout |
|---|---|---|---|---|---|---|
fast |
1 | never |
10 | 8.000.000 | 40.000.000 | 30 s |
balanced |
2 | fallback |
30 | 12.000.000 | 60.000.000 | 120 s |
accurate |
3 | fallback |
50 | 20.000.000 | 100.000.000 | 300 s |
O padrão é balanced. Todos os limites podem ser sobrescritos dentro das faixas aceitas; maxFileSizeBytes tem padrão de 30 MiB em todos os perfis. Mais passes e OCR aumentam consumo de CPU, memória e latência.
As funções de extração resolvem um ExtractionResult com quatro estados:
success: uma ou mais chaves foram encontradas e o escopo configurado foi concluído;not_found: o processamento terminou sem chave válida;partial: houve chave antes de uma falha ou o escopo foi truncado, por exemplo pormaxPages;error: nenhuma chave foi preservada e ocorreu uma falha.
success é um booleano independente do campo status: ele é verdadeiro sempre que results contém ao menos uma chave, inclusive em uma resposta partial. O consumidor deve avaliar ambos.
Além das funções de extração, o pacote exporta:
validateAccessKey;parseAccessKey;calculateAccessKeyCheckDigit;validateIssuerIdentifier;ACCESS_KEY_ISSUE_CODES;- os tipos TypeScript da entrada, opções, resultados, componentes, problemas de validação e metadados.
O contrato completo, os limites, os códigos de erro e a interpretação da confiança estão em API.
Os scripts declarados no projeto cobrem verificação de tipos, lint, formatação, build, auditoria e benchmark. O fluxo consolidado é npm run check; o CI executa verificação de tipos, lint, formatação e build em Node.js 20, 22 e 24, além de uma auditoria separada em Node.js 22.
As fixtures sintéticas e determinísticas em bench/ verificam regressões de resultado e desempenho, mas o benchmark não faz parte do workflow de CI atual.
MIT. Consulte LICENSE.