Como a Receita Federal válida CPFs e o que isso significa para APIs de consulta

A Receita Federal valida CPFs em dois níveis: sintático (algoritmo de módulo 11 aplicado aos dígitos verificadores) e cadastral (confronto com os dados do titular registrados no banco oficial). APIs de consulta como a CPFHub.io replicam essa segunda camada, retornando nome, data de nascimento e gênero para que sistemas privados possam verificar identidades em tempo real.

Introdução

O Cadastro de Pessoas Físicas (CPF) é administrado pela Receita Federal do Brasil (RFB). Toda pessoa física no Brasil -- brasileiros e estrangeiros com obrigações tributárias -- possui um número de CPF vinculado a um conjunto de dados cadastrais. Entender como a Receita Federal gerencia e válida esses dados é fundamental para quem utiliza APIs de consulta de CPF em seus sistemas.

Muitas empresas e desenvolvedores utilizam APIs como a da CPFHub.io para acessar dados cadastrais de CPF de forma automatizada, agilizando processos de verificação de identidade que antes exigiam consulta manual.

Estrutura do número de CPF

O CPF é composto por 11 dígitos, divididos em três partes:

Dígitos de inscrição (1-8)

Os oito primeiros dígitos identificam o contribuinte de forma sequencial. Não seguem uma lógica geográfica fixa, embora historicamente o nono dígito estivesse vinculado à região fiscal.

Dígito da região fiscal (9)

O nono dígito indica a região fiscal onde o CPF foi originalmente inscrito:

Dígitos verificadores (10-11)

Os dois últimos dígitos são calculados a partir dos nove primeiros usando um algoritmo de módulo 11. Esses dígitos garantem a integridade do número e permitem a validação sintática (verificação de que o número é matematicamente válido).

Validação sintática vs. validação real

É importante distinguir entre dois tipos de validação de CPF:

Validação sintática

Verifica se o número de CPF é matematicamente válido, aplicando o algoritmo de módulo 11. Essa validação pode ser feita localmente, sem consultar nenhuma base de dados:

• Verifica se os dígitos verificadores estão corretos.
• Rejeita CPFs com todos os dígitos iguais (ex: 111.111.111-11).
• Rejeita CPFs com menos ou mais de 11 dígitos.

A validação sintática não confirma que o CPF está ativo, que pertence a uma pessoa real ou que os dados cadastrais são corretos.

Validação real (via API)

Consulta os dados cadastrais vinculados ao CPF em uma base de dados atualizada. Retorna informações como nome completo, data de nascimento e gênero. Essa validação:

• Confirma que o CPF pertence a uma pessoa real.
• Retorna os dados cadastrais oficiais para confronto.
• Identifica CPFs que não existem na base.

A API da CPFHub.io realiza esse tipo de validação real, permitindo que sistemas privados verifiquem identidades com os dados que constam na base cadastral.

Como a Receita Federal mantém o cadastro

Inscrição

O CPF pode ser inscrito por meio de:

• Agências dos Correios.
• Agências do Banco do Brasil ou Caixa Econômica Federal.
• Portal e-CAC da Receita Federal.
• Cartórios de registro civil (para recém-nascidos).

Atualização

Os dados cadastrais podem ser atualizados pelo titular a qualquer momento pelos mesmos canais de inscrição. A Receita Federal também atualiza dados com base em informações recebidas de outros órgãos.

Obrigatoriedade

Desde 2017, o CPF é o documento de identificação único para diversas operações no Brasil, incluindo:

• Abertura de contas bancárias.
• Matrícula em instituições de ensino.
• Acesso a programas sociais.
• Operações imobiliárias.

O que APIs de consulta retornam

Uma API de consulta de CPF bem estruturada retorna os dados cadastrais necessários para verificação de identidade. A resposta da CPFHub.io inclui:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Cada campo serve a um propósito específico na validação:

• name / nameUpper -- Permite confrontar com o nome declarado pelo usuário.

• gender -- Pode ser usado para validação cruzada com outros documentos.

• birthDate / day / month / year -- Permite verificar maioridade e confrontar com dados declarados.

Implementação da validação completa

Exemplo em JavaScript com validação sintática + real

function validarDigitosCPF(cpf) {
    const numeros = cpf.replace(/\D/g, '');
    if (numeros.length !== 11) return false;
    if (/^(\d)\1{10}$/.test(numeros)) return false;

    for (let t = 9; t < 11; t++) {
    let soma = 0;
    for (let i = 0; i < t; i++) {
    soma += parseInt(numeros[i]) * (t + 1 - i);
    }
    let resto = (soma * 10) % 11;
    if (resto === 10) resto = 0;
    if (resto !== parseInt(numeros[t])) return false;
    }
    return true;
}

async function validarCPFCompleto(cpf, nomeDeclarado) {
    // Etapa 1: Validacao sintatica
    if (!validarDigitosCPF(cpf)) {
    return { valido: false, motivo: 'CPF sintaticamente invalido' };
    }

    // Etapa 2: Validacao real via API
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: controller.signal
    });

    clearTimeout(timeoutId);
    const dados = await response.json();

    if (!dados.success) {
    return { valido: false, motivo: 'CPF nao encontrado na base' };
    }

    const nomeConfere = dados.data.nameUpper === nomeDeclarado.toUpperCase().trim();

    return {
    valido: nomeConfere,
    motivo: nomeConfere ? 'CPF validado com sucesso' : 'Nome divergente',
    dados: dados.data
    };
    } catch (erro) {
    clearTimeout(timeoutId);
    return { valido: false, motivo: 'Erro na consulta: ' + erro.message };
    }
}

Diferenças entre validação local e via API

A abordagem recomendada é combinar ambas: primeiro a validação sintática (para rejeitar CPFs obviamente inválidos sem consumir créditos da API) e depois a validação real via API.

Boas práticas ao utilizar APIs de consulta

• Valide sintaticamente primeiro -- Economize créditos da API rejeitando CPFs inválidos localmente.

• Cache com moderação -- Se o mesmo CPF é consultado repetidamente em curto intervalo, considere cache temporário (respeitando a LGPD).

• Trate erros adequadamente -- Implemente retry com backoff exponencial para falhas de rede.

• Registre logs de auditoria -- Cada consulta deve ser registrada para conformidade regulatória.

• Gerencie o volume -- O plano gratuito oferece 50 consultas/mês sem cartão de crédito; consultas excedentes são cobradas a R$0,15 cada, sem bloqueio da API.

Perguntas frequentes

Qual a diferença entre validação sintática e validação real de CPF?

A validação sintática aplica o algoritmo de módulo 11 localmente e confirma apenas que os dígitos verificadores estão matematicamente corretos — não garante que o CPF pertence a uma pessoa real. A validação real, feita via API, consulta a base cadastral e retorna nome, data de nascimento e gênero do titular, confirmando que o CPF existe e está ativo.

A API retorna erro quando o limite de consultas é atingido?

Não. A API da CPFHub.io nunca bloqueia consultas nem retorna erro por limite excedido. Ao ultrapassar as 50 consultas mensais do plano gratuito, cada consulta adicional é cobrada automaticamente a R$0,15, garantindo continuidade operacional sem interrupções.

Por que combinar validação sintática com validação via API?

A combinação evita consumo desnecessário de créditos: CPFs com dígitos verificadores incorretos são rejeitados localmente (custo zero) antes de chegar à API. Apenas CPFs sintaticamente válidos chegam à consulta, que então confirma a existência real do titular e retorna os dados cadastrais.

Quais dados a Receita Federal vincula ao CPF?

O cadastro mantido pela Receita Federal vincula ao CPF o nome completo do titular, data de nascimento, gênero e situação cadastral. APIs de consulta como a CPFHub.io retornam esses dados em formato JSON estruturado, permitindo automação de processos de verificação de identidade.

Conclusão

Compreender como a Receita Federal gerencia o CPF permite que desenvolvedores e empresas utilizem APIs de consulta de forma mais inteligente e eficaz. A combinação de validação sintática local com validação real via API oferece o melhor equilíbrio entre custo, performance e segurança. Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e implemente a validação completa de CPF com apenas uma chamada GET ao endpoint da API.