Como fazer consulta de CPF por nome completo via API

Introdução

A necessidade de consultar dados de CPF a partir de um nome completo é uma demanda recorrente em diversos setores, desde fintechs que precisam validar a identidade de clientes durante o onboarding até e-commerces que buscam confirmar a titularidade de um comprador. Em um cenário onde fraudes digitais crescem a cada ano, ter acesso a uma ferramenta confiável de consulta de CPF deixou de ser um diferencial e se tornou uma necessidade operacional.

O que significa consultar CPF por nome completo

Quando falamos em "consultar CPF por nome completo", estamos nos referindo ao processo de verificar se um determinado CPF está associado a um nome específico. Esse tipo de verificação é fundamental em processos de KYC (Know Your Customer), prevenção a fraudes e validação cadastral.

Cenários comuns de uso

• Onboarding digital -- Fintechs e bancos digitais precisam confirmar que o CPF informado pelo usuário corresponde ao nome declarado.

• Checkout de e-commerce -- Lojas virtuais verificam se o nome do comprador coincide com o titular do CPF para reduzir chargebacks.

• Cadastro de prestadores de serviço -- Plataformas de mobilidade e delivery validam motoristas e entregadores antes de liberar acesso.

• Processos jurídicos e imobiliários -- Escritórios de advocacia e imobiliárias confirmam a identidade das partes envolvidas em contratos.

Como funciona a API de consulta de CPF da CPFHub.io

A CPFHub.io disponibiliza um endpoint REST para consulta de CPF que retorna o nome completo, data de nascimento e gênero do titular em menos de 200ms. A autenticação é feita por API key no header, e o retorno é JSON estruturado — pronto para comparação com os dados informados pelo usuário.

Endpoint

GET https://api.cpfhub.io/cpf/{CPF_NUMBER}

Autenticação

A autenticação é feita via header x-api-key, que você obtém no painel de controle em app.cpfhub.io após criar sua conta gratuita.

Exemplo de requisição com cURL

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

Exemplo de resposta JSON

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Maria da Silva Santos",
    "nameUpper": "MARIA DA SILVA SANTOS",
    "gender": "F",
    "birthDate": "22/03/1985",
    "day": 22,
    "month": 3,
    "year": 1985
    }
}

Com essa resposta, o campo name retorna o nome completo associado ao CPF consultado. A partir daí, seu sistema pode comparar esse nome com o nome informado pelo usuário no cadastro.

Implementando a validação de nome em seu sistema

O fluxo ideal para validar se um CPF corresponde a um nome é o seguinte: o usuário informa o CPF e o nome no formulário; sua aplicação consulta a API com o CPF informado; e, em seguida, compara o nome retornado com o nome declarado pelo usuário.

Exemplo em JavaScript (Node.js)

const axios = require('axios');

async function validarNomeCPF(cpf, nomeInformado) {
    try {
    const response = await axios.get(
    `https://api.cpfhub.io/cpf/${cpf}`,
    {
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    timeout: 10000
    }
    );

    if (response.data.success) {
    const nomeOficial = response.data.data.nameUpper;
    const nomeUsuario = nomeInformado.toUpperCase().trim();

    if (nomeOficial === nomeUsuario) {
    return { valido: true, mensagem: 'Nome corresponde ao CPF.' };
    } else {
    return { valido: false, mensagem: 'Nome não corresponde ao CPF informado.' };
    }
    }

    return { valido: false, mensagem: 'Não foi possível consultar o CPF.' };
    } catch (error) {
    return { valido: false, mensagem: 'Erro na consulta: ' + error.message };
    }
}

// Uso
validarNomeCPF('12345678900', 'Maria da Silva Santos')
    .then(resultado => console.log(resultado));

Boas práticas na comparação de nomes

A comparação de nomes exige cuidado. Nomes podem conter acentos, abreviações ou variações de escrita. Algumas práticas recomendadas incluem:

• Normalização -- Converta ambos os nomes para maiúsculas e remova acentos antes de comparar.

• Tolerância a variações -- Considere usar algoritmos de similaridade como Levenshtein ou Jaro-Winkler para lidar com pequenas diferenças de digitação.

• Verificação parcial -- Em alguns cenários, verificar se o primeiro e último nome coincidem já oferece um nível aceitável de confiança.

Diferença entre consulta por CPF e busca por nome

Um ponto importante a esclarecer: a API da CPFHub.io consulta por CPF, não por nome. Não há busca reversa — essa é justamente a abordagem correta do ponto de vista da LGPD.

A busca reversa (informar nome para obter CPF) apresenta problemas significativos de privacidade e conformidade legal, uma vez que a LGPD restringe o acesso a dados pessoais sem base legal adequada. A abordagem correta e em conformidade com a legislação é:

1. O usuário informa o CPF e o nome.
2. Sua aplicação consulta a API com o CPF.
3. O sistema compara o nome retornado com o informado.

Esse fluxo respeita a LGPD porque o próprio titular está fornecendo seus dados, e a consulta serve apenas para validar a veracidade das informações declaradas.

Planos e limites de uso

A CPFHub.io oferece planos que atendem desde desenvolvedores individuais até grandes corporações:

O plano gratuito é ideal para testes e projetos em fase inicial. Não exige cartão de crédito e permite até 50 consultas por mês, funcionando como um ambiente de sandbox com dados reais.

Cuidados com a LGPD

A consulta de CPF envolve tratamento de dados pessoais, e por isso deve seguir os princípios da LGPD. Algumas recomendações importantes:

• Base legal -- Certifique-se de ter uma base legal válida para o tratamento dos dados, como o legítimo interesse ou a execução de contrato.

• Finalidade específica -- Use os dados retornados apenas para a finalidade declarada (validação cadastral, prevenção a fraudes etc.).

• Minimização -- Não armazene mais dados do que o necessário. Se a validação for pontual, descarte os dados após a verificação.

• Transparência -- Informe ao titular que seus dados estão sendo consultados e para qual finalidade.

A CPFHub.io foi desenvolvida para operar dentro dos limites da LGPD: as consultas são feitas via HTTPS, o acesso é controlado por API key e a API retorna apenas os dados cadastrais mínimos necessários para validação de identidade.

Integração rápida em diferentes linguagens

A API da CPFHub.io oferece exemplos de integração prontos em mais de 13 linguagens, incluindo Node.js, Python, PHP, Laravel, Go, Ruby, Java, .NET, Rust e Elixir. Isso significa que, independentemente da stack tecnológica da sua empresa, a integração pode ser feita em poucos minutos.

Exemplo em Python

import requests

cpf = '12345678900'
nome_informado = 'Maria da Silva Santos'

url = f'https://api.cpfhub.io/cpf/{cpf}'
headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
}

response = requests.get(url, headers=headers, timeout=10)
data = response.json()

if data['success']:
    nome_oficial = data['data']['nameUpper']
    if nome_oficial == nome_informado.upper():
    print('Nome corresponde ao CPF.')
    else:
    print('Nome não corresponde.')
else:
    print('Erro na consulta.')

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

A consulta de CPF por nome completo é uma verificação direta que barra a maioria das fraudes de identidade no onboarding. O usuário informa CPF e nome, seu backend consulta a API, e em menos de 200ms você sabe se os dados conferem. Comece com 50 consultas gratuitas em cpfhub.io.