# Como consumir API de CPF em PHP com cURL e Guzzle

> Aprenda a consumir uma API de consulta de CPF em PHP utilizando cURL nativo e Guzzle HTTP Client. Exemplos completos com tratamento de erros.

**Publicado:** 21/04/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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](https://www.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
<?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
<?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

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

### Exemplo básico com Guzzle

```php
<?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
<?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:

```json
{
 "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:

| Código | Significado | Ação recomendada |
| --- | --- | --- |
| 200 | Consulta bem-sucedida | Processar os dados normalmente |
| 400 | CPF com formato inválido | Validar o CPF antes de enviar |
| 401 | Chave de API inválida | Verificar a chave no painel |
| 500 | Erro interno do servidor | Tentar novamente após alguns segundos |

**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](https://www.gov.br/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.

### 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)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Guia de headers HTTP obrigatórios para consumir API de CPF corretamente](https://cpfhub.io/blog/guia-de-headers-http-obrigatorios-para-consumir-api-de-cpf-corretamente)

---

## 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](https://www.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.