src/config/env.ts

Versão: 1.0
 Última atualização: 26 de agosto de 2025
 Responsável: Ariel Spencer & Fabrício Bahiense

📋 Descrição

O que faz?

Centraliza a configuração e validação de todas as variáveis de ambiente da aplicação, garantindo que valores obrigatórios estejam definidos em produção e fornecendo valores padrão quando apropriado.

Por que existe?

Padroniza o acesso às configurações de ambiente, valida dependências críticas do sistema e evita erros de configuração em produção, mantendo a aplicação segura e funcional.

Como funciona?

Carrega variáveis de ambiente pelo .env, válida variáveis obrigatórias apenas em produção (pula em desenvolvimento), e exporta um objeto tipado com todas as configurações da aplicação.

🔧 Documentação Técnica

Arquitetura

.env file → dotenv.config() → validateEnvVariables() → env object

↓

Aplicação usa env.VARIAVEL

Tecnologias Utilizadas

Configuração: dotenv
Runtime: Node.js com TypeScript
Validação: Custom validation function

Estrutura de Pastas

backend/                 
				  # Projeto
└── src/                  # Source
        └── config/         # Configurações
                └── env.ts 
				         # Variáveis de ambiente

Configuração

Variáveis de Ambiente Obrigatórias (Produção)

# Banco de Dados
DB_URI=mongodb://[user]:[password]@[host]:[port]/[database]
# Servidor
PORT=3001
# Autenticação JWT
JWT_NONCE=seu_jwt_secret_key_aqui
JWT_NONCE_ADMIN=seu_jwt_admin_secret_key_aqui
# Email
RESEND_API_KEY=re_seu_resend_api_key
# AWS Pinpoint
PINPOINT_ACCESS_KEY_ID=sua_aws_access_key
PINPOINT_SECRET_ACCESS_KEY=sua_aws_secret_key
# Redis
REDIS_URL=redis://localhost
REDIS_PORT=6379

Variáveis Opcionais/Comentadas

# SMS Services
TWILIO_ACCOUNT_SID=seu_twilio_sid
TWILIO_AUTH_TOKEN=seu_twilio_token
ZENVIA_API_TOKEN=seu_zenvia_token
SMS_DEFAULT_CALLBACK_URL=https://seu-dominio.com/callback

# Action Voice
ACTION_VOICE_API_URL=https://interfacebr2-inst.actionvoicesms.com.br
ACTION_VOICE_ACCOUNT=sua_conta
ACTION_VOICE_CODE=seu_codigo

# D7Networks
D7_API_TOKEN=seu_d7_token
D7_API_URL=https://api.d7networks.com/messages/v1
D7_ORIGINATOR=SignOTP
D7_CALLBACK_URL=https://seu-dominio.com/d7-callback

# Infobip
INFOBIP_API_KEY=seu_infobip_key
INFOBIP_API_KEY_BET=seu_infobip_bet_key
INFOBIP_API_URL=https://api.infobip.com
INFOBIP_API_URL_BET=https://bet.api.infobip.com
INFOBIP_FROM=SeuSender
INFOBIP_CALLBACK_URL=https://seu-dominio.com/infobip-callback

# Redis
REDIS_PASSWORD=sua_redis_password

Como usar

import { env } from './config/env'

// Acessar configurações
const dbUri =
				env.DBURI
const jwtSecret = env.JWT_NONCE
const port =
				env.PORT

📦 Dependências

Dependências Principais

Pacote	Versão	Finalidade
dotenv	^16.4.5	Carregamento de variáveis .env

Serviços Externos

Serviço	Finalidade	Documentação
MongoDB	Banco de dados	MongoDB Docs
JWT	Autenticação	JWT.io
Resend	Envio de emails	Resend Docs
AWS Pinpoint	Notificações	AWS Pinpoint
Redis	Cache/Sessions	Redis Docs
Twilio	SMS	Twilio Docs
Zenvia	SMS Brasil	Zenvia API
D7Networks	SMS Internacional	D7Networks
Infobip	SMS/Communications	Infobip Docs
Action Voice	SMS Brasil	Action Voice

🧪 Validação

Comportamento por Ambiente

Development: Pula validação (permite valores em branco)
Production/Test: Valida todas as variáveis obrigatórias

Variáveis com Valores Padrão

PORT: 3001 // Porta padrão

REDIS_URL: 'localhost' // Redis local

REDIS_PORT: 6379 // Porta padrão Redis

ACTION_VOICE_API_URL: '...' // URL padrão da API

🐛 Troubleshooting

Problemas Comuns

Missing required environment variables

Sintomas: ENV: Missing required environment variables: [lista]
Causa: Variáveis obrigatórias não definidas
				em produção
Solução: Definir todas as variáveis listadas no arquivo
				.env

Valores '_unset' em runtime

Sintomas: Aplicação usa valores '_unset'
Causa: Variável não definida no ambiente
Solução: Verificar se a variável está no .env e se
				dotenv.config() foi chamado

Configuração não funciona em development

Sintomas: Valores não carregam em dev
Causa: Arquivo .env ausente ou mal configurado
Solução: Criar .env baseado no .env.example

📚 Referências e Links Úteis

Última revisão: 26 de agosto de 2025 por Ariel Spencer