Como formatar e validar CPF no navegador ou no backend
Muita gente procura por uma biblioteca ou script pronto pra aplicar a máscara de CPF e validar o dígito verificador. A pergunta "nome com q brasileiro" aparece bastante em fóruns quando alguém precisa implementar isso e não sabe por onde começar. Vou mostrar como fazer sem depender de algo pesado. O CPF tem 11 dígitos e a máscara padrão é XXX.XXX.XXX-XX. A parte que todo mundo erra é a validação dos dois dígitos verificadores. Formatar visualmente é trivial. Validar se o número é matematicamente válido é onde os erros acontecem.
nome com q brasileiro
A validação funciona assim: você pega os nove primeiros dígitos, multiplica cada um por um peso decrescente a partir de 10, soma tudo e calcula o resto da divisão por 11. Se o resto for menor que 2, o primeiro dígito verificador é 0. Senão, é 11 menos o resto. O segundo dígito repete o processo incluindo o primeiro dígito calculado, mas com pesos que começam em 11. Eu já vi gente implementar isso errado porque acha que o peso começa sempre em 10. Começa em 10 pro primeiro dígito e em 11 pro segundo. Parece mínimo, mas é o erro mais comum que eu já encontrei em code review.
Um problema que eu tive na prática envolveu CNPJs e CPFs sendo misturados no mesmo campo de formulário. O usuário colou um CNPJ formatado e o sistema tentou validar como CPF, gerando um erro de validade que não fazia sentido pro usuário final. A solução foi detectar o tamanho da string antes de decidir qual validação aplicar. CPF tem 11 dígitos, CNPJ tem 14. Se o campo aceitar ambos, trata os dois separadamente.
Implementação prática
Se você só quer formatar enquanto digita, umEventHandler de input já resolve. Remove tudo que não for dígito, aplica a máscara manualmente e atualiza o campo. Nada de biblioteca pesada. Aqui vai um exemplo simples em JavaScript: Para a máscara de input, você remove caracteres não numéricos, limita a 11 dígitos e insere pontos e traço nas posições corretas: 3 dígitos, ponto, 3 dígitos, ponto, 3 dígitos, traço, 2 dígitos. Isso acontece em tempo real conforme o usuário digita.
Para a validação dos dígitos verificadores, o código recebe os 11 dígitos brutos, calcula o primeiro dígito com pesos de 10 a 2, depois o segundo com pesos de 11 a 2 e compara com os dígitos informados no final do CPF. Se qualquer um dos dois não bater, o CPF é inválido.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Armazenamento e normalização
Sempre armazene CPF sem formatação. Só aplique a máscara na camada de apresentação, nunca no banco de dados. Quem armazena com pontos e traço acaba tendo problemas quando precisa fazer busca, ordenação ou join com outras tabelas. Inteiro ou string pura de 11 dígitos é o jeito certo. Também vale normalizar antes de validar. CPF preenchido com zeros à esquerda, como 000.123.456-78, às vezes chega como 12345678 apenas se o usuário apagou os zeros no formulário. Sempre valide o tamanho da string numérica antes de rodar o algoritmo.
Edge cases que dão trabalho
Existem CPFs com dígitos repetidos que são válidos matematicamente, como 111.111.111-11. Sistemas que bloqueiam esses casos por achar que são inválidos estão errados. A receita federal aceita. Se a sua validação rejeita repetidos, está mais rígito do que deveria. Outro problema comum é tratar CPF de pessoa jurídica por acidente. Às vezes o sistema recebe um CNPJ num campo de CPF porque o usuário selecionou o tipo de pessoa errado no passo anterior. Se você não valida o formato antes de aplicar a máscara, o CNPJ vai parecer um CPF válido nos primeiros nove dígitos e só vai falhar nos dois últimos, o que gera uma experiência ruim.
Para evitar isso, coloque a validação de tipo no início do fluxo, antes de qualquer coisa. Isso também evita que validações massivas de banco de dados travem porque alguém cadastrou CNPJ no campo errado há dois anos.
Alternativas e quando não usar
Se você já está usando um framework como React, Vue ou Angular, existem pacotes como cpf-cnpj-validator ou bibliotecas similares que já entregam máscara e validação prontas. A desvantagem é o tamanho adicional e a dependência de terceiros que podem ser abandonados. Para projetos pequenos ou APIs simples, o código acima resolve em menos de cinquenta linhas. Se precisar validar CPF de forma mais rigorosa, como conferir se o número existe na base da receita federal, a validação matemática não basta. Você precisaria consultar a API pública da receita, que tem limitação de rate e nem sempre responde rápido. Nesse caso, a validação dos dígitos verificadores já é suficiente para a maioria dos casos de uso, e a consulta à receita deve ser feita de forma assíncrona ou em lote.
Para aplicações críticas onde a precisão é fundamental, como sistemas financeiros, considere também validar o dígito verificador do CNPJ além do CPF. Muitos cadastros empresariais aceitam os dois tipos de documento e o erro de confusão é frequente. Resumindo o que funciona: máscara no frontend apenas para experiência do usuário, validação matemática dos dígitos verificadores no backend, armazenamento limpo sem formatação e detecção de edge cases antes de processar. O resto é detalhe.
