Validar CPF: como checar se um CPF é válido online e no código

CPF válido e CPF de pessoa real existente são coisas distintas. Um CPF pode passar no algoritmo mod-11, ter máscara correta e ainda assim estar suspenso, cancelado ou nunca ter sido emitido. Entender essa diferença evita bugs silenciosos em produção e, mais importante, evita decisões erradas baseadas em dados que parecem corretos mas não são.

O que define um CPF como válido

Estrutura do documento: 9 dígitos base e 2 verificadores

O CPF tem 11 dígitos numéricos: 9 dígitos base (D1 a D9) e 2 dígitos verificadores (D10 e D11). A máscara padrão é NNN.NNN.NNN-DD. Os primeiros 8 dígitos são sequenciais dentro de uma região fiscal; o nono identifica a Superintendência Regional da Receita Federal (SRRF) responsável pela inscrição.

O que o dígito verificador garante (e o que não garante)

Os dígitos D10 e D11 são derivados dos 9 anteriores via algoritmo mod-11. Eles garantem que qualquer erro de digitação em um único dígito resulta num CPF com verificadores incorretos. Isso cobre transposições simples e erros de uma tecla.

O que os verificadores não garantem: que o CPF foi emitido, que pertence a uma pessoa viva, ou que está ativo na base da Receita Federal. Um CPF pode ser matematicamente perfeito e ainda assim nunca ter existido.

CPFs matematicamente válidos que a Receita Federal rejeita

Além das regras do algoritmo, a Receita Federal reserva alguns intervalos como inválidos por definição. O mais conhecido é a lista de CPFs com todos os dígitos iguais: 000.000.000-00, 111.111.111-11 até 999.999.999-99. Qualquer implementação que não bloqueie esses casos vai aceitar valores claramente fictícios como válidos.

O algoritmo mod-11 explicado passo a passo

Cálculo do primeiro dígito verificador

Pegue os 9 primeiros dígitos e multiplique cada um por um peso decrescente, de 10 a 2:

D1×10 + D2×9 + D3×8 + D4×7 + D5×6 + D6×5 + D7×4 + D8×3 + D9×2

Some os produtos. Calcule o resto da divisão por 11. Se o resto for 0 ou 1, o primeiro verificador é 0. Caso contrário, é 11 - resto.

Cálculo do segundo dígito verificador

Repita o processo com os 10 primeiros dígitos (incluindo D10 já calculado), com pesos de 11 a 2. Mesma regra de resto: se resto for menor que 2, verificador é 0; senão, 11 - resto.

Casos especiais obrigatórios: CPFs com todos os dígitos iguais

Os 10 CPFs com todos os dígitos iguais (de 00000000000 a 99999999999) passam matematicamente no mod-11 porque a soma dos produtos sempre produz um verificador consistente com a sequência. A Receita Federal os rejeita por critério administrativo. Toda implementação precisa checar esse caso explicitamente antes de rodar o algoritmo.

Implementação em TypeScript/JavaScript

Função validarCPF anotada linha a linha

export function validarCPF(cpf: string): boolean {
  // Remove máscara: pontos e traço
  const digits = cpf.replace(/[.\-]/g, "").trim();

  // Rejeita comprimento errado ou não-numérico
  if (!/^\d{11}$/.test(digits)) return false;

  // Rejeita CPFs com todos os dígitos iguais
  if (/^(\d)\1{10}$/.test(digits)) return false;

  const calc = (length: number): number => {
    let sum = 0;
    for (let i = 0; i < length; i++) {
      sum += parseInt(digits[i]) * (length + 1 - i);
    }
    const remainder = sum % 11;
    return remainder < 2 ? 0 : 11 - remainder;
  };

  const d10 = calc(9);
  const d11 = calc(10);

  return d10 === parseInt(digits[9]) && d11 === parseInt(digits[10]);
}

Remover máscara antes de calcular (erro mais comum)

O erro mais frequente em produção é receber "123.456.789-09" e tentar calcular diretamente sobre a string com pontuação. O caractere "." vira NaN no parseInt, o que faz a soma retornar NaN e o verificador calculado nunca bate com o esperado. A função acima trata isso na primeira linha com replace(/[.\-]/g, "").

Conjunto de casos de teste: válidos, inválidos, edge cases

import { describe, it, expect } from "vitest";
import { validarCPF } from "./cpf";

describe("validarCPF", () => {
  it("aceita CPF válido sem máscara", () => {
    expect(validarCPF("52998224725")).toBe(true);
  });

  it("aceita CPF válido com máscara", () => {
    expect(validarCPF("529.982.247-25")).toBe(true);
  });

  it("rejeita CPF com dígito errado", () => {
    expect(validarCPF("52998224724")).toBe(false);
  });

  it("rejeita 111.111.111-11", () => {
    expect(validarCPF("111.111.111-11")).toBe(false);
  });

  it("rejeita string vazia", () => {
    expect(validarCPF("")).toBe(false);
  });

  it("rejeita CPF com letras", () => {
    expect(validarCPF("529.982.247-2A")).toBe(false);
  });

  it("rejeita CPF com comprimento errado", () => {
    expect(validarCPF("5299822472")).toBe(false);
  });
});

Implementação em Python

Função valida_cpf equivalente com tipagem

import re

def valida_cpf(cpf: str) -> bool:
    digits = re.sub(r"[.\-]", "", cpf).strip()

    if not re.fullmatch(r"\d{11}", digits):
        return False

    if len(set(digits)) == 1:
        return False

    def calc(length: int) -> int:
        total = sum(int(digits[i]) * (length + 1 - i) for i in range(length))
        remainder = total % 11
        return 0 if remainder < 2 else 11 - remainder

    return calc(9) == int(digits[9]) and calc(10) == int(digits[10])

Integração com Pydantic v2 como validador de campo personalizado

from pydantic import BaseModel, field_validator

class Cliente(BaseModel):
    nome: str
    cpf: str

    @field_validator("cpf")
    @classmethod
    def cpf_valido(cls, v: str) -> str:
        if not valida_cpf(v):
            raise ValueError("CPF inválido")
        return v

Uso em Django Forms e FastAPI

Em Django Forms, implemente clean_cpf no formulário:

def clean_cpf(self):
    cpf = self.cleaned_data.get("cpf", "")
    if not valida_cpf(cpf):
        raise forms.ValidationError("CPF inválido.")
    return cpf

Em FastAPI, o modelo Pydantic com @field_validator já funciona como dependência: async def criar_cliente(cliente: Cliente). O framework chama a validação automaticamente antes de entrar no handler.

Validar CPF online: o que cada ferramenta faz de fato

Existem três categorias de "validação online" e elas não são equivalentes.

Validação de formato (algoritmo local, sem rede)

Qualquer implementação do mod-11 roda completamente offline. Não há motivo para enviar o CPF a um servidor externo apenas para checar o formato. Isso aplica tanto para validação em formulários públicos quanto para suítes de testes automatizados.

FakeForge /validar-cpf: validação client-side, nenhum dado trafega ao servidor

O validador de CPF do FakeForge executa o algoritmo diretamente no navegador via JavaScript. O CPF digitado não é enviado a nenhuma API, não é registrado em log e não é armazenado. Útil para checar rapidamente se um CPF de fixture está correto ou para confirmar o resultado do seu próprio algoritmo.

Receita Federal: situação cadastral pública vs. dados protegidos

O portal de consulta de situação cadastral permite verificar se um CPF está regular, suspenso, cancelado ou pendente de regularização. Para isso, o CPF é enviado ao servidor da Receita. O retorno é público: nome completo, situação e data de inscrição. Nenhum dado financeiro ou endereço é retornado sem convênio formal.

Consulta de situação cadastral na Receita Federal

O que o portal da Receita revela: nome, situação, data de inscrição

A consulta pública retorna três campos: nome completo do titular, situação cadastral atual e data de inscrição. Isso é suficiente para confirmar que o CPF foi emitido e está ativo, mas não é suficiente para verificar identidade porque qualquer pessoa com o número pode consultar.

O que não está disponível sem convênio formal

Endereço, data de nascimento, nome da mãe, vínculos trabalhistas e dados fiscais são protegidos. O acesso programático a esses dados exige convênio com a Receita Federal, com base jurídica explícita e aprovação do comitê de segurança da informação da RF.

Scraping do portal da Receita: por que é arriscado tecnicamente e juridicamente

Tecnicamente: o portal usa CAPTCHA e pode retornar rate-limiting ou banimento de IP sem aviso. Juridicamente: automatizar o acesso ao portal pode configurar acesso não autorizado a sistema informático, nos termos da Lei 9.983/2000, que inseriu os Art. 313-A e Art. 313-B no Código Penal. Há precedentes de autuações administrativas e inquéritos.

AVISO: Nunca automatize scraping do portal da Receita Federal sem convênio formal. Além do risco jurídico, qualquer dado obtido dessa forma não tem base legal sob a LGPD e não pode ser armazenado ou processado.

LGPD e validação de CPF: onde está a linha

CPF como dado pessoal direto (LGPD Art. 5º, I — Lei 13.709/2018)

O CPF identifica diretamente uma pessoa natural. Ele se enquadra como dado pessoal nos termos do Art. 5º, I da Lei 13.709/2018, o que significa que qualquer operação sobre ele (coleta, armazenamento, transmissão, consulta) exige base legal documentada.

Bases legais para tratar CPF em produção: Art. 7º, II (contrato) e Art. 7º, IX (legítimo interesse)

As duas bases mais usadas em contexto de desenvolvimento de software são:

• Art. 7º, II: execução de contrato do qual o titular é parte. Se o usuário está comprando um produto e o CPF é necessário para emissão de nota fiscal, há base legal clara.
• Art. 7º, IX: legítimo interesse do controlador. Aplicável quando o tratamento é necessário para prevenir fraude, desde que não sobreponha os direitos do titular. Exige Relatório de Impacto (RIPD) para casos de alto risco.

Validar formato em formulário público não requer consentimento, mas armazenar exige

Rodar o algoritmo mod-11 no navegador, sem transmitir o CPF, não constitui tratamento de dado pessoal sob a LGPD porque nenhum dado sai da máquina do usuário. O momento que exige base legal é o armazenamento ou transmissão. Um formulário de cadastro que coleta CPF deve ter aviso de privacidade claro antes do envio.

Gerar CPFs válidos para testes sem risco de LGPD

Por que usar CPFs fictícios em fixtures e seeds

CPFs reais em seeds de banco de dados ou fixtures de testes violam o princípio da minimização de dados (LGPD Art. 6º, III). Além do risco legal, expõem dados pessoais a desenvolvedores que não precisam deles, aumentam a superfície de um eventual vazamento e podem travar pipelines de CI/CD que rodam em infraestrutura de terceiros.

A solução direta é usar CPFs gerados especificamente para testes: matematicamente válidos, sem correspondência com pessoas reais.

FakeForge API: GET /api/generate?type=cpf&quantity=50&format=json

curl "https://fakeforge.com.br/api/generate?type=cpf&quantity=10&format=json"

O retorno inclui um campo _meta com fonte, URL e data de geração, seguido do array data com os CPFs.

Exportação SQL com CREATE TABLE pronto para popular banco de testes

const res = await fetch(
  "https://fakeforge.com.br/api/generate?type=cpf&quantity=50&format=sql"
);
const sql = await res.text();
// sql contém CREATE TABLE + INSERT INTO prontos para executar
await db.execute(sql);

A mesma chamada funciona com type=pessoa para obter CPF, nome e endereço correlacionados, o que evita dados incoerentes em testes de integração. Veja a referência completa da API REST e os planos para uso em CI/CD. Para gerar uma pessoa completa com CPF, nome e endereço correlacionados, troque type=cpf por type=pessoa.

Erros frequentes na implementação de validação de CPF

Não remover pontos e traço antes de calcular

O erro mais recorrente em code review. A entrada pode vir com ou sem máscara dependendo de onde o CPF foi coletado. Sempre normalize antes de qualquer cálculo.

Ignorar a lista de CPFs universalmente inválidos

Os 10 CPFs com dígitos repetidos passam no mod-11. Sem a checagem explícita, 111.111.111-11 retorna true. Isso costuma aparecer como dado de teste em bancos de produção quando desenvolvedores usam valores triviais sem perceber que são aceitos pelo algoritmo.

Tratar "formato válido" como "CPF de pessoa real existente"

O algoritmo valida estrutura, não existência. Um CPF pode ser válido matematicamente e nunca ter sido emitido. Se o negócio exige confirmação de existência, isso requer consulta à Receita Federal com base legal adequada.

Validar apenas no front-end sem repetir no servidor

Validação no cliente melhora UX, mas não substitui a validação no servidor. Qualquer chamada direta à API bypassa o front-end. Valide o CPF no handler antes de persistir.

Resumo

• Implemente o mod-11 com dois dígitos verificadores e bloqueie explicitamente os 10 CPFs com dígitos todos iguais antes de rodar qualquer cálculo.
• Sempre normalize a entrada removendo pontos e traço; esse é o erro de implementação mais comum e silencioso.
• Validação de formato roda 100% offline. Só consulte a Receita Federal quando precisar confirmar situação cadastral, e apenas com base legal documentada (Art. 7º, II ou IX da LGPD).
• CPF é dado pessoal direto (LGPD Art. 5º, I); armazenar ou transmitir sem base legal expõe o controlador a sanções da ANPD.
• Use CPFs gerados pelo FakeForge em fixtures e seeds. Nunca use CPFs reais em ambientes de desenvolvimento ou CI/CD.
• Valide qualquer CPF diretamente no navegador sem transmitir o dado a nenhum servidor.