> ## 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.

# نظرة عامة على تكامل شحن الهاتف

> تعلّم كيفية دمج شحن الهاتف المحمول للمشغلين الجزائريين

<div dir="rtl">
  ## مقدمة

  ادمج وظيفة شحن الهاتف المحمول للمشغلين الجزائريين (Mobilis وDjezzy وOoredoo وPixx) في 4 خطوات بسيطة. تشرح هذه النظرة العامة سير عمل التكامل - والتنفيذ التفصيلي مع أمثلة الكود بلغات Node.js وPython وPHP وcURL موجود في الأدلة التفصيلية أدناه.

  ## كيف يعمل النظام

  ```mermaid theme={null}
  sequenceDiagram
      participant User
      participant YourApp
      participant API as OneClickDz API

      YourApp->>API: 1. Load available plans
      API-->>YourApp: Plans with pricing
      
      User->>YourApp: Select plan & enter phone
      YourApp->>YourApp: 2. Validate input
      
      YourApp->>API: 3. Send top-up request
      API-->>YourApp: Order ID
      
      loop Until complete
          YourApp->>API: 4. Check status
          API-->>YourApp: Status update
      end
      
      YourApp->>User: Notify success/failure
  ```

  ## عملية التكامل في 4 خطوات

  <Steps>
    <Step title="تحميل الخطط">
      احصل على خطط الشحن المتاحة بالأسعار وخزّنها في الكاش محلياً.

      → [انظر الخطوة 1: تحميل الخطط](/ar/mobile-topup-guides/1-loading-plans)
    </Step>

    <Step title="التحقق من المدخلات">
      تحقق من أرقام الهواتف (10 أرقام، بادئة المشغل الصحيحة) والمبالغ قبل الإرسال.

      → [انظر الخطوة 2: التحقق](/ar/mobile-topup-guides/2-validation)
    </Step>

    <Step title="إرسال الشحن">
      أرسل طلب الشحن بمرجع فريد للتتبع.

      → [انظر الخطوة 3: إرسال عمليات الشحن](/ar/mobile-topup-guides/3-sending-topups)
    </Step>

    <Step title="تتبع الحالة">
      تحقق من حالة الطلب كل 5–10 ثوانٍ حتى يكتمل (FULFILLED أو REFUNDED أو UNKNOWN\_ERROR).

      → [انظر الخطوة 4: تتبع الحالة](/ar/mobile-topup-guides/4-status-polling)
    </Step>
  </Steps>

  ## ما تحتاج معرفته

  ### أنواع الخطط

  تدعم API **3 أنواع** من الخطط:

  * **الخطط الديناميكية**: مبالغ مرنة (مثل 50–5000 دينار لـ Djezzy مسبق الدفع)
  * **الخطط الثابتة**: مبالغ محددة (مثل Pixx 500 دينار)
  * **خطط GetMenu**: تجلب عروضاً مخصصة لرقم هاتف معين

  → [مزيد من المعلومات في الخطوة 1](/ar/mobile-topup-guides/1-loading-plans)

  ### حالات الطلب

  تتقدم الطلبات عبر هذه الحالات:

  * `PENDING` / `HANDLING` → استمر في التحقق
  * `FULFILLED` → نجاح! ✅
  * `REFUNDED` → فشل، تم الاسترداد ❌
  * `UNKNOWN_ERROR` → **انتظر 24 ساعة قبل الاسترداد** ⚠️

  → [معالجة الحالات التفصيلية في الخطوة 4](/ar/mobile-topup-guides/4-status-polling)

  ### صيغة رقم الهاتف

  يجب أن تتكون أرقام الهواتف من **10 أرقام**: `0[567][0-9]{8}`

  * Mobilis: `06...`
  * Djezzy: `07...`
  * Ooredoo: `05...`

  → [كود التحقق في الخطوة 2](/ar/mobile-topup-guides/2-validation)

  ### التسعير

  تُعيد API **أسعار الجملة**. طبّق هامشك الربحي قبل عرضها للعملاء.

  مثال: `cost: 0.98` لـ 1000 دينار → تدفع 980 دينار → تبيع بـ 1029 دينار (هامش 5%) → الربح: 49 دينار

  → [استراتيجيات التسعير في الخطوة 1](/ar/mobile-topup-guides/1-loading-plans)

  ## النقاط الأساسية

  <AccordionGroup>
    <Accordion title="استخدم دائماً مراجع فريدة" icon="fingerprint">
      ولّد `ref` فريداً لكل طلب لمنع التكرار وتمكين التتبع.

      → [التنفيذ في الخطوة 3](/ar/mobile-topup-guides/3-sending-topups)
    </Accordion>

    <Accordion title="خزّن الخطط في الكاش محلياً" icon="database">
      نادراً ما تتغير الخطط. خزّنها في الكاش لتقليل استدعاءات API وتحسين السرعة.

      → [استراتيجية الكاش في الخطوة 1](/ar/mobile-topup-guides/1-loading-plans)
    </Accordion>

    <Accordion title="تعامل مع UNKNOWN_ERROR بحذر" icon="triangle-exclamation">
      **لا تسترد المبلغ فوراً!** انتظر حتى 24 ساعة حتى تُحسم الحالة.

      → [معالجة الأخطاء في الخطوة 4](/ar/mobile-topup-guides/4-status-polling)
    </Accordion>

    <Accordion title="اعرض رسائل الخطأ بالعربية" icon="language">
      اعرض حقل `refund_message` (بالعربية) للعملاء - يشرح ما حدث.

      → [معالجة الرسائل في الخطوة 4](/ar/mobile-topup-guides/4-status-polling)
    </Accordion>
  </AccordionGroup>

  ## مرجع API

  للمواصفات الكاملة للـ endpoints:

  <CardGroup cols={2}>
    <Card title="سرد خطط الهاتف المحمول" icon="list" href="/ar/api-reference/mobile/list-plans">
      GET /v3/mobile/plans
    </Card>

    <Card title="إرسال شحن" icon="paper-plane" href="/ar/api-reference/mobile/send-topup">
      POST /v3/mobile/send
    </Card>

    <Card title="التحقق بالمرجع" icon="tag" href="/ar/api-reference/mobile/check-by-ref">
      GET /v3/mobile/check-ref/:ref
    </Card>

    <Card title="التحقق بالمعرّف" icon="id-card" href="/ar/api-reference/mobile/check-by-id">
      GET /v3/mobile/check-id/:id
    </Card>
  </CardGroup>

  ## الاختبار

  استخدم **وضع sandbox** للاختبار بدون أموال حقيقية. اختبر بهذه الأرقام الخاصة:

  * أرقام عادية → سير نجاح
  * `0600000001` → سيناريو الاسترداد
  * `0600000002` → عروض مقترحة
  * `0600000003` → خطأ غير معروف

  فعّل sandbox في [إعدادات لوحة التحكم](https://app.oneclickdz.com/#/settings).

  ## بدء التكامل

  <Card title="ابدأ بالخطوة 1: تحميل الخطط" icon="play" href="/ar/mobile-topup-guides/1-loading-plans" color="#0D9373">
    ابدأ بتحميل وتخزين خطط الهاتف المحمول في الكاش مع أمثلة الكود
  </Card>

  ## موارد إضافية

  <CardGroup cols={2}>
    <Card title="دليل البدء السريع" icon="rocket" href="/ar/quickstart">
      ابدأ في 5 دقائق
    </Card>

    <Card title="المصادقة" icon="key" href="/ar/authentication">
      تعلّم كيفية مصادقة الطلبات
    </Card>

    <Card title="أفضل ممارسات الأمان" icon="shield" href="/ar/security-best-practices">
      أمّن تكاملك
    </Card>

    <Card title="استراتيجيات Polling" icon="chart-line" href="/ar/polling-strategies">
      حسّن التحقق من الحالة
    </Card>

    <Card title="Webhooks" icon="webhook" href="/ar/webhooks">
      إشعارات الحالة الفورية
    </Card>

    <Card title="التواصل مع الدعم" icon="headset" href="/ar/contact">
      احصل على مساعدة فريقنا
    </Card>
  </CardGroup>
</div>