Deployment

Provisionamento via AWS CDK e variáveis de ambiente.

---

Stack CDK

Arquivo: infra/whatsapp-bot-stack.ts

Recurso	Descrição
BotFunction	NodejsFunction ARM64, Node.js 20, 256MB, timeout 30s, tracing X-Ray
BotLogGroup	/aws/lambda/contrasync-whatsapp-bot-{stage} retenção 7 dias
BotHttpApi	API Gateway HTTP API com rotas /webhook e /health
BotErrorsAlarm	Alarm CloudWatch quando Lambda errors ≥ 3 em 5 min
BotThrottlesAlarm	Alarm quando Lambda throttles ≥ 1 em 5 min

Outputs:

Output	Descrição
BotApiUrl	URL base do API Gateway (configurar no painel Z-API)
BotFunctionName	Nome do Lambda

Tags: service=contrasync-whatsapp-bot, stage={dev|prod}.

---

Bundling

NodejsFunction com esbuild:

• format: CJS
• minify: true
• sourceMap: true + NODE_OPTIONS: --enable-source-maps
• target: node20
• externalModules: ['@aws-sdk/*']

---

Removal Policy

Stage	BotLogGroup
dev	DESTROY
prod	RETAIN

---

Variáveis de Ambiente

Nome	Obrigatória em prod?	Default	Descrição
STAGE	sim		dev / prod
NODE_OPTIONS	sim	--enable-source-maps	Source maps em runtime
ZAPI_INSTANCE_ID	sim	''	ID da instância Z-API
ZAPI_TOKEN	sim	''	Token da instância
ZAPI_CLIENT_TOKEN	sim	''	Client-Token do Account Security
ZAPI_BASE_URL	não	https://api.z-api.io	Base URL do Z-API
CONTRASYNC_API_URL	sim	''	URL da API NestJS (ex.: https://api.contrasync.com)
BOT_API_KEY	sim	''	Shared secret enviado no header x-bot-api-key; precisa bater com o BOT_API_KEY do nest-api

resolveRequiredEnv() falha o cdk synth/deploy se alguma dessas estiver vazia em prod.

Gerando BOT_API_KEY

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Use o mesmo valor nos dois projetos (whatsapp-bot e nest-api). Em prod, gerencie via Secrets Manager, nunca commite.

---

Pipeline Local

npm install
cp .env.example .env
# preencher ZAPI_*, CONTRASYNC_API_URL e BOT_API_KEY

npm run build        # tsc --noEmit
npm run test         # vitest run + coverage 100%
npm run cdk:synth    # valida CDK + bundling

npm run cdk:diff     # diff contra o stack
npm run cdk:deploy   # deploy

---

Dev Server Local

Para testar o handler localmente apontando para uma API NestJS rodando em localhost:8011:

npm run dev        # sobe HTTP em http://localhost:3001

O scripts/dev-server.ts envelopa o handler em um servidor HTTP simples (sem AWS SAM, sem Docker). Cada request vira um APIGatewayProxyEventV2 antes de chamar o handler.

Para o Z-API entregar mensagens reais no dev server, tunele com ngrok:

ngrok http 3001
# configurar webhook do Z-API em https://abc123.ngrok.io/webhook

---

Configuração Pós-Deploy

1. Pegue o output BotApiUrl do cdk deploy
2. No painel Z-API, configure o webhook "ao receber mensagem" apontando para {BotApiUrl}/webhook
3. Configure BOT_API_KEY no Secrets Manager / .env da nest-api com o mesmo valor do Lambda
4. Smoke test: curl {BotApiUrl}/health deve retornar {"status":"ok","service":"contrasync-whatsapp-bot"}

---

Documento atualizado em Maio 2026