Como integrar uma API de consulta de CPF em PHP (passo a passo)

Introdução

A integração de uma API de consulta de CPF em aplicações PHP é essencial para empresas que desejam validar dados de clientes de forma automatizada e segura. Isso é especialmente útil para fintechs, e-commerces e instituições financeiras que precisam evitar fraudes e garantir a conformidade com a legislação.

Neste guia, explicamos passo a passo como integrar a API da CPFHub.io em um sistema PHP para realizar consultas de CPF em tempo real.

1. Pré-requisitos para a integração

Antes de iniciar a integração, certifique-se de que possui:

✅ Um ambiente PHP configurado (versão 7.4 ou superior recomendada).
✅ Uma conta na CPFHub.io para obter a chave de API.
✅ Biblioteca cURL ou Guzzle instalada para fazer requisições HTTP.

2. Instalando dependências (opcional)

Se você deseja usar Guzzle para facilitar as requisições HTTP, instale-o via Composer:

composer require guzzlehttp/guzzle

Caso prefira usar cURL nativo do PHP, essa etapa não é necessária.

3. Fazendo uma consulta de CPF com PHP

Usando cURL

Aqui está um exemplo de como consultar um CPF utilizando a API da CPFHub.io com cURL:

<?php
$cpf = "123.456.789-00";
$birthDate = "15/06/1990";
$apiKey = "SUA_CHAVE_DE_API";

$url = "https://api.cpfhub.io/api/cpf";

$data = json_encode([
    "cpf" => $cpf,
    "birthDate" => $birthDate
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "x-api-key: $apiKey"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

print_r($result);
?>

Usando Guzzle

Se você estiver utilizando Guzzle, pode fazer a requisição da seguinte maneira:

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;

$cpf = "123.456.789-00";
$birthDate = "15/06/1990";
$apiKey = "SUA_CHAVE_DE_API";

$client = new Client();
$response = $client->post('https://api.cpfhub.io/api/cpf', [
    'headers' => [
        'Content-Type' => 'application/json',
        'x-api-key' => $apiKey
    ],
    'json' => [
        'cpf' => $cpf,
        'birthDate' => $birthDate
    ]
]);

$result = json_decode($response->getBody(), true);
print_r($result);
?>

4. Exemplo de resposta da API

Após a requisição, a API retornará uma resposta no seguinte formato:

{
  "success": true,
  "data": {
    "name": "João da Silva",
    "status": "Regular",
    "situation": "Ativo",
    "birthDate": "15/06/1990",
    "cpfNumber": "12345678900",
    "registrationDate": "anterior a 10/11/1990",
    "verificationDigit": "03",
    "receipt": {
      "emissionTime": "22:08:26",
      "emissionDate": "13/01/2025",
      "controlCode": "XXXX.XXXX.XXXX.XXXX"
    },
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678900&cc=XXXXXX&de=13012025&he=220826&dv=03&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/api/view-proof/12345678900/XXXXXXXXXXXXX"
  }
}

✅ O que essa resposta indica?

• success: Se a consulta foi realizada com sucesso.

• name: Nome completo do titular do CPF.

• status: Indica se o CPF está regular ou irregular.

• situation: Situação cadastral do CPF.

• birthDate: Data de nascimento associada ao CPF.

• validationUrl: Link direto para consulta na Receita Federal.

5. Como tratar erros na consulta

A API pode retornar erros caso os dados sejam inválidos ou a chave de API esteja incorreta. Veja um exemplo de tratamento de erros:

if (!$result['success']) {
    echo "Erro na consulta: " . $result['message'];
} else {
    echo "CPF válido: " . $result['data']['name'];
}

Possíveis mensagens de erro:

✅ Dica: Sempre valide a entrada do usuário antes de enviar uma consulta para evitar erros desnecessários.

Conclusão

A integração da API de consulta de CPF em PHP é um processo simples, mas extremamente eficiente para validar a identidade de clientes e evitar fraudes. Com a API da CPFHub.io, você pode realizar consultas rápidas, seguras e confiáveis.