مرجع API

البدء

ثلاثة أشياء تفصل بين حساب جديد ورسالة مسلَّمة: رمز، وبعض الرصيد، ومفتاح. لا يتدخّل بشر في أيٍّ منها.

1. أنشئ حسابًا — يُنشئ متصفحك الرمز (token)، وهذا الرمز هو الحساب.
2. موّله. الحد الأدنى $40، بأي من العملات المذكورة في صفحة المدفوعات.
3. أنشئ مفتاح API في لوحة التحكم. يُعرض مرة واحدة فقط؛ ونحتفظ بتجزئته فقط، تمامًا كما هو الحال مع الرمز.

المصادقة

رمز حامل (bearer token) في كل طلب. يُعرِّف المفتاح الحساب؛ لا عامل تحقق ثانٍ، لا توقيع على الطلب، ولا قائمة عناوين IP مسموح بها — المفتاح هو بيانات الاعتماد بأكملها، فتعامل معه على هذا الأساس.

Authorization: Bearer ws_live_9f2c…

إرسال الرسائل

POST/v1/messages

استدعاء واحد، مستلم واحد أو عدة مستلمين، وجهات مختلطة. يُسعَّر كل مستلم بسعر وجهته الخاصة ويُحتسب لكل مقطع. يُقبل الاستدعاء أو يُرفض ككل؛ لا يُحاسبك جزئيًا أبدًا.

نص الطلب

مثال

# 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
}

التجميع

تُقبل الدفعة فورًا وتُصرَف بمعدّل 200 رسالة في الدقيقة لكل حساب، فتستغرق 50,000 من المستلمين نحو 4 س 10 د. لا ينبغي أن تنتظر الحركة الحساسة للوقت خلف إرسال تسويقي: استخدم مفتاحًا منفصلًا لها.

حالة الرسالة

GET/v1/messages/{batch_id}

الاستطلاع الدوري مدعوم ومحدود المعدّل؛ أما الويب هوكس فهي المسار المقصود. تجمع الاستجابة الدفعة وتسرد حالة كل مستلم.

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

refund_usd تُسوّى مرة واحدة فقط، عند انتهاء الدفعة. وتكون قد عادت بالفعل إلى رصيدك بحلول الوقت الذي تستطيع فيه قراءتها.

الرصيد

GET/v1/balance

تحقّق قبل أي إرسال كبير. تُحفظ الأرصدة داخليًا بوحدات ميكرودولار صحيحة — تصل الأسعار إلى أربع خانات عشرية، ولا مكان للأعداد العشرية التقريبية (float) في سجل حركات — وتُعرَض هنا مقرَّبة إلى ست خانات.

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

إيصالات التسليم

يُصدَر إيصال لكل مستلم كما يبلّغ عنه المشغّل. هذه هي الحالات الأربع الوحيدة؛ لا توجد فئة «غير معروف» تعني بصمت «فقدناها».

الأرقام التي لا تُطابِق وجهة مُسعَّرة تُرفَض عند الإرسال ولا تدخل هذه الدورة إطلاقًا — لا تُحصَّل ثم تُرَدّ، بل ببساطة لا تُحصَّل.

Webhooks

اضبط نقطة نهاية في لوحة التحكم أو لكل دفعة عبر callback_url. نرسل JSON عبر POST ونتوقع 2xx خلال 5 ثوانٍ. تُعاد محاولة الحالات غير 2xx ست مرات بتراجع أسّي على مدى ساعة تقريبًا، ثم تُسقَط.

الحمولة

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

جارٍ التحقق من التوقيع

يحمل كل تسليم ⁦X-WorldSMS-Signature⁩ و⁦X-WorldSMS-Timestamp⁩. التوقيع هو ⁦HMAC-SHA256⁩(timestamp + "." + body) باستخدام سرّ الويب هوك الخاص بك. قارِنه في زمن ثابت، وارفض أي طابع زمني يتجاوز عمره خمس دقائق حتى لا يُعاد تشغيل تسليم مُعتَرَض ضدّك لاحقًا.

// $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);

الأخطاء

كل فشل يعيد جسم JSON يحتوي على معرّف error ثابت. طابِق على المعرّف لا على النص أبدًا — فالنص قابل للتحسين.

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

الحدود

تُطبَّق حدود المعدّل على طلبات API لا على الرسائل: الطلب الواحد الذي يحمل 5,000 مستلم يُحتسب بطلب واحد ضمن الحد.