# Guia de headers HTTP obrigatórios para consumir API de CPF corretamente

> Conheça os headers HTTP obrigatórios para consumir a API de CPF corretamente. Aprenda a configurar autenticação, content type e timeout.

**Publicado:** 04/03/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/guia-de-headers-http-obrigatorios-para-consumir-api-de-cpf-corretamente

---


Para consumir a API de CPF da CPFHub.io, dois headers são obrigatórios em toda requisição: `x-api-key` (autenticação) e `Accept: application/json` (formato da resposta). Sem eles, a API retorna erro 401 ou resposta mal formatada — e os erros de integração mais comuns têm exatamente essa origem.

## Introdução

Os headers HTTP são metadados que acompanham cada requisição e resposta em uma comunicação entre cliente e servidor. Em APIs REST de consulta de CPF, os headers desempenham funções essenciais: autenticação, definição do formato de resposta e controle de comportamento da conexão. Configurar os headers incorretamente é uma das causas mais comuns de erros de integração.

---

## Headers obrigatórios

A API da [**CPFHub.io**](https://www.cpfhub.io/) exige dois headers em cada chamada: `x-api-key` para autenticação e `Accept` para indicar o formato desejado da resposta.

### x-api-key

O header `x-api-key` contém a chave de autenticação que identifica sua aplicação. Sem ele, a API retorna erro 401 (Unauthorized).

| Propriedade | Valor |
| --- | --- |
| Nome | x-api-key |
| Tipo | String |
| Obrigatório | Sim |
| Onde obter | Painel de controle em app.cpfhub.io |

**Exemplo:**
```
x-api-key: sk_live_abc123def456ghi789
```

### Accept

O header `Accept` informa à API em qual formato você deseja receber a resposta. Para a API da CPFHub.io, o valor deve ser `application/json`.

| Propriedade | Valor |
| --- | --- |
| Nome | Accept |
| Tipo | MIME type |
| Obrigatório | Sim |
| Valor | application/json |

**Exemplo:**
```
Accept: application/json
```

---

## Requisição completa com todos os headers

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

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

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

### JavaScript (Node.js)

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

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

clearTimeout(timeoutId);
const dados = await response.json();
console.log(dados);
```

### 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);
print_r($data);
```

### Go

```go
package main

import (
 "fmt"
 "io"
 "net/http"
 "time"
)

func main() {
 cpf := "12345678900"
 url := fmt.Sprintf("https://api.cpfhub.io/cpf/%s", cpf)

 client := &http.Client{Timeout: 10 * time.Second}
 req, _ := http.NewRequest("GET", url, nil)

 req.Header.Set("x-api-key", "SUA_CHAVE_DE_API")
 req.Header.Set("Accept", "application/json")

 resp, err := client.Do(req)
 if err != nil {
 fmt.Println("Erro:", err)
 return
 }
 defer resp.Body.Close()

 body, _ := io.ReadAll(resp.Body)
 fmt.Println(string(body))
}
```

---

## Headers recomendados (opcionais)

Além dos headers obrigatórios, alguns headers opcionais podem melhorar a integração:

### User-Agent

Identifica a aplicação que está fazendo a requisição. Útil para debugging e monitoramento:

```
User-Agent: MeuApp/1.0 (contato@empresa.com)
```

### Content-Type

Para requisições GET (como a da CPFHub.io), o `Content-Type` não é necessário, pois não há corpo na requisição. Ele é relevante apenas em requisições POST, PUT ou PATCH.

### Cache-Control

Se sua aplicação usa um proxy ou CDN intermediário, o header `Cache-Control` pode controlar o comportamento de cache:

```
Cache-Control: no-cache
```

---

## Erros comuns relacionados a headers

### Erro 401: Unauthorized

**Causa:** Header `x-api-key` ausente, incorreto ou com chave expirada.

**Solução:** Verificar se o header está presente na requisição e se a chave é válida no painel app.cpfhub.io.

```bash
# Errado: sem o header de autenticação
curl -X GET https://api.cpfhub.io/cpf/12345678900

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

### Nome do header com case incorreto

Headers HTTP são case-insensitive pelo padrão HTTP/1.1, mas é uma boa prática usar o formato exato documentado pela API (`x-api-key` em minúsculas).

### Header duplicado

Algumas bibliotecas HTTP adicionam headers padrão automaticamente. Se você definir `Accept: application/json` manualmente e a biblioteca também adicionar `Accept: */*`, pode haver conflito. Verifique os headers reais enviados usando logs ou ferramentas como Postman.

### Espaços extras no valor do header

```
# Errado: espaço extra antes do valor
x-api-key: SUA_CHAVE_DE_API

# Correto
x-api-key: SUA_CHAVE_DE_API
```

---

## Segurança da chave de API

A chave de API (`x-api-key`) é um segredo que não deve ser exposto em código-fonte público ou em requisições feitas diretamente do navegador do usuário. A [OWASP](https://owasp.org/www-project-api-security/) lista a exposição de credenciais entre as principais vulnerabilidades de segurança em APIs.

**Boas práticas:**

* **Armazene em variáveis de ambiente** -- Nunca coloque a chave diretamente no código.

* **Use a chave apenas no backend** -- Requisições à API de CPF devem partir do servidor, não do front-end.

* **Rotacione as chaves periodicamente** -- Gere novas chaves no painel e desative as antigas.

* **Não comite em repositórios** -- Adicione arquivos `.env` ao `.gitignore` para evitar exposição acidental.

```python
import os

headers = {
 "x-api-key": os.environ.get("CPFHUB_API_KEY"),
 "Accept": "application/json"
}
```

---

## Inspecionando headers para debugging

Para verificar exatamente quais headers sua aplicação está enviando, use a flag `-v` do cURL:

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

O modo verbose exibirá todos os headers enviados e recebidos, facilitando a identificação de problemas na integração.

---

## Perguntas frequentes

### Quais headers são obrigatórios para chamar a API de CPF da CPFHub.io?
São dois: `x-api-key`, com a chave de autenticação obtida no painel, e `Accept: application/json`, que instrui a API a retornar a resposta no formato JSON. Sem o `x-api-key`, a requisição retorna 401 Unauthorized. Sem o `Accept` correto, algumas implementações podem retornar formato inesperado.

### O que acontece se eu enviar o header `x-api-key` com valor errado ou expirado?
A API retorna HTTP 401 (Unauthorized). Verifique se a chave está correta no painel em app.cpfhub.io, se não há espaços extras no valor e se a chave não foi revogada. Chaves geradas em ambiente de teste não funcionam em produção.

### Posso fazer a chamada à API de CPF direto do frontend (navegador)?
Não é recomendado. Se você incluir a chave `x-api-key` no código JavaScript do frontend, ela ficará exposta a qualquer pessoa que inspecionar o código-fonte. Sempre faça as chamadas a partir do seu servidor (backend) e exponha ao frontend apenas o resultado já processado.

### A CPFHub.io bloqueia requisições quando o limite do plano é atingido?
Não. A API não retorna erro 429 nem bloqueia o acesso ao atingir o limite de consultas. O que ocorre é a cobrança de R$0,15 por consulta adicional além da franquia. O plano gratuito inclui 50 consultas/mês sem cartão; o plano Pro oferece 1.000 consultas por R$149/mês, também com excedente a R$0,15 por consulta.

### 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)
- [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)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)

---

## Conclusão

Configurar os headers HTTP corretamente é o passo mais básico e, ao mesmo tempo, o mais importante para consumir uma API de CPF com sucesso. Os dois headers obrigatórios da [**CPFHub.io**](https://www.cpfhub.io/) — `x-api-key` e `Accept: application/json` — são simples de implementar e eliminam a grande maioria dos erros de integração relatados por desenvolvedores.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a consumir a API de CPF com os headers corretos configurados em menos de 30 minutos.