API de CPF grátis para desenvolvedores: como começar em 5 minutos

Introdução

Se você é desenvolvedor e precisa integrar validação de CPF na sua aplicação, provavelmente já passou pela frustração de encontrar APIs que exigem contrato, cartão de crédito ou longos processos de aprovação antes de liberar qualquer acesso. Para quem está prototipando, construindo um MVP ou simplesmente testando uma integração, essas barreiras atrasam o desenvolvimento.

A CPFHub.io resolve isso: o cadastro é feito em minutos, sem burocracia, e você recebe acesso imediato à API com 50 consultas mensais gratuitas.

Por que usar uma API de CPF no desenvolvimento

Antes do passo a passo, vale entender os cenários mais comuns em que desenvolvedores precisam de uma API de consulta de CPF.

Validação de cadastro

Em qualquer formulário que coleta CPF, verificar se o número informado é válido e corresponde a uma pessoa real reduz fraudes e erros de digitação. Isso vai além da validação matemática dos dígitos verificadores -- envolve consultar se o CPF realmente existe e obter os dados associados.

Onboarding automatizado

Fintechs, plataformas de pagamento e marketplaces precisam validar a identidade do usuário durante o cadastro. Com uma API, esse processo acontece em tempo real, sem intervenção manual.

Preenchimento automático de formulários

Ao consultar um CPF válido, você pode preencher automaticamente campos como nome completo e data de nascimento, reduzindo o atrito no cadastro e melhorando a experiência do usuário.

Compliance e auditoria

Empresas que operam em setores regulados (financeiro, saúde, apostas) precisam manter registros de validação de identidade. Uma API com logs auditáveis facilita esse processo.

Passo 1: Criar sua conta gratuita

O primeiro passo é acessar cpfhub.io e criar uma conta — basta informar e-mail e senha, sem cartão de crédito.

Após confirmar o e-mail, você terá acesso imediato ao painel de controle em app.cpfhub.io.

O que está incluso no plano gratuito

• 50 consultas por mês -- Suficiente para testes e protótipos.

• API REST completa -- Mesmo endpoint e formato de resposta dos planos pagos.

• Exemplos de integração prontos -- Em mais de 13 linguagens.

• Dashboard de histórico -- Acompanhe todas as consultas realizadas.

• SLA de 80% -- Adequado para ambientes de desenvolvimento e testes.

Passo 2: Gerar sua chave de API

No painel de controle (app.cpfhub.io), acesse a seção de Chaves de API. Clique em gerar nova chave e copie o valor. Essa chave será usada em todas as requisições no header x-api-key.

Boas práticas para gerenciar sua chave:

• Nunca exponha a chave no frontend -- Use-a apenas em chamadas server-side ou em variáveis de ambiente.

• Use variáveis de ambiente -- Armazene como CPFHUB_API_KEY no .env do seu projeto.

• Adicione .env ao .gitignore -- Evite commitar credenciais no repositório.

Passo 3: Fazer a primeira consulta

Com a chave em mãos, você pode fazer sua primeira consulta. O endpoint é simples:

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

O CPF vai diretamente na URL (apenas números, sem pontos ou traços) e a autenticação é feita via header.

Exemplo com cURL

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

Resposta JSON

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Pronto. Com uma única requisição GET, você obtém o nome completo, gênero e data de nascimento do titular.

Exemplos de integração em diferentes linguagens

A CPFHub.io disponibiliza exemplos prontos em mais de 13 linguagens na documentação:

Node.js

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

const data = await response.json();
console.log(data);

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()
print(data)

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.Add("x-api-key", "SUA_CHAVE_DE_API")
    req.Header.Add("Accept", "application/json")

    res, _ := client.Do(req)
    defer res.Body.Close()

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

Tratamento de erros

Uma integração robusta precisa lidar com os possíveis erros da API. Os códigos HTTP mais comuns são:

Implementando retry com backoff exponencial (Node.js)

async function consultarCPF(cpf, tentativas = 3) {
    for (let i = 0; i < tentativas; i++) {
    const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: AbortSignal.timeout(10000)
    });

    if (response.status === 429) {
    const espera = Math.pow(2, i) * 1000;
    await new Promise(r => setTimeout(r, espera));
    continue;
    }

    return await response.json();
    }
    throw new Error('Limite de tentativas excedido');
}

Rate limits do plano gratuito

O plano gratuito permite 1 requisição a cada 2 segundos e um total de 50 consultas por mês. Esses limites são adequados para:

• Testes de integração -- Validar que sua aplicação consome a API corretamente.

• Protótipos e MVPs -- Demonstrar a funcionalidade para stakeholders.

• Desenvolvimento local -- Testar fluxos de cadastro e onboarding.

Se precisar de mais volume, o Plano Pro (R$ 149/mês) oferece 1.000 consultas mensais com rate limit de 1 requisição por segundo e SLA de 99%.

Dicas para otimizar o uso do plano gratuito

Cache de resultados

Se o mesmo CPF é consultado mais de uma vez na sua aplicação, implemente cache local para evitar consumir consultas desnecessárias:

const cache = new Map();

async function consultarCPFComCache(cpf) {
    if (cache.has(cpf)) {
    return cache.get(cpf);
    }

    const resultado = await consultarCPF(cpf);
    cache.set(cpf, resultado);

    // Limpar cache após 24 horas
    setTimeout(() => cache.delete(cpf), 86400000);

    return resultado;
}

Validação local antes da consulta

Antes de consumir uma consulta da API, valide o CPF localmente usando o algoritmo dos dígitos verificadores. Isso evita gastar consultas com CPFs obviamente inválidos.

Ambiente de desenvolvimento separado

Use o plano gratuito exclusivamente para desenvolvimento e testes. Para produção, migre para o Plano Pro, que oferece maior volume e SLA adequado.

Quando fazer upgrade para o Plano Pro

O plano gratuito é ideal para começar, mas existem sinais claros de que é hora de fazer upgrade:

• Você excede as 50 consultas mensais regularmente -- O Plano Pro oferece 1.000 consultas.

• Sua aplicação está em produção -- O SLA de 99% do Pro garante disponibilidade adequada.

• Você precisa de suporte prioritário -- O Pro inclui suporte via WhatsApp e e-mail.

• O volume está crescendo -- Com o Pro, consultas excedentes custam apenas R$ 0,15 cada.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

Começar a usar uma API de consulta de CPF não precisa ser complicado nem caro. Com a CPFHub.io, o processo leva menos de 5 minutos: cadastro sem cartão, geração de API key no painel e primeira consulta funcionando. O plano gratuito com 50 consultas mensais é suficiente para testes, protótipos e MVPs. Quando sua aplicação crescer, o upgrade para o Plano Pro é simples e imediato. Acesse cpfhub.io para começar.