## نظرة عامة يُرجع قائمة مرقّمة بجميع عمليات شحن الهاتف المحمول، مرتبةً من الأحدث إلى الأقدم. ## معلمات الاستعلام رقم الصفحة (الحد الأدنى: 1) عدد العناصر في الصفحة (الحد الأدنى: 1، الحد الأقصى: 100) ## الاستجابة يشير إلى نجاح الطلب مصفوفة من كائنات الشحن معرّف الشحن الداخلي مرجعك الداخلي (إذا أُوفِّر عند الإرسال) الحالة الحالية للشحن: `PENDING`، `SUCCESS`، `FAILED`، `UNKNOWN_ERROR` رقم الهاتف الذي تم شحنه مشغّل الشبكة: `Mobilis`، `Djezzy`، أو `Ooredoo` رمز الخطة المستخدمة الاسم المقروء للخطة مبلغ الشحن بالدينار الجزائري التكلفة الفعلية من رصيدك طابع زمني للإنشاء (ISO 8601) طابع زمني لآخر تحديث للحالة (ISO 8601) رقم الصفحة الحالية عدد العناصر في الصفحة العدد الإجمالي للصفحات العدد الإجمالي للشحنات طابع زمني للاستجابة بتنسيق ISO 8601 ## الأمثلة ```bash cURL theme={null} curl https://api.oneclickdz.com/v3/mobile/topups?page=1&pageSize=20 \ -H "X-Access-Token: YOUR_API_KEY" ``` ```javascript Node.js theme={null} const response = await fetch( "https://api.oneclickdz.com/v3/mobile/topups?page=1&pageSize=20", { headers: { "X-Access-Token": "YOUR_API_KEY" }, } ); const { data } = await response.json(); const topups = data.items; const pagination = data.pagination; ``` ```python Python theme={null} import requests response = requests.get( 'https://api.oneclickdz.com/v3/mobile/topups', headers={'X-Access-Token': 'YOUR_API_KEY'}, params={'page': 1, 'pageSize': 20} ) data = response.json()['data'] topups = data['items'] pagination = data['pagination'] ``` ```php PHP theme={null} ``` ### مثال على الاستجابة ```json theme={null} { "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` لمتابعتها أنشئ تقارير المبيعات والتشغيل راجع جميع العمليات لأغراض المحاسبة ## متابعة الطلبات المعلّقة ```javascript theme={null} 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); } } ``` ## أمثلة على التصفية ### حسب النطاق الزمني ```bash cURL theme={null} 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" ``` ```javascript Node.js theme={null} const from = "2025-10-01T00:00:00Z"; const to = "2025-10-31T23:59:59Z"; const response = await fetch( `https://api.oneclickdz.com/v3/mobile/list?from=${from}&to=${to}`, { headers: { "X-Access-Token": "YOUR_API_KEY" } } ); ``` ```python Python theme={null} response = requests.get( 'https://api.oneclickdz.com/v3/mobile/list', headers={'X-Access-Token': 'YOUR_API_KEY'}, params={ 'from': '2025-10-01T00:00:00Z', 'to': '2025-10-31T23:59:59Z', 'page': 1, 'pageSize': 50 } ) ``` ### التصفية من جهة العميل ```javascript theme={null} 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 ذات الصلة إرسال شحن هاتف محمول البحث بالمرجع الداخلي عرض الخطط المتاحة