Formatador de CPF

Formatos aceitos e produzidos

O formatador aceita uma lista de CPFs, um por linha, em qualquer formato que contenha os 11 dígitos: 52998224725, 529.982.247-25, 529 982 247 25 ou até com espaços sobrando no começo e no fim. A ferramenta remove tudo o que não é dígito e aplica a saída escolhida:

Linhas vazias são ignoradas. Cada linha da saída corresponde a uma linha não vazia da entrada, na mesma ordem, o que facilita colar o resultado de volta em uma planilha. 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 decisão de descartar ou corrigir fica com você. Na máscara parcial, linhas que não têm exatamente 11 dígitos não mostram nenhum número mascarado — só a marcação # inválido —, porque não há como saber quais dígitos ocultar.

A regra prática para sistemas é simples: armazene só os números, exiba com pontuação. Guardar o CPF como texto de 11 caracteres evita a perda de zeros à esquerda e deixa buscas e índices consistentes. A pontuação é aplicada apenas na camada de apresentação.

Máscara parcial para LGPD

O modo “Mascarar” oculta os três primeiros e os dois últimos dígitos e mantém os seis do meio visíveis: ***.982.247-**. Esse formato aparece com frequência em recibos, comprovantes e telas de confirmação, porque permite que a pessoa reconheça o próprio número sem que ele fique inteiro à vista de quem olha a tela, o papel ou um print.

A LGPD não define um formato obrigatório de mascaramento, mas pede que o tratamento de dados pessoais se limite ao necessário para a finalidade. Em muitas telas, mostrar o CPF inteiro não é necessário: um atendente que só precisa confirmar o cadastro ou um comprovante enviado por e-mail funcionam bem com o número parcial. Ocultar 3 + 2 dígitos é uma escolha comum porque mantém um trecho suficiente para conferência e esconde as pontas.

Dois cuidados:

• Mascare no servidor quando possível. Se a API envia o CPF completo e o front-end só esconde os dígitos na tela, o número inteiro continua trafegando e aparece nas ferramentas do navegador.
• Máscara não é anonimização. O dado mascarado continua sendo pessoal. Ele reduz a exposição, mas não dispensa os demais cuidados com o tratamento.

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, o que importa quando a lista contém CPFs reais.

Esse fluxo resolve tarefas comuns de limpeza de dados:

• padronizar uma coluna que mistura CPFs com e sem pontuação antes de uma importação;
• converter uma lista para “só números” antes de usar como filtro em uma consulta SQL;
• gerar a versão mascarada de uma lista para um relatório que vai circular entre equipes;
• identificar rapidamente quais linhas têm CPF inválido, pela marcação # inválido.

A ferramenta trata cada linha como um CPF. Se a sua lista vem separada por vírgula ou ponto e vírgula, como em uma exportação de sistema ou em um trecho de log, troque os separadores por quebras de linha antes de colar; do contrário, a linha inteira é lida como um único número com dígitos demais e será marcada como inválida.

Se você precisa de CPFs novos em vez de formatar os existentes, use o gerador em lote, que já entrega os números no formato escolhido.

Regex de formatação por linguagem

Em código, a formatação costuma ser feita em duas etapas: remover tudo o que não é dígito e reinserir a pontuação com grupos de captura. O exemplo em JavaScript traz as três operações da ferramenta:

const limpar = (cpf) => String(cpf).replace(/\D/g, '');

const formatar = (cpf) =>
limpar(cpf).replace(/^(\d{3})(\d{3})(\d{3})(\d{2})$/, '$1.$2.$3-$4');

const mascarar = (cpf) =>
limpar(cpf).replace(/^\d{3}(\d{3})(\d{3})\d{2}$/, '***.$1.$2-**');

formatar('52998224725');    // '529.982.247-25'
mascarar('529.982.247-25'); // '***.982.247-**'

As âncoras ^ e $ garantem que a substituição só aconteça quando há exatamente 11 dígitos; com outra quantidade, a função devolve o número limpo, sem pontuação, em vez de uma formatação errada.

Em Python, o módulo re faz o mesmo, com \1, \2 para os grupos:

import re

def formatar(cpf: str) -> str:
    limpo = re.sub(r"\D", "", cpf)
    return re.sub(r"^(\d{3})(\d{3})(\d{3})(\d{2})$", r"\1.\2.\3-\4", limpo)

Em PHP, preg_replace aceita $1, $2 na substituição:

function formatar(string $cpf): string {
    $limpo = preg_replace('/\D/', '', $cpf);
    return preg_replace('/^(\d{3})(\d{3})(\d{3})(\d{2})$/', '$1.$2.$3-$4', $limpo);
}

Para máscaras de input que formatam enquanto o usuário digita, a abordagem é diferente, porque o valor ainda está incompleto. O guia de máscara de CPF em React, Vue e Angular trata desse caso, e o guia de regex para CPF explica as expressões em detalhe, incluindo os limites do que uma regex consegue validar.

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/cpf/formatar?cpf=52998224725

{
  "formatado": "529.982.247-25",
  "limpo": "52998224725",
  "valido": true
}

O parâmetro cpf aceita o número com ou sem pontuação, mas precisa conter 11 dígitos; caso contrário, a API responde com erro 400. Não há chave nem cadastro, e o limite é de 60 requisições por minuto por IP. Veja a documentação da API para os formatos de erro.