# Como criar um validador de CPF grátis para seu site > Aprenda a criar um validador de CPF para seu site combinando verificação local e consulta via API gratuita. Inclui exemplos de código prontos para uso. **Publicado:** 21/09/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-criar-um-validador-de-cpf-gratis-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: ```javascript 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: ```javascript 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: ```javascript 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: ```json { "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: | Código HTTP | Significado | Ação recomendada | | --- | --- | --- | | 200 | Consulta bem-sucedida | Processar os dados retornados | | 400 | CPF com formato inválido | Exibir mensagem de erro ao usuário | | 401 | API key inválida ou ausente | Verificar configuração da chave | | 404 | CPF não encontrado | Informar que o CPF não consta na base | | 500/503 | Erro interno ou indisponibilidade | Exibir mensagem e tentar novamente | --- ## 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)](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm). 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. ### Leia também - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [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 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](https://www.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.