Como criar um validador de CPF grátis para seu site

Para criar um validador de CPF grátis para seu site, combine validação sintática no front-end — verificando os dígitos verificadores localmente em JavaScript — com consulta real à API da CPFHub.io no back-end, usando a chave x-api-key. O plano gratuito oferece 50 consultas por mês sem cartão de crédito, o que é suficiente para MVPs e sites com baixo volume de cadastros.

Introdução

Adicionar um validador de CPF ao seu site é uma das formas mais eficientes de prevenir cadastros com dados falsos, garantir a emissão correta de notas fiscais e melhorar a qualidade dos dados armazenados. A boa notícia é que isso pode ser feito sem custo, combinando validação sintática no front-end com consulta real via API no back-end.

Arquitetura do validador

O validador ideal funciona em duas camadas:

• Camada 1 -- Validação sintática (front-end) -- verifica se o CPF tem formato válido antes de enviar para o servidor. Isso acontece no navegador do usuário e não consome nenhuma requisição da API.

• Camada 2 -- Validação real (back-end) -- consulta a API da CPFHub.io para confirmar que o CPF pertence a uma pessoa real e retorna os dados cadastrais associados.

Essa arquitetura em duas camadas garante que apenas CPFs com formato válido sejam enviados para a API, economizando consultas e melhorando a performance.

Camada 1: validação sintática no front-end

A validação sintática verifica o formato do CPF usando o algoritmo oficial de dígitos verificadores. Ela pode ser implementada diretamente em JavaScript no navegador:

function validarCPFFormato(cpf) {
    cpf = cpf.replace(/\D/g, '');

    if (cpf.length !== 11) return false;
    if (/^(\d)\1{10}$/.test(cpf)) return false;

    let soma = 0;
    for (let i = 0; i < 9; i++) {
    soma += parseInt(cpf[i]) * (10 - i);
    }
    let resto = (soma * 10) % 11;
    if (resto === 10) resto = 0;
    if (resto !== parseInt(cpf[9])) return false;

    soma = 0;
    for (let i = 0; i < 10; i++) {
    soma += parseInt(cpf[i]) * (11 - i);
    }
    resto = (soma * 10) % 11;
    if (resto === 10) resto = 0;
    return resto === parseInt(cpf[10]);
}

// Uso no formulário
document.getElementById('cpf-input').addEventListener('blur', function() {
    const cpf = this.value;
    const mensagem = document.getElementById('cpf-mensagem');

    if (!validarCPFFormato(cpf)) {
    mensagem.textContent = 'CPF com formato inválido.';
    mensagem.style.color = 'red';
    } else {
    mensagem.textContent = 'Formato válido. Verificando dados...';
    mensagem.style.color = 'green';
    // Aqui você envia para o back-end validar via API
    }
});

Essa validação acontece instantaneamente no navegador, sem nenhuma chamada ao servidor. CPFs com formato inválido são rejeitados antes mesmo de chegarem ao back-end.

Camada 2: validação real no back-end

Para CPFs que passaram na validação sintática, o back-end consulta a API da CPFHub.io para confirmar a existência do CPF e obter dados cadastrais. Abaixo, um exemplo usando Node.js com Express:

const express = require('express');
const app = express();

app.get('/api/validar-cpf/:cpf', async (req, res) => {
    const { cpf } = req.params;

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    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);
    const data = await response.json();

    if (data.success) {
    res.json({
    valido: true,
    nome: data.data.name,
    dataNascimento: data.data.birthDate
    });
    } else {
    res.json({
    valido: false,
    motivo: 'CPF não encontrado na base de dados'
    });
    }
    } catch (error) {
    clearTimeout(timeoutId);
    res.status(500).json({
    valido: false,
    motivo: 'Erro na consulta. Tente novamente.'
    });
    }
});

app.listen(3000);

Conectando front-end e back-end

Para completar o fluxo, o front-end precisa enviar o CPF validado sintaticamente para o endpoint do back-end e exibir o resultado:

async function validarCPFCompleto(cpf) {
    // Camada 1: validação local
    if (!validarCPFFormato(cpf)) {
    return { valido: false, motivo: 'Formato de CPF inválido' };
    }

    // Camada 2: validação via API (back-end)
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 15000);

    try {
    const response = await fetch(`/api/validar-cpf/${cpf}`, {
    signal: controller.signal
    });
    clearTimeout(timeoutId);
    return await response.json();
    } catch (error) {
    clearTimeout(timeoutId);
    return { valido: false, motivo: 'Erro de conexão. Tente novamente.' };
    }
}

Resposta da API da CPFHub.io

Quando a consulta é bem-sucedida, a API retorna:

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

Com esses dados, seu site pode:

• Exibir o nome completo do titular para confirmação visual.

• Preencher automaticamente campos como nome e data de nascimento.

• Comparar os dados informados pelo usuário com os dados reais.

Tratamento de erros e códigos HTTP

Seu validador precisa tratar diferentes cenários de resposta da API:

Boas práticas para seu validador

Não exponha a chave de API no front-end

A chamada à API da CPFHub.io deve ser feita exclusivamente pelo back-end. Nunca inclua a x-api-key em código JavaScript que roda no navegador.

Adicione máscara ao campo de CPF

Facilite o preenchimento usando uma máscara que formata o CPF automaticamente (000.000.000-00). Antes de enviar para a API, remova os caracteres de formatação.

Implemente debounce

Se o validador é acionado enquanto o usuário digita, use debounce para evitar múltiplas chamadas desnecessárias ao back-end.

Use cache para consultas repetidas

Se o mesmo CPF é submetido mais de uma vez em um curto intervalo, retorne o resultado em cache em vez de consumir uma nova consulta da API.

Custos e escalabilidade

O plano gratuito da CPFHub.io oferece 50 consultas por mês, suficiente para:

• Sites com até 50 cadastros mensais que exigem validação.

• Fase de desenvolvimento e testes da integração.

• Projetos pessoais ou MVPs.

Quando o tráfego do site crescer, o plano Pro (R$ 149/mês, 1.000 consultas) oferece maior volume e SLA de 99%. A migração é transparente -- basta alterar o plano no painel, sem modificar o código.

Perguntas frequentes

Preciso de back-end para criar um validador de CPF no meu site?

A validação sintática (verificação dos dígitos) pode ser feita inteiramente no front-end em JavaScript, sem custo e sem back-end. Já a consulta real — que confirma se o CPF pertence a uma pessoa real — exige uma chamada à API da CPFHub.io e deve ser feita no back-end para proteger a chave de API.

O plano gratuito é suficiente para validar CPF em produção?

Depende do volume. Com 50 consultas por mês, o plano gratuito atende sites com poucos cadastros, MVPs e ambientes de teste. Para sites com mais de 50 cadastros mensais, o plano Pro (R$ 149/mês) oferece 1.000 consultas. Se o limite for ultrapassado em qualquer plano, a API continua funcionando e cobra R$ 0,15 por consulta adicional, sem bloquear o serviço.

Como evitar consumir consultas da API com CPFs claramente inválidos?

Implemente a validação sintática no front-end antes de enviar para o back-end. Verificar o algoritmo dos dígitos verificadores em JavaScript rejeita a maioria dos CPFs mal digitados sem gastar nenhuma consulta da API. Apenas CPFs sintaticamente válidos chegam à camada de consulta real.

A validação de CPF via API está em conformidade com a LGPD?

Sim, desde que você respeite os princípios de finalidade e necessidade previstos na Lei Geral de Proteção de Dados (LGPD). Use o CPF somente para a finalidade declarada ao titular, não armazene o número em texto puro se um identificador interno bastar e documente a base legal para o tratamento.

Conclusão

Criar um validador de CPF para seu site é um projeto acessível que combina validação sintática no front-end com consulta real via API no back-end. Essa abordagem em duas camadas economiza recursos, melhora a experiência do usuário e garante dados confiáveis no seu sistema.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione um validador de CPF completo ao seu site em menos de 30 minutos.