Formatador e máscara de CNPJ

Máscara que aceita letras

O formatador recebe uma lista de CNPJs, um por linha, e aplica uma das três saídas:

A máscara é a mesma para os dois formatos: dois caracteres, ponto, três, ponto, três, barra, quatro, hífen e os dois dígitos verificadores. O que mudou com o CNPJ alfanumérico, emitido pela Receita Federal para novas inscrições desde julho de 2026 (IN RFB nº 2.229/2024), é o conteúdo das doze primeiras posições, que agora pode incluir letras de A a Z. Os CNPJs numéricos existentes não mudam, então a mesma lista pode misturar os dois tipos.

Antes de formatar, a ferramenta converte tudo para maiúsculas e descarta o que não é dígito nem letra. Linhas vazias são ignoradas, e cada linha da saída corresponde a uma linha não vazia da entrada, na mesma ordem. Se o número não passa na validação, a linha recebe a marcação # inválido ao lado, mas é formatada mesmo assim.

A regra prática para sistemas continua valendo: armazene só os caracteres, exiba com pontuação. Guarde o CNPJ como texto de 14 posições em maiúsculas e aplique a máscara apenas na camada de apresentação.

Por que replace(/\D/g,'') quebra o alfanumérico

Durante anos, a forma padrão de limpar um CNPJ foi remover tudo o que não é dígito. Em JavaScript, cnpj.replace(/\D/g, ''); em PHP, preg_replace('/\D/', '', $cnpj); em Python, re.sub(r'\D', '', cnpj). Com o CNPJ numérico isso funciona, porque só sobram os 14 dígitos.

Com o alfanumérico, o mesmo código apaga as letras. 12.ABC.345/01DE-35 vira 123450135: nove caracteres, que falham no teste de tamanho ou, pior, podem ser completados com zeros à esquerda por alguma rotina e virar outro número. O erro é silencioso, porque o código não lança exceção; ele só produz um valor errado.

A correção é trocar a classe de caracteres: em vez de manter dígitos, mantenha dígitos e letras, depois de converter para maiúsculas.

// Antes: descarta letras
const limpar = (cnpj) => String(cnpj).replace(/\D/g, '');

// Depois: preserva o formato alfanumérico
const limpar = (cnpj) => String(cnpj).toUpperCase().replace(/[^A-Z0-9]/g, '');

Vale procurar no código todas as ocorrências de \D, [^0-9], parseInt, Number(...) e conversões para bigint aplicadas a CNPJ. O guia CNPJ alfanumérico: o que muda no seu sistema lista esses pontos por camada.

Mascarar mantendo a ordem

O modo “Mascarar (ocultar raiz)” oculta a raiz e os dígitos verificadores e mantém visível apenas a ordem: **.***.***/01DE-**. A ordem identifica o estabelecimento dentro da empresa (0001 costuma ser a matriz), então ela ajuda a distinguir filiais em uma lista sem expor o número completo. Diferente do CPF, o CNPJ em geral não é dado pessoal — é um identificador de empresa, público no CNPJ da Receita Federal — então ocultar a raiz aqui é uma questão de reduzir ruído visual em relatórios e telas compartilhadas, não uma exigência da LGPD.

Algumas observações:

• Linhas com tamanho errado não mostram nada mascarado. Se a linha não tem exatamente 14 caracteres, não há como saber quais posições ocultar, e a saída traz só a marcação # inválido.
• Mascare no servidor quando possível. Se a API envia o CNPJ completo e só a tela esconde parte dele, o número inteiro continua trafegando.
• Em empresas individuais, o CNPJ pode estar ligado a uma pessoa física. Nesse caso específico, trate o número com o mesmo cuidado do CPF.

Para entender o papel de cada bloco do número, veja o guia sobre raiz, ordem e dígitos do CNPJ.

Formatar em lote

A caixa de entrada não tem limite fixo de linhas: cole uma coluna inteira de uma planilha, escolha o modo e copie a saída com o botão “Copiar saída”. Como tudo acontece no navegador, os números não saem do seu computador.

Esse fluxo resolve tarefas comuns de limpeza:

• padronizar uma coluna que mistura CNPJs com e sem pontuação, em maiúsculas e minúsculas, antes de uma importação;
• converter para “só caracteres” antes de usar a lista como filtro em uma consulta SQL;
• gerar a versão mascarada para um relatório que vai circular entre equipes;
• encontrar linhas com CNPJ inválido pela marcação # inválido.

A ferramenta trata cada linha como um CNPJ. Se a lista vem separada por vírgula ou ponto e vírgula, troque os separadores por quebras de linha antes de colar. Para criar números novos em vez de formatar os existentes, use o gerador de CNPJ em lote.

Regex de formatação por linguagem

Em código, a formatação tem duas etapas: limpar (maiúsculas e só [A-Z0-9]) e reinserir a pontuação com grupos de captura. Em JavaScript:

const limpar = (cnpj) => String(cnpj).toUpperCase().replace(/[^A-Z0-9]/g, '');

const formatar = (cnpj) =>
limpar(cnpj).replace(/^([A-Z0-9]{2})([A-Z0-9]{3})([A-Z0-9]{3})([A-Z0-9]{4})(\d{2})$/, '$1.$2.$3/$4-$5');

const mascarar = (cnpj) =>
limpar(cnpj).replace(/^[A-Z0-9]{8}([A-Z0-9]{4})\d{2}$/, '**.***.***/$1-**');

formatar('12abc34501de35');     // '12.ABC.345/01DE-35'
formatar('11222333000181');     // '11.222.333/0001-81'
mascarar('12.ABC.345/01DE-35'); // '**.***.***/01DE-**'

As âncoras ^ e $ garantem que a substituição só aconteça com exatamente 14 caracteres no padrão certo; caso contrário, a função devolve o valor limpo, sem pontuação. O último grupo usa \d{2} porque os dígitos verificadores nunca são letras.

Em Python:

import re

def formatar(cnpj: str) -> str:
    limpo = re.sub(r"[^A-Z0-9]", "", cnpj.upper())
    return re.sub(r"^([A-Z0-9]{2})([A-Z0-9]{3})([A-Z0-9]{3})([A-Z0-9]{4})(\d{2})$",
                  r"\1.\2.\3/\4-\5", limpo)

Em PHP:

function formatar(string $cnpj): string {
    $limpo = preg_replace('/[^A-Z0-9]/', '', strtoupper($cnpj));
    return preg_replace('/^([A-Z0-9]{2})([A-Z0-9]{3})([A-Z0-9]{3})([A-Z0-9]{4})(\d{2})$/',
                        '$1.$2.$3/$4-$5', $limpo);
}

O guia de regex para CNPJ detalha as expressões de validação de formato, e as páginas de código para JavaScript, Python e PHP trazem as funções completas.

Formatar pela API

A API pública também formata, útil quando o código que precisa disso não é JavaScript ou quando você quer a validação no mesmo passo:

GET https://www.cpf.dev.br/api/v1/cnpj/formatar?cnpj=12abc34501de35

{
  "formatado": "12.ABC.345/01DE-35",
  "limpo": "12ABC34501DE35",
  "valido": true,
  "formato": "alfanumerico"
}

O campo formato indica se o número é numerico ou alfanumerico, e valido diz se os dígitos verificadores conferem, então uma única chamada serve para normalizar o valor antes de gravar e para decidir se ele deve ser aceito. O parâmetro cnpj aceita o número com ou sem pontuação e em minúsculas. Não há chave nem cadastro, e o limite é de 60 requisições por minuto por IP. Os formatos de erro estão na documentação da API.