SMSGo + NestJS — Exemplo oficial

Exemplo completo de integração da SMSGo com NestJS: módulo, serviço de OTP, controller de webhook assinado e testes com chave test_.

O que este exemplo demonstra

• Configuração do cliente SMSGo via módulo NestJS com injeção de dependência.
• Geração e validação de código OTP de 6 dígitos com TTL de 5 minutos no Redis.
• Envio de SMS OTP através de serviço encapsulado.
• Recebimento de webhooks de entrega (DLR) assinados com HMAC-SHA256.
• Testes e2e com chave de teste, sem gastar créditos reais.

Estrutura do exemplo

smsgo-nestjs-example/
├── src/
│   ├── smsgo/
│   │   ├── smsgo.module.ts            # Registra o cliente SMSGo
│   │   ├── smsgo.service.ts           # Cliente encapsulado
│   │   ├── smsgo_otp.service.ts       # Lógica de OTP
│   │   └── smsgo_webhook.controller.ts # Recebe DLR assinado
│   ├── otp/
│   │   ├── otp.controller.ts          # POST /otp/request e /otp/verify
│   │   ├── otp.service.ts             # Gera e valida código com Redis
│   │   └── otp.module.ts
│   ├── app.module.ts
│   └── main.ts
├── test/
│   ├── otp.e2e-spec.ts
│   └── jest-e2e.json
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── .env.example
├── .github/workflows/ci.yml
└── LICENSE

Instalação

npm install

Configure o .env:

SMSGO_KEY="test_sua_chave_aqui"
SMSGO_WEBHOOK_SECRET="whsec_..."
REDIS_URL="redis://localhost:6379"

Inicie o Redis localmente (ou use Docker):

docker run -d -p 6379:6379 redis:7-alpine

Como funciona

1. O usuário solicita OTP via POST /otp/request informando o telefone.
2. O OtpService gera um código de 6 dígitos e armazena no Redis com TTL de 5 minutos.
3. O SmsgoOtpService envia o SMS usando o cliente SMSGo injetado.
4. A SMSGo entrega o status de entrega (DLR) via POST /webhooks/smsgo, assinado com HMAC-SHA256.

Endpoints

Método	Rota	Descrição
POST	/otp/request	Solicita envio de OTP
POST	/otp/verify	Verifica código de OTP
POST	/webhooks/smsgo	Recebe callback de status da SMSGo

Exemplos de requisição

# Solicitar OTP
curl -X POST http://localhost:3000/otp/request \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999990000"}'

# Verificar OTP
curl -X POST http://localhost:3000/otp/verify \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999990000","code":"123456"}'

Testes

npm test
npm run test:e2e

Documentação

• SDK Node.js: https://github.com/sms-go/smsgo-sdk-nodejs
• API completa: https://smsgo.apidog.io
• Painel SMSGo: https://smsgo.com.br

Licença

MIT © SMSGo