novo-cnpj — Validador e Gerador de CNPJ Alfanumérico

Fork multilinguagem do projeto original novo-cnpj criado por Gabriel Froes e Vanessa Weber (Código Fonte TV). Este repositório porta a implementação TypeScript original para outras linguagens e ecossistemas, mantendo o mesmo algoritmo e os mesmos casos de teste.

Monorepo com implementações do validador e gerador de CNPJ Alfanumérico (Instrução Normativa RFB nº 2.229/2024) para 5 linguagens/ecossistemas, compartilhando algoritmo, dados de teste e CI.

Importante: o novo formato alfanumérico entra em vigor em julho de 2026. CNPJs numéricos existentes não serão alterados — esta biblioteca suporta ambos os formatos.

---

O que é o novo CNPJ Alfanumérico?

O CNPJ (Cadastro Nacional da Pessoa Jurídica) passa a aceitar letras maiúsculas (A–Z) além de dígitos (0–9) nas 12 primeiras posições, mantendo os 2 dígitos verificadores sempre numéricos. Formato: XX.XXX.XXX/XXXX-DD.

Veja a especificação completa do algoritmo.

---

Packages

Package	Ecossistema	Gerenciador	Instalação
packages/typescript	TypeScript / Node.js / Deno / Bun	npm	npm install novo-cnpj
packages/go	Go	pkg.go.dev	go get github.com/alanmatiasdev/cnpj/packages/go
packages/php	PHP	Packagist	composer require alanmatiasdev/novo-cnpj
packages/python	Python	PyPI	pip install novo-cnpj
packages/jvm	Kotlin + Java	Maven Central	ver abaixo

JVM (Kotlin + Java)

// Kotlin
implementation("io.github.alanmatiasdev:novo-cnpj-jvm:1.0.0")

<!-- Java (Maven) -->
<dependency>
  <groupId>io.github.alanmatiasdev</groupId>
  <artifactId>novo-cnpj-jvm</artifactId>
  <version>1.0.0</version>
</dependency>

---

API — visão geral

Todos os packages expõem as mesmas três operações:

Operação	Descrição
isValid(cnpj)	Retorna true se o CNPJ for válido (limpa máscara, aceita maiúsculas/minúsculas)
create(cnpj)	Retorna o CNPJ normalizado (14 chars, sem máscara) ou lança erro
generate(n)	Gera n CNPJs válidos aleatórios em formato normalizado

TypeScript

import { CnpjValidator } from "novo-cnpj";

CnpjValidator.isValid("12.ABC.345/01AB-77"); // true
CnpjValidator.isValid("12.abc.345/01ab-77"); // true  — normaliza automaticamente
CnpjValidator.isValid("00000000000000");      // false — sequência uniforme
CnpjValidator.isValid(null);                  // false — não é string

CnpjValidator.create("12.abc.345/01ab-77");   // "12ABC34501AB77"
CnpjValidator.create("12ABC34501AB35");        // throws Error

CnpjValidator.generate();    // ["XXXXXXXXXXX77"]       — 1 CNPJ
CnpjValidator.generate(5);   // ["...", "...", ...]     — 5 CNPJs

Go

import "github.com/alanmatiasdev/cnpj/packages/go"

cnpj.IsValid("12.ABC.345/01AB-77")  // true
cnpj.IsValid("00000000000000")       // false

normalized, err := cnpj.Create("12.ABC.345/01AB-77")
// normalized = "12ABC34501AB77", err = nil

cnpjs := cnpj.Generate(5)
// []string{"...", "...", ...}

PHP

use NovoCnpj\CnpjValidator;

CnpjValidator::isValid("12.ABC.345/01AB-77"); // true
CnpjValidator::isValid(null);                  // false

CnpjValidator::create("12.abc.345/01ab-77");  // "12ABC34501AB77"

CnpjValidator::generate(5); // ["...", "...", ...]

Python

from novo_cnpj import CnpjValidator

CnpjValidator.is_valid("12.ABC.345/01AB-77")  # True
CnpjValidator.is_valid(None)                   # False

CnpjValidator.create("12.abc.345/01ab-77")    # "12ABC34501AB77"

CnpjValidator.generate(5)  # ["...", ...]

Kotlin

import io.github.alanmatiasdev.cnpj.CnpjValidator

CnpjValidator.isValid("12.ABC.345/01AB-77")  // true
CnpjValidator.isValid(null)                   // false

CnpjValidator.create("12.abc.345/01ab-77")   // "12ABC34501AB77"

CnpjValidator.generate(5)  // listOf("...", ...)

// Extension functions
"12.ABC.345/01AB-77".isValidCnpj()  // true
"12.abc.345/01ab-77".toCnpj()       // "12ABC34501AB77"

Java

import io.github.alanmatiasdev.cnpj.CnpjValidator;

CnpjValidator.isValid("12.ABC.345/01AB-77");  // true
CnpjValidator.isValid(null);                   // false

CnpjValidator.create("12.abc.345/01ab-77");   // "12ABC34501AB77"

List<String> cnpjs = CnpjValidator.generate(5);

---

Rodando os testes

Com Docker (recomendado — sem nenhuma dependência local)

# Todos os packages de uma vez
make test-all

# Apenas um package específico
make test-typescript
make test-go
make test-php
make test-python
make test-jvm

# Remover imagens e volumes criados
make clean

Sem Docker (requer as ferramentas instaladas localmente)

./scripts/cross-check.sh

Ou individualmente:

# TypeScript (Node 22+)
cd packages/typescript
node --test --experimental-strip-types tests/CnpjValidator.test.ts

# Go
cd packages/go
go test ./... -v

# PHP
cd packages/php
composer install && ./vendor/bin/phpunit --testdox tests/

# Python
cd packages/python
pip install -e ".[dev]" && pytest -v tests/

# JVM (Kotlin + Java)
cd packages/jvm
gradle test --no-daemon

---

Estrutura do monorepo

novo-cnpj/
├── spec/
│   ├── algorithm.md          # documentação canônica do algoritmo
│   └── test-vectors.json     # vetores de referência anotados
├── tests/
│   └── shared/               # JSON de casos de teste compartilhados entre os 5 packages
│       ├── valid.json
│       ├── invalid.json
│       └── edge-cases.json
├── packages/
│   ├── typescript/           # npm
│   ├── go/                   # pkg.go.dev
│   ├── php/                  # Packagist
│   ├── python/               # PyPI
│   └── jvm/                  # Maven Central (Kotlin + Java)
├── docker-compose.yml
├── Makefile
└── scripts/
    └── cross-check.sh

---

Créditos

O algoritmo, a implementação TypeScript original e a documentação foram criados por Gabriel Froes e Vanessa Weber do Código Fonte TV. As ports para Go, PHP, Python e JVM (Kotlin/Java) neste repositório foram desenvolvidas a partir desse trabalho.

• Repositório original: gabrielfroes/novo-cnpj

---

Referências oficiais

• CNPJ Alfanumérico — Receita Federal
• Instrução Normativa RFB nº 2.229/2024