API referansı

Başlarken

Yeni bir hesap ile iletilen bir mesaj arasında üç şey vardır: bir belirteç, biraz bakiye ve bir anahtar. Hiçbiri bir insan içermez.

1. Hesap oluşturun — belirteci tarayıcınız üretir ve hesap bu belirtecin kendisidir.
2. Fonlayın. $40 minimum, ödemeler sayfası üzerindeki kripto paralardan herhangi biriyle.
3. Panelde bir API anahtarı oluşturun. Yalnızca bir kez gösterilir; tıpkı belirteçte olduğu gibi yalnızca karmasını (hash) saklarız.

Kimlik doğrulama

Her istekte taşıyıcı (bearer) belirteç. Anahtar hesabı tanımlar; ikinci bir doğrulama faktörü yoktur, istek üzerinde imza yoktur ve IP izin listesi yoktur — anahtar kimlik bilgisinin tamamıdır, bu yüzden ona öyle davranın.

Authorization: Bearer ws_live_9f2c…

Mesaj gönderin

POST/v1/messages

Tek çağrı, bir veya birçok alıcı, karışık hedefler. Her alıcı kendi hedefinin oranına göre fiyatlandırılır ve segment başına faturalandırılır. Çağrı bir bütün olarak kabul edilir veya reddedilir; sizi hiçbir zaman kısmen ücretlendirmez.

İstek gövdesi

Örnek

# one call, many recipients, mixed destinations
curl -X POST https://api.worldsms.io/v1/messages \
  -H "Authorization: Bearer $WORLDSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "ACME",
    "to":   ["+447700900123", "+33612345678"],
    "text": "Your code is 480913"
  }'

{
  "batch_id": "b_7Kq2xR9wLm",
  "accepted": 2,
  "rejected": 0,
  "segments": 1,
  "cost_usd": 0.0353
}

Toplu işleme

Bir toplu gönderim hemen kabul edilir ve hesap başına dakikada 200 mesaj hızında akar, yani 50.000 alıcı yaklaşık 4 sa 10 dk sürer. Zamana duyarlı trafik bir pazarlama gönderiminin arkasında kuyruğa girmemelidir: bunun için ayrı bir anahtar kullanın.

Mesaj durumu

GET/v1/messages/{batch_id}

Sorgulama desteklenir ve hız sınırlıdır; web kancaları amaçlanan yoldur. Yanıt, toplu işi özetler ve alıcı başına durumu listeler.

{
  "batch_id":    "b_7Kq2xR9wLm",
  "status":      "done",
  "sending":     0,
  "delivered":   1,
  "undelivered": 1,
  "refund_usd":  0.0216
}

refund_usd, toplu gönderim tamamlandığında bir kez kesinleşir. Siz onu okuyabildiğinizde zaten bakiyenize geri dönmüştür.

Bakiye

GET/v1/balance

Büyük bir gönderimden önce kontrol edin. Bakiyeler dahili olarak tam sayı mikro-dolar cinsinden tutulur — fiyatlar dört ondalık basamağa kadar gider ve bir ondalıklı sayının (float) hesap hareketlerinde işi yoktur — ve burada altı basamağa yuvarlanarak döndürülür.

{ "balance_usd": 412.905400, "currency": "USD" }

Teslim raporları

Operatör bildirdikçe alıcı başına bir makbuz yayımlanır. Bunlar sadece dört durumdur; sessizce "onu kaybettik" anlamına gelen bir "bilinmiyor" kutusu yoktur.

Fiyatlandırılmış bir hedefe hiç karşılık gelmeyen numaralar gönderim sırasında reddedilir ve bu yaşam döngüsüne hiç girmez — önce faturalandırılıp sonra iade edilmezler, basitçe faturalandırılmazlar.

Webhook'lar

Panelde veya toplu iş başına callback_url ile bir uç nokta ayarlayın. JSON POST ediyoruz ve 5 saniye içinde bir 2xx bekliyoruz. 2xx olmayan yanıtlar, yaklaşık bir saat boyunca üstel geri çekilmeyle altı kez yeniden denenir, ardından bırakılır.

Veri yükü

{
  "event":     "message.delivered",
  "batch_id":  "b_7Kq2xR9wLm",
  "to":        "+447700900123",
  "destination": "gb",
  "segments":  1,
  "cost_usd":  0.0137,
  "reference": "order-4471",
  "ts":        1785312041
}

İmza doğrulanıyor

Her teslimat X-WorldSMS-Signature ve X-WorldSMS-Timestamp taşır. İmza, webhook gizli anahtarınızı kullanan HMAC-SHA256(timestamp + "." + body)'dur. Sabit zamanda karşılaştırın ve beş dakikadan eski bir zaman damgasını reddedin, böylece yakalanmış bir teslimat size karşı tekrar oynatılamaz.

// $secret is the webhook secret from the dashboard
$raw  = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_WORLDSMS_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_WORLDSMS_SIGNATURE'] ?? '';

// A stale timestamp is a replay, however well it is signed.
if (abs(time() - (int) $ts) > 300) { http_response_code(408); exit; }

$mine = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($mine, $sig)) { http_response_code(401); exit; }

http_response_code(204);

Hatalar

Her başarısızlık, sabit bir error slug'ı içeren bir JSON gövdesi döndürür. Slug üzerinden eşleştirin, metin üzerinden asla — metnin iyileşmesine izin verilir.

{
  "error":       "insufficient_credit",
  "message":     "Batch costs $84.20, balance is $12.05.",
  "required_usd": 84.20,
  "balance_usd":  12.05
}

Limitler

Hız sınırları API çağrılarına uygulanır, mesajlara değil: 5.000 alıcı taşıyan tek bir çağrı, sınıra karşı yalnızca bir istek olarak sayılır.