SMSGo OTP Example — Node.js + Redis

Exemplo completo de fluxo OTP (2FA) com SMSGo, Node.js, Express e Redis: geração de código, envio de SMS, validação e webhook de status assinado.

O que este exemplo demonstra

• Geração segura de código OTP de 6 dígitos.
• Armazenamento do código no Redis com TTL de 5 minutos.
• Envio de SMS via SDK oficial @orynlabs/smsgo.
• Validação de OTP com comparação em tempo constante.
• Recebimento de webhooks de entrega (DLR) assinados com HMAC-SHA256.
• Testes com chave de teste, sem gastar créditos reais.

Estrutura do exemplo

smsgo-otp-example/
├── src/
│   ├── index.ts              # Servidor Express
│   ├── otp.service.ts        # Gera, armazena e valida códigos no Redis
│   ├── sms.service.ts        # Cliente SMSGo encapsulado
│   └── webhook.controller.ts # Recebe e verifica DLR assinado
├── tests/
│   └── otp.test.ts           # Testes com chave test_
├── package.json
├── tsconfig.json
├── .env.example
├── .github/workflows/ci.yml
└── LICENSE

Instalação

npm install
cp .env.example .env

Configure o .env:

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

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 SmsService envia o SMS usando o SDK Node.js.
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

Executar localmente

npm run dev
# ou
npm run build
npm start

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