Validação de CPF em Docker com variáveis 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.

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

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

// 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:

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

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:

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:

# 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:

docker compose up -d

5. Teste o container

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

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

Resposta esperada da API da CPFHub.io

{
    "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:

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

No docker-compose.yml para Swarm:

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:

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:

# 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 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.

Conclusão

Containerizar aplicações que consomem a API da CPFHub.io

Cadastre-se em cpfhub.io

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver documentação

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.

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