# Como integrar validação de CPF em Laravel com HTTP Client

> Aprenda a integrar validação de CPF em Laravel usando o HTTP Client nativo. Exemplos com Service Class, Form Request e tratamento de erros.

**Publicado:** 06/05/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-laravel-com-http-client

---


Para integrar validação de CPF em Laravel, use o HTTP Client nativo (disponível desde a versão 7) para chamar `GET https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. Encapsule a chamada em uma Service Class, registre-a como singleton no container e reutilize em controllers, Form Requests e Custom Validation Rules. A resposta chega em ~900ms com nome, data de nascimento e gênero do titular.

## Introdução

O **Laravel** é o framework PHP mais popular do mundo, amplamente adotado por desenvolvedores brasileiros para construir desde aplicações simples até plataformas complexas de fintechs e e-commerces. Uma necessidade recorrente nesses projetos é a **validação de CPF** durante o cadastro de clientes, checkout de compras ou processos de onboarding.

A partir da versão 7, o Laravel passou a incluir um **HTTP Client** nativo baseado no Guzzle, que simplifica drasticamente a forma como fazemos requisições HTTP.

---

## 1. Configuração inicial

### Obtendo a chave de API

Antes de tudo, cadastre-se gratuitamente em [**CPFHub.io**](https://www.cpfhub.io/) para obter sua chave de API. O plano gratuito oferece 50 consultas mensais sem cartão de crédito.

### Adicionando a chave ao .env

Adicione sua chave de API ao arquivo `.env` do projeto Laravel:

```bash
CPFHUB_API_KEY=SUA_CHAVE_DE_API
```

Em seguida, crie uma entrada no arquivo `config/services.php` para centralizar a configuração:

```php
// config/services.php
return [
 // ... outras configurações
 'cpfhub' => [
 'api_key' => env('CPFHUB_API_KEY'),
 'base_url' => 'https://api.cpfhub.io',
 'timeout' => 30,
 ],
];
```

---

## 2. Criando o Service Class

A melhor prática no Laravel é encapsular integrações externas em uma Service Class. Isso mantém o código organizado, testável e reutilizável.

```php
<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class CpfHubService
{
 private string $apiKey;
 private string $baseUrl;
 private int $timeout;

 public function __construct()
 {
 $this->apiKey = config('services.cpfhub.api_key');
 $this->baseUrl = config('services.cpfhub.base_url');
 $this->timeout = config('services.cpfhub.timeout', 30);
 }

 public function consultar(string $cpf): ?array
 {
 $cpfLimpo = preg_replace('/\D/', '', $cpf);

 try {
 $response = Http::withHeaders([
 'x-api-key' => $this->apiKey,
 'Accept' => 'application/json',
 ])
 ->timeout($this->timeout)
 ->get("{$this->baseUrl}/cpf/{$cpfLimpo}");

 if ($response->successful() && $response->json('success')) {
 return $response->json('data');
 }

 Log::warning('CPFHub: Consulta sem sucesso', [
 'cpf' => $cpfLimpo,
 'status' => $response->status(),
 'body' => $response->body(),
 ]);

 return null;
 } catch (\Exception $e) {
 Log::error('CPFHub: Erro na requisição', [
 'cpf' => $cpfLimpo,
 'message' => $e->getMessage(),
 ]);
 return null;
 }
 }

 public function validarIdentidade(string $cpf, string $nome): bool
 {
 $dados = $this->consultar($cpf);

 if (!$dados) {
 return false;
 }

 $nomeApi = mb_strtoupper($dados['nameUpper']);
 $nomeInput = mb_strtoupper(trim($nome));

 return str_contains($nomeApi, $nomeInput) || str_contains($nomeInput, $nomeApi);
 }
}
```

### Registrando o Service no container

No `AppServiceProvider`, registre o service como singleton:

```php
<?php

namespace App\Providers;

use App\Services\CpfHubService;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
 public function register()
 {
 $this->app->singleton(CpfHubService::class, function () {
 return new CpfHubService();
 });
 }
}
```

---

## 3. Usando em Controllers

Com o Service registrado, a injeção de dependência do Laravel facilita o uso em qualquer controller:

```php
<?php

namespace App\Http\Controllers;

use App\Services\CpfHubService;
use Illuminate\Http\Request;

class CadastroController extends Controller
{
 public function verificarCpf(Request $request, CpfHubService $cpfHub)
 {
 $request->validate([
 'cpf' => 'required|string|size:11',
 ]);

 $dados = $cpfHub->consultar($request->cpf);

 if (!$dados) {
 return response()->json([
 'message' => 'Não foi possível validar o CPF informado.',
 ], 422);
 }

 return response()->json([
 'nome' => $dados['name'],
 'genero' => $dados['gender'],
 'nascimento' => $dados['birthDate'],
 ]);
 }
}
```

---

## 4. Criando uma Custom Validation Rule

O Laravel permite criar regras de validação personalizadas. Vamos criar uma rule que valida se o CPF existe e está ativo via API:

```php
<?php

namespace App\Rules;

use App\Services\CpfHubService;
use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class CpfValido implements ValidationRule
{
 public function validate(string $attribute, mixed $value, Closure $fail): void
 {
 $cpfLimpo = preg_replace('/\D/', '', $value);

 if (strlen($cpfLimpo) !== 11) {
 $fail('O :attribute deve conter exatamente 11 dígitos.');
 return;
 }

 $service = app(CpfHubService::class);
 $dados = $service->consultar($cpfLimpo);

 if (!$dados) {
 $fail('O :attribute informado não é válido ou não foi encontrado.');
 }
 }
}
```

Uso no Form Request:

```php
<?php

namespace App\Http\Requests;

use App\Rules\CpfValido;
use Illuminate\Foundation\Http\FormRequest;

class CadastroRequest extends FormRequest
{
 public function rules(): array
 {
 return [
 'cpf' => ['required', 'string', new CpfValido],
 'nome' => ['required', 'string', 'max:255'],
 'email' => ['required', 'email'],
 ];
 }
}
```

---

## 5. Exemplo de resposta da API

A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna o seguinte JSON:

```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 bem-sucedida.
* **name / nameUpper** — Nome completo do titular em formato normal e maiúsculas.
* **gender** — Gênero do titular (M ou F).
* **birthDate** — Data de nascimento completa.
* **day, month, year** — Componentes da data de nascimento separados, úteis para cálculos de idade.

---

## 6. Implementando cache para otimizar consultas

Para reduzir o consumo de consultas da API, implemente cache usando o sistema nativo do Laravel:

```php
public function consultar(string $cpf): ?array
{
 $cpfLimpo = preg_replace('/\D/', '', $cpf);
 $cacheKey = "cpfhub:{$cpfLimpo}";

 return cache()->remember($cacheKey, now()->addHours(24), function () use ($cpfLimpo) {
 $response = Http::withHeaders([
 'x-api-key' => $this->apiKey,
 'Accept' => 'application/json',
 ])
 ->timeout($this->timeout)
 ->get("{$this->baseUrl}/cpf/{$cpfLimpo}");

 if ($response->successful() && $response->json('success')) {
 return $response->json('data');
 }

 return null;
 });
}
```

Essa abordagem é especialmente útil no plano gratuito, onde você dispõe de 50 consultas mensais. Com cache de 24 horas, consultas repetidas ao mesmo CPF não consomem sua cota.

---

## 7. Tratamento de erros e resiliência

A CPFHub.io não retorna HTTP 429 ao atingir o limite do plano — ao ultrapassar a cota, cada consulta adicional é cobrada a R$0,15, sem bloqueio do serviço. Ainda assim, implemente retry para erros transitórios como timeouts e erros 5xx:

```php
$response = Http::withHeaders([
 'x-api-key' => $this->apiKey,
 'Accept' => 'application/json',
])
->timeout($this->timeout)
->retry(3, 2000, function ($exception, $request) {
 // Retry apenas em erros de conexão ou erros 5xx
 return $exception instanceof \Illuminate\Http\Client\ConnectionException
 || ($exception instanceof \Illuminate\Http\Client\RequestException
 && $exception->response->status() >= 500);
})
->get("{$this->baseUrl}/cpf/{$cpfLimpo}");
```

O método `retry` tentará a requisição até 3 vezes, aguardando 2 segundos entre cada tentativa, apenas para falhas de conectividade ou erros de servidor.

---

## Perguntas frequentes

### Como testar a integração com Laravel sem consumir consultas reais?

Utilize o método `Http::fake()` do Laravel para simular respostas da API nos testes automatizados. Defina um fixture com a estrutura de resposta da CPFHub.io e injete no service durante os testes. Isso garante cobertura completa dos fluxos de sucesso e erro sem gastar cota do plano gratuito.

### O Service Class funciona com injeção de dependência em jobs e commands?

Sim. Como o `CpfHubService` é registrado como singleton no container do Laravel, ele pode ser injetado normalmente em qualquer classe resolvida pelo container — incluindo jobs, commands artisan, listeners e middlewares. O timeout configurado em `services.cpfhub.timeout` se aplica a todas essas chamadas.

### Qual timeout configurar para o HTTP Client em Laravel?

Recomenda-se 10 segundos para chamadas síncronas em fluxos de cadastro (onde o usuário aguarda). Para processamento em batch ou jobs assíncronos, 30 segundos é aceitável. A CPFHub.io responde em ~900ms em condições normais, então timeouts abaixo de 5 segundos podem gerar falsos negativos em momentos de latência de rede.

### Como o cache de 24 horas afeta a conformidade com a LGPD?

Armazenar o resultado da consulta por 24 horas é aceitável para fins de validação de cadastro, pois dados cadastrais do CPF raramente mudam nesse período. A [ANPD](https://www.gov.br/anpd) orienta que o armazenamento deve ser proporcional à finalidade declarada. Para dados sensíveis, considere armazenar apenas um hash ou token de validação em vez dos dados completos, eliminando a necessidade de reter informações pessoais.

### 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)
- [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)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Como consumir API de CPF em Go com net/http e tratamento de erros](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-go-com-net-http-e-tratamento-de-erros)

---

## Conclusão

Integrar a validação de CPF em Laravel com o HTTP Client nativo é um processo elegante e produtivo. A combinação de Service Class, Custom Validation Rules e cache permite construir uma integração robusta, testável e eficiente, pronta para ambientes de produção.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e tenha a validação de CPF funcionando no seu projeto Laravel em menos de 30 minutos.