## نظرة عامة يُرجع حالة شحن هاتف محمول باستخدام قيمة `ref` التي حددتها عند [إرسال الشحن](/ar/api-reference/mobile/send-topup). إذا أرسلت طلبًا بدون `ref`، استخدم [check-by-id](/ar/api-reference/mobile/check-by-id) مع `topupId` المُرجع. ## المعلمات مرجعك الداخلي كما وفّرته في طلب الشحن ## الاستجابة `true` إذا تم العثور على الشحن وإرجاع حالته معرّف الشحن الداخلي مرجعك الداخلي الحالة الحالية للشحن. القيم المحتملة: * `PENDING`: قيد المعالجة * `SUCCESS`: اكتمل الشحن * `FAILED`: فشل بشكل نهائي (الرصيد مُسترد) * `UNKNOWN_ERROR`: حالة غير محددة - انتظر، لا تسترد الأموال رقم الهاتف الذي تم شحنه مشغّل الشبكة: `Mobilis`، `Djezzy`، أو `Ooredoo` رمز الخطة المستخدمة الاسم المقروء للخطة مبلغ الشحن بالدينار الجزائري التكلفة الفعلية من رصيدك طابع زمني للإنشاء (ISO 8601) طابع زمني لآخر تحديث للحالة (ISO 8601) ## قيم الحالة | الحالة | المعنى | الإجراء | | --------------- | ------------------ | ------------------------------------ | | `PENDING` | الشحن قيد المعالجة | تحقق مجددًا بعد 5-10 ثوانٍ | | `SUCCESS` | الشحن اكتمل بنجاح | أبلغ المستخدم بالنجاح | | `FAILED` | الشحن فشل نهائيًا | الرصيد مُسترد - يمكن المحاولة مجددًا | | `UNKNOWN_ERROR` | حالة غير محددة | **انتظر 24 ساعة** - لا تسترد الأموال | ## الأمثلة ```bash cURL theme={null} curl https://api.oneclickdz.com/v3/mobile/topup/ref/order-001 \ -H "X-Access-Token: YOUR_API_KEY" ``` ```javascript Node.js theme={null} const ref = "order-001"; const response = await fetch( `https://api.oneclickdz.com/v3/mobile/topup/ref/${encodeURIComponent(ref)}`, { headers: { "X-Access-Token": "YOUR_API_KEY" }, } ); const data = await response.json(); console.log("Status:", data.data.status); ``` ```python Python theme={null} import requests ref = 'order-001' response = requests.get( f'https://api.oneclickdz.com/v3/mobile/topup/ref/{ref}', headers={'X-Access-Token': 'YOUR_API_KEY'} ) data = response.json() print('Status:', data['data']['status']) ``` ```php PHP theme={null} ``` ### مثال على الاستجابة ```json theme={null} { "success": true, "data": { "_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" } } ``` ## استراتيجية الاستطلاع (Polling) ```javascript theme={null} async function pollTopUpStatus(ref, maxAttempts = 12, intervalMs = 5000) { for (let attempt = 1; attempt <= maxAttempts; attempt++) { const response = await fetch( `https://api.oneclickdz.com/v3/mobile/topup/ref/${encodeURIComponent(ref)}`, { headers: { "X-Access-Token": API_KEY }, } ); const data = await response.json(); if (!data.success) { throw new Error(`Failed to check status: ${data.error.message}`); } const { status } = data.data; if (status === "SUCCESS") { return { success: true, data: data.data }; } if (status === "FAILED") { return { success: false, data: data.data }; } if (status === "UNKNOWN_ERROR") { // Stop polling - schedule a check after 24h, do NOT refund return { success: null, data: data.data, requiresManualReview: true }; } // Still PENDING - wait and retry if (attempt < maxAttempts) { await new Promise((resolve) => setTimeout(resolve, intervalMs)); } } // Timeout - treat as UNKNOWN_ERROR return { success: null, timedOut: true, requiresManualReview: true }; } ``` ## متى تستخدم هذا الـ Endpoint عندما يسأل المستخدمون عن طلباتهم باستخدام معرّف الطلب الخاص بك التكامل مع نظام تتبع الطلبات الحالي لديك عرض حالة الطلب باستخدام مراجع مواجهة العملاء البحث عن الطلبات عبر أرقام المراجع الخاصة بالعملاء ## استجابة الخطأ **404 - غير موجود:** ```json theme={null} { "success": false, "error": { "code": "NOT_FOUND", "message": "Top-up with reference 'order-12345' not found" }, "requestId": "req_1730160975_abc123" } ``` هذا يعني أنه لا يوجد شحن بهذا المرجع. الأسباب المحتملة: * لم يُرسَل المرجع أبداً * خطأ إملائي في المرجع * المرجع ينتمي إلى حساب مختلف ## أفضل الممارسات أنشئ مراجع تكون: * فريدة في نظامك * سهلة التعرف عليها (مثل `order-{timestamp}-{userId}`) * آمنة في عناوين URL (بدون أحرف خاصة) * قابلة للبحث في قاعدة بياناتك احفظ كلاً من مرجعك ومعرّف topupId الخاص بـ API: ```javascript theme={null} await db.orders.update({ orderId: 'order-12345', apiTopupId: response.data.topupId, apiTopupRef: response.data.topupRef }); ``` يتيح لك ذلك التتبع باستخدام أي من المعرّفين. إذا نسيت تقديم `ref`، ينشئ الـ API مرجعاً تلقائياً. احفظه: ```javascript theme={null} const response = await sendTopup({ plan_code: 'PREPAID_DJEZZY', MSSIDN: '0778037340', amount: 500 // No ref provided }); // API returns: { topupRef: "auto-gen-1730160975" } await db.orders.update({ orderId: order.id, apiRef: response.data.topupRef }); ``` ## Endpoints ذات الصلة البحث بـ topupId إرسال شحن جديد عرض الشحنات السابقة