NovoVerificação de identidade facial

Como fazer consulta de CPF por nome completo via API

Aprenda como realizar consulta de CPF por nome completo usando uma API REST. Veja exemplos de código, boas práticas e como integrar em seu sistema.

Lucas Vieira
Lucas Vieira
··8 min de leitura
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 ~150 ms. 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:

PlanoPreçoConsultas/mêsSLA
GrátisR$ 05080%
ProR$ 149/mês1.00099%
CorporativoSob consultaPersonalizado99,9%

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 ~150 ms, permitindo a verificação em tempo real durante o cadastro ou transação.

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

O plano gratuito oferece 50 créditos por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 créditos mensais por R$149. Não além da franquia contratada: no plano Grátis a pausa vem com HTTP 403 e a mensagem "Limite de créditos excedido" assim que os 50 créditos mensais acabam. Nos planos pagos o excedente, quando previsto, é cobrado na fatura seguinte conforme a página de preços, e o limite por minuto responde HTTP 429 com Retry-After.

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 ~150 ms você sabe se os dados conferem. Comece com 50 consultas gratuitas em cpfhub.io.

CPFHub.io

Pronto para integrar a API?

50 créditos gratuitos para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

WhatsApp