الانتقال إلى المحتوى الرئيسي
POST
/
v3
/
mobile
/
send
إرسال شحن الهاتف المحمول
curl --request POST \
  --url https://api.oneclickdz.com/v3/mobile/send \
  --header 'X-Access-Token: <api-key>'

Documentation Index

Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt

Use this file to discover all available pages before exploring further.

نظرة عامة

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

متن الطلب

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

الاستجابة

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

الأمثلة

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

curl -X POST https://api.oneclickdz.com/v3/mobile/send \
  -H "X-Access-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0776543210",
    "amount": 500,
    "ref": "order-001"
  }'

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

curl -X POST https://api.oneclickdz.com/v3/mobile/send \
  -H "X-Access-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_code": "MIX1000_OOREDOO",
    "MSSIDN": "0554926570",
    "ref": "order-002"
  }'

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

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "order-001",
    "newBalance": 826.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:59.454Z"
  }
}

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

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "Validation error",
    "details": {
      "amount": "Amount must be between 100 and 10000 for this plan"
    }
  }
}
{
  "success": false,
  "error": {
    "code": "ERR_PHONE",
    "message": "Invalid phone number"
  }
}
{
  "success": false,
  "error": {
    "code": "NO_BALANCE",
    "message": "Insufficient balance"
  }
}
{
  "success": false,
  "error": {
    "code": "DUPLICATED_REF",
    "message": "This reference ID is already in use"
  }
}
إذا تلقيت هذا الخطأ، لا ترسل طلبًا جديدًا. بدلًا من ذلك، تحقق من حالة الطلب الموجود باستخدام ref.
{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Developer was notified and will check shortly"
  }
}
لا تسترد الأموال فورًا. ابقَ على تتبع الطلب لمدة 24 ساعة. نظام الشحن غالبًا ما يُكمل العملية رغم هذا الخطأ.

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

يضمن حقل ref معالجة الشحن مرة واحدة فقط حتى في حالات مشكلات الشبكة.
async function sendTopUpSafe(planCode, phone, amount, orderId) {
  // Use orderId as the ref for idempotency
  const ref = `topup-${orderId}`;

  try {
    const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
      method: "POST",
      headers: {
        "X-Access-Token": API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        plan_code: planCode,
        MSSIDN: phone,
        amount,
        ref,
      }),
    });

    const data = await response.json();

    if (data.success) {
      return { success: true, topupId: data.data.topupId };
    }

    // Handle duplicate ref - order already exists
    if (data.error.code === "DUPLICATED_REF") {
      const status = await checkTopUpByRef(ref);
      return { success: true, topupId: status.data._id, fromExisting: true };
    }

    throw new Error(`${data.error.code}: ${data.error.message}`);
  } catch (networkError) {
    // Network error - check if order was created
    const status = await checkTopUpByRef(ref);
    if (status.success) {
      return { success: true, topupId: status.data._id, fromExisting: true };
    }
    throw networkError;
  }
}

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

async function processTopUp(userId, planCode, phone, amount) {
  // 1. Validate inputs
  if (!/^0[567]\d{8}$/.test(phone)) {
    throw new Error('Invalid Algerian phone number format');
  }

  // 2. Check balance
  const balance = await getBalance();
  if (balance < amount * 1.05) { // Add buffer for safety
    throw new Error('Insufficient balance');
  }

  // 3. Generate unique ref
  const ref = `topup-${userId}-${Date.now()}`;

  // 4. Send topup
  const result = await sendTopUp({
    plan_code: planCode,
    MSSIDN: phone,
    amount,
    ref
  });

  // 5. Store result
  await saveTransaction({
    ref,
    topupId: result.topupId,
    status: 'PENDING',
    createdAt: new Date()
  });

  // 6. Return success
  return result;
}

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

يجب أن يكون رقم الهاتف نصاً (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