Skip to main content
POST
إرسال شحن الهاتف المحمول

نظرة عامة

إرسال شحن هاتف محمول فوري إلى جميع شبكات الهاتف الجزائرية (Mobilis وDjezzy وOoredoo وPixx) مع تتبع الحالة في الوقت الفعلي.
لا تعيد محاولة الطلبات الفاشلة دون التحقق من الحالة أولًا باستخدام check-by-ref أو check-by-id. يمكن أن تتسبب طلبات الإرسال المكررة في خصم مزدوج.

متن الطلب

string
مطلوب
رمز الخطة من list-plans (مثلًا: PREPAID_DJEZZY، MIX1000_OOREDOO)
string
مطلوب
رقم الهاتف المحمول الجزائري بصيغة 0XXXXXXXXX (10 أرقام تبدأ بـ 05، 06، أو 07)
number
مبلغ الشحن بالدينار الجزائري. مطلوب فقط للخطط الديناميكية (حيث min_amount وmax_amount محددان). غير مطلوب للخطط الثابتة.
string
مرجع داخلي فريد (معرّف طلبك). يُستخدم لمنع الطلبات المكررة والتحقق من الحالة لاحقًا.
استخدم ref دائمًا إذا كنت ترسل طلبات من جانب الخادم. يمنع الخصم المزدوج إذا فشل طلب الشبكة.

الاستجابة

boolean
مطلوب
يشير إلى نجاح الطلب
object
مطلوب
object
مطلوب

الأمثلة

خطة ديناميكية (يحدد المبلغ)

خطة ثابتة (لا مبلغ)

مثال على الاستجابة

استجابات الخطأ

إذا تلقيت هذا الخطأ، لا ترسل طلبًا جديدًا. بدلًا من ذلك، تحقق من حالة الطلب الموجود باستخدام ref.
لا تسترد الأموال فورًا. ابقَ على تتبع الطلب لمدة 24 ساعة. نظام الشحن غالبًا ما يُكمل العملية رغم هذا الخطأ.

منع الطلبات المكررة

يضمن حقل ref معالجة الشحن مرة واحدة فقط حتى في حالات مشكلات الشبكة.

نموذج تدفق كامل

تنسيق رقم الهاتف

يجب أن يكون رقم الهاتف نصاً (string)، وليس رقماً. الصفر البادئ مطلوب.
تنسيقات صحيحة:
  • "0778037340" (نص مع صفر بادئ)
  • "0665983439"
  • "0556121212"
تنسيقات غير صحيحة:
  • 778037340 (الصفر البادئ مفقود)
  • 0778037340 (رقم بدل نص)
  • "+213778037340" (تنسيق دولي)
  • "0778 037 340" (يحتوي على مسافات)

دورة حياة الحالة

بعد إرسال الشحن، يمر بالحالات التالية:
1

PENDING

تم إنشاء الطلب وإضافته للمعالجة المدة: 2-15 ثانية (عادةً)
2

HANDLING

جارٍ المعالجة من قِبَل المشغّل المدة: 3-8 ثوانٍ (عادةً)
3

الحالة النهائية

FULFILLED: اكتمل بنجاح ✅ REFUNDED: فشل واسترداد المبلغ ❌ UNKNOWN_ERROR: حالة غير محددة (تُحسم خلال 24 ساعة) ⚠️
تعرّف على تتبع الحالة →

اختبار Sandbox

فعّل وضع Sandbox للاختبار دون معاملات حقيقية:

التدفق الطبيعي

استخدم أي رقم عادي (مثل 0778037340) التدفق: PENDING (5ث) → HANDLING (15ث) → FULFILLED

استرداد مع رسالة

استخدم: 0600000001 النتيجة: REFUNDED مع refund_message

عدم تطابق الخطة

استخدم: 0600000002 النتيجة: REFUNDED مع suggested_offers

خطأ غير معروف

استخدم: 0600000003 النتيجة: حالة UNKNOWN_ERROR
راجع دليل سير عمل شحن الهاتف للحصول على تعليمات اختبار Sandbox الكاملة.

أفضل الممارسات

استخدم مراجع فريدة

قدّم دائماً ref فريداً لمنع التكرار وتسهيل التتبع

تحقق قبل الإرسال

تحقق من الخطة وتنسيق الهاتف والرصيد من جهة العميل لتقليل الأخطاء

اعمل بشكل غير متزامن

نفّذ طلبات API بشكل غير متزامن لتجنب إيقاف طلبات المستخدمين

نفّذ منطق إعادة المحاولة

أعد المحاولة عند فشل الطلبات مع تأخير أسي لأخطاء الشبكة

Endpoints ذات الصلة

قائمة الخطط

استعرض الخطط المتاحة

التحقق من الحالة بالمرجع

تتبع باستخدام مرجعك

التحقق من الحالة بالمعرّف

تتبع باستخدام topupId