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

نظرة عامة

يُرجع قائمة مرقّمة بجميع عمليات شحن الهاتف المحمول، مرتبةً من الأحدث إلى الأقدم.

معلمات الاستعلام

page
integer
افتراضي:1
رقم الصفحة (الحد الأدنى: 1)
pageSize
integer
افتراضي:20
عدد العناصر في الصفحة (الحد الأدنى: 1، الحد الأقصى: 100)

الاستجابة

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

الأمثلة

curl https://api.oneclickdz.com/v3/mobile/topups?page=1&pageSize=20 \
  -H "X-Access-Token: YOUR_API_KEY"

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

{
  "success": true,
  "data": {
    "items": [
      {
        "_id": "6901616fe9e88196b4eb64b0",
        "ref": "order-001",
        "status": "SUCCESS",
        "MSSIDN": "0776543210",
        "operator": "Djezzy",
        "planCode": "PREPAID_DJEZZY",
        "planName": "📱 PREPAID | عادي",
        "amount": 500,
        "cost": 496.25,
        "createdAt": "2025-10-29T00:35:59.454Z",
        "updatedAt": "2025-10-29T00:36:05.123Z"
      },
      {
        "_id": "68fe2cdd51bc170608683e3a",
        "ref": "order-002",
        "status": "SUCCESS",
        "MSSIDN": "0554926570",
        "operator": "Ooredoo",
        "planCode": "MIX1000_OOREDOO",
        "planName": "📱🌐 AUTO | MIX 1000",
        "amount": 1000,
        "cost": 990,
        "createdAt": "2025-10-26T14:14:53.074Z",
        "updatedAt": "2025-10-26T14:15:02.891Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 15,
      "totalResults": 293
    }
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.710Z"
  }
}

حالات الاستخدام

سجل الطلبات

اعرض سجل الشحن للمستخدمين في تطبيقك

متابعة الطلبات المعلّقة

ابحث عن الشحنات ذات الحالة PENDING أو UNKNOWN_ERROR لمتابعتها

التقارير

أنشئ تقارير المبيعات والتشغيل

التدقيق

راجع جميع العمليات لأغراض المحاسبة

متابعة الطلبات المعلّقة

async function followUpPendingTopUps() {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/mobile/topups?page=1&pageSize=100",
    {
      headers: { "X-Access-Token": API_KEY },
    }
  );

  const { data } = await response.json();
  const pendingTopUps = data.items.filter(
    (t) => t.status === "PENDING" || t.status === "UNKNOWN_ERROR"
  );

  for (const topup of pendingTopUps) {
    const checkResponse = await fetch(
      `https://api.oneclickdz.com/v3/mobile/topup/${topup._id}`,
      {
        headers: { "X-Access-Token": API_KEY },
      }
    );

    const checkData = await checkResponse.json();
    await updateLocalOrderStatus(topup._id, checkData.data.status);
  }
}

أمثلة على التصفية

حسب النطاق الزمني

curl "https://api.oneclickdz.com/v3/mobile/list?from=2025-10-01T00:00:00Z&to=2025-10-31T23:59:59Z" \
  -H "X-Access-Token: YOUR_API_KEY"

التصفية من جهة العميل

const { items } = data;

// Filter by status
const fulfilled = items.filter((t) => t.status === "FULFILLED");
const refunded = items.filter((t) => t.status === "REFUNDED");

// Filter by operator
const djezzy = items.filter((t) => t.plan_code.includes("DJEZZY"));

// Filter by amount range
const large = items.filter((t) => t.topup_amount >= 1000);

// Calculate totals
const totalAmount = items.reduce((sum, t) => sum + t.topup_amount, 0);
const totalCost = items.reduce((sum, t) => sum + t.balance_amount, 0);
const profit = totalAmount - totalCost;

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

  • استخدم أحجام صفحات معقولة (20-50 عنصرًا)
  • خزّن النتائج مؤقتاً عند الإمكان
  • نفّذ “تحميل المزيد” أو التمرير اللانهائي
  • استخدم pagination.totalPages لتحديد ما إذا كانت هناك صفحات إضافية
  • وفّر دائماً كلاً من from وto
  • استخدم تنسيق ISO 8601 الصحيح
  • ضع في اعتبارك المنطقة الزمنية للمستخدم عند التصفية
  • حدّد نطاقات تاريخ معقولة للأداء الأمثل
  • خزّن بيانات القائمة مؤقتاً لفترات قصيرة
  • استخدم مرشحات التاريخ للحدّ من مجموعات النتائج
  • تجنّب جلب جميع الصفحات دفعة واحدة
  • أنشئ فهرساً باستخدام created_at في قاعدة بياناتك المحلية
  • اعرض الحالة مع أيقونات/ألوان
  • نسّق الطوابع الزمنية بالمنطقة الزمنية المحلية
  • اعرض شعارات المشغّلين
  • اربط بصفحات الحالة التفصيلية
  • اعرض سبب الاسترداد للشحنات الفاشلة

Endpoints ذات الصلة

إرسال الشحن

إرسال شحن هاتف محمول

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

البحث بالمرجع الداخلي

قائمة الخطط

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