# Como integrar API de CPF em aplicações Electron para desktop
> Aprenda a integrar a API de consulta de CPF da CPFHub.io em aplicações Electron para desktop com exemplos completos em JavaScript.
**Publicado:** 07/11/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-api-de-cpf-em-aplicacoes-electron-para-desktop
---
Para integrar a API de CPF da CPFHub.io em uma aplicação Electron, a chave de API deve ficar exclusivamente no main process e as consultas devem ser feitas via IPC (Inter-Process Communication), mantendo o renderer process sem acesso direto a segredos. Essa arquitetura garante segurança e evita exposição da chave de API no front-end da aplicação desktop.
## Introdução
O Electron é um framework que permite construir aplicações desktop multiplataforma (Windows, macOS e Linux) utilizando tecnologias web como HTML, CSS e JavaScript. Empresas que precisam de ferramentas desktop para gestão de clientes, emissão de notas fiscais ou controle de cadastros frequentemente optam pelo Electron pela rapidez de desenvolvimento e pela possibilidade de reutilizar código web.
Quando essas aplicações operam no mercado brasileiro, a validação de CPF é uma funcionalidade essencial para garantir a integridade dos dados cadastrais.
---
## Arquitetura de segurança no Electron
No Electron, existem dois processos fundamentais:
* **Main process** -- Tem acesso total ao sistema operacional e ao Node.js. É onde a chave de API deve ser armazenada e as requisições externas devem ser feitas.
* **Renderer process** -- Executa o código da interface (HTML/CSS/JS) em um contexto similar a um navegador. Não deve ter acesso direto a segredos como chaves de API.
A comunicação entre os processos é feita via IPC (Inter-Process Communication). Essa arquitetura garante que a chave de API nunca seja exposta na interface do usuário. A [documentação oficial do Electron](https://www.electronjs.org/docs/latest/tutorial/ipc) detalha os padrões recomendados de IPC e context isolation.
---
## Configuração do projeto
### Estrutura de diretórios
```
meu-app-electron/
main.js
preload.js
renderer/
index.html
script.js
.env
package.json
```
### Dependências
```bash
npm init -y
npm install electron dotenv node-fetch
```
### Variáveis de ambiente (.env)
```
CPFHUB_API_KEY=SUA_CHAVE_DE_API
```
---
## Implementando o main process
O arquivo `main.js` configura a janela do Electron e registra o handler IPC para consultas de CPF. Quando o limite de consultas gratuitas for ultrapassado, a API cobra R$0,15 por consulta adicional — nunca bloqueia a requisição.
```javascript
const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('path');
require('dotenv').config();
function createWindow() {
const win = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false,
},
});
win.loadFile('renderer/index.html');
}
ipcMain.handle('consultar-cpf', async (event, cpf) => {
const cpfLimpo = cpf.replace(/\D/g, '');
if (cpfLimpo.length !== 11) {
return { success: false, error: 'CPF deve ter 11 dígitos.' };
}
const apiKey = process.env.CPFHUB_API_KEY;
if (!apiKey) {
return { success: false, error: 'Chave de API não configurada.' };
}
const url = `https://api.cpfhub.io/cpf/${cpfLimpo}`;
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);
try {
const fetch = (await import('node-fetch')).default;
const response = await fetch(url, {
method: 'GET',
headers: {
'x-api-key': apiKey,
'Accept': 'application/json',
},
signal: controller.signal,
});
clearTimeout(timeoutId);
if (!response.ok) {
return { success: false, error: `Erro HTTP: ${response.status}` };
}
const dados = await response.json();
return dados;
} catch (error) {
clearTimeout(timeoutId);
if (error.name === 'AbortError') {
return { success: false, error: 'Tempo limite excedido.' };
}
return { success: false, error: 'Erro ao consultar CPF.' };
}
});
app.whenReady().then(createWindow);
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit();
});
```
---
## Configurando o preload script
O `preload.js` expõe uma API segura ao renderer process:
```javascript
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('cpfHub', {
consultarCpf: (cpf) => ipcRenderer.invoke('consultar-cpf', cpf),
});
```
Isso garante que o renderer só tenha acesso à função `consultarCpf`, sem contato direto com o Node.js ou com a chave de API.
---
## Interface do usuário (renderer)
### index.html
```html
Consulta de CPF
`;
resultadoDiv.style.display = 'block';
} else {
erroDiv.textContent = dados.error || 'CPF não encontrado.';
}
} catch (error) {
erroDiv.textContent = 'Erro ao consultar CPF.';
}
});
```
---
## Testando a aplicação
Adicione o script de execução no `package.json`:
```json
{
"scripts": {
"start": "electron ."
}
}
```
Execute com:
```bash
npm start
```
Para testar a API diretamente via terminal:
```bash
curl -X GET https://api.cpfhub.io/cpf/12345678900 \
-H "x-api-key: SUA_CHAVE_DE_API" \
-H "Accept: application/json" \
--max-time 10
```
---
## Cenários de uso para aplicações desktop
* **Sistemas de gestão de clientes** -- Validar CPF ao cadastrar novos clientes no CRM desktop.
* **Emissão de notas fiscais** -- Conferir CPF antes de gerar NF-e para evitar rejeições.
* **Ferramentas de RH** -- Validar CPF de colaboradores durante o processo de admissão.
* **Aplicações para cartórios** -- Conferir dados cadastrais antes de lavrar documentos.
---
## Boas práticas
* **Context isolation** -- Sempre mantenha `contextIsolation: true` e `nodeIntegration: false` para segurança.
* **Chave de API no .env** -- Nunca inclua a chave diretamente no código do renderer.
* **Timeout** -- Configure timeout nas requisições para evitar travamento da aplicação.
* **Controle de consumo** -- No plano gratuito, o rate limit é de 1 requisição a cada 2 segundos e 50 consultas/mês. Quando o limite é ultrapassado, a API cobra R$0,15/consulta — não bloqueia. No plano Pro, o limite sobe para 1 req/s e 1.000 consultas por R$149/mês.
---
## Perguntas frequentes
### Por que a chave de API não pode ficar no renderer process do Electron?
O renderer process roda em um contexto de navegador e qualquer usuário com acesso à máquina pode inspecionar as DevTools, extrair variáveis de ambiente expostas ao renderer e reutilizar a chave. Mantendo a chave no main process e usando IPC, ela nunca trafega para o contexto web da aplicação.
### O que acontece se o usuário fazer muitas consultas e ultrapassar o limite do plano?
A API da CPFHub.io não bloqueia as requisições ao atingir o limite de consultas. Cada consulta excedente é cobrada automaticamente a R$0,15. Você pode acompanhar o consumo em tempo real no painel em app.cpfhub.io/settings/billing e configurar alertas para evitar surpresas na fatura.
### É possível usar a API da CPFHub.io em aplicações Electron offline?
Não. A consulta à API requer conexão com a internet, pois os dados cadastrais são verificados em tempo real contra a base de dados. Para cenários offline, é possível fazer apenas validação sintática dos dígitos verificadores localmente, sem acesso à API.
### Como distribuir a chave de API com o executável do Electron sem expô-la?
Use variáveis de ambiente no ambiente de produção (configuradas no servidor ou na estação de trabalho) em vez de empacotar a chave no build. Ferramentas como `electron-builder` permitem injetar variáveis no momento da build. Jamais inclua a chave em repositórios de código.
### Leia também
- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos)
- [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei)
---
## Conclusão
Integrar a API de consulta de CPF da [**CPFHub.io**](https://www.cpfhub.io/) em aplicações Electron é direto quando se usa a arquitetura correta: chave de API no main process, comunicação via IPC e context isolation ativado. O resultado é uma aplicação desktop segura, com validação de CPF em tempo real e sem exposição de credenciais.
Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF à sua aplicação Electron hoje mesmo.