SMSGo + AdonisJS — Exemplo oficial

Exemplo completo de integração da SMSGo com AdonisJS: provider, controller de OTP, rota de webhook assinado e testes funcionais com chave test_.

O que este exemplo demonstra

• Configuração do cliente SMSGo via provider no container do AdonisJS.
• 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 do cliente injetado.
• Recebimento de webhooks de entrega (DLR) assinados com HMAC-SHA256.
• Testes funcionais com chave de teste, sem gastar créditos reais.

Estrutura do exemplo

smsgo-adonisjs-example/
├── app/
│   ├── controllers/
│   │   ├── otp_controller.ts      # POST /otp/request e /otp/verify
│   │   └── webhook_controller.ts  # POST /webhooks/smsgo
│   └── exceptions/
│       └── handler.ts
├── config/
│   ├── app.ts
│   └── redis.ts
├── providers/
│   └── smsgo_provider.ts          # Registra o cliente SMSGo no container
├── start/
│   ├── kernel.ts
│   └── routes.ts                  # Rotas públicas
├── tests/
│   └── functional/
│       └── otp.spec.ts            # Testes funcionais
├── bin/
│   ├── server.ts
│   ├── console.ts
│   └── test.ts
├── adonisrc.ts
├── package.json
├── tsconfig.json
├── .env.example
├── .github/workflows/ci.yml
└── LICENSE

Instalação

npm install
cp .env.example .env

Registre o provider em adonisrc.ts:

providers: [
  // ...
  () => import('#providers/smsgo_provider'),
],

Configure o .env:

SMSGO_KEY="test_sua_chave_aqui"
SMSGO_WEBHOOK_SECRET="whsec_..."
REDIS_HOST="localhost"
REDIS_PORT="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 OtpController gera um código de 6 dígitos e armazena no Redis com TTL de 5 minutos.
3. O cliente SMSGo injetado envia o SMS.
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:3333/otp/request \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999990000"}'

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

Testes

npm test

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