Como validar CPF em React Native usando fetch e axios

Aprenda a validar CPF em aplicações React Native usando fetch e axios. Guia completo com exemplos de código e integração com a API CPFHub.io.

Redação CPFHub.io
Redação CPFHub.io
··7 min de leitura
Como validar CPF em React Native usando fetch e axios

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ísticafetchaxios
InstalaçãoNativoRequer npm install
TimeoutManual (AbortController)Configuração nativa
InterceptorsNão nativoSim
Transformação de dadosManualAutomática
Tamanho do bundleZero~13KB
Tratamento de erros HTTPNão lança exceção para 4xx/5xxLanç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.

Redação CPFHub.io

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.

WhatsAppFale conosco via WhatsApp