SMS API integracja REST — przewodnik dla programistów 2026

Krok-po-kroku integracja SMS API w 30 minut — REST endpoints, Bearer auth, webhook callbacks, biblioteki PHP/Node.js/Python, error handling, retry logic, two-way SMS, sandbox testing. Code examples gotowe do produkcji.

Pierwszy request — quickstart

Poniższy przykład pokazuje schemat żądania. Dokładny adres endpointu, nazwy pól i sposób autoryzacji zależą od dostawcy - adres endpointu i klucz API otrzymujesz razem z dostępem do bramki; dokumentację API przekazujemy przy wdrożeniu.

# 1. Test endpoint (curl)
curl -X POST https://<endpoint-z-dokumentacji>/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "+48500600700",
    "message": "Witaj! Test SMS API.",
    "from": "GMWEB",
    "webhookUrl": "https://yourapp.com/webhook"
  }'

# Response 200 OK
{
  "messageId": "msg_01HZ8X9YR2N3K4L5M6P7Q8R9S0",
  "status": "queued",
  "estimatedDelivery": "2026-04-30T10:00:05Z",
  "cost": { "currency": "PLN", "value": 0 }
}

# Webhook callback (po dostarczeniu)
POST https://yourapp.com/webhook
{
  "messageId": "msg_01HZ8X9YR2N3K4L5M6P7Q8R9S0",
  "status": "delivered",
  "deliveredAt": "2026-04-30T10:00:03.245Z",
  "operator": "Plus"
}

Node.js — produkcyjny przykład

// Node.js — produkcyjny przykład (bez dedykowanego SDK, zwykły fetch)
import { randomUUID } from 'crypto'

const API_URL = process.env.SMS_API_URL! // adres endpointu z dokumentacji dostawcy
const API_KEY = process.env.SMS_API_KEY!

async function sendAppointmentReminder(phone: string, when: Date) {
  const res = await fetch(API_URL + '/sms', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: phone,
      message: 'Przypominamy: wizyta jutro ' + when.toLocaleTimeString() +
        '. Odpowiedz TAK aby potwierdzić, NIE aby anulować.',
      idempotencyKey: randomUUID(),
      webhookUrl: process.env.APP_URL + '/webhooks/sms',
    }),
  })

  if (res.status === 429) {
    // Retry z exponential backoff
    await new Promise(r => setTimeout(r, 2000))
    return sendAppointmentReminder(phone, when)
  }
  if (!res.ok) throw new Error('SMS API error: ' + res.status)

  const result = await res.json()
  return result.messageId
}

// Webhook handler (Express)
app.post('/webhooks/sms', (req, res) => {
  const sig = req.headers['x-sms-signature'] // nazwa nagłówka zależy od dostawcy
  // Weryfikację podpisu zaimplementuj zgodnie z dokumentacją dostawcy
  if (!verifySignature(req.rawBody, sig, process.env.SMS_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature')
  }
  const { messageId, status, deliveredAt } = req.body
  // Update DB...
  res.status(200).send('OK')
})

Endpoints API — podstawy

Poniższa tabela to typowy schemat REST API bramki SMS - pokazuje, jakie operacje zwykle znajdziesz w API. Dokładne ścieżki, nazwy pól i dostępność metod zależą od dostawcy; aktualną listę endpointów znajdziesz w dokumentacji API, którą przekazujemy przy wdrożeniu.

Webhook security — weryfikacja podpisu

Nie każda bramka podpisuje webhooki. Sprawdź w dokumentacji dostawcy, czy webhooki są podpisywane i jakim algorytmem (np. HMAC-SHA256), a także pod jaką nazwą nagłówka przychodzi podpis. Jeśli tak - zweryfikuj podpis przed przetworzeniem żądania.

// PHP — weryfikacja podpisu webhooka (gdy dostawca podpisuje payload)
$secret = $_ENV['SMS_WEBHOOK_SECRET'];                 // sekret od dostawcy
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SMS_SIGNATURE'] ?? '';   // nazwa nagłówka z dokumentacji

$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Process: $data['messageId'], $data['status']

Error codes — co robić

FAQ

Powiązane artykuły