Fala Devs! 🚀
Quem nunca precisou validar um CPF ou CNPJ em um formulário de cadastro, que atire o primeiro if. Essa é uma daquelas tarefas que parecem simples, mas que escondem uma lógica de dígitos verificadores bem traiçoeira para se implementar na mão.
E o perigo dessa abordagem é real: um pequeno bug na sua função é o suficiente para deixar passar dados inválidos, comprometendo a integridade do seu sistema e gerar uma bela dor de cabeça no futuro. Afinal garantir que um CPF ou CNPJ é válido logo na entrada é o primeiro passo para uma aplicação robusta. Para saber mais sobre como manter seus dados consistentes, dá uma olhada nos nossos posts sobre banco de dados.
Mas as coisas estão prestes a mudar, e precisamos estar preparados!
O Futuro Chegou: O CNPJ Alfanumérico
Você pode não saber, mas o formato do CNPJ que conhecemos está com os dias contados. Diante do crescimento contínuo do número de empresas, a Receita Federal anunciou que os CNPJs numéricos estão se esgotando.
E a solução? O CNPJ Alfanumérico.
Segundo o comunicado oficial do governo, a partir de julho de 2026, todas as novas empresas receberão um CNPJ Alfanumérico, um novo padrão que mistura letras e números. Os CNPJs númericos atuais continuarão válidos, mas é crucial que nossos sistemas estejam aptos a lidar com essa novidade.
Aí eu te pergunto: e o seu sistema? Ele já está pronto para aceitar e validar os novos tipos de CNPJ?
Isso acende um alerta gigante para nós, desenvolvedores, pois muitos sistemas, estão presos ao formato de 14 dígitos numéricos, o que pode gerar problemas sérios em um futuro próximo. Para te ajudar a se antecipar e garantir que seu sistema esteja pronto, quero te apresentar uma ferramenta que desenvolvi e que já está pronta para esse desafio.
Uma Solução Completa: @dmalbuquerque/cpf-cnpj-validator
Minha intenção foi justamente abstrair toda a complexidade da validação, geração e formatação de CPF e CNPJ, incluindo o suporte ao novo formato alfanumérico.
Com ela, você pode focar no que realmente importa: a lógica de negócio da sua aplicação.
Por que usar uma biblioteca para isso?
Simples: para focar no que realmente importa. Uma boa biblioteca como essa já vem com:
- Algoritmos de validação testados: Chega de se preocupar com os cálculos dos dígitos verificadores.
- Funções utilitárias: Gerar e formatar documentos com uma única linha de código.
- Integração com outras ferramentas: Como veremos, ela já vem pronta para usar com o Joi, um canivete suíço para validação de schemas.
Mão na Massa: Instalando e Configurando
O primeiro passo é adicionar a biblioteca ao seu projeto Node.js. É só rodar o bom e velho npm:
npm install @dmalbuquerque/cpf-cnpj-validatorAgora, vamos à importação. A forma de fazer isso muda um pouco dependendo se você está usando TypeScript ou JavaScript puro.
Para projetos com TypeScript (nosso padrão aqui no blog):
import { cpf, cnpj, documentValidator } from '@dmalbuquerque/cpf-cnpj-validator';
console.log(cpf.isValid('21156032300')); // Exemplo de uso
console.log(cnpj.isValid('20245526000149')); // Exemplo de usoPara projetos com JavaScript (CommonJS):
const { cpf, cnpj, documentValidator } = require('@dmalbuquerque/cpf-cnpj-validator');
console.log(cpf.isValid('21156032300'));
console.log(cnpj.isValid('20245526000149'));Simples assim! Com a lib importada, já temos acesso a um conjunto de ferramentas poderosas.
Trabalhando com CPF
Vamos ver as principais funcionalidades para manipular CPFs.
Gerando um CPF válido
Precisa de um CPF para seus testes ou para popular um banco de dados? Sem problemas.
// Gera um CPF numérico, sem pontos ou traço
const cpfNumerico = cpf.generate();
// Exemplo de retorno: "07208766053"
// Gera um CPF já com a máscara
const cpfFormatado = cpf.generate({ formatted: true });
// Exemplo de retorno: "072.087.660-53"Validando um CPF
Essa é a função principal. Ela aceita tanto CPFs com máscara quanto sem.
// CPF Válido
cpf.isValid("07208766053"); // Retorna: true
cpf.isValid("072.087.660-53"); // Retorna: true
// CPF Inválido
cpf.isValid("07208766050"); // Retorna: false
cpf.isValid("11111111111"); // Também retorna false para sequências inválidasFormatando um CPF
Recebeu um CPF só com números e precisa exibi-lo com a máscara padrão? Moleza.
const cpfOriginal = "07208766053";
const cpfComMascara = cpf.format(cpfOriginal); // Retorna: "072.087.660-53"Trabalhando com CNPJ (Numérico e Alfanumérico)
É aqui que a mágica acontece. A biblioteca lida nativamente com os formatos numérico e alfanumérico.
Gerando um CNPJ
Você pode especificar se quer um CNPJ clássico (numérico) ou alfanumérico, o que é perfeito para testar seu sistema.
// Gera um CNPJ numérico, sem formatação
const cnpjNumerico = cnpj.generate(); // ou cnpj.generate({ type: "numeric" });
// Exemplo de retorno: "25143815000150"
// Gera um CNPJ numérico, formatado
const cnpjNumFormatado = cnpj.generate({ type: "numeric", formatted: true });
// Exemplo de retorno: "25.143.815/0001-50"
// Gera um CNPJ alfanumérico, sem formatação
const cnpjAlfa = cnpj.generate({ type: "alfanumeric" });
// Exemplo de retorno: "OGZP0N77444Y42"
// Gera um CNPJ alfanumérico, formatado
const cnpjAlfaFormatado = cnpj.generate({ type: "alfanumeric", formatted: true });
// Exemplo de retorno: "OG.ZP0.N77/444Y-42"Validando um CNPJ
A função isValid é inteligente o suficiente para identificar o tipo de CNPJ e aplicar a regra de validação correta, sem que você precise se preocupar com nada. Além disso a validação funciona mesmo que você passe um CNPJ com ou sem máscara.
// CNPJ numérico válido
cnpj.isValid("25143815000150"); // Retorna: true
cnpj.isValid("25.143.815/0001-50"); // Retorna: true
// CNPJ alfanumérico válido
cnpj.isValid("OGZP0N77444Y42"); // Retorna: true
cnpj.isValid("OG.ZP0.N77/444Y-42"); // Retorna: true
// CNPJs inválidos
cnpj.isValid("25143815000140"); // Retorna: false
cnpj.isValid("OGZP0N77444Y40"); // Retorna: false🧠 Bônus: Integração Poderosa com Joi
Essa é a minha parte favorita! Se você constrói APIs em Node.js, provavelmente já usa o Joi para validar os payloads das requisições.
A @dmalbuquerque/cpf-cnpj-validator já vem pronto para integrar com o Joi. Veja como é fácil criar um schema de validação:
import Joi from "joi";
// Importamos o documentValidator, que é a extensão para o Joi
import { documentValidator } from "@dmalbuquerque/cpf-cnpj-validator";
// Estendemos o Joi com nossas regras de CPF e CNPJ
const joi = Joi.extend(documentValidator);
// Criamos o schema de validação
const schema = Joi.object({
cpf: joi.document().cpf().optional().label("CPF"),
cnpj: joi.document().cnpj().required().label("CNPJ"),
});
// Testando o schema
const payload = {
cpf: null, // Válido, pois é opcional
cnpj: "25.143.815/0001-50"
};
const { error } = schema.validate(payload);
if (error) {
console.log("Erro de validação:", error.details[0].message);
} else {
console.log("✅ Dados válidos!");
}Explicação do código:
Joi.extend(documentValidator): “Ensinamos” ao Joi as novas regrascpf()ecnpj().joi.document().cpf(): Encadeamos a chamada. Primeirodocument()para acessar as regras da nossa lib, e depoiscpf()para aplicar a validação específica..optional()e.required(): Usamos os validadores padrão do Joi para definir a obrigatoriedade dos campos.
Com isso, a validação de documentos no seu DTO (Data Transfer Object) fica limpa, declarativa e muito mais fácil de manter.
Resumo Final: O que você ganha com essa lib?
- ✅ Integridade dos Dados: Validações rigorosas para CPF, CNPJ (numérico e alfanumérico).
- ✅ Geração de Dados: Crie documentos válidos para testes e mock de dados.
- ✅ Formatação Automática: Converta documentos para o formato com máscara facilmente.
- ✅ Integração com Joi: Adicione validação de CPF/CNPJ diretamente nos seus schemas de API.
- ✅ Código Limpo: Abstrai uma lógica complexa, deixando seu código de negócio mais enxuto.
Não espere 2026 para descobrir que o seu sistema de cadastro vai quebrar. A mudança está vindo, e estar preparado é o que diferencia um bom profissional.
Essa é uma daquelas bibliotecas pequenas que têm um impacto gigante na qualidade e segurança de um projeto. Recomendo fortemente que você a adicione à sua caixa de ferramentas.
E aí, o que achou da biblioteca? Já tinha parado para pensar no impacto do CNPJ Alfanumérico? Deixe seu comentário e abaixo e vamos trocar uma ideia! E se o post te ajudou, compartilhe com a galera!
Até a próxima! 🚀
