# Como integrar a API de CPF em uma aplicação Symfony

> Aprenda a consumir a API de consulta de CPF da CPFHub.io em uma aplicação Symfony com HttpClient, serviços e boas práticas.

**Publicado:** 20/02/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/integrar-api-cpf-symfony

---


Para integrar a API de CPF da CPFHub.io em uma aplicação Symfony, crie um serviço dedicado usando o componente HttpClient, configure a chave de API via variáveis de ambiente e injete o serviço nos controllers que precisam de validação. A integração leva menos de 30 minutos em projetos Symfony 6 ou 7.

## Introdução

O **Symfony** é um dos frameworks PHP mais utilizados para aplicações empresariais e de grande porte. Se você precisa integrar a consulta de CPF via API em um projeto Symfony, este tutorial mostra como fazer isso de forma organizada, usando o componente **HttpClient** e boas práticas de arquitetura. A [documentação oficial do Symfony](https://symfony.com/doc/current/http_client.html) detalha todas as opções de configuração do HttpClient — incluindo timeouts, retry automático e mock para testes.

Vamos integrar a API da [**CPFHub.io**](https://www.cpfhub.io/) com injeção de dependência, tratamento de erros e exemplos prontos para uso.

---

## Pré-requisitos

* PHP 8.1+ com Symfony 6 ou 7 instalado.

* Componente HttpClient (`composer require symfony/http-client`).

* Uma conta gratuita na [CPFHub.io](https://www.cpfhub.io/) com a API key gerada no painel.

---

## 1. Configure a chave de API no .env

Adicione a chave no arquivo `.env`:

```
CPFHUB_API_KEY=sua_chave_aqui
CPFHUB_BASE_URL=https://api.cpfhub.io
```

E declare no `config/services.yaml`:

```yaml
parameters:
 cpfhub_api_key: '%env(CPFHUB_API_KEY)%'
 cpfhub_base_url: '%env(CPFHUB_BASE_URL)%'
```

---

## 2. Crie o serviço de consulta de CPF

Crie um serviço dedicado em `src/Service/CpfHubService.php`:

```php
<?php

namespace App\Service;

use Symfony\Contracts\HttpClient\HttpClientInterface;

class CpfHubService
{
 public function __construct(
 private HttpClientInterface $httpClient,
 private string $cpfhubApiKey,
 private string $cpfhubBaseUrl,
 ) {}

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

 $response = $this->httpClient->request('GET', "{$this->cpfhubBaseUrl}/cpf/{$cpf}", [
 'headers' => [
 'x-api-key' => $this->cpfhubApiKey,
 'Accept' => 'application/json',
 ],
 ]);

 $statusCode = $response->getStatusCode();

 if ($statusCode !== 200) {
 throw new \RuntimeException("Erro na consulta de CPF: HTTP {$statusCode}");
 }

 return $response->toArray();
 }
}
```

Registre no `config/services.yaml`:

```yaml
services:
 App\Service\CpfHubService:
 arguments:
 $cpfhubApiKey: '%cpfhub_api_key%'
 $cpfhubBaseUrl: '%cpfhub_base_url%'
```

---

## 3. Crie o controller

```php
<?php

namespace App\Controller;

use App\Service\CpfHubService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

class CpfController extends AbstractController
{
 #[Route('/api/cpf/{cpf}', name: 'consultar_cpf', methods: ['GET'])]
 public function consultar(string $cpf, CpfHubService $cpfHubService): JsonResponse
 {
 try {
 $resultado = $cpfHubService->consultarCpf($cpf);
 return $this->json($resultado);
 } catch (\RuntimeException $e) {
 return $this->json(['error' => $e->getMessage()], 400);
 }
 }
}
```

---

## 4. Tratamento de erros HTTP

Adicione tratamento granular no serviço para os códigos de resposta da API:

```php
public function consultarCpf(string $cpf): array
{
 $cpf = preg_replace('/\D/', '', $cpf);

 $response = $this->httpClient->request('GET', "{$this->cpfhubBaseUrl}/cpf/{$cpf}", [
 'headers' => [
 'x-api-key' => $this->cpfhubApiKey,
 'Accept' => 'application/json',
 ],
 ]);

 return match ($response->getStatusCode()) {
 200 => $response->toArray(),
 400 => throw new \InvalidArgumentException('CPF com formato inválido'),
 401 => throw new \RuntimeException('Chave de API inválida ou ausente'),
 404 => throw new \RuntimeException('CPF não encontrado'),
 default => throw new \RuntimeException('Erro inesperado na API'),
 };
}
```

---

## 5. Exemplo de resposta

Ao acessar `GET /api/cpf/12345678900`, a resposta será:

```json
{
 "success": true,
 "data": {
 "cpf": "12345678900",
 "name": "João da Silva",
 "nameUpper": "JOÃO DA SILVA",
 "gender": "M",
 "birthDate": "15/06/1990",
 "day": 15,
 "month": 6,
 "year": 1990
 }
}
```

---

## 6. Boas práticas

* **Variáveis de ambiente** — Nunca hardcode a chave de API no código.

* **Injeção de dependência** — Use o container do Symfony para gerenciar o serviço.

* **Timeout** — Configure timeout no HttpClient para evitar requisições travadas. A API responde em ~900ms; um timeout de 10 a 15 segundos é adequado.

* **Cache** — Para CPFs consultados repetidamente, use o componente Cache do Symfony.

* **Testes** — Mock o HttpClient nos testes unitários para não consumir consultas reais.

---

## Perguntas frequentes

### Como configurar timeout no HttpClient do Symfony para a API CPFHub.io?
No `config/services.yaml`, configure o `default_options` do HttpClient com `timeout: 10`. Alternativamente, passe o parâmetro diretamente na chamada: `$this->httpClient->request('GET', $url, ['timeout' => 10])`. A API responde em ~900ms; 10 segundos dá margem suficiente sem travar requisições por tempo indeterminado.

### Como mockar o CpfHubService nos testes funcionais do Symfony?
Use o `MockHttpClient` do Symfony com uma `MockResponse` contendo o JSON esperado. Registre o mock no container de teste via `$this->getContainer()->set(HttpClientInterface::class, $mockClient)`. Assim, os testes não consomem consultas reais da cota mensal.

### A API CPFHub.io retorna erro 429 quando o limite é atingido?
Não. Ao atingir o limite do plano gratuito (50 consultas/mês), a API continua respondendo normalmente com HTTP 200 e cobra R$0,15 por consulta adicional. Não há bloqueio nem HTTP 429. Por isso, o tratamento de 429 pode ser removido do switch/match — o fluxo de erro para essa situação não ocorre.

### Como usar o componente Cache do Symfony para evitar consultas duplicadas à API?
Injete o `CacheInterface` no `CpfHubService` e armazene o resultado usando o CPF como chave de cache com TTL de 24 horas. Assim, um mesmo CPF consultado múltiplas vezes no dia consome apenas 1 consulta da cota, economizando créditos no plano gratuito.

### 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 integrar API de CPF em Django/Python](https://cpfhub.io/blog/como-integrar-api-cpf-django-python)
- [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)

---

## Conclusão

Integrar a API da [**CPFHub.io**](https://www.cpfhub.io/) em uma aplicação Symfony é direto: um serviço PHP com HttpClient, configuração via `.env` e injeção de dependência pelo container. Com o tratamento de erros correto e cache habilitado, a integração fica robusta para produção e econômica no consumo de cota.

O plano gratuito de 50 consultas por mês é ideal para começar — seja em staging ou em produção com volume baixo. Quando o projeto crescer, o upgrade para o plano Pro é transparente: mesmo endpoint, mesma chave de API, sem refatorar nada. Crie sua conta em [cpfhub.io](https://www.cpfhub.io/) agora e tenha sua integração Symfony rodando em menos de 30 minutos, sem cartão de crédito.