## نظرة عامة إرسال شحن هاتف محمول فوري إلى جميع شبكات الهاتف الجزائرية (Mobilis وDjezzy وOoredoo وPixx) مع تتبع الحالة في الوقت الفعلي. لا تعيد محاولة الطلبات الفاشلة دون التحقق من الحالة أولًا باستخدام [check-by-ref](/ar/api-reference/mobile/check-by-ref) أو [check-by-id](/ar/api-reference/mobile/check-by-id). يمكن أن تتسبب طلبات الإرسال المكررة في خصم مزدوج. ## متن الطلب رمز الخطة من [list-plans](/ar/api-reference/mobile/list-plans) (مثلًا: `PREPAID_DJEZZY`، `MIX1000_OOREDOO`) رقم الهاتف المحمول الجزائري بصيغة `0XXXXXXXXX` (10 أرقام تبدأ بـ 05، 06، أو 07) مبلغ الشحن بالدينار الجزائري. **مطلوب فقط للخطط الديناميكية** (حيث `min_amount` و`max_amount` محددان). غير مطلوب للخطط الثابتة. مرجع داخلي فريد (معرّف طلبك). يُستخدم لمنع الطلبات المكررة والتحقق من الحالة لاحقًا. استخدم `ref` دائمًا إذا كنت ترسل طلبات من جانب الخادم. يمنع الخصم المزدوج إذا فشل طلب الشبكة. ## الاستجابة يشير إلى نجاح الطلب معرّف الشحن الداخلي. استخدمه مع [check-by-id](/ar/api-reference/mobile/check-by-id) للتتبع. مرجعك الداخلي (من حقل `ref` في الطلب). يُرجع `null` إذا لم تُحدد `ref`. رصيد حسابك بعد إرسال الشحن طابع زمني للاستجابة بتنسيق ISO 8601 ## الأمثلة ### خطة ديناميكية (يحدد المبلغ) ```bash cURL theme={null} 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" }' ``` ```javascript Node.js theme={null} const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", { method: "POST", headers: { "X-Access-Token": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ plan_code: "PREPAID_DJEZZY", MSSIDN: "0776543210", amount: 500, ref: "order-001", }), }); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.oneclickdz.com/v3/mobile/send', headers={'X-Access-Token': 'YOUR_API_KEY', 'Content-Type': 'application/json'}, json={ 'plan_code': 'PREPAID_DJEZZY', 'MSSIDN': '0776543210', 'amount': 500, 'ref': 'order-001' } ) data = response.json() ``` ### خطة ثابتة (لا مبلغ) ```bash cURL theme={null} 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" }' ``` ```javascript Node.js theme={null} const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", { method: "POST", headers: { "X-Access-Token": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ plan_code: "MIX1000_OOREDOO", MSSIDN: "0554926570", ref: "order-002", }), }); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.oneclickdz.com/v3/mobile/send', headers={'X-Access-Token': 'YOUR_API_KEY'}, json={ 'plan_code': 'MIX1000_OOREDOO', 'MSSIDN': '0554926570', 'ref': 'order-002' } ) data = response.json() ``` ### مثال على الاستجابة ```json theme={null} { "success": true, "data": { "topupId": "6901616fe9e88196b4eb64b0", "topupRef": "order-001", "newBalance": 826.13 }, "meta": { "timestamp": "2025-10-29T00:35:59.454Z" } } ``` ## استجابات الخطأ ```json theme={null} { "success": false, "error": { "code": "ERR_VALIDATION", "message": "Validation error", "details": { "amount": "Amount must be between 100 and 10000 for this plan" } } } ``` ```json theme={null} { "success": false, "error": { "code": "ERR_PHONE", "message": "Invalid phone number" } } ``` ```json theme={null} { "success": false, "error": { "code": "NO_BALANCE", "message": "Insufficient balance" } } ``` ```json theme={null} { "success": false, "error": { "code": "DUPLICATED_REF", "message": "This reference ID is already in use" } } ``` إذا تلقيت هذا الخطأ، **لا ترسل طلبًا جديدًا**. بدلًا من ذلك، تحقق من حالة الطلب الموجود باستخدام `ref`. ```json theme={null} { "success": false, "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Developer was notified and will check shortly" } } ``` **لا تسترد الأموال فورًا.** ابقَ على تتبع الطلب لمدة 24 ساعة. نظام الشحن غالبًا ما يُكمل العملية رغم هذا الخطأ. ## منع الطلبات المكررة يضمن حقل `ref` معالجة الشحن مرة واحدة فقط حتى في حالات مشكلات الشبكة. ```javascript theme={null} 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; } } ``` ## نموذج تدفق كامل ```javascript theme={null} 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"` (يحتوي على مسافات) ## دورة حياة الحالة بعد إرسال الشحن، يمر بالحالات التالية: تم إنشاء الطلب وإضافته للمعالجة **المدة:** 2-15 ثانية (عادةً) جارٍ المعالجة من قِبَل المشغّل **المدة:** 3-8 ثوانٍ (عادةً) **FULFILLED:** اكتمل بنجاح ✅ **REFUNDED:** فشل واسترداد المبلغ ❌ **UNKNOWN\_ERROR:** حالة غير محددة (تُحسم خلال 24 ساعة) ⚠️ [تعرّف على تتبع الحالة →](/ar/api-reference/mobile/check-by-ref) ## اختبار Sandbox فعّل وضع Sandbox للاختبار دون معاملات حقيقية: **استخدم أي رقم عادي** (مثل `0778037340`) التدفق: PENDING (5ث) → HANDLING (15ث) → FULFILLED **استخدم:** `0600000001` النتيجة: REFUNDED مع `refund_message` **استخدم:** `0600000002` النتيجة: REFUNDED مع `suggested_offers` **استخدم:** `0600000003` النتيجة: حالة UNKNOWN\_ERROR راجع [دليل سير عمل شحن الهاتف](../../mobile-topup-guides/4-status-polling) للحصول على تعليمات اختبار Sandbox الكاملة. ## أفضل الممارسات قدّم دائماً `ref` فريداً لمنع التكرار وتسهيل التتبع تحقق من الخطة وتنسيق الهاتف والرصيد من جهة العميل لتقليل الأخطاء نفّذ طلبات API بشكل غير متزامن لتجنب إيقاف طلبات المستخدمين أعد المحاولة عند فشل الطلبات مع تأخير أسي لأخطاء الشبكة ## Endpoints ذات الصلة استعرض الخطط المتاحة تتبع باستخدام مرجعك تتبع باستخدام topupId