# Como validar CPF no frontend com React e API REST

> Aprenda a implementar validação de CPF em aplicações React usando API REST. Exemplos completos de código com hooks, formulários e boas práticas.

**Publicado:** 26/02/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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](https://www.gov.br/receitafederal). 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:

```javascript
// 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:

```javascript
// 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.

```typescript
// 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:

| Código | Significado |
| --- | --- |
| 200 | Consulta bem-sucedida |
| 400 | CPF em formato inválido |
| 401 | API Key inválida ou ausente |
| 429 | Rate limit excedido |
| 500 | Erro interno do servidor |

---

## 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:

```bash
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](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

- [Como fazer consulta de CPF por nome completo via API](https://cpfhub.io/blog/como-fazer-consulta-de-cpf-por-nome-completo-via-api)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## 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](https://www.cpfhub.io/).