README

Validação, formatação e geração de CNPJ alfanumérico (e numérico) em PHP, conforme a IN RFB nº 2.229/2024.

✅ Algoritmo oficial da Receita Federal (valor do caractere = ASCII − 48, módulo 11)
✅ Valida os dois formatos: numérico tradicional e o novo alfanumérico (desde 31/07/2026)
✅ Zero dependências, PHP 7.4+
✅ Porta fiel da implementação de referência em JavaScript usada em produção em cnpjcomletras.com.br — mesmos algoritmo e mensagens de erro
✅ Testado contra o exemplo oficial da Receita e 10.000 CNPJs gerados (PHP 8.2)

🔧 Prefere validar sem instalar nada? Ferramentas online gratuitas (validador, validação em lote com CSV e gerador de massa de teste) em cnpjcomletras.com.br.

Instalação

composer require cnpjcomletras/valida-cnpj-alfanumerico

Uso

use CnpjComLetras\Cnpj;

Cnpj::isValid("12.ABC.345/01DE-35");  // true  (exemplo oficial da Receita)
Cnpj::isValid("00.000.000/0001-91");  // true  (numérico continua válido)
Cnpj::isValid("12.ABC.345/01DE-00");  // false (DV não confere)

Cnpj::validate("12ABC34501DE35");
// [
//   "valid" => true, "reason" => null, "stripped" => "12ABC34501DE35",
//   "formatted" => "12.ABC.345/01DE-35", "isAlphanumeric" => true, "expectedDigits" => "35",
// ]

Cnpj::checkDigits("12ABC34501DE");   // "35" — calcula os 2 DVs para uma base de 12
Cnpj::format("12abc34501de35");      // "12.ABC.345/01DE-35"
Cnpj::strip("12.ABC.345/01DE-35");   // "12ABC34501DE35"

Cnpj::generate(true);   // ex.: "BD4KZ2OX000108" (CNPJ de teste válido, alfanumérico)
Cnpj::generate(false);  // CNPJ de teste só numérico

$ex = Cnpj::explain("12ABC34501DE35");
$ex["base"];    // "12ABC34501DE"
$ex["digits"];  // "35" — passo a passo do cálculo em $ex["dv1"] / $ex["dv2"]

O que muda com o CNPJ alfanumérico?

Desde 31 de julho de 2026, novas inscrições podem receber CNPJ contendo letras:

Posições	Conteúdo	Aceita
1–8 (raiz)	identificação da empresa	`0-9` e `A-Z`
9–12 (ordem)	estabelecimento	`0-9` e `A-Z`
13–14 (DV)	dígitos verificadores	somente `0-9`

CNPJs já emitidos não mudam. O cálculo do DV usa o mesmo módulo 11 de sempre, mas cada caractere entra com o valor ASCII − 48 ('0'→0 … '9'→9, 'A'→17 … 'Z'→42).

Sistemas que guardam CNPJ como coluna INT/BIGINT, validam com regex só-dígitos (^\d{14}$) ou fazem (int) $cnpj rejeitam ou corrompem os novos CNPJs. Guia completo de adaptação: como adaptar seu sistema · funções em Python, Java, C# e SQL.

API

Método estático	Descrição
`Cnpj::isValid($valor)`	`true`/`false` — aceita com ou sem máscara, maiúsculas ou minúsculas
`Cnpj::validate($valor)`	array com `valid`, `reason` (se inválido), `stripped`, `formatted`, `isAlphanumeric`, `expectedDigits`
`Cnpj::checkDigits($base12)`	calcula os 2 dígitos verificadores de uma base de 12 caracteres
`Cnpj::format($valor)`	aplica a máscara `XX.XXX.XXX/XXXX-XX`
`Cnpj::strip($valor)`	remove máscara e normaliza para maiúsculas
`Cnpj::generate($alphanumeric = true, $branch = null)`	gera CNPJ de teste válido
`Cnpj::explain($valor)`	array com o passo a passo do cálculo do DV (para depuração/didática)

Motivos possíveis em reason: empty, length, invalid_chars, dv_not_numeric, repeated, check_digits.

⚠️ A validação é estrutural (formato + dígitos verificadores). Ela não consulta a base da Receita Federal — um CNPJ estruturalmente válido pode não existir.

Testes

Sem dependências (roda com qualquer PHP 7.4+, sem composer install):

php tests/run.php

Com PHPUnit (composer install primeiro):

vendor/bin/phpunit tests/CnpjTest.php

Ferramentas relacionadas

🔍 Validador online + gerador de massa de teste — grátis, roda no navegador
📊 Auditoria de Cadastro — cole sua planilha de clientes/fornecedores e veja quantos CNPJs estão inválidos, duplicados ou corrompidos pelo Excel
🩺 Diagnóstico de Prontidão — varredura do seu código-fonte atrás de padrões que quebram com o CNPJ alfanumérico

cnpjcomletras / valida-cnpj-alfanumerico

Maintainers

Package info

Statistics

Security

README

Instalação

Uso

O que muda com o CNPJ alfanumérico?

API

Testes

Ferramentas relacionadas

Licença