Guia de headers HTTP obrigatórios 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 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).

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.

Exemplo:

Accept: application/json

Requisição completa com todos os headers

cURL

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

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)

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

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.

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

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:

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.

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