SMSGo + Laravel — Exemplo oficial

Exemplo completo de integração da SMSGo com Laravel: service provider, envio de OTP em fila, controller de webhook assinado e testes com chave test_.

O que este exemplo demonstra

• Configuração do cliente SMSGo via Service Provider.
• Geração e validação de código OTP de 6 dígitos com TTL de 5 minutos.
• Envio assíncrono de SMS usando Laravel Queue Jobs.
• Recebimento de webhooks de entrega (DLR) assinados com HMAC-SHA256.
• Testes de feature com chave de teste, sem gastar créditos reais.

Estrutura do exemplo

smsgo-laravel-example/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       ├── OtpController.php      # POST /otp/request e /otp/verify
│   │       └── WebhookController.php  # POST /webhooks/smsgo
│   ├── Jobs/
│   │   └── SendOtpJob.php             # Envio assíncrono em fila
│   └── Providers/
│       └── SmsgoServiceProvider.php   # Registra o cliente SMSGo no container
├── config/services.php                # Configuração smsgo.api_key
├── routes/web.php                     # Rotas públicas
├── tests/Feature/OtpFlowTest.php      # Testes com chave test_
├── composer.json
├── phpunit.xml
├── .env.example
├── .github/workflows/ci.yml
└── LICENSE

Instalação

composer install
cp .env.example .env

Adicione SmsgoServiceProvider em config/app.php (Laravel 10) ou ele será descoberto automaticamente (Laravel 11+):

'providers' => [
    // ...
    App\Providers\SmsgoServiceProvider::class,
],

Configure o .env:

SMSGO_KEY="test_sua_chave_aqui"
SMSGO_WEBHOOK_SECRET="whsec_..."

Como funciona

1. O usuário solicita OTP via POST /otp/request informando o telefone.
2. O controller gera um código de 6 dígitos e despacha o SendOtpJob.
3. O job envia o SMS pelo cliente SMSGo injetado no container.
4. A aplicação armazena o código com TTL no cache para validação posterior.
5. 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:8000/otp/request \
  -H "Content-Type: application/json" \
  -d '{"phone":"+5511999990000"}'

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

Testes

composer test
# ou
vendor/bin/phpunit

Formatação

composer format

Documentação

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

Licença

MIT © SMSGo