Como integrar API de CPF em aplicações 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 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

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.

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:

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

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <title>Consulta de CPF</title>
    <style>
    body { font-family: Arial, sans-serif; padding: 40px; }
    input { padding: 10px; width: 250px; font-size: 16px; }
    button { padding: 10px 20px; font-size: 16px; margin-left: 10px; }
    .resultado { margin-top: 20px; padding: 16px; background: #f5f5f5; border-radius: 8px; }
    .erro { color: red; margin-top: 12px; }
    </style>
</head>
<body>
    <h1>Consulta de CPF</h1>
    <div>
    <input type="text" id="cpfInput" placeholder="Digite o CPF" maxlength="11" />
    <button id="btnConsultar">Consultar</button>
    </div>
    <div id="resultado" class="resultado" style="display: none;"></div>
    <div id="erro" class="erro"></div>
    <script src="script.js"></script>
</body>
</html>

script.js

document.getElementById('btnConsultar').addEventListener('click', async () => {
    const cpf = document.getElementById('cpfInput').value;
    const resultadoDiv = document.getElementById('resultado');
    const erroDiv = document.getElementById('erro');

    resultadoDiv.style.display = 'none';
    erroDiv.textContent = '';

    if (!cpf || cpf.replace(/\D/g, '').length !== 11) {
    erroDiv.textContent = 'Informe um CPF com 11 dígitos.';
    return;
    }

    try {
    const dados = await window.cpfHub.consultarCpf(cpf);

    if (dados.success && dados.data) {
    resultadoDiv.innerHTML = `
    <p><strong>Nome:</strong> ${dados.data.name}</p>
    <p><strong>CPF:</strong> ${dados.data.cpf}</p>
    <p><strong>Nascimento:</strong> ${dados.data.birthDate}</p>
    <p><strong>Gênero:</strong> ${dados.data.gender}</p>
    `;
    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:

{
    "scripts": {
    "start": "electron ."
    }
}

Execute com:

npm start

Para testar a API diretamente via terminal:

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.

Conclusão

Integrar a API de consulta de CPF da 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 — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF à sua aplicação Electron hoje mesmo.