# Como configurar proxy reverso para API de CPF em ambientes corporativos

> Aprenda a configurar um proxy reverso para acessar a API de consulta de CPF em ambientes corporativos com seguranca e controle.

**Publicado:** 22/01/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/configurar-proxy-reverso-api-cpf-ambientes-corporativos

---


Em ambientes corporativos com firewall restritivo, a forma correta de acessar a API de CPF é configurar um proxy reverso que centraliza a chave de autenticação, aplica cache de 30 minutos, distribui cotas por equipe e registra todas as consultas em um ponto único de auditoria — sem expor a `x-api-key` às aplicações internas.

## Introdução

Em ambientes corporativos, o acesso direto a APIs externas nem sempre é possível. Firewalls, políticas de segurança e requisitos de auditoria exigem que todo tráfego passe por um ponto central de controle. Um proxy reverso resolve esse problema, intermediando as chamadas à API de CPF e adicionando camadas de segurança, cache e monitoramento. O [OWASP](https://owasp.org/www-project-api-security/) recomenda a centralização de credenciais de API como boa prática de segurança para ambientes corporativos.

## Por que usar um proxy reverso

* **Segurança** — A API key fica centralizada no proxy, não distribuída entre múltiplas aplicações.

* **Controle de acesso** — Definir quais aplicações internas podem consultar CPF.

* **Auditoria** — Registrar todas as chamadas em um ponto único.

* **Cache** — Evitar chamadas duplicadas à API externa.

* **Rate limiting interno** — Distribuir a cota entre diferentes equipes.

* **Compliance** — Atender políticas de segurança que exigem controle centralizado de tráfego.

## Arquitetura com proxy reverso

```
[App 1] ─────┐
             │
[App 2] ─────┼──→ [Proxy Reverso] ──→ [api.cpfhub.io]
             │ (cache, auth,
[App 3] ─────┘  rate limit, log)
```

As aplicações internas chamam o proxy, que adiciona a API key e encaminha para a CPFHub.io. A resposta volta pelo mesmo caminho.

## Configuração com Nginx

### Nginx como proxy reverso

```nginx
upstream cpfhub_api {
 server api.cpfhub.io:443;
 keepalive 10;
}

server {
 listen 8080;
 server_name cpf-proxy.interno.empresa.com;

 # Acesso restrito à rede interna
 allow 10.0.0.0/8;
 allow 172.16.0.0/12;
 allow 192.168.0.0/16;
 deny all;

 # Logs detalhados
 access_log /var/log/nginx/cpf_proxy_access.log;
 error_log /var/log/nginx/cpf_proxy_error.log;

 location /cpf/ {
 # Rate limit interno: 10 req/seg por IP
 limit_req zone=cpf_limit burst=5 nodelay;

 proxy_pass https://api.cpfhub.io/cpf/;
 proxy_ssl_server_name on;

 # Adicionar API key (centralizada no proxy)
 proxy_set_header x-api-key "SUA_CHAVE_DE_API";
 proxy_set_header Accept "application/json";
 proxy_set_header Host api.cpfhub.io;

 # Remover headers que não devem vazar
 proxy_hide_header x-api-key;

 # Timeouts
 proxy_connect_timeout 10s;
 proxy_read_timeout 20s;
 proxy_send_timeout 10s;

 # Cache de respostas
 proxy_cache cpf_cache;
 proxy_cache_valid 200 30m;
 proxy_cache_valid 404 5m;
 proxy_cache_key $uri;
 }
}

# Zona de rate limit
limit_req_zone $binary_remote_addr zone=cpf_limit:10m rate=10r/s;

# Configuração de cache
proxy_cache_path /var/cache/nginx/cpf levels=1:2 keys_zone=cpf_cache:10m
 max_size=100m inactive=30m use_temp_path=off;
```

### Uso pelas aplicações internas

```bash
# As aplicações chamam o proxy interno (sem API key)
curl -X GET http://cpf-proxy.interno.empresa.com:8080/cpf/12345678900 \
 -H "Accept: application/json" \
 --max-time 15
```

## Configuração com Node.js (Express)

Para maior flexibilidade, use um proxy em Node.js:

```javascript
const express = require('express');
const app = express();

const API_KEY = process.env.CPFHUB_API_KEY;

// Middleware de autenticação interna
function autenticarCliente(req, res, next) {
 const token = req.headers['x-internal-token'];
 const tokensValidos = process.env.INTERNAL_TOKENS?.split(',') || [];

 if (!tokensValidos.includes(token)) {
 return res.status(403).json({ error: 'Acesso negado' });
 }

 next();
}

// Middleware de logging
function logConsulta(req, res, next) {
 const inicio = performance.now();

 res.on('finish', () => {
 const duracao = performance.now() - inicio;
 console.log(JSON.stringify({
 timestamp: new Date().toISOString(),
 ip: req.ip,
 cpf: req.params.cpf,
 status: res.statusCode,
 duracao_ms: Math.round(duracao),
 cliente: req.headers['x-client-name'] || 'desconhecido'
 }));
 });

 next();
}

// Cache simples em memória
const cache = new Map();
const CACHE_TTL = 30 * 60 * 1000; // 30 minutos

app.get('/cpf/:cpf', autenticarCliente, logConsulta, async (req, res) => {
 const { cpf } = req.params;

 // Verificar cache
 const cached = cache.get(cpf);
 if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
 return res.json({ ...cached.data, _cache: true });
 }

 try {
 const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
 method: 'GET',
 headers: {
 'x-api-key': API_KEY,
 'Accept': 'application/json'
 },
 signal: AbortSignal.timeout(15000)
 });

 const data = await response.json();

 // Cachear respostas de sucesso
 if (response.ok) {
 cache.set(cpf, { data, timestamp: Date.now() });
 }

 res.status(response.status).json(data);

 } catch (error) {
 res.status(502).json({
 error: 'Erro ao consultar API externa',
 detalhes: error.message
 });
 }
});

app.listen(8080, () => {
 console.log('Proxy CPF rodando na porta 8080');
});
```

## Controle de cota por equipe

Distribua a cota entre diferentes equipes ou aplicações:

```javascript
const cotas = {
 'equipe-onboarding': { limite: 500, consumido: 0 },
 'equipe-credito': { limite: 300, consumido: 0 },
 'equipe-compliance': { limite: 200, consumido: 0 }
};

function verificarCota(req, res, next) {
 const equipe = req.headers['x-client-name'];

 if (!cotas[equipe]) {
 return res.status(403).json({ error: 'Equipe não cadastrada' });
 }

 if (cotas[equipe].consumido >= cotas[equipe].limite) {
 return res.status(429).json({
 error: 'Cota da equipe esgotada',
 consumido: cotas[equipe].consumido,
 limite: cotas[equipe].limite
 });
 }

 cotas[equipe].consumido++;
 next();
}

// Resetar cotas no início de cada mês
const cron = require('node-cron');
cron.schedule('0 0 1 * *', () => {
 for (const equipe of Object.keys(cotas)) {
 cotas[equipe].consumido = 0;
 }
 console.log('Cotas resetadas');
});
```

## Segurança adicional

### Criptografia em trânsito

Garanta que o proxy use HTTPS tanto na entrada (aplicações internas) quanto na saída (API externa).

### Máscara de dados nos logs

```javascript
function mascararCPF(cpf) {
 return cpf.substring(0, 3) + '.***.***-' + cpf.substring(9);
}

// No log: 123.***.***-00 em vez do CPF completo
```

### Firewall rules

* Permitir saída do proxy apenas para `api.cpfhub.io:443`.

* Permitir entrada no proxy apenas da rede interna.

* Bloquear todo outro tráfego.

## Monitoramento do proxy

* **Latência do proxy** — Tempo adicionado pelo proxy (deve ser mínimo, abaixo de 10ms).

* **Cache hit rate** — Percentual de respostas servidas do cache.

* **Distribuição de cota** — Consumo por equipe.

* **Erros 502/504** — Problemas de comunicação com a API externa.

## Perguntas frequentes

### Por que centralizar a chave de API no proxy em vez de distribuir por aplicação?

Distribuir a `x-api-key` entre múltiplas aplicações aumenta o risco de vazamento (repositórios, logs, variáveis de ambiente mal configuradas). Centralizando no proxy, apenas uma instância conhece a chave. Todas as aplicações internas se autenticam com tokens internos, que podem ser revogados individualmente sem afetar a integração com a CPFHub.io.

### O proxy reverso aumenta a latência das consultas de CPF?

O overhead do proxy é mínimo — geralmente abaixo de 10ms. Para consultas em cache, a resposta é ainda mais rápida, pois não há requisição à API externa. A latência total para o cliente interno fica em torno de 910ms na primeira consulta e próxima de zero nas consultas subsequentes ao mesmo CPF dentro da janela de cache de 30 minutos.

### Como garantir que o proxy não vire um ponto único de falha?

Configure o proxy com redundância: duas instâncias atrás de um load balancer interno, com health checks automáticos. Para o Nginx, use o bloco `upstream` com múltiplos servidores e a diretiva `fail_timeout`. Para o proxy em Node.js, implemente um circuit breaker que responde com erro 503 quando a API externa está indisponível, evitando cascata de falhas.

### Qual é o custo da API CPFHub.io para ambientes corporativos com múltiplas equipes?

O plano Pro cobre 1.000 consultas/mês por R$149. Para volumes corporativos maiores, o plano Corporativo é personalizado. Em ambos os casos, ao atingir o limite, a API não bloqueia — cada consulta excedente é cobrada a R$0,15. O controle de cota por equipe no proxy permite distribuir e monitorar o consumo internamente antes de atingir o limite do plano.

### Leia também

- [SLA de API de CPF: níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [Guia completo para integração de APIs de CPF em fintechs](https://cpfhub.io/blog/guia-completo-para-integracao-de-apis-de-cpf-em-fintechs)
- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [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

Um proxy reverso é a solução ideal para ambientes corporativos que precisam de controle centralizado sobre consultas de CPF. Com cache, rate limiting interno, auditoria e distribuição de cota por equipe, você garante segurança, eficiência e conformidade com as políticas da organização — sem expor a chave de API e sem criar dependências diretas entre cada aplicação e a API externa.

A [**CPFHub.io**](https://www.cpfhub.io/) oferece 50 consultas gratuitas por mês para você testar a integração via proxy antes de qualquer contratação. Quando estiver pronto para produção, o plano Pro e o plano Corporativo acompanham o crescimento da sua operação. [Crie sua conta gratuita em cpfhub.io](https://www.cpfhub.io/) e comece a configurar seu proxy hoje.