# Como consumir API de CPF em Capacitor para apps híbridos

> Aprenda a consumir a API de CPF da CPFHub.io em aplicações híbridas Capacitor com plugins nativos e fetch para iOS e Android.

**Publicado:** 07/07/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-capacitor-para-apps-hibridos

---


O **Capacitor** é uma runtime moderna criada pela equipe do Ionic que transforma aplicações web em apps nativos para iOS e Android. Para consumir a API de CPF da CPFHub.io em um app híbrido, você usa a API `fetch` nativa do webview com o header `x-api-key`, armazenando a chave de API com segurança via `@capacitor/preferences`. A API responde em ~900ms com nome, data de nascimento e demais dados do titular ao receber `GET https://api.cpfhub.io/cpf/{CPF}`.

---

## 1. Pré-requisitos

* **Node.js 18+** e um projeto web (React, Vue, Angular ou vanilla).

* Capacitor instalado: `npm install @capacitor/core @capacitor/cli`.

* Plataformas adicionadas: `npx cap add ios` e/ou `npx cap add android`.

* Uma conta gratuita na [**CPFHub.io**](https://www.cpfhub.io/)

---

## 2. Configure o Capacitor

No `capacitor.config.ts`, configure o servidor e permissões de rede. Consulte a [documentação oficial do Capacitor](https://capacitorjs.com/docs/config) para referência completa de opções:

```typescript
// capacitor.config.ts
import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
 appId: "io.cpfhub.app",
 appName: "CPF Validator",
 webDir: "dist",
 server: {
 androidScheme: "https",
 cleartext: false,
 },
};

export default config;
```

---

## 3. Crie o serviço de consulta de CPF

Crie um módulo TypeScript para encapsular a comunicação com a API:

```typescript
// src/services/cpfhub.ts

interface CpfData {
 cpf: string;
 name: string;
 nameUpper: string;
 gender: string;
 birthDate: string;
 day: number;
 month: number;
 year: number;
}

interface CpfResponse {
 success: boolean;
 data: CpfData;
}

interface CpfError {
 message: string;
 statusCode: number;
}

const CPFHUB_CONFIG = {
 baseUrl: "https://api.cpfhub.io",
 timeout: 5000,
};

export async function consultarCpf(
 cpf: string,
 apiKey: string
): Promise<CpfData> {
 const cpfLimpo = cpf.replace(/\D/g, "");

 if (cpfLimpo.length !== 11) {
 throw { message: "CPF deve conter exatamente 11 dígitos", statusCode: 400 } as CpfError;
 }

 const url = `${CPFHUB_CONFIG.baseUrl}/cpf/${cpfLimpo}`;
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), CPFHUB_CONFIG.timeout);

 try {
 const response = await fetch(url, {
 method: "GET",
 headers: {
 "x-api-key": apiKey,
 Accept: "application/json",
 },
 signal: controller.signal,
 });

 clearTimeout(timeoutId);

 if (response.ok) {
 const data: CpfResponse = await response.json();
 if (data.success) {
 return data.data;
 }
 throw { message: "Resposta inesperada da API", statusCode: 500 } as CpfError;
 }

 const errorMap: Record<number, string> = {
 400: "CPF com formato inválido",
 401: "Chave de API inválida ou ausente",
 404: "CPF não encontrado na base de dados",
 };

 throw {
 message: errorMap[response.status] || `Erro HTTP ${response.status}`,
 statusCode: response.status,
 } as CpfError;
 } catch (error: any) {
 clearTimeout(timeoutId);

 if (error.name === "AbortError") {
 throw { message: "Timeout na consulta", statusCode: 504 } as CpfError;
 }
 if (error.statusCode) {
 throw error;
 }
 throw { message: `Erro de conexão: ${error.message}`, statusCode: 502 } as CpfError;
 }
}
```

---

## 4. Armazene a chave de API com segurança

Use o plugin `@capacitor/preferences` para armazenar a chave de API de forma segura no dispositivo:

```bash
npm install @capacitor/preferences
```

```typescript
// src/services/config.ts
import { Preferences } from "@capacitor/preferences";

const API_KEY_STORAGE = "cpfhub_api_key";

export async function salvarApiKey(apiKey: string): Promise<void> {
 await Preferences.set({
 key: API_KEY_STORAGE,
 value: apiKey,
 });
}

export async function obterApiKey(): Promise<string | null> {
 const { value } = await Preferences.get({ key: API_KEY_STORAGE });
 return value;
}

export async function removerApiKey(): Promise<void> {
 await Preferences.remove({ key: API_KEY_STORAGE });
}
```

---

## 5. Crie o componente de consulta

Exemplo com vanilla JavaScript (adaptável para React, Vue ou Angular):

```typescript
// src/components/cpf-consulta.ts
import { consultarCpf } from "../services/cpfhub";
import { obterApiKey } from "../services/config";

export async function inicializarConsulta(): Promise<void> {
 const form = document.getElementById("cpf-form") as HTMLFormElement;
 const input = document.getElementById("cpf-input") as HTMLInputElement;
 const resultado = document.getElementById("resultado") as HTMLDivElement;
 const btnConsultar = document.getElementById("btn-consultar") as HTMLButtonElement;

 form.addEventListener("submit", async (e) => {
 e.preventDefault();

 const cpf = input.value.trim();
 if (!cpf) {
 resultado.innerHTML = '<p class="erro">Digite um CPF valido.</p>';
 return;
 }

 btnConsultar.disabled = true;
 resultado.innerHTML = "<p>Consultando...</p>";

 try {
 const apiKey = await obterApiKey();
 if (!apiKey) {
 resultado.innerHTML = '<p class="erro">Chave de API nao configurada.</p>';
 return;
 }

 const dados = await consultarCpf(cpf, apiKey);
 resultado.innerHTML = `
 <div class="sucesso">
 <h3>CPF Encontrado</h3>
 <p><strong>Nome:</strong> ${dados.name}</p>
 <p><strong>CPF:</strong> ${dados.cpf}</p>
 <p><strong>Genero:</strong> ${dados.gender}</p>
 <p><strong>Nascimento:</strong> ${dados.birthDate}</p>
 </div>
 `;
 } catch (error: any) {
 resultado.innerHTML = `<p class="erro">${error.message}</p>`;
 } finally {
 btnConsultar.disabled = false;
 }
 });
}
```

---

## 6. Verifique a conectividade antes da consulta

Use o plugin `@capacitor/network` para verificar a conexão antes de consultar:

```bash
npm install @capacitor/network
```

```typescript
// src/services/network.ts
import { Network } from "@capacitor/network";

export async function verificarConexao(): Promise<boolean> {
 const status = await Network.getStatus();
 return status.connected;
}

export function monitorarConexao(
 callback: (conectado: boolean) => void
): void {
 Network.addListener("networkStatusChange", (status) => {
 callback(status.connected);
 });
}
```

```typescript
// Uso na consulta
import { verificarConexao } from "../services/network";

async function consultarComVerificacao(cpf: string, apiKey: string) {
 const conectado = await verificarConexao();
 if (!conectado) {
 throw { message: "Sem conexão com a internet", statusCode: 0 };
 }
 return consultarCpf(cpf, apiKey);
}
```

---

## 7. Adicione máscara de CPF no input

Implemente uma máscara para melhorar a experiência do usuário:

```typescript
// src/utils/cpf-mask.ts
export function aplicarMascaraCpf(valor: string): string {
 const numeros = valor.replace(/\D/g, "").slice(0, 11);

 if (numeros.length <= 3) return numeros;
 if (numeros.length <= 6) return `${numeros.slice(0, 3)}.${numeros.slice(3)}`;
 if (numeros.length <= 9) return `${numeros.slice(0, 3)}.${numeros.slice(3, 6)}.${numeros.slice(6)}`;
 return `${numeros.slice(0, 3)}.${numeros.slice(3, 6)}.${numeros.slice(6, 9)}-${numeros.slice(9)}`;
}

// Aplicar no input
const cpfInput = document.getElementById("cpf-input") as HTMLInputElement;
cpfInput.addEventListener("input", (e) => {
 const target = e.target as HTMLInputElement;
 target.value = aplicarMascaraCpf(target.value);
});
```

---

## 8. Boas práticas

* **Segurança** -- Nunca exponha a chave de API no código-fonte do app. Use armazenamento seguro via Preferences ou, idealmente, um backend intermediário.

* **Conectividade** -- Sempre verifique a conexão antes de fazer requisições em apps mobile. Dispositivos móveis frequentemente perdem conectividade.

* **Timeout** -- Configure timeout de 5 segundos via `AbortController` para evitar que o app trave em conexões lentas.

* **UX mobile** -- Adicione feedback visual (loading, sucesso, erro) e máscaras de input para melhorar a experiência do usuário mobile.

* **HTTPS** -- O Capacitor exige HTTPS por padrão em produção. A API da CPFHub.io já utiliza HTTPS.

* **LGPD** -- A API da CPFHub.io é 100% compatível com a LGPD. Em apps mobile, informe ao usuário sobre o tratamento de dados pessoais conforme a legislação.

---

## Perguntas frequentes

### Como armazenar a chave de API com segurança em um app Capacitor?

O plugin `@capacitor/preferences` armazena valores em `UserDefaults` no iOS e `SharedPreferences` no Android — ambos inacessíveis a outros apps. Para cenários com maior exigência de segurança, considere um backend intermediário que mantém a chave de API no servidor e expõe apenas um endpoint autenticado para o app, seguindo as recomendações do [OWASP Mobile Application Security](https://owasp.org/www-project-mobile-application-security/).

### A API da CPFHub.io bloqueia consultas quando o limite mensal é atingido?

Não. Ao ultrapassar o limite mensal, a API continua respondendo normalmente e cobra R$0,15 por consulta adicional — sem retornar erro nem interromper o serviço. O plano gratuito inclui 50 consultas/mês e o plano Pro inclui 1.000 consultas/mês por R$149. Para monitorar o uso, acesse `app.cpfhub.io/settings/billing`.

### Como lidar com o tempo de resposta de ~900ms em apps mobile?

Desabilite o botão de consulta imediatamente após o clique e exiba um indicador de carregamento. No Capacitor, o `AbortController` com timeout de 5 segundos garante que o app não trave em conexões lentas. Verifique a conectividade com `@capacitor/network` antes de fazer a requisição para evitar erros desnecessários em áreas sem sinal.

### Qual a diferença entre usar fetch direto e um plugin nativo para chamadas HTTP no Capacitor?

O `fetch` nativo do webview funciona bem para a maioria dos casos e é suficiente para consumir a API da CPFHub.io. Plugins nativos como `@capacitor-community/http` são úteis quando você precisa contornar restrições de CORS no ambiente nativo ou acessar certificados de cliente. Para requisições simples com `x-api-key` via HTTPS, o `fetch` com `AbortController` oferece controle suficiente de timeout e cancelamento.

---

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [Como consumir API de CPF em Flutter com Dart e pacote http](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-flutter-com-dart-e-pacote-http)
- [Como consumir API de CPF em TypeScript com tipagem segura](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-typescript-com-tipagem-segura)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)

---

## Conclusão

Consumir a API da [**CPFHub.io**](https://www.cpfhub.io/)

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)