Biblioteca autoral do ecossistema AS-CNPJ para validacao, normalizacao, formatacao, calculo de digitos verificadores e validacao em lote de CNPJ numerico e alfanumerico em Java.

Repositorio | Site | Hub do ecossistema | API | Testes

Idiomas: Portugues (Brasil) | English | Espanol | Francais

Status

• repositorio publico e ativo;
• API unitaria e validacao em lote ja implementadas;
• CI publica rodando em Java 17;
• algoritmo alinhado aos vetores compartilhados do ecossistema;
• artefato Maven Central ainda nao publicado.

Instalacao

Estado atual:

• o codigo esta publico e pronto para uso no repositorio;
• a distribuicao em registry Java ainda nao foi publicada;
• a primeira publicacao planejada usa as coordenadas io.ascnpj:as-cnpj-java.

Coordenadas previstas para a primeira publicacao:

<dependency>
  <groupId>io.ascnpj</groupId>
  <artifactId>as-cnpj-java</artifactId>
  <version>0.1.0</version>
</dependency>

Enquanto o artefato nao estiver no Maven Central, o consumo atual e via checkout do repositorio e integracao local do codigo ao seu build Java.

Exemplo rapido

import io.ascnpj.Cnpj;
import io.ascnpj.ValidationOptions;

boolean valid = Cnpj.isValid("12.ABC.345/01DE-35");
String normalized = Cnpj.normalize("12.abc.345/01de-35");
String formatted = Cnpj.format("12ABC34501DE35");
String asserted = Cnpj.assertValid("12.ABC.345/01DE-35", ValidationOptions.strict());
String dv = Cnpj.calculateCnpjCheckDigits("12ABC34501DE");

Validacao em lote

import io.ascnpj.Cnpj;

var result = Cnpj.validateMany(java.util.Arrays.asList(
    "12.ABC.345/01DE-35",
    "12.ABC.345/01DE-36",
    null
));

result.items().get(0).valid();
result.items().get(1).reason();
result.summary().reasons();

Casos de uso

• backends corporativos em Java que precisam aceitar CNPJ legado e alfanumerico;
• validacao de payloads antes de persistencia, faturamento ou integracao;
• saneamento de base e normalizacao consistente em migracoes;
• suites de homologacao que precisam validar multiplos CNPJs com resumo por motivo.

O que esta biblioteca entrega

• validacao de CNPJ numerico legado;
• validacao de CNPJ alfanumerico previsto pela Receita Federal para julho de 2026;
• suporte a entradas com mascara e sem mascara;
• modo permissivo e modo estrito;
• validacao em lote com items e summary;
• zero dependencias externas no nucleo do algoritmo.

API publica

Metodos principais:

• normalize(String value)
• isValid(String value)
• isValid(String value, ValidationOptions options)
• format(String value)
• format(String value, ValidationOptions options)
• assertValid(String value)
• assertValid(String value, ValidationOptions options)
• calculateCheckDigits(String base12)
• validateMany(List<?> values)
• validateMany(List<?> values, ValidationOptions options)

Aliases explicitos:

• normalizeCnpj(String value)
• isValidCnpj(...)
• formatCnpj(...)
• assertValidCnpj(...)
• calculateCnpjCheckDigits(String base12)
• validateManyCnpj(...)

Garantias centrais

• aceita A-Z0-9 nos 12 primeiros caracteres;
• mantem os 2 digitos verificadores como numericos;
• usa modulo 11 com conversao ASCII - 48;
• normaliza entrada para caixa alta;
• rejeita repeticoes triviais invalidas;
• preserva ordem e motivo por item na validacao em lote.

Documentacao e referencias

• API da biblioteca
• Estrategia de testes
• Checklist de release
• Politica de seguranca
• Hub do ecossistema AS-CNPJ

Publicacao

• repositorio publicado: as-cnpj-java
• coordenadas planejadas: io.ascnpj:as-cnpj-java
• proximo marco: publicacao do artefato em registry Java

Vetores compartilhados

O as-cnpj-java nao define a verdade sozinho.

O contrato do ecossistema depende tambem de:

• vetores compartilhados no hub;
• regras documentadas a partir das fontes oficiais;
• convergencia entre implementacoes em linguagens diferentes.

Manutencao

Maintainer: @0moura
Contato institucional: ascnpj@0moura.io