Consulta de CPF grátis: como funciona a limitacao de 50 consultas mensais

O plano gratuito da CPFHub.io oferece 50 consultas por mês, sem cartão de crédito. Essa é uma cota mensal: ao atingir o limite, a API não bloqueia nem retorna erro — ela continua funcionando e cobra R$0,15 por consulta adicional. O limite se renova automaticamente no primeiro dia de cada mês, e consultas não utilizadas não acumulam.

Como funciona o limite de 50 consultas

O plano gratuito da CPFHub.io oferece 50 consultas por mes, sem nenhum custo e sem necessidade de cartão de crédito. Cada requisição GET ao endpoint da API consome uma consulta do limite mensal.

Detalhes do limite

O que acontece ao atingir o limite

Quando as 50 consultas mensais são esgotadas, a API não bloqueia o acesso nem retorna erro. O serviço continua disponível e cobra R$0,15 por cada consulta adicional realizada no restante do mês. O limite mensal é zerado e renovado automaticamente no primeiro dia do mês seguinte.

O rate limit no plano gratuito

Além da cota mensal de 50 consultas, o plano gratuito possui um rate limit de 1 requisição a cada 2 segundos. Isso significa que, mesmo dentro das 50 consultas permitidas, não e possível enviar requisições em intervalos menores que 2 segundos.

Tratando o rate limit no código

async function consultarCPFComRetry(cpf, tentativas = 3) {
    for (let i = 0; i < tentativas; i++) {
    try {
    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) * 2000; // Backoff exponencial
    console.log(`Rate limit de requisições atingido. Aguardando ${espera}ms...`);
    await new Promise(resolve => setTimeout(resolve, espera));
    continue;
    }

    return await response.json();
    } catch (erro) {
    console.error(`Tentativa ${i + 1} falhou:`, erro.message);
    }
    }

    return { success: false, error: 'Todas as tentativas falharam' };
}

consultarCPFComRetry('12345678900')
    .then(resultado => console.log(resultado));

Resposta em caso de sucesso

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

Estrategias para otimizar as 50 consultas

1. Validação sintatica antes da API

Antes de consumir uma consulta, valide localmente se o CPF e sintaticamente válido. Isso evita desperdicar consultas com CPFs que contem letras, tem menos de 11 digitos ou cujos digitos verificadores são inválidos.

2. Cache de resultados

Se o mesmo CPF for consultado mais de uma vez no mesmo período, armazene o resultado em cache (memoria, Redis ou banco de dados local) e retorne o valor armazenado em vez de fazer uma nova requisição.

3. Deduplicacao na entrada

Se você processa listas de CPFs (por exemplo, em importacoes de planilhas), remova duplicatas antes de enviar para a API.

4. Priorizacao de consultas

Em cenários onde você tem mais CPFs para validar do que consultas disponíveis, priorize os casos mais críticos (por exemplo, novos cadastros) e deixe atualizações cadastrais para o próximo ciclo.

5. Monitoramento de consumo

Acompanhe o número de consultas realizadas pelo dashboard da CPFHub.io. Isso permite planejar o uso e identificar o momento certo de migrar para o plano Pro.

Quando migrar para o plano Pro

O plano gratuito e ideal para testes, prototipos, MVPs e operações de baixo volume. Quando a demanda cresce, a migração para o plano Pro e recomendada.

Sinais de que e hora de migrar

• Consultas esgotam antes do final do mes — Se você atinge o limite de 50 consultas regularmente e as cobranças de R$0,15 por extra começam a acumular, o volume ja justifica o plano Pro.

• Rate limit impacta a experiência — Se o intervalo de 2 segundos entre requisições afeta o fluxo do usuário, o plano Pro oferece 1 requisição por segundo.

• SLA mais alto e necessário — O plano Pro oferece SLA de 99%, contra 80% do plano gratuito.

• Operação em produção — Sistemas em produção que atendem clientes reais devem operar com um plano que garanta disponibilidade.

Comparativo de planos

A transicao entre planos não exige nenhuma alteracao de código. Basta atualizar o plano no painel de controle.

Boas práticas gerais

• Nunca dependa do plano gratuito para produção crítica — O SLA de 80% e adequado para testes, mas não para sistemas que atendem clientes em tempo real.

• Monitore o consumo da cota mensal — Acompanhe as consultas realizadas no dashboard para evitar cobranças inesperadas de excedente.

• Armazene a chave de API em variavel de ambiente — Nunca exponha credenciais no código-fonte.

• Planeje o crescimento — Monitore o consumo e planeje a migração de plano com antecedencia.

Perguntas frequentes

O que acontece quando o plano gratuito atinge as 50 consultas?

A API não bloqueia nem retorna erro ao atingir a cota mensal. Ela continua respondendo normalmente e cobra R$0,15 por cada consulta adicional realizada no restante do mês. O limite é renovado automaticamente no primeiro dia do mês seguinte, sem nenhuma ação necessária da sua parte.

Posso usar o plano gratuito em produção?

Tecnicamente sim, mas não é recomendado para sistemas críticos. O SLA do plano gratuito é de 80%, adequado para testes e MVPs. Para produção com clientes reais, o plano Pro oferece SLA de 99% e 1.000 consultas mensais por R$149 — com R$0,15 por consulta extra se necessário.

Qual é a latência da API CPFHub.io?

A latência média é de ~900ms por consulta. Para minimizar o impacto na experiência do usuário, faça a consulta em paralelo com outros processos de onboarding ou exiba um indicador de carregamento durante a verificação.

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

Conclusão

A limitacao de 50 consultas mensais no plano gratuito da CPFHub.io é uma cota mensal — não um bloqueio. Ao atingir o limite, a API continua funcionando e cobra R$0,15 por consulta adicional, o que oferece flexibilidade para picos esporádicos sem interrupção de serviço. Para volumes regulares acima de 50 consultas por mês, o plano Pro representa o melhor custo-benefício.

Cadastre-se em cpfhub.io