Integração de API CPF no Laravel
O Laravel disponibiliza um cliente HTTP que facilita enviar headers, configurar timeout e verificar status sem lidar diretamente com cURL. Para consultar CPF, use GET https://api.apicpf.dev/consulta?cpf= com a chave no header X-API-KEY. A documentação descreve o formato JSON e os erros.
A lógica deve ficar em uma classe de serviço do backend, não no Blade com JavaScript visível ao usuário. Garanta autenticação e autorização antes de permitir consultas pelo seu sistema.
Configurar a variável de ambiente
Defina APICPF_KEY no ambiente do servidor; para desenvolvimento, mantenha .env fora do repositório. Em config/services.php, acrescente:
'apicpf' => [
'key' => env('APICPF_KEY'),
],
Assim o aplicativo usa config('services.apicpf.key'), inclusive em produção com cache de configuração, sem chamar env() diretamente na lógica da requisição.
Exemplo com o HTTP Client do Laravel
<?php
use Illuminate\Support\Facades\Http;
function consultarCpfLaravel(string $cpf): array
{
$digitos = preg_replace('/\D/', '', $cpf);
if (strlen($digitos) !== 11) {
throw new InvalidArgumentException('CPF com formato inválido');
}
$key = config('services.apicpf.key');
if (!$key) throw new RuntimeException('API Key não configurada');
$response = Http::withHeaders([
'X-API-KEY' => $key,
'Accept' => 'application/json',
])->connectTimeout(3)->timeout(10)->get(
'https://api.apicpf.dev/consulta', ['cpf' => $digitos]
);
if ($response->failed()) {
throw new RuntimeException('Falha HTTP: ' . $response->status());
}
$dados = $response->json('data');
if (!is_array($dados)) throw new RuntimeException('JSON inesperado');
return $dados;
}
O exemplo não substitui tratamento de exceções de rede nem autorização de usuários. Em aplicação real, capture essas exceções no serviço ou controlador e devolva erro genérico ao consumidor, registrando apenas o código e a duração.
Validação anterior e erros
Use /v1/validate?cpf= antes da consulta cadastral quando apropriado. Como a validação de dígitos não consome crédito de consulta, ela pode evitar solicitações desnecessárias. Ela não confirma situação oficial nem titularidade.
401 pede revisão da credencial; 402 indica créditos insuficientes; 404 exige conferir rota e message; 429 pede contenção e espera. Não use retry irrestrito em qualquer código.
Perguntas frequentes
Laravel precisa de pacote extra para HTTP?
O HTTP Client faz parte das versões modernas do framework. Confira a versão do seu projeto e as dependências configuradas.
É correto retornar todo o JSON ao frontend?
Não como padrão. Filtre campos conforme finalidade, permissões e necessidade. Leia proteção de chave e logs.
