Validar CPF em React Native envolve duas etapas: verificar os dígitos verificadores localmente (sem custo de rede) e consultar a API da CPFHub.io para confirmar nome, data de nascimento e gênero do titular. O endpoint é GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key, retorna JSON em ~900ms e nunca bloqueia por limite de uso — consultas acima da cota são cobradas a R$0,15 cada.
Introdução
O React Native é um dos frameworks mais utilizados para desenvolvimento de aplicativos móveis multiplataforma. Aplicativos brasileiros que envolvem cadastro de usuários, pagamentos ou onboarding digital precisam validar o CPF dos usuários para garantir a autenticidade dos dados e prevenir fraudes.
Pré-requisitos
- React Native 0.72+ -- Com ambiente configurado para Android e/ou iOS.
- Node.js 18+ -- Para gerenciamento de pacotes.
- Conta na CPFHub.io -- Para obter a chave de API. O plano gratuito inclui 50 consultas/mês.
Instalando axios (opcional)
Se preferir usar axios em vez de fetch:
npm install axios
Consultando CPF com fetch
A API fetch já está disponível no React Native sem necessidade de bibliotecas adicionais. Consulte a documentação da Fetch API no MDN para referência completa dos parâmetros:
const API_KEY = 'SUA_CHAVE_DE_API';
async function consultarCpfComFetch(cpf) {
const cpfLimpo = cpf.replace(/\D/g, '');
if (cpfLimpo.length !== 11) {
throw new Error('CPF deve ter 11 dígitos.');
}
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);
try {
const response = await fetch(
`https://api.cpfhub.io/cpf/${cpfLimpo}`,
{
method: 'GET',
headers: {
'x-api-key': API_KEY,
'Accept': 'application/json',
},
signal: controller.signal,
}
);
clearTimeout(timeoutId);
if (!response.ok) {
throw new Error(`Erro HTTP: ${response.status}`);
}
const dados = await response.json();
if (dados.success && dados.data) {
return dados.data;
} else {
throw new Error('CPF não encontrado na base de dados.');
}
} catch (error) {
clearTimeout(timeoutId);
if (error.name === 'AbortError') {
throw new Error('A requisição excedeu o tempo limite.');
}
throw error;
}
}
Consultando CPF com axios
O axios oferece uma interface mais rica, com interceptors, transformadores de dados e configuração de timeout nativa:
import axios from 'axios';
const API_KEY = 'SUA_CHAVE_DE_API';
const cpfHubApi = axios.create({
baseURL: 'https://api.cpfhub.io',
timeout: 10000,
headers: {
'x-api-key': API_KEY,
'Accept': 'application/json',
},
});
async function consultarCpfComAxios(cpf) {
const cpfLimpo = cpf.replace(/\D/g, '');
if (cpfLimpo.length !== 11) {
throw new Error('CPF deve ter 11 dígitos.');
}
try {
const response = await cpfHubApi.get(`/cpf/${cpfLimpo}`);
if (response.data.success && response.data.data) {
return response.data.data;
} else {
throw new Error('CPF não encontrado na base de dados.');
}
} catch (error) {
if (error.response) {
throw new Error(`Erro HTTP: ${error.response.status}`);
} else if (error.code === 'ECONNABORTED') {
throw new Error('A requisição excedeu o tempo limite.');
}
throw error;
}
}
Exemplo de resposta da API
Ambas as abordagens retornam os mesmos dados:
{
"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
}
}
Criando um componente de consulta
Abaixo está um componente React Native completo que implementa a tela de consulta:
import React, { useState } from 'react';
import {
View,
Text,
TextInput,
TouchableOpacity,
StyleSheet,
ActivityIndicator,
} from 'react-native';
const API_KEY = 'SUA_CHAVE_DE_API';
export default function ConsultaCpfScreen() {
const [cpf, setCpf] = useState('');
const [resultado, setResultado] = useState(null);
const [erro, setErro] = useState('');
const [carregando, setCarregando] = useState(false);
async function handleConsulta() {
setErro('');
setResultado(null);
setCarregando(true);
const cpfLimpo = cpf.replace(/\D/g, '');
if (cpfLimpo.length !== 11) {
setErro('Informe um CPF com 11 dígitos.');
setCarregando(false);
return;
}
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);
try {
const response = await fetch(
`https://api.cpfhub.io/cpf/${cpfLimpo}`,
{
method: 'GET',
headers: {
'x-api-key': API_KEY,
'Accept': 'application/json',
},
signal: controller.signal,
}
);
clearTimeout(timeoutId);
const dados = await response.json();
if (dados.success && dados.data) {
setResultado(dados.data);
} else {
setErro('CPF não encontrado.');
}
} catch (error) {
clearTimeout(timeoutId);
if (error.name === 'AbortError') {
setErro('Tempo limite excedido.');
} else {
setErro('Erro ao consultar CPF.');
}
} finally {
setCarregando(false);
}
}
return (
<View style={styles.container}>
<Text style={styles.titulo}>Consulta de CPF</Text>
<TextInput
style={styles.input}
value={cpf}
onChangeText={setCpf}
placeholder="Digite o CPF"
keyboardType="numeric"
maxLength={11}
/>
<TouchableOpacity
style={styles.botao}
onPress={handleConsulta}
disabled={carregando}
>
{carregando ? (
<ActivityIndicator color="#fff" />
) : (
<Text style={styles.botaoTexto}>Consultar</Text>
)}
</TouchableOpacity>
{resultado && (
<View style={styles.resultado}>
<Text>Nome: {resultado.name}</Text>
<Text>CPF: {resultado.cpf}</Text>
<Text>Nascimento: {resultado.birthDate}</Text>
<Text>Gênero: {resultado.gender}</Text>
</View>
)}
{erro ? <Text style={styles.erro}>{erro}</Text> : null}
</View>
);
}
const styles = StyleSheet.create({
container: { flex: 1, padding: 20, justifyContent: 'center' },
titulo: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 },
input: { borderWidth: 1, borderColor: '#ccc', padding: 12, borderRadius: 8 },
botao: { backgroundColor: '#007AFF', padding: 14, borderRadius: 8, marginTop: 12, alignItems: 'center' },
botaoTexto: { color: '#fff', fontSize: 16, fontWeight: '600' },
resultado: { marginTop: 20, padding: 16, backgroundColor: '#f0f0f0', borderRadius: 8 },
erro: { color: 'red', marginTop: 12 },
});
Comparação entre fetch e axios
| Característica | fetch | axios |
|---|---|---|
| Instalação | Nativo | Requer npm install |
| Timeout | Manual (AbortController) | Configuração nativa |
| Interceptors | Não nativo | Sim |
| Transformação de dados | Manual | Automática |
| Tamanho do bundle | Zero | ~13KB |
| Tratamento de erros HTTP | Não lança exceção para 4xx/5xx | Lança exceção automaticamente |
Para projetos simples, fetch é suficiente. Para projetos maiores com necessidade de interceptors e configuração centralizada, axios é a escolha recomendada.
Boas práticas
-
Chave de API -- Em produção, utilize um back-end intermediário para proteger a chave. Nunca exponha a chave no código do aplicativo distribuído.
-
Timeout -- Sempre configure timeout para evitar que o app fique travado aguardando resposta.
-
Validação local -- Valide o formato e os dígitos verificadores do CPF antes de chamar a API.
-
Consumo de cota -- No plano gratuito, 50 consultas/mês. A API nunca bloqueia: ao ultrapassar o limite, cada consulta adicional custa R$0,15. O plano Pro oferece 1.000 consultas por R$149/mês.
Perguntas frequentes
A API CPFHub.io retorna HTTP 429 quando o limite de consultas é atingido no React Native?
Não. A CPFHub.io nunca retorna HTTP 429 nem bloqueia requisições, independentemente do volume. Ao ultrapassar o limite do plano gratuito (50 consultas/mês), as consultas adicionais são cobradas a R$0,15 cada. Isso significa que seu app React Native continua funcionando normalmente — sem erros inesperados de rate limit.
Devo usar fetch ou axios para consumir a API CPFHub.io em React Native?
Para apps simples, fetch é suficiente — já está disponível nativamente e não adiciona tamanho ao bundle. Para apps maiores, o axios facilita o gerenciamento centralizado de headers (incluindo o x-api-key), interceptors para log e retry, e tratamento automático de erros HTTP. Ambos funcionam perfeitamente com a CPFHub.io.
Como proteger a API key em um app React Native distribuído?
Nunca inclua a chave de API diretamente no código do app. A solução correta é criar um back-end intermediário (ex: uma Minimal API .NET, uma função serverless ou um endpoint Node.js) que receba o CPF do app, consulte a CPFHub.io com a chave guardada em variáveis de ambiente e devolva apenas os dados necessários.
Como lidar com o timeout de ~900ms da API em apps móveis com conexão instável?
Configure o timeout do AbortController (fetch) ou da instância axios para 10-15 segundos, cobrindo redes 3G lentas. Adicione lógica de retry com backoff exponencial para reconexão automática. No componente, exiba um skeleton loading ou um ActivityIndicator durante a espera para manter o usuário informado sem frustração.
Conclusão
Validar CPF em aplicações React Native é um processo direto com a API da CPFHub.io: uma chamada GET com o header x-api-key retorna nome, data de nascimento e gênero em ~900ms, sem risco de bloqueio por volume.
Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF ao seu app React Native ainda hoje.
CPFHub.io
Pronto para integrar a API?
50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.
Sobre a redação
Redação CPFHub.io
Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.



