Recharge API

القواعد الأساسية

• كل endpoints تتطلب client_id في الهيدر ما عدا /docs.
• إنشاء طلب: POST /recharge يتطلب idempotency_key + operator + msisdn + amount.
• operator يجب أن يكون فقط mtn أو syriatel.
• idempotency_key يمنع تكرار الطلب. تكرار نفس القيمة لنفس client_id يعيد نفس النتيجة.
• صيغة msisdn المقبولة: 09XXXXXXXX أو XXXXXXXXX (9 أرقام) أو XXXXXXXX (8 أرقام).
• أمثلة مطابقة الشبكة: mtn مع 10 أرقام يبدأ بـ 094/095/096، و9 أرقام تعتبر MTN حسب القاعدة الحالية. syriatel مع 10 أرقام يبدأ بـ 093/098/099، و8 أرقام تعتبر Syriatel حسب القاعدة الحالية.
• إذا كان الرقم لا يدل على نفس operator المرسل، يعيد API الخطأ OPERATOR_MISMATCH.

عرض الباقات

curl -s "${BASE_URL}/packages"   -H "client_id: ${CLIENT_ID}"

{
  "ok": true,
  "packages": [
    { "$id": "...", "network_id": "SYR", "name": "...", "value": 5000 }
  ]
}

عرض الرصيد

curl -s "${BASE_URL}/balance"   -H "client_id: ${CLIENT_ID}"

{ "ok": true, "available": 120000 }

إنشاء طلب تعبئة

# Required body: idempotency_key + operator + msisdn + amount
curl -s -X POST "${BASE_URL}/recharge"   -H "Content-Type: application/json"   -H "client_id: ${CLIENT_ID}"   -d '{
    "idempotency_key": "req-2026-04-04-0002",
    "operator": "mtn",
    "msisdn": "0940000000",
    "amount": 5000
  }'

# Example (MTN)
{
  "idempotency_key": "req-mtn-001",
  "operator": "mtn",
  "msisdn": "0941234567",
  "amount": 5000
}

# Example (Syriatel)
{
  "idempotency_key": "req-syr-001",
  "operator": "syriatel",
  "msisdn": "0931234567",
  "amount": 5000
}

# Example (9 digits -> MTN by current rule)
{
  "idempotency_key": "req-9digits-001",
  "operator": "mtn",
  "msisdn": "412345678",
  "amount": 5000
}

# Example (8 digits -> Syriatel by current rule)
{
  "idempotency_key": "req-8digits-001",
  "operator": "syriatel",
  "msisdn": "12345678",
  "amount": 5000
}

{
  "ok": true,
  "request": { "id": "DOCUMENT_ID", "status": "pending" }
}

عرض الطلبات

curl -s "${BASE_URL}/requests/[${ID1},${ID2},${ID3}]"   -H "client_id: ${CLIENT_ID}"

{
  "ok": true,
  "requests": [ { "id": "...", "status": "processing" } ],
  "missing": [ "..." ]
}

حالات الطلب (Status)

أكواد أخطاء مهمة

• MISSING_CLIENT_ID: لم يتم إرسال client_id.
• UNKNOWN_CLIENT: client_id غير موجود في جدول accounts.
• SUSPENDED / NOT_ALLOWED: الحساب موقوف أو غير مسموح له بالشحن.
• INVALID_PHONE: رقم الهاتف غير صالح.
• INVALID_OPERATOR: operator يجب أن يكون mtn أو syriatel.
• OPERATOR_MISMATCH: شبكة الرقم لا تطابق operator المرسل.
• INSUFFICIENT_BALANCE: رصيد غير كاف (بدون overdraft).