Integração Rápida de API CPF em PHP e Laravel

Introdução

Laravel é um dos frameworks PHP mais populares do mundo, conhecido por sua elegância e produtividade. Neste guia prático, você aprenderá a integrar a API CPF Nacional em projetos Laravel de forma rápida e eficiente, usando service providers, middlewares e validações customizadas.

Pré-requisitos

• Laravel 8 ou superior
• PHP 7.4 ou superior
• Composer instalado
• Conta na API CPF Nacional

Instalação e Configuração

1. Instalar Pacote HTTP Client

Laravel já inclui o Guzzle HTTP Client, mas vamos garantir que está instalado:

composer require guzzlehttp/guzzle

2. Configurar Variáveis de Ambiente

Adicione no arquivo .env:

CPF_API_KEY=sua-chave-api-aqui
CPF_API_URL=https://api.cpf-brasil.org/api.php

3. Criar Service Provider

php artisan make:provider CPFApiServiceProvider

Implementação Completa

1. Service para API CPF (app/Services/CPFApiService.php)

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class CPFApiService
{
    protected $apiKey;
    protected $apiUrl;
    
    public function __construct()
    {
        $this->apiKey = config('services.cpf_api.key');
        $this->apiUrl = config('services.cpf_api.url');
    }
    
    /**
     * Consulta CPF na API
     */
    public function consultar(string $cpf): array
    {
        // Limpar CPF
        $cpfLimpo = preg_replace('/\D/', '', $cpf);
        
        // Validar formato
        if (strlen($cpfLimpo) !== 11) {
            return [
                'success' => false,
                'error' => 'CPF deve conter 11 dígitos'
            ];
        }
        
        // Verificar cache
        $cacheKey = 'cpf_' . $cpfLimpo;
        $cached = Cache::get($cacheKey);
        
        if ($cached) {
            return [
                'success' => true,
                'data' => $cached,
                'cached' => true
            ];
        }
        
        try {
            // Fazer requisição
            $response = Http::timeout(5)
                ->withHeaders([
                    'X-API-Key' => $this->apiKey
                ])
                ->get($this->apiUrl, [
                    'cpf' => $cpfLimpo
                ]);
            
            if ($response->successful()) {
                $data = $response->json();
                
                if ($data['success'] ?? false) {
                    // Salvar no cache (1 hora)
                    Cache::put($cacheKey, $data['data'], 3600);
                    
                    return [
                        'success' => true,
                        'data' => $data['data']
                    ];
                }
                
                return [
                    'success' => false,
                    'error' => $data['error'] ?? 'CPF inválido'
                ];
            }
            
            return [
                'success' => false,
                'error' => 'Erro ao consultar API'
            ];
        } catch (\Exception $e) {
            return [
                'success' => false,
                'error' => 'Erro de conexão: ' . $e->getMessage()
            ];
        }
    }
    
    /**
     * Valida se CPF é válido
     */
    public function validar(string $cpf): bool
    {
        $resultado = $this->consultar($cpf);
        return $resultado['success'] ?? false;
    }
}

2. Validação Customizada (app/Rules/CPFValido.php)

<?php

namespace App\Rules;

use App\Services\CPFApiService;
use Illuminate\Contracts\Validation\Rule;

class CPFValido implements Rule
{
    protected $cpfService;
    
    public function __construct()
    {
        $this->cpfService = app(CPFApiService::class);
    }
    
    public function passes($attribute, $value)
    {
        return $this->cpfService->validar($value);
    }
    
    public function message()
    {
        return 'O CPF informado é inválido ou não existe na base da Receita Federal.';
    }
}

3. Middleware (app/Http/Middleware/ValidarCPF.php)

<?php

namespace App\Http\Middleware;

use Closure;
use App\Services\CPFApiService;

class ValidarCPF
{
    protected $cpfService;
    
    public function __construct(CPFApiService $cpfService)
    {
        $this->cpfService = $cpfService;
    }
    
    public function handle($request, Closure $next)
    {
        if ($request->has('cpf')) {
            $resultado = $this->cpfService->consultar($request->cpf);
            
            if (!$resultado['success']) {
                return response()->json([
                    'error' => 'CPF inválido',
                    'message' => $resultado['error']
                ], 400);
            }
            
            // Adicionar dados do CPF à requisição
            $request->merge(['cpf_data' => $resultado['data']]);
        }
        
        return $next($request);
    }
}

4. Controller (app/Http/Controllers/CPFController.php)

<?php

namespace App\Http\Controllers;

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

class CPFController extends Controller
{
    protected $cpfService;
    
    public function __construct(CPFApiService $cpfService)
    {
        $this->cpfService = $cpfService;
    }
    
    public function consultar(Request $request)
    {
        $request->validate([
            'cpf' => 'required|string'
        ]);
        
        $resultado = $this->cpfService->consultar($request->cpf);
        
        if ($resultado['success']) {
            return response()->json($resultado);
        }
        
        return response()->json($resultado, 400);
    }
    
    public function validar(Request $request)
    {
        $request->validate([
            'cpf' => ['required', new \App\Rules\CPFValido()]
        ]);
        
        return response()->json([
            'success' => true,
            'message' => 'CPF válido'
        ]);
    }
}

5. Rotas (routes/api.php)

use App\Http\Controllers\CPFController;

Route::get('/cpf/consultar', [CPFController::class, 'consultar']);
Route::post('/cpf/validar', [CPFController::class, 'validar']);

6. Configuração (config/services.php)

'cpf_api' => [
    'key' => env('CPF_API_KEY'),
    'url' => env('CPF_API_URL', 'https://api.cpf-brasil.org/api.php'),
],

Uso em Formulários

// No FormRequest
public function rules()
{
    return [
        'cpf' => ['required', new CPFValido()]
    ];
}

// No Controller
public function store(Request $request)
{
    $request->validate([
        'cpf' => ['required', new CPFValido()],
        'nome' => 'required|string'
    ]);
    
    // CPF já validado - pode processar
}

Testes Automatizados

// tests/Feature/CPFValidationTest.php
public function test_cpf_validation()
{
    $response = $this->postJson('/api/cpf/validar', [
        'cpf' => '12345678901'
    ]);
    
    $response->assertStatus(200)
        ->assertJson(['success' => true]);
}

Conclusão

Com esta implementação, você tem uma integração completa e profissional da API CPF Nacional no Laravel. Use service providers, middlewares e validações customizadas para manter seu código organizado e reutilizável.