# API de CPF grátis para desenvolvedores: como começar em 5 minutos > Aprenda a usar a API gratuita de consulta de CPF da CPFHub.io. Cadastro sem cartão de crédito, 50 consultas/mês e exemplos de código prontos. **Publicado:** 25/03/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-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**](https://www.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](https://www.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 ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" ``` ### Resposta JSON ```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**](https://www.cpfhub.io/) disponibiliza exemplos prontos em mais de 13 linguagens na documentação: ### Node.js ```javascript 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 ```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 "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.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: | Código | Significado | O que fazer | | --- | --- | --- | | 200 | Consulta bem-sucedida | Processar os dados retornados | | 400 | CPF malformado | Validar o formato antes de enviar | | 401 | Chave de API inválida | Verificar se a chave está correta | | 429 | Rate limit excedido | Aguardar e tentar novamente | | 500 | Erro interno do servidor | Implementar retry com backoff | ### Implementando retry com backoff exponencial (Node.js) ```javascript 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: ```javascript 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](https://www.gov.br/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. ### Leia também - [Checklist para escolher uma API de CPF: o que verificar antes de contratar](https://cpfhub.io/blog/checklist-escolher-api-cpf) - [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 consulta de CPF: diferenças entre planos gratuito, Pro e Corporate](https://cpfhub.io/blog/api-de-consulta-de-cpf-diferencas-entre-planos-gratuito-pro-e-corporate) - [APIs de CPF: como avaliar o custo-benefício antes de contratar?](https://cpfhub.io/blog/apis-de-cpf-como-avaliar-o-custo-beneficio-antes-de-contratar) --- ## Conclusão Começar a usar uma API de consulta de CPF não precisa ser complicado nem caro. Com a [**CPFHub.io**](https://www.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](https://www.cpfhub.io/) para começar.