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 ~150 ms.

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 créditos mensais, sem necessidade de cartão de crédito, utilizando o mesmo endpoint e formato de resposta dos planos pagos. Quando os créditos do Grátis acabam, a API pausa e devolve HTTP 403, "Limite de créditos excedido". Se o plano for pago e tiver excedente, a cobrança extra sai na fatura seguinte — veja a página de preços. O teto por minuto, se estourado, responde HTTP 429 com Retry-After.

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. No gratuito, zerar os 50 créditos do mês interrompe as consultas com HTTP 403 ("Limite de créditos excedido"). Nos planos pagos o excedente não é um valor único: ele varia e está publicado na página de preços. O limite por minuto responde HTTP 429 com Retry-After. O HTTP 429 é limite por minuto, não esgotamento 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:

• Quando os créditos do Grátis terminam, a API pausa com HTTP 403 e a mensagem "Limite de créditos excedido". Nos planos pagos a cobrança extra, se o plano tiver excedente, sai na fatura seguinte (veja a página de preços). Requisições além do limite por minuto recebem HTTP 429 com Retry-After.
• Rate limit de 30 requisições por minuto.
• 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 créditos por mês sem cartão de crédito. Atingir o fim da cota no Grátis devolve HTTP 403 ("Limite de créditos excedido") e interrompe novas consultas. Nos planos pagos, havendo excedente, ele é faturado depois conforme a página de preços. O limite por minuto não entra nessa conta: é HTTP 429 com Retry-After. 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.