Validação

Normalizar CPF: remover máscara e validar formato

Aprenda a normalizar CPF com ou sem máscara antes do envio à API e entenda limites da validação matemática.

Imagem editorial sobre Normalização de CPF
Normalização de CPF.

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.

Continue aprendendo