# Como integrar validação de CPF em Docker containers com variáveis de ambiente

> Aprenda a integrar a API de consulta de CPF da CPFHub.io em Docker containers usando variáveis de ambiente e boas práticas de segurança.

**Publicado:** 20/03/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-docker-containers-com-variaveis-de-ambiente

---

Para integrar validação de CPF em Docker containers, passe a chave de API da CPFHub.io via variável de ambiente (`CPFHUB_API_KEY`) no runtime — nunca no Dockerfile. Use `docker run --env-file .env`, Docker Compose ou Docker Secrets para gerenciar credenciais de forma segura. A API responde em ~900ms; configure um timeout de pelo menos 5 segundos na sua aplicação.

O **Docker** é a principal tecnologia de containerização no desenvolvimento moderno. Ao containerizar aplicações que consomem APIs externas, como a validação de CPF, o gerenciamento seguro de chaves de API via variáveis de ambiente segue as boas práticas descritas na [documentação oficial do Docker](https://docs.docker.com/compose/environment-variables/set-environment-variables/).

---

## 1. Aplicação de exemplo com Node.js

Crie uma aplicação Express simples que consome a API da CPFHub.io:

```javascript
// app.js
const express = require('express');
const app = express();

const CPFHUB_BASE_URL = process.env.CPFHUB_BASE_URL || 'https://api.cpfhub.io';
const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY;
const PORT = process.env.PORT || 3000;

if (!CPFHUB_API_KEY) {
 console.error('ERRO: CPFHUB_API_KEY não configurada');
 process.exit(1);
}

app.get('/api/cpf/:cpf', async (req, res) => {
 const cpf = req.params.cpf.replace(/\D/g, '');

 if (cpf.length !== 11) {
 return res.status(400).json({ error: 'CPF deve conter 11 dígitos' });
 }

 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), 5000);

 try {
 const response = await fetch(`${CPFHUB_BASE_URL}/cpf/${cpf}`, {
 method: 'GET',
 headers: {
 'x-api-key': CPFHUB_API_KEY,
 'Accept': 'application/json'
 },
 signal: controller.signal
 });

 clearTimeout(timeoutId);
 const data = await response.json();
 res.json(data);
 } catch (error) {
 clearTimeout(timeoutId);
 res.status(502).json({ error: 'Falha na consulta de CPF' });
 }
});

app.get('/health', (req, res) => {
 res.json({ status: 'ok' });
});

app.listen(PORT, () => {
 console.log(`Servidor rodando na porta ${PORT}`);
});
```

---

## 2. Dockerfile

Crie o `Dockerfile` para containerizar a aplicação:

```dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY app.js ./

# Não definir CPFHUB_API_KEY no Dockerfile
# Passar via variável de ambiente no runtime
ENV CPFHUB_BASE_URL=https://api.cpfhub.io
ENV PORT=3000

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
 CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

USER node

CMD ["node", "app.js"]
```

---

## 3. Passando variáveis de ambiente

### 3.1 Via docker run

```bash
docker build -t cpf-validator .

docker run -d \
 --name cpf-validator \
 -p 3000:3000 \
 -e CPFHUB_API_KEY=SUA_CHAVE_DE_API \
 -e CPFHUB_BASE_URL=https://api.cpfhub.io \
 cpf-validator
```

### 3.2 Via arquivo .env

Crie um arquivo `.env`:

```
CPFHUB_API_KEY=SUA_CHAVE_DE_API
CPFHUB_BASE_URL=https://api.cpfhub.io
PORT=3000
```

Execute com a flag `--env-file`:

```bash
docker run -d \
 --name cpf-validator \
 -p 3000:3000 \
 --env-file .env \
 cpf-validator
```

---

## 4. Docker Compose

Para ambientes com múltiplos serviços, use o Docker Compose:

```yaml
# docker-compose.yml
version: '3.8'

services:
 cpf-validator:
 build: .
 ports:
 - "3000:3000"
 environment:
 - CPFHUB_API_KEY=${CPFHUB_API_KEY}
 - CPFHUB_BASE_URL=https://api.cpfhub.io
 env_file:
 - .env
 restart: unless-stopped
 healthcheck:
 test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
 interval: 30s
 timeout: 5s
 retries: 3
```

Execute com:

```bash
docker compose up -d
```

---

## 5. Teste o container

Após iniciar o container, teste a integração:

```bash
curl -X GET http://localhost:3000/api/cpf/12345678900 \
 -H "Accept: application/json"
```

Resposta esperada da API da [**CPFHub.io**](https://www.cpfhub.io/)

```json
{
 "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
 }
}
```

---

## 6. Docker Secrets para produção

Em ambientes de produção com Docker Swarm, use **Docker Secrets** em vez de variáveis de ambiente:

```bash
# Criar o secret
echo "SUA_CHAVE_DE_API" | docker secret create cpfhub_api_key -
```

No `docker-compose.yml` para Swarm:

```yaml
version: '3.8'

services:
 cpf-validator:
 image: cpf-validator:latest
 ports:
 - "3000:3000"
 secrets:
 - cpfhub_api_key
 environment:
 - CPFHUB_BASE_URL=https://api.cpfhub.io

secrets:
 cpfhub_api_key:
 external: true
```

Na aplicação, leia o secret do filesystem:

```javascript
const fs = require('fs');

const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY
 || fs.readFileSync('/run/secrets/cpfhub_api_key', 'utf8').trim();
```

---

## 7. Multi-stage build para imagem otimizada

Para imagens menores e mais seguras:

```dockerfile
# Stage de build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Stage de runtime
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY app.js ./

ENV CPFHUB_BASE_URL=https://api.cpfhub.io
ENV PORT=3000
EXPOSE 3000

USER node
CMD ["node", "app.js"]
```

---

## 8. Boas práticas

* **Nunca hardcode secrets** -- A chave de API jamais deve estar no Dockerfile ou no código-fonte. Use variáveis de ambiente ou Docker Secrets.

* **Timeout** -- O exemplo usa `AbortController` com 5 segundos de timeout para evitar que a aplicação trave esperando a API.

* **Health check** -- Configure health checks no Docker para reiniciar containers com falhas de conectividade.

* **User não-root** -- Use `USER node` para rodar o container com privilégios mínimos.

* **.dockerignore** -- Adicione `.env`, `node_modules` e arquivos sensíveis ao `.dockerignore`.

* **Logs** -- Use `console.log` estruturado para facilitar monitoramento com ferramentas como ELK ou Datadog.

---

## Perguntas frequentes

### O que é necessário para implementar validação de CPF neste contexto?
A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em ~900ms, permitindo a verificação em tempo real durante o cadastro ou transação.

### A API CPFHub.io funciona para todos os volumes de consulta?
Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

### Como garantir conformidade com a LGPD ao usar uma API de CPF?
Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade.

### Quanto tempo leva para integrar a API CPFHub.io?
A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

### 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 implementar validação de CPF em microsserviços com Docker e Kubernetes](https://cpfhub.io/blog/como-implementar-validacao-cpf-microsservicos-docker-kubernetes)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)

---

## Conclusão

Containerizar aplicações que consomem a API da [**CPFHub.io**](https://www.cpfhub.io/)

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