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

{
    "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

Exemplos de integração por linguagem

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

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)

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

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

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

Conclusão

A API gratuita da 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 — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF ao seu sistema ainda hoje.