Tutorial

API CPF no Laravel: cliente HTTP e configuração segura

Aprenda a consultar CPF no Laravel com Http Client, .env, timeout, status HTTP e validação de respostas.

Imagem editorial sobre Laravel e Http Client
Laravel e Http Client.

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.

Continue aprendendo