Como usar Guzzle para fazer requisições na API de CPF em PHP

Guzzle é o cliente HTTP mais popular do ecossistema PHP. Para consultar a API de CPF da CPFHub.io em PHP, basta instalar o pacote via Composer, configurar o header x-api-key e fazer um GET para https://api.cpfhub.io/cpf/{CPF}. A resposta chega em ~900ms com nome, gênero e data de nascimento do titular — pronta para uso em qualquer fluxo de cadastro ou validação.

Instalação

composer require guzzlehttp/guzzle

Consulte a documentação oficial em docs.guzzlephp.org para detalhes sobre versões e configuração avançada.

Consulta básica

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.cpfhub.io/',
    'timeout' => 10,
    'headers' => [
    'x-api-key' => getenv('CPFHUB_API_KEY'),
    'Accept' => 'application/json',
    ],
]);

$cpf = '12345678900';

$response = $client->get("cpf/{$cpf}");
$dados = json_decode($response->getBody(), true);

if ($dados['success']) {
    echo "Nome: " . $dados['data']['name'] . PHP_EOL;
    echo "Nascimento: " . $dados['data']['birthDate'] . PHP_EOL;
    echo "Genero: " . $dados['data']['gender'] . PHP_EOL;
} else {
    echo "CPF nao encontrado" . PHP_EOL;
}

Tratamento de erros

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Exception\ConnectException;
use GuzzleHttp\Exception\ServerException;

function consultarCpf(Client $client, string $cpf): array
{
    try {
    $response = $client->get("cpf/{$cpf}");
    return json_decode($response->getBody(), true);

    } catch (ClientException $e) {
    $status = $e->getResponse()->getStatusCode();

    if ($status === 401) {
    return ['error' => 'Chave de API invalida', 'code' => 401];
    }
    if ($status === 404) {
    return ['error' => 'CPF nao encontrado', 'code' => 404];
    }

    return ['error' => "Erro HTTP {$status}", 'code' => $status];

    } catch (ServerException $e) {
    return ['error' => 'Erro interno do servidor', 'code' => 500];

    } catch (ConnectException $e) {
    return ['error' => 'Erro de conexao: ' . $e->getMessage(), 'code' => 0];
    }
}

Retry automático com middleware

Guzzle permite configurar retries automáticos para erros temporários de servidor:

<?php

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;

$stack = HandlerStack::create();

$stack->push(Middleware::retry(
    function (int $retries, Request $request, ?Response $response = null) {
    if ($retries >= 3) return false;

    $status = $response ? $response->getStatusCode() : 0;
    return $status >= 500;
    },
    function (int $retries) {
    return 1000 * pow(2, $retries); // 1s, 2s, 4s
    }
));

$client = new Client([
    'handler' => $stack,
    'base_uri' => 'https://api.cpfhub.io/',
    'timeout' => 10,
    'headers' => [
    'x-api-key' => getenv('CPFHUB_API_KEY'),
    'Accept' => 'application/json',
    ],
]);

Consultas assíncronas

Para processar múltiplos CPFs em paralelo:

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Promise\Utils;

$client = new Client([
    'base_uri' => 'https://api.cpfhub.io/',
    'timeout' => 10,
    'headers' => [
    'x-api-key' => getenv('CPFHUB_API_KEY'),
    'Accept' => 'application/json',
    ],
]);

$cpfs = ['12345678900', '98765432100', '11122233344'];
$promises = [];

foreach ($cpfs as $cpf) {
    $promises[$cpf] = $client->getAsync("cpf/{$cpf}");
}

$resultados = Utils::settle($promises)->wait();

foreach ($resultados as $cpf => $resultado) {
    if ($resultado['state'] === 'fulfilled') {
    $dados = json_decode($resultado['value']->getBody(), true);
    echo "{$cpf}: {$dados['data']['name']}" . PHP_EOL;
    } else {
    echo "{$cpf}: Erro" . PHP_EOL;
    }
}

Boas práticas

• Variáveis de ambiente — Use getenv('CPFHUB_API_KEY') para a chave; nunca a coloque diretamente no código.

• Timeout — Sempre configure timeout de 5 a 10 segundos, considerando a latência de ~900ms da API.

• Base URI — Configure uma vez no client, não repita em cada chamada.

• Retry — Use middleware para erros 5xx. A CPFHub.io não retorna 429 — ao ultrapassar o limite de consultas, cobra R$0,15 por requisição adicional.

• Logging — Mascare CPFs nos logs de requisição para conformidade com a LGPD.

Perguntas frequentes

Por que usar Guzzle em vez do cURL nativo do PHP para consultar a API de CPF?

O Guzzle oferece uma interface orientada a objetos, suporte nativo a promises para requisições assíncronas, middleware de retry configurável e tratamento de exceções tipado — tudo que o cURL exige que você implemente manualmente. Para integrações em produção com a CPFHub.io, o Guzzle reduz o código boilerplate e facilita testes unitários com mocks via MockHandler.

Como configurar o timeout corretamente levando em conta a latência da API?

A API da CPFHub.io tem latência de ~900ms em condições normais. Configure o timeout do Guzzle entre 5 e 10 segundos — suficiente para acomodar variações de rede sem prejudicar a experiência do usuário. Valores muito baixos (abaixo de 2 segundos) causam timeouts falsos em picos de tráfego; valores muito altos travam requisições por tempo excessivo.

O que acontece quando o limite mensal de consultas é atingido?

A API da CPFHub.io não bloqueia nem retorna erro ao atingir o limite. Cada consulta além da cota mensal é cobrada a R$0,15, sem interrupção do serviço. Para controlar custos, monitore o uso pelo painel em app.cpfhub.io/settings/billing e configure alertas antes de atingir o teto desejado.

Como processar múltiplos CPFs sem travar a aplicação PHP?

Use as promises assíncronas do Guzzle com getAsync() e Utils::settle(), como mostrado no exemplo acima. Esse padrão dispara todas as requisições em paralelo e aguarda a resolução de cada uma — muito mais eficiente do que um loop sequencial quando você precisa validar lotes de CPFs. A ANPD orienta que consultas em massa devem ter base legal registrada.

Conclusão

Guzzle é a forma mais profissional de consumir APIs REST em PHP. Com tratamento de erros tipado, retry automático e suporte a chamadas assíncronas, ele torna a integração com a CPFHub.io robusta e fácil de manter.

Cadastre-se em cpfhub.io para obter sua chave gratuitamente e começar a validar CPFs em produção.