# 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. **Publicado:** 23/02/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/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 ```bash 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 ```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) ```javascript 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: | Plano | Preço | Consultas/mês | SLA | | --- | --- | --- | --- | | Grátis | R$ 0 | 50 | 80% | | Pro | R$ 149/mês | 1.000 | 99% | | Corporativo | Sob consulta | Personalizado | 99,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 ```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](https://www.gov.br/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. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## 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](https://www.cpfhub.io/).