Como validar CPF no frontend com React e API REST

Introdução

A validação de CPF é uma etapa fundamental em qualquer aplicação brasileira que envolva cadastro de usuários, transações financeiras ou emissão de documentos fiscais. No ecossistema React, essa validação pode ser implementada em duas camadas: uma verificação de formato no frontend e uma consulta de dados cadastrais via API no backend.

Validação de formato vs. validação de dados

Antes de partir para o código, é importante entender a diferença entre os dois tipos de validação de CPF:

Validação de formato (frontend)

A validação de formato verifica se o número informado tem 11 dígitos e se os dígitos verificadores estão corretos de acordo com o algoritmo da Receita Federal. Essa validação pode ser feita inteiramente no frontend, sem necessidade de chamada a APIs externas.

Ela impede que o usuário envie números claramente inválidos, como sequências repetidas (111.111.111-11) ou CPFs com dígitos verificadores incorretos.

Validação de dados (API)

A validação de dados consulta uma base cadastral para verificar se o CPF existe de fato e retorna informações como nome completo, gênero e data de nascimento do titular. Essa validação deve ser feita no backend para proteger a chave de API.

Implementando a validação de formato em React

Vamos começar com um hook personalizado que valida o formato do CPF:

// hooks/useCPFValidation.js
import { useState, useCallback } from 'react';

function validarDigitosCPF(cpf) {
    const numeros = cpf.replace(/\D/g, '');

    if (numeros.length !== 11) return false;

    // Rejeitar sequências repetidas
    if (/^(\d)\1{10}$/.test(numeros)) return false;

    // Validar primeiro dígito verificador
    let soma = 0;
    for (let i = 0; i < 9; i++) {
    soma += parseInt(numeros[i]) * (10 - i);
    }
    let resto = (soma * 10) % 11;
    if (resto === 10) resto = 0;
    if (resto !== parseInt(numeros[9])) return false;

    // Validar segundo dígito verificador
    soma = 0;
    for (let i = 0; i < 10; i++) {
    soma += parseInt(numeros[i]) * (11 - i);
    }
    resto = (soma * 10) % 11;
    if (resto === 10) resto = 0;
    if (resto !== parseInt(numeros[10])) return false;

    return true;
}

export function useCPFValidation() {
    const [cpf, setCpf] = useState('');
    const [erro, setErro] = useState('');
    const [formatoValido, setFormatoValido] = useState(false);

    const validar = useCallback((valor) => {
    setCpf(valor);
    const numeros = valor.replace(/\D/g, '');

    if (numeros.length === 0) {
    setErro('');
    setFormatoValido(false);
    return;
    }

    if (numeros.length < 11) {
    setErro('CPF incompleto.');
    setFormatoValido(false);
    return;
    }

    if (!validarDigitosCPF(numeros)) {
    setErro('CPF inválido.');
    setFormatoValido(false);
    return;
    }

    setErro('');
    setFormatoValido(true);
    }, []);

    return { cpf, erro, formatoValido, validar };
}

Criando o componente de formulário

Agora vamos criar um componente de formulário que usa o hook de validação:

// components/CPFForm.jsx
import React, { useState } from 'react';
import { useCPFValidation } from '../hooks/useCPFValidation';

function formatarCPF(valor) {
    const numeros = valor.replace(/\D/g, '');
    return numeros
    .replace(/(\d{3})(\d)/, '$1.$2')
    .replace(/(\d{3})(\d)/, '$1.$2')
    .replace(/(\d{3})(\d{1,2})$/, '$1-$2');
}

export function CPFForm() {
    const { cpf, erro, formatoValido, validar } = useCPFValidation();
    const [dadosTitular, setDadosTitular] = useState(null);
    const [carregando, setCarregando] = useState(false);

    const handleChange = (e) => {
    const valorFormatado = formatarCPF(e.target.value);
    validar(valorFormatado);
    };

    const handleSubmit = async (e) => {
    e.preventDefault();
    if (!formatoValido) return;

    setCarregando(true);
    try {
    const numeros = cpf.replace(/\D/g, '');
    const response = await fetch(`/api/cpf/${numeros}`);
    const data = await response.json();

    if (data.success) {
    setDadosTitular(data.data);
    }
    } catch (error) {
    console.error('Erro na consulta:', error);
    } finally {
    setCarregando(false);
    }
    };

    return (
    <form onSubmit={handleSubmit}>
    <label htmlFor="cpf">CPF</label>
    <input
    id="cpf"
    type="text"
    value={cpf}
    onChange={handleChange}
    maxLength={14}
    placeholder="000.000.000-00"
    />
    {erro && <span className="erro">{erro}</span>}
    {formatoValido && <span className="valido">Formato válido</span>}

    <button type="submit" disabled={!formatoValido || carregando}>
    {carregando ? 'Consultando...' : 'Consultar'}
    </button>

    {dadosTitular && (
    <div className="resultado">
    <p>Nome: {dadosTitular.name}</p>
    <p>Data de nascimento: {dadosTitular.birthDate}</p>
    <p>Gênero: {dadosTitular.gender === 'M' ? 'Masculino' : 'Feminino'}</p>
    </div>
    )}
    </form>
    );
}

Configurando a rota de API no backend

A chave de API nunca deve ser exposta no frontend. Por isso, a consulta à CPFHub.io deve ser feita a partir de uma rota de API no servidor, que usa a chave armazenada em variável de ambiente e repassa apenas o resultado para o cliente.

// app/api/cpf/[cpf]/route.ts
export async function GET(
    request: Request,
    { params }: { params: { cpf: string } }
) {
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${params.cpf}`,
    {
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY!,
    'Accept': 'application/json'
    }
    }
    );

    const data = await response.json();
    return Response.json(data);
}

A variável de ambiente CPFHUB_API_KEY deve ser definida no arquivo .env.local do seu projeto Next.js:

CPFHUB_API_KEY=sua_chave_aqui

Boas práticas de segurança

Ao implementar validação de CPF em aplicações React, observe as seguintes práticas:

Nunca exponha a API key no frontend

A chave de API deve ficar exclusivamente no servidor. Qualquer chamada à API da CPFHub.io deve passar por uma rota de API no seu backend (Next.js API Routes, Express, etc.).

Implemente rate limiting na sua rota

Mesmo que a CPFHub.io tenha seus próprios rate limits, é recomendável implementar um limite de requisições na sua rota de API para evitar abuso por parte de usuários.

Valide o formato antes de consultar a API

Sempre valide o formato do CPF no frontend antes de enviar para o backend. Isso evita chamadas desnecessárias à API e melhora a experiência do usuário com feedback imediato.

Trate erros adequadamente

A API pode retornar diferentes códigos HTTP. Os mais comuns são:

Máscara de input com formatação automática

Para melhorar a experiência do usuário, a função formatarCPF que usamos no componente aplica automaticamente a máscara no formato 000.000.000-00 conforme o usuário digita. Isso reduz erros de digitação e torna o formulário mais intuitivo.

Se preferir uma solução mais robusta, bibliotecas como react-input-mask ou react-imask oferecem funcionalidades avançadas de máscara com suporte a acessibilidade.

Testando a integração

Para testar sua implementação sem custos, utilize o plano gratuito da CPFHub.io: 50 consultas por mês, sem cartão de crédito, com os mesmos dados e estrutura de resposta do plano pago.

Você pode testar a API diretamente com cURL antes de integrar ao React:

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

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

Validar CPF em uma aplicação React envolve duas camadas: verificação de formato no frontend para feedback imediato, e consulta via API no backend para confirmar dados reais. Manter essa separação protege a chave de API e garante uma experiência fluida. Comece com 50 consultas gratuitas em cpfhub.io.