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

> Aprenda a usar Guzzle para fazer requisições na API de CPF em PHP. Instalação, configuração, tratamento de erros e boas práticas.

**Publicado:** 09/05/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-usar-guzzle-para-consultar-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

```bash
composer require guzzlehttp/guzzle
```

Consulte a documentação oficial em [docs.guzzlephp.org](https://docs.guzzlephp.org) para detalhes sobre versões e configuração avançada.

---

## Consulta básica

```php
<?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
<?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
<?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
<?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](https://www.gov.br/anpd) orienta que consultas em massa devem ter base legal registrada.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [Como consumir API de CPF em PHP com cURL e Guzzle](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-php-com-curl-e-guzzle)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)

---

## 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**](https://www.cpfhub.io/) robusta e fácil de manter.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) para obter sua chave gratuitamente e começar a validar CPFs em produção.