Como integrar a API de CPF em uma aplicação 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 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 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 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:

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

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:

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

3. Crie o controller

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

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á:

{
    "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.

Conclusão

Integrar a API da 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 agora e tenha sua integração Symfony rodando em menos de 30 minutos, sem cartão de crédito.