Como integrar uma API de consulta de CPF em PHP (passo a passo)

Integrar uma API de consulta de CPF em PHP leva menos de 30 minutos com a CPFHub.io. Você faz uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key, recebe nome, data de nascimento e gênero em JSON, e já pode validar identidades em tempo real — sem cartão de crédito para começar.

Introdução

A integração de uma API de consulta de CPF em aplicações PHP é essencial para empresas que desejam validar dados de clientes de forma automatizada e segura. Isso é especialmente útil para fintechs, e-commerces e instituições financeiras que precisam evitar fraudes e garantir a conformidade com a legislação.

Este tutorial mostra passo a passo como integrar a CPFHub.io em um sistema PHP para realizar consultas de CPF em tempo real. A CPFHub.io oferece suporte a mais de 13 linguagens de programação, incluindo PHP, com conformidade LGPD.

1. Pré-requisitos para a integração

Antes de iniciar a integração, certifique-se de que possui:

• Um ambiente PHP configurado (versão 7.4 ou superior recomendada).
• Uma conta na CPFHub.io para obter a chave de API (plano gratuito com 50 consultas/mês, sem necessidade de cartão).
• Biblioteca cURL ou Guzzle instalada para fazer requisições HTTP.

Se ainda não tem uma conta, cadastre-se em CPFHub.io — o plano gratuito não exige cartão de crédito.

2. Instalando dependências (opcional)

Se você deseja usar Guzzle para facilitar as requisições HTTP, instale-o via Composer:

composer require guzzlehttp/guzzle

Caso prefira usar cURL nativo do PHP, essa etapa não é necessária.

3. Fazendo uma consulta de CPF com PHP

Usando cURL

Aqui está um exemplo de como consultar um CPF utilizando a API da CPFHub.io com cURL:

<?php
$cpf = "12345678900";
$apiKey = "SUA_CHAVE_DE_API";

$url = "https://api.cpfhub.io/cpf/" . $cpf;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: $apiKey",
    "Accept: application/json"
]);
curl_setopt($ch, CURLOPT_HTTPGET, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

print_r($result);
?>

Usando Guzzle

Se você estiver utilizando Guzzle, pode fazer a requisição da seguinte maneira:

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;

$cpf = "12345678900";
$apiKey = "SUA_CHAVE_DE_API";

$client = new Client();
$response = $client->get("https://api.cpfhub.io/cpf/{$cpf}", [
    'headers' => [
    'x-api-key' => $apiKey,
    'Accept' => 'application/json'
    ]
]);

$result = json_decode($response->getBody(), true);
print_r($result);
?>

4. Exemplo de resposta da API

Após a requisição, a API retornará uma resposta no seguinte formato:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

O que essa resposta indica:

• success: Se a consulta foi realizada com sucesso.
• cpf: Número do CPF consultado.
• name: Nome completo do titular do CPF.
• nameUpper: Nome completo em letras maiúsculas.
• gender: Gênero do titular (M ou F).
• birthDate: Data de nascimento no formato dd/mm/aaaa.
• day, month, year: Dia, mês e ano de nascimento separados.

5. Como tratar erros na consulta

A API pode retornar erros caso os dados sejam inválidos ou a chave de API esteja incorreta. Veja um exemplo de tratamento de erros:

if (!$result['success']) {
    echo "Erro na consulta: " . $result['message'];
} else {
    echo "CPF válido: " . $result['data']['name'];
}

Possíveis mensagens de erro

Dica: Sempre valide a entrada do usuário antes de enviar uma consulta para evitar erros desnecessários.

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 integração da API de consulta de CPF em PHP é um processo simples, mas extremamente eficiente para validar a identidade de clientes e evitar fraudes. Com a API da CPFHub.io, você pode realizar consultas rápidas (aproximadamente 900ms), seguras e confiáveis, com 99.9% de uptime e conformidade LGPD.

A API retorna dados como nome completo, nome em maiúsculas, gênero e data de nascimento (com dia, mês e ano separados), atendendo às necessidades de validação de identidade. Mais de 1.300 empresas já confiam na CPFHub.io.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.