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

> Aprenda a integrar uma API de consulta de CPF em PHP de forma rápida e segura. Tutorial passo a passo com exemplos práticos!

**Publicado:** 11/10/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/integrar-api-cpf-php

---


Integrar uma API de consulta de CPF em PHP leva menos de 30 minutos com a CPFHub.io. Você faz uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`, recebe nome, data de nascimento e gênero em JSON, e já pode validar identidades em tempo real — sem cartão de crédito para começar.

## 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.

Este tutorial mostra passo a passo como integrar a **CPFHub.io** em um sistema PHP para realizar consultas de CPF em tempo real. A CPFHub.io oferece suporte a mais de 13 linguagens de programação, incluindo PHP, com conformidade LGPD.

---

## 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 (plano gratuito com 50 consultas/mês, sem necessidade de cartão).
- **Biblioteca cURL ou Guzzle instalada** para fazer requisições HTTP.

Se ainda não tem uma conta, cadastre-se em [**CPFHub.io**](https://www.cpfhub.io/) — o plano gratuito não exige cartão de crédito.

---

## 2. Instalando dependências (opcional)

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

```bash
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
<?php
$cpf = "12345678900";
$apiKey = "SUA_CHAVE_DE_API";

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

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
 "x-api-key: $apiKey",
 "Accept: application/json"
]);
curl_setopt($ch, CURLOPT_HTTPGET, true);

$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
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;

$cpf = "12345678900";
$apiKey = "SUA_CHAVE_DE_API";

$client = new Client();
$response = $client->get("https://api.cpfhub.io/cpf/{$cpf}", [
 'headers' => [
 'x-api-key' => $apiKey,
 'Accept' => 'application/json'
 ]
]);

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

```json
{
 "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
 }
}
```

O que essa resposta indica:

* **success**: Se a consulta foi realizada com sucesso.
* **cpf**: Número do CPF consultado.
* **name**: Nome completo do titular do CPF.
* **nameUpper**: Nome completo em letras maiúsculas.
* **gender**: Gênero do titular (M ou F).
* **birthDate**: Data de nascimento no formato dd/mm/aaaa.
* **day, month, year**: Dia, mês e ano de nascimento separados.

---

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

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

### Possíveis mensagens de erro

| Código | Mensagem | Motivo |
| --- | --- | --- |
| 400 | CPF inválido | O CPF informado não segue o formato correto |
| 401 | Chave de API inválida | A chave de API fornecida está errada ou expirada |
| 403 | Acesso negado | Sua conta não tem permissão para esta consulta |
| 500 | Erro interno | Problema temporário na API |

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

---

## Perguntas frequentes

### O que é necessário para implementar validação de CPF neste contexto?
A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

### A API CPFHub.io funciona para todos os volumes de consulta?
Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

### Como garantir conformidade com a LGPD ao usar uma API de CPF?
Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A [ANPD](https://www.gov.br/anpd/) orienta que dados de identificação devem ser tratados com o princípio da necessidade.

### Quanto tempo leva para integrar a API CPFHub.io?
A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

### Leia também

- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos)
- [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei)

---

## 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 (aproximadamente 900ms), seguras e confiáveis, com 99.9% de uptime e conformidade LGPD.

A API retorna dados como nome completo, nome em maiúsculas, gênero e data de nascimento (com dia, mês e ano separados), atendendo às necessidades de validação de identidade. Mais de 1.300 empresas já confiam na CPFHub.io.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.