@frenet/document-validation

Validação e formatação de documentos brasileiros — CPF, CNPJ (com suporte a CNPJ alfanumérico, IN RFB 2.229/2024) e chave de acesso de NF-e / DC-e (44 posições). Sem dependências de runtime, ESM, com tipos TypeScript.

É a fonte única (SSOT) de validação de documentos dos fronts da Frenet — evita reimplementar (e divergir) as regras de CPF/CNPJ/chave em cada projeto.

Instalação

npm i @frenet/document-validation
# ou
pnpm add @frenet/document-validation

Uso

import { cpf, cnpj, accessKey } from "@frenet/document-validation";

// CPF
cpf.isValid("390.533.447-05");        // true
cpf.strip("390.533.447-05");          // "39053344705"
cpf.format("39053344705");            // "390.533.447-05"

// CNPJ — numérico ou alfanumérico
cnpj.isValid("04.252.011/0001-10");   // true
cnpj.isValid("12.ABC.345/01DE-35");   // true (alfanumérico)
cnpj.strip("12.ABC.345/01DE-35");     // "12ABC34501DE35"
cnpj.format("12ABC34501DE35");        // "12.ABC.345/01DE-35"

// Chave de acesso da NF-e / DC-e (44) — novidade da 0.2.0
const chave = "35260712ABC34501DE35550010000001231000001234";
accessKey.isValid(chave);             // true
accessKey.extractIssuerCnpj(chave);   // "12ABC34501DE35" (CNPJ do emitente, com letras)
accessKey.strip("3526 0712 ABC3 ...");// remove máscara/espaços e coloca em maiúsculas

API

cpf / cnpj

| Método | Descrição | |---|---| | isValid(value, strict?) | valida o dígito verificador (CNPJ aceita alfanumérico) | | strip(value, strict?) | remove a máscara | | format(value) | aplica a máscara | | verifierDigit(...) | calcula o(s) dígito(s) verificador(es) | | generate(formatted?) | gera um documento válido (uso em testes) |

accessKey (0.2.0+)

Chave de acesso de Documentos Fiscais Eletrônicos (NF-e, NFC-e, DC-e, ...) — 44 posições, cujo CNPJ do emitente pode ser alfanumérico.

| Método | Descrição | |---|---| | isValid(key) | valida o layout (letras só nas 12 posições do CNPJ) e o dígito verificador | | computeDv(first43) | calcula o DV oficial (Módulo 11 com conversão ASCII−48, NT CJ 2025.001, Anexo II) | | extractIssuerCnpj(key) | extrai o CNPJ do emitente preservando as letras | | strip(key) | normaliza (remove máscara/espaços e coloca em maiúsculas) |

CNPJ alfanumérico (IN RFB 2.229/2024)

A partir de 06/07/2026, o CNPJ pode conter letras nas 12 primeiras posições ([A-Z0-9]), mantendo os 2 dígitos verificadores numéricos. O DV é calculado por Módulo 11 usando o valor ASCII(caractere) − 48 (dígitos 0–9; A=17 … Z=42). Documentos e chaves 100% numéricos continuam validando de forma idêntica (totalmente retrocompatível).

Changelog

0.2.2

• README passa a ser renderizado na página do npm (publicado via npm, que preenche o campo readme). Sem mudança de código.

0.2.1

• Adição de README e descrição ao pacote. Sem mudança de código.

0.2.0

• Novo accessKey: validação da chave de acesso de NF-e/DC-e com CNPJ emitente alfanumérico (isValid, computeDv, extractIssuerCnpj, strip).

0.1.x

• cpf e cnpj (este já com suporte a CNPJ alfanumérico).

Licença

UNLICENSED — uso interno Frenet.