# Como usar a API gratuita da CPFHub.io para validar CPFs no seu sistema

> Guia completo para usar a API gratuita da CPFHub.io. Veja como criar conta, gerar chave de API e integrar a validação de CPF no seu sistema.

**Publicado:** 05/11/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-usar-a-api-gratuita-da-cpfhub-io-para-validar-cpfs-no-seu-sistema

---


A API gratuita da CPFHub.io permite validar CPFs em qualquer sistema com uma única chamada GET, sem cartão de crédito e com 50 consultas mensais incluídas. Basta criar uma conta, gerar a chave de API e autenticar as requisições via header `x-api-key`. A resposta inclui nome, data de nascimento e gênero do titular em menos de 1 segundo.

## Introdução

A validação de CPF é uma funcionalidade presente em praticamente todo sistema que opera no Brasil -- de plataformas de e-commerce a fintechs, de sistemas de RH a ERPs. Implementar essa validação de forma confiável e econômica é uma demanda recorrente para desenvolvedores.

A [**CPFHub.io**](https://www.cpfhub.io/) oferece um plano gratuito com 50 consultas mensais, sem necessidade de cartão de crédito, utilizando o mesmo endpoint e formato de resposta dos planos pagos. Quando o limite é ultrapassado, a API cobra R$0,15 por consulta adicional — sem bloquear as requisições.

## Criando sua conta e gerando a chave de API

### Passo 1: criar conta gratuita

Acesse [cpfhub.io](https://www.cpfhub.io/) e crie sua conta gratuitamente, sem necessidade de cartão de crédito.

### Passo 2: acessar o painel de controle

Após o cadastro, acesse o dashboard em app.cpfhub.io. No painel, você encontrará o histórico de consultas, informações do plano e a seção de Chaves de API.

### Passo 3: gerar a chave de API

Na seção de Chaves de API, gere sua `x-api-key`. Essa chave será o identificador de autenticação em todas as requisições. Mantenha-a segura e nunca a exponha em código front-end.

---

## Entendendo o endpoint e a resposta

### Endpoint

```
GET https://api.cpfhub.io/cpf/{CPF_NUMBER}
```

O CPF é enviado diretamente na URL, somente números (11 dígitos). A autenticação é feita via header `x-api-key`.

### Headers obrigatórios

```
x-api-key: SUA_CHAVE_DE_API
Accept: application/json
```

### Resposta de sucesso

```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
 }
}
```

### Campos retornados

| Campo | Descrição |
| --- | --- |
| cpf | Número do CPF consultado |
| name | Nome completo do titular |
| nameUpper | Nome em letras maiúsculas |
| gender | Gênero (M/F) |
| birthDate | Data de nascimento (DD/MM/YYYY) |
| day | Dia de nascimento |
| month | Mês de nascimento |
| year | Ano de nascimento |

---

## Exemplos de integração por linguagem

### cURL

```bash
curl -X GET https://api.cpfhub.io/cpf/12345678900 \
 -H "x-api-key: SUA_CHAVE_DE_API" \
 -H "Accept: application/json" \
 --max-time 10
```

### Python

```python
import requests

cpf = "12345678900"
url = f"https://api.cpfhub.io/cpf/{cpf}"
headers = {
 "x-api-key": "SUA_CHAVE_DE_API",
 "Accept": "application/json"
}

response = requests.get(url, headers=headers, timeout=10)
data = response.json()

if data["success"]:
 print(f"Nome: {data['data']['name']}")
 print(f"Nascimento: {data['data']['birthDate']}")
 print(f"Gênero: {data['data']['gender']}")
```

### JavaScript (Node.js)

```javascript
const consultarCPF = async (cpf) => {
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), 10000);

 const response = await fetch(
 `https://api.cpfhub.io/cpf/${cpf}`,
 {
 method: 'GET',
 headers: {
 'x-api-key': process.env.CPFHUB_API_KEY,
 'Accept': 'application/json'
 },
 signal: controller.signal
 }
 );

 clearTimeout(timeoutId);
 return await response.json();
};

// Uso
const resultado = await consultarCPF('12345678900');
console.log(resultado);
```

### PHP

```php
<?php
$cpf = '12345678900';
$curl = curl_init();

curl_setopt_array($curl, [
 CURLOPT_URL => "https://api.cpfhub.io/cpf/{$cpf}",
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_TIMEOUT => 10,
 CURLOPT_HTTPHEADER => [
 'x-api-key: SUA_CHAVE_DE_API',
 'Accept: application/json'
 ],
]);

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

$data = json_decode($response, true);

if ($data['success']) {
 echo "Nome: " . $data['data']['name'] . "\n";
 echo "Nascimento: " . $data['data']['birthDate'] . "\n";
}
```

---

## Tratamento de erros

A API retorna códigos HTTP padronizados. Seu sistema deve tratar cada cenário. Importante: a API **não retorna HTTP 429** quando o limite mensal é atingido — ela cobra R$0,15 por consulta adicional e segue respondendo normalmente. O código 429 não precisa ser tratado como bloqueio de cota.

```python
import requests

def consultar_cpf(cpf):
 url = f"https://api.cpfhub.io/cpf/{cpf}"
 headers = {
 "x-api-key": "SUA_CHAVE_DE_API",
 "Accept": "application/json"
 }

 try:
 response = requests.get(url, headers=headers, timeout=10)

 if response.status_code == 200:
 return response.json()
 elif response.status_code == 400:
 return {"error": "CPF com formato inválido"}
 elif response.status_code == 401:
 return {"error": "Chave de API inválida ou ausente"}
 elif response.status_code == 404:
 return {"error": "CPF não encontrado"}
 else:
 return {"error": f"Erro inesperado: {response.status_code}"}

 except requests.exceptions.Timeout:
 return {"error": "Timeout na requisição"}
 except requests.exceptions.RequestException as e:
 return {"error": f"Erro de conexão: {str(e)}"}
```

---

## O que o plano gratuito inclui

| Recurso | Disponível |
| --- | --- |
| 50 consultas/mês | Sim |
| API REST completa | Sim |
| Dashboard de histórico | Sim |
| Exemplos de integração | Sim |
| Documentação completa | Sim |
| Suporte por e-mail | Sim |
| SLA | 80% |
| Rate limit | 1 req/2s |

O plano gratuito oferece exatamente o mesmo endpoint e formato de resposta dos planos pagos. A única diferença está no volume de consultas, no rate limit e no nível de SLA.

---

## Boas práticas de integração

* **Nunca exponha a API key no front-end** -- todas as chamadas à API devem ser feitas pelo back-end.

* **Valide o CPF sintaticamente antes de chamar a API** -- economize consultas rejeitando CPFs com formato inválido antes de consumir a API.

* **Implemente timeout em todas as requisições** -- defina um tempo máximo de espera (10 segundos é um bom padrão).

* **Trate todos os códigos de erro** -- implemente lógica específica para cada código HTTP retornado.

* **Armazene a API key em variáveis de ambiente** -- nunca coloque credenciais diretamente no código-fonte.

* **Monitore o consumo de consultas** -- acompanhe o uso no dashboard para evitar ultrapassar o limite inesperadamente e receber cobranças de excedente.

---

## Quando migrar para o plano Pro

O plano gratuito é ideal para começar, mas conforme a operação cresce, o plano Pro (R$ 149/mês) oferece:

* 1.000 consultas mensais (com adicional a R$ 0,15).
* Rate limit de 1 requisição por segundo.
* SLA de 99%.
* Suporte via WhatsApp e e-mail.
* Desconto por volume.

A migração é feita diretamente no painel, sem necessidade de alterar a integração.

---

## Perguntas frequentes

### Como funciona o limite de consultas do plano gratuito?
O plano gratuito inclui 50 consultas por mês sem cartão de crédito. Quando esse limite é ultrapassado, a API **não bloqueia** as requisições — ela cobra R$0,15 por consulta adicional. Você pode acompanhar o consumo em tempo real no dashboard em app.cpfhub.io/settings/billing.

### Quais dados a API retorna em cada consulta?
A resposta inclui: CPF consultado, nome completo do titular, nome em maiúsculas, gênero (M/F), data de nascimento no formato DD/MM/YYYY e os campos separados de dia, mês e ano. Não são retornados dados financeiros ou de crédito — apenas dados cadastrais de identificação.

### É seguro chamar a API diretamente do front-end?
Não. A chave de API (`x-api-key`) nunca deve ser exposta no código front-end, pois qualquer usuário pode inspecionar o tráfego e reutilizar a chave. Todas as chamadas devem ser feitas pelo back-end. A [OWASP](https://owasp.org/www-project-api-security/) recomenda que credenciais de API fiquem exclusivamente no lado do servidor.

### Quanto tempo leva para integrar a API no meu sistema?
A integração básica leva menos de 30 minutos: crie a conta em cpfhub.io, gere a chave de API e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. Exemplos prontos estão disponíveis para Python, Node.js, PHP, cURL e outras linguagens.

### Leia também

- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [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 consulta de CPF: diferenças entre planos gratuito, Pro e Corporate](https://cpfhub.io/blog/api-de-consulta-de-cpf-diferencas-entre-planos-gratuito-pro-e-corporate)
- [APIs de CPF: como avaliar o custo-benefício antes de contratar?](https://cpfhub.io/blog/apis-de-cpf-como-avaliar-o-custo-beneficio-antes-de-contratar)

---

## Conclusão

A API gratuita da [**CPFHub.io**](https://www.cpfhub.io/) oferece tudo o que você precisa para validar CPFs em qualquer sistema: o mesmo endpoint dos planos pagos, resposta JSON completa com dados cadastrais e 50 consultas mensais sem nenhum custo inicial.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF ao seu sistema ainda hoje.