CPF com máscara e CPF sem máscara
Um CPF pode aparecer como 529.982.247-25 ou 52998224725. Antes de chamar uma API, normalizar CPF significa transformar a representação em uma sequência estável, normalmente removendo pontuação. Isso diminui erros de comparação e de envio, mas não valida os dígitos verificadores.
A API CPF documenta aceitação de CPF com e sem máscara nos endpoints /v1/validate e /consulta. Mesmo assim, padronizar a entrada no backend ajuda a manter integrações consistentes.
Exemplo de normalização em JavaScript
function normalizarCpf(valor) {
const numeros = String(valor).replace(/\D/g, "");
if (!/^\d{11}$/.test(numeros)) {
throw new Error("CPF deve conter 11 dígitos");
}
return numeros;
}
console.log(normalizarCpf("529.982.247-25"));
// 52998224725
O teste de expressão regular verifica comprimento e caracteres, não os dígitos matemáticos. Para isso, utilize uma implementação adequada de cálculo ou a rota específica de validação, conforme o guia de validação.
Exemplo equivalente em PHP
<?php
function normalizarCpf(string $valor): string {
$cpf = preg_replace('/\D/', '', $valor);
if (strlen($cpf) !== 11) {
throw new InvalidArgumentException('CPF mal formatado');
}
return $cpf;
}
Em formulários, preserve zeros à esquerda: CPF é identificador textual, não número para operações aritméticas. Evite converter para inteiro, pois isso pode alterar a representação.
Qual é a ordem correta?
Receba → normalize → confira comprimento → valide dígitos → decida se consulta cadastral é necessária → envie somente no backend autorizado. Uma validação positiva não demonstra cadastro ativo ou titularidade do número.
Erros comuns de implementação
- Salvar CPF como campo numérico em vez de texto.
- Confundir formato de 11 dígitos com CPF matematicamente válido.
- Enviar valores sem normalizar a múltiplos sistemas e criar duplicidades.
- Registrar CPF completo em logs ao falhar a validação.
- Consultar dados pessoais sempre que alguém preenche um campo, mesmo sem necessidade.
Perguntas frequentes
Preciso remover pontos e hífen antes de consultar?
O contrato aceita máscara, mas a normalização facilita padronização e validação.
Normalizar um CPF confirma sua regularidade?
Não. É só uma operação sobre a string informada.
