Como consumir a API da CPFHub.io em PHP usando cURL

Para consumir a API de CPF da CPFHub.io em PHP com cURL, basta inicializar um handle cURL, configurar a URL do endpoint com o CPF desejado, adicionar o header x-api-key com sua chave e executar a requisição. O retorno é um JSON com nome, data de nascimento e gênero do titular em menos de 200ms. A ANPD orienta que dados de identificação pessoal devem ser tratados com finalidade declarada e armazenamento mínimo.

Introdução

O PHP é uma das linguagens mais utilizadas no desenvolvimento web, e o cURL é a forma nativa de fazer requisições HTTP em PHP. Se você precisa consultar CPFs via API em um projeto PHP, este tutorial mostra como integrar a API da CPFHub.io com código completo, tratamento de erros e boas práticas de segurança.

Pré-requisitos

• PHP 7.4+ com extensão cURL habilitada.

• Conta gratuita na CPFHub.io para obter sua API key.

Código básico: consulta de CPF

<?php
$cpf = '12345678900';
$apiKey = getenv('CPFHUB_API_KEY'); // Use variavel de ambiente

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.cpfhub.io/cpf/{$cpf}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
    "x-api-key: {$apiKey}",
    'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);
curl_close($curl);

if ($error) {
    echo "Erro de conexao: {$error}";
    exit;
}

$data = json_decode($response, true);

if ($httpCode === 200 && $data['success']) {
    echo "Nome: " . $data['data']['name'] . "\n";
    echo "Nascimento: " . $data['data']['birthDate'] . "\n";
    echo "Genero: " . $data['data']['gender'] . "\n";
} else {
    echo "Erro na consulta. HTTP: {$httpCode}\n";
}

Resposta esperada

{
    "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
    }
}

Versão com função reutilizável

<?php
function consultarCpf(string $cpf): ?array
{
    $cpf = preg_replace('/\D/', '', $cpf);
    $apiKey = getenv('CPFHUB_API_KEY');

    $curl = curl_init();
    curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.cpfhub.io/cpf/{$cpf}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
    "x-api-key: {$apiKey}",
    'Accept: application/json',
    ],
    ]);

    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);

    if ($httpCode !== 200) {
    return null;
    }

    $data = json_decode($response, true);
    return $data['success'] ? $data['data'] : null;
}

// Uso
$dados = consultarCpf('123.456.789-00');
if ($dados) {
    echo "Nome: {$dados['name']}\n";
} else {
    echo "CPF nao encontrado.\n";
}

Tratamento de erros HTTP

<?php
function tratarErroHttp(int $httpCode): string
{
    return match ($httpCode) {
    400 => 'CPF com formato invalido',
    401 => 'Chave de API invalida ou ausente',
    404 => 'CPF nao encontrado na base',
    500 => 'Erro interno do servidor',
    default => "Erro desconhecido: HTTP {$httpCode}",
    };
}

Boas práticas

• Variáveis de ambiente -- Nunca coloque a chave de API diretamente no código. Use getenv() ou arquivos .env.

• Timeout -- Sempre configure CURLOPT_TIMEOUT para evitar requisições travadas.

• Sanitização -- Remova caracteres não numéricos do CPF antes de enviar (preg_replace('/\D/', '', $cpf)).

• Cache -- Para CPFs consultados repetidamente, implemente cache com TTL adequado.

• LGPD -- Não armazene dados pessoais além do necessário. Mascare CPFs em logs.

Perguntas frequentes

Como habilitar a extensão cURL no PHP para usar com a API?

Verifique se a extensão está ativa rodando php -m | grep curl. No Linux/Ubuntu, instale com sudo apt install php-curl e reinicie o servidor web. No Windows com XAMPP, descomente extension=curl no php.ini. Sem a extensão ativa, as funções curl_init() e curl_exec() não estão disponíveis.

O que fazer quando a requisição PHP retorna erro de timeout?

Configure CURLOPT_TIMEOUT com um valor adequado (recomendado: 10 segundos) e CURLOPT_CONNECTTIMEOUT com 5 segundos. Se os timeouts persistirem, verifique se o servidor tem saída para a internet na porta 443. Em ambientes com proxy corporativo, configure CURLOPT_PROXY com o endereço do proxy.

Como armazenar a API key com segurança em um projeto PHP?

Use variáveis de ambiente lidas com getenv('CPFHUB_API_KEY') em vez de hardcodar no código-fonte. Em produção, defina a variável no servidor via painel de controle da hospedagem ou arquivo .env carregado pela biblioteca vlucas/phpdotenv. Nunca versione arquivos com chaves de API no Git.

A API CPFHub.io funciona bem com volumes altos de consultas em PHP?

Sim. Para consultas em lote, recomenda-se implementar cache para evitar chamadas repetidas do mesmo CPF. O plano gratuito oferece 50 consultas por mês para testes. Ao exceder o limite de qualquer plano, a API não bloqueia — cobra R$0,15 por consulta adicional, sem interrupção do serviço.

Conclusão

Integrar a API da CPFHub.io em PHP com cURL é direto: poucos parâmetros de configuração, uma chamada GET e o JSON de resposta já traz nome, data de nascimento e gênero do titular. Com as boas práticas de variáveis de ambiente, timeout e sanitização do CPF, o código fica seguro e pronto para produção.

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