Download the PHP package orynlabs/smsgo without Composer

orynlabs/smsgo

SDK oficial PHP para a SMSGo — a API de SMS simples para o Brasil. Envie OTP/2FA, alertas transacionais e campanhas com poucas linhas de código.

• ⚡ Integra em minutos — autenticação cuidada pra você (sem ritual de token manual).
• 💸 Sem mensalidade — créditos pré-pagos que não expiram, preço em real.
• 🇧🇷 Brasil-first — entrega para todas as operadoras, LGPD nativo.
• 🟢 Zero dependências — só ext-json + ext-curl. Tipado com DTOs readonly.
• 🎁 R$ 10 grátis ao criar a conta — dá pra testar sem cartão.

Nova conta e chave em smsgo.com.br → painel → Minha conta → API.

Requisitos

• PHP 8.1+
• Extensões ext-json e ext-curl

Instalação

Começo rápido

Você passa só a apiKey. O SDK troca a chave por um token Bearer (válido 48h), guarda em cache e renova sozinho quando expira (ou no primeiro 401).

O construtor aceita opções:

Enviar um OTP (2FA)

Envio em massa

Consultar envios

Modo de teste (sandbox)

Use a chave de teste (prefixo test_, no painel → Minha conta → API) como apiKey. Nada muda no código: os envios não debitam saldo nem são despachados de verdade, as respostas são idênticas às de produção (com test: true) e os webhooks disparam com o mesmo flag.

Saldo e catálogo

Comprar créditos (off-session)

Cobra um cartão salvo sem abrir o painel (o cartão é cadastrado no painel via Stripe; a API só cobra um já salvo).

Idempotência: cada purchase gera uma cobrança nova. Em timeout, consulte billing->invoices() antes de repetir — não faça retry cego. O endpoint tem rate-limit estrito (6/min).

Recarga automática + alerta de saldo

Webhooks de saída (DLR + respostas)

Cada requisição traz X-SMSGo-Signature: sha256=<hmac> — o HMAC-SHA256 do corpo bruto com o seu secret. Valide sempre com o helper Webhook::verifySignature() (comparação em tempo constante):

Veja examples/receive-dlr-webhook.php para o handler completo.

Contatos e listas

Tratamento de erros

Toda resposta não-2xx vira um SMSGoError com status e um code estável:

Em falhas de validação (422), $e->errors traz o detalhe por campo (list<array{field, message}>). Falhas de rede/transporte viram SMSGoError com status = 0 e code = 'network_error'.

Referência da API

new Client(string $apiKey, array $options = [])

Métodos

SMS

• send(phone, message, schedule?, reference?, from?, smsTypeId?) → SendResult
• sendBulk(messages, urlCallback?, flashSms?, smsTypeId?) → SendResult
• list(page = 1) → Paginated<SendListItem>
• get(id) → SendDetail (com summary)
• getNumbers(id, status?, page?) → Paginated<SendNumberItem> (status: delivered · failed · in_progress)
• getSmsTypes() → list<SmsTypeItem>

Conta

• getBalance() → Balance
• getAutoRecharge() / setAutoRecharge(...) → AutoRechargeConfig
• getWebhook() / setWebhook(url?, rotateSecret?) → WebhookConfig
• mode() → 'live' | 'test' | null · resolveMode() → 'live' | 'test'

Faturamento ($client->billing)

• plans() → list<Plan> · cards() → list<Card> · invoices(page?, perPage?) → Paginated<InvoiceItem>
• purchase(quantity?, planId?, cardId?, coupon?) → PurchaseResult

Contatos ($client->contacts)

• list(page, perPage?, search?, title?) · create(fullName, phone, email?, lists?) → string (uuid)
• get(id) → ContactDetail · update(id, fullName, phone, email?, lists?) → string · delete(id) → array{message}

Listas ($client->lists)

• list(page, perPage?, title?) · create(name) → ListResult · get(id) → ListResult
• update(id, name) → ListResult · delete(id) → array{message}

Webhook (estático)

• Webhook::verifySignature(rawBody, signatureHeader, secret) → bool

Referência de máquina completa: smsgo.apidog.io — importável no Apidog/Postman.

Exemplos

Na pasta examples/:

• send.php — envio simples
• otp.php — código OTP/2FA
• status.php — envio em massa + consulta de status
• balance.php — saldo + catálogo de tipos de SMS
• buy-credits.php — compra off-session + recarga automática
• configure-webhook.php — configura o webhook de saída
• receive-dlr-webhook.php — recebe callbacks de entrega (DLR) e valida a assinatura

Desenvolvimento

Migrando da TotalVoice / Twilio?

SMSGo foca em DX simples e preço em real. Sem cadastro de remetente pra começar, sem cobrança em dólar, créditos que não expiram. Documentação completa da API: smsgo.apidog.io.

Licença

MIT © SMSGo