Como consumir API de CPF em PHP com cURL e Guzzle

Para consumir a API de CPF em PHP, faça uma requisição GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. Com cURL nativo, configure CURLOPT_TIMEOUT e CURLOPT_CONNECTTIMEOUT para evitar bloqueios. Com Guzzle, use os parâmetros timeout e connect_timeout no construtor do Client. Ambas as abordagens retornam nome, gênero e data de nascimento do titular em ~900ms.

Introdução

O PHP continua sendo uma das linguagens mais utilizadas no desenvolvimento web, presente em milhões de sites e aplicações ao redor do mundo. Para empresas que operam no Brasil, integrar uma API de consulta de CPF diretamente em aplicações PHP é uma necessidade frequente, seja para validar cadastros de clientes, prevenir fraudes em e-commerces ou garantir conformidade regulatória em fintechs.

1. Pré-requisitos

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

• PHP 7.4 ou superior — versões mais recentes oferecem melhor desempenho e segurança.

• Extensão cURL habilitada — a maioria das instalações PHP já inclui essa extensão por padrão.

• Composer instalado — necessário apenas se você optar por usar o Guzzle.

• Conta na CPFHub.io — cadastre-se gratuitamente em CPFHub.io.

Após criar sua conta, acesse o painel de controle em app.cpfhub.io para gerar sua chave de API (x-api-key).

2. Consumindo a API com cURL nativo do PHP

O cURL é a forma mais direta de fazer requisições HTTP em PHP, sem depender de bibliotecas externas. Essa abordagem é ideal para projetos que precisam de simplicidade ou que não utilizam gerenciadores de dependências como o Composer.

Exemplo básico com cURL

<?php

$cpf = '12345678900';
$apiKey = 'SUA_CHAVE_DE_API';
$url = "https://api.cpfhub.io/cpf/{$cpf}";

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_CONNECTTIMEOUT => 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 na requisição: " . $error;
    exit;
}

if ($httpCode === 200) {
    $data = json_decode($response, true);
    if ($data['success']) {
    echo "Nome: " . $data['data']['name'] . PHP_EOL;
    echo "CPF: " . $data['data']['cpf'] . PHP_EOL;
    echo "Gênero: " . $data['data']['gender'] . PHP_EOL;
    echo "Nascimento: " . $data['data']['birthDate'] . PHP_EOL;
    } else {
    echo "Consulta não retornou dados." . PHP_EOL;
    }
} else {
    echo "Erro HTTP: " . $httpCode . PHP_EOL;
    echo "Resposta: " . $response . PHP_EOL;
}

Observe que configuramos CURLOPT_TIMEOUT com 30 segundos e CURLOPT_CONNECTTIMEOUT com 10 segundos. Definir timeouts é uma prática essencial para evitar que sua aplicação fique bloqueada indefinidamente caso a rede apresente lentidão.

Criando uma função reutilizável

Para facilitar o uso em diferentes partes da aplicação, encapsule a lógica em uma função:

<?php

function consultarCpf(string $cpf, string $apiKey): ?array
{
    $url = "https://api.cpfhub.io/cpf/{$cpf}";
    $curl = curl_init();

    curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_CONNECTTIMEOUT => 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 || $httpCode !== 200) {
    return null;
    }

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

// Uso
$resultado = consultarCpf('12345678900', 'SUA_CHAVE_DE_API');
if ($resultado) {
    echo "Nome: " . $resultado['name'];
} else {
    echo "Não foi possível consultar o CPF.";
}

3. Consumindo a API com Guzzle HTTP Client

O Guzzle é o cliente HTTP mais popular do ecossistema PHP, oferecendo uma interface orientada a objetos, suporte a middlewares, tratamento de erros robusto e compatibilidade com requisições assíncronas. É a escolha ideal para projetos que já utilizam Composer e frameworks como Laravel ou Symfony.

Instalação do Guzzle

composer require guzzlehttp/guzzle

Exemplo básico com Guzzle

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'base_uri' => 'https://api.cpfhub.io',
    'timeout' => 30,
    'connect_timeout' => 10,
]);

$cpf = '12345678900';
$apiKey = 'SUA_CHAVE_DE_API';

try {
    $response = $client->get("/cpf/{$cpf}", [
    'headers' => [
    'x-api-key' => $apiKey,
    'Accept' => 'application/json',
    ],
    ]);

    $body = json_decode($response->getBody()->getContents(), true);

    if ($body['success']) {
    echo "Nome: " . $body['data']['name'] . PHP_EOL;
    echo "Nome (maiúsculas): " . $body['data']['nameUpper'] . PHP_EOL;
    echo "Gênero: " . $body['data']['gender'] . PHP_EOL;
    echo "Nascimento: " . $body['data']['birthDate'] . PHP_EOL;
    }
} catch (RequestException $e) {
    echo "Erro na requisição: " . $e->getMessage() . PHP_EOL;
    if ($e->hasResponse()) {
    echo "Resposta: " . $e->getResponse()->getBody()->getContents();
    }
}

Classe de serviço para consulta de CPF

Em projetos maiores, é recomendável criar uma classe de serviço dedicada:

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class CpfHubService
{
    private Client $client;
    private string $apiKey;

    public function __construct(string $apiKey)
    {
    $this->apiKey = $apiKey;
    $this->client = new Client([
    'base_uri' => 'https://api.cpfhub.io',
    'timeout' => 30,
    'connect_timeout' => 10,
    ]);
    }

    public function consultar(string $cpf): ?array
    {
    try {
    $response = $this->client->get("/cpf/{$cpf}", [
    'headers' => [
    'x-api-key' => $this->apiKey,
    'Accept' => 'application/json',
    ],
    ]);

    $body = json_decode($response->getBody()->getContents(), true);
    return $body['success'] ? $body['data'] : null;
    } catch (RequestException $e) {
    error_log("Erro ao consultar CPF: " . $e->getMessage());
    return null;
    }
    }
}

// Uso
$service = new CpfHubService('SUA_CHAVE_DE_API');
$resultado = $service->consultar('12345678900');

if ($resultado) {
    echo "Nome: {$resultado['name']}" . PHP_EOL;
    echo "Dia: {$resultado['day']}, Mês: {$resultado['month']}, Ano: {$resultado['year']}";
}

4. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON estruturado com os dados cadastrais do titular:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• success — indica se a consulta foi realizada com sucesso.
• cpf — número do CPF consultado.
• name — nome completo do titular.
• nameUpper — nome 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. Tratamento de erros e códigos HTTP

Uma integração robusta deve tratar adequadamente os diferentes códigos de resposta que a API pode retornar:

Importante: a CPFHub.io nunca retorna HTTP 429 nem bloqueia requisições. Ao ultrapassar o limite do plano, cada consulta extra é cobrada a R$0,15 — sem interrupção do serviço.

6. Boas práticas para produção

Ao levar sua integração para produção, considere as seguintes recomendações:

• Armazene a chave de API em variáveis de ambiente — nunca inclua chaves diretamente no código-fonte. Utilize arquivos .env ou variáveis de ambiente do servidor.

• Implemente cache de resultados — para CPFs consultados com frequência, utilize cache (Redis ou Memcached) para reduzir o número de chamadas e melhorar a performance.

• Valide o CPF antes de enviar — verifique se o CPF tem 11 dígitos e se os dígitos verificadores estão corretos antes de fazer a requisição à API.

• Configure timeouts adequados — sempre defina timeouts para evitar que sua aplicação fique bloqueada.

• Registre logs de consultas — mantenha registros de todas as consultas realizadas para fins de auditoria e conformidade com a LGPD. A ANPD recomenda que o controlador mantenha registros das operações de tratamento de dados pessoais.

Perguntas frequentes

Devo usar cURL nativo ou Guzzle para consumir a API de CPF em PHP?

Depende do contexto do projeto. O cURL nativo é ideal para scripts simples, projetos legados ou quando não há Composer disponível. O Guzzle é preferível em projetos Laravel, Symfony ou qualquer aplicação que já use Composer — ele oferece tratamento de erros mais expressivo, suporte a middlewares e facilita testes unitários com mocks.

A API CPFHub.io bloqueia quando o limite do plano é atingido?

Não. A CPFHub.io nunca retorna HTTP 429 nem suspende o serviço. Quando o plano gratuito (50 consultas/mês) ou o Pro (1.000 consultas/mês, R$149) é ultrapassado, cada requisição extra é cobrada a R$0,15. Não é necessário implementar retry com backoff exponencial para o caso de rate limit.

Como proteger a chave de API em aplicações PHP?

Nunca inclua a x-api-key diretamente no código-fonte. Use variáveis de ambiente (via $_ENV ou getenv()) e arquivos .env carregados pela biblioteca vlucas/phpdotenv. Em produção, configure a variável diretamente no servidor ou no gerenciador de secrets do seu provedor de nuvem.

É possível fazer consultas em lote (batch) com a API?

A API CPFHub.io opera no modelo de consulta individual: um CPF por requisição. Para consultas em lote, implemente um loop com controle de concorrência. Com Guzzle, você pode usar requisições assíncronas (Guzzle\Pool) para processar múltiplos CPFs em paralelo, respeitando os limites do seu plano.

Conclusão

Consumir a API de consulta de CPF em PHP é um processo direto, seja utilizando o cURL nativo para projetos simples ou o Guzzle HTTP Client para aplicações mais complexas. Ambas as abordagens permitem integrar a validação de CPF de forma segura e eficiente, com tempo de resposta de aproximadamente 900ms.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e valide CPFs em PHP com poucas linhas de código ainda hoje.