> ## 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">
  ## مقدمة

  ادمج بيع بطاقات الهدايا والمنتجات الرقمية في 5 خطوات بسيطة. توضح هذه النظرة العامة سير العمل-يوجد التطبيق التفصيلي مع أمثلة الكود في الأدلة التفصيلية أدناه.

  <Info>
    تُعالَج طلبات بطاقات الهدايا في غضون ثوانٍ ويتم تسليم رموز البطاقات رقميًا عبر API.
  </Info>

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

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

      YourApp->>API: 1. Load product catalog
      API-->>YourApp: Categories & products

      User->>YourApp: Select product
      YourApp->>API: 2. Check product details
      API-->>YourApp: Types, pricing, stock

      User->>YourApp: Choose type & quantity
      YourApp->>API: 3. Place order
      API-->>YourApp: Order ID

      loop Until Complete
          YourApp->>API: 4. Check order status
          API-->>YourApp: Status update
      end

      YourApp->>User: 5. Deliver card codes
  ```

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

  <Steps>
    <Step title="تحميل الكتالوج">
      جلب المنتجات المتاحة مصنفةً حسب الفئات (ألعاب، بث، إلخ).
      → [انظر الخطوة 1: تحميل الكتالوج](/ar/gift-card-guides/1-loading-catalog)
    </Step>

    <Step title="فحص المنتج">
      الحصول على الفئات السعرية والتسعير والمخزون الفعلي لمنتج محدد. →
      [انظر الخطوة 2: فحص المنتجات](/ar/gift-card-guides/2-checking-products)
    </Step>

    <Step title="تقديم الطلب">
      إرسال الطلب مع معرّف المنتج ومعرّف النوع (الفئة السعرية) والكمية. → [انظر
      الخطوة 3: تقديم الطلبات](/ar/gift-card-guides/3-placing-orders)
    </Step>

    <Step title="تتبع الحالة">
      استطلاع حالة الطلب كل 5-10 ثوانٍ حتى الاكتمال. → [انظر الخطوة 4: تتبع الحالة](/ar/gift-card-guides/4-status-tracking)
    </Step>

    <Step title="تسليم البطاقات">
      استرداد رموز/أرقام تسلسل البطاقات وتسليمها بأمان إلى العميل. → [انظر الخطوة 5:
      التسليم الآمن](/ar/gift-card-guides/5-secure-delivery)
    </Step>
  </Steps>

  ## ما تحتاج إلى معرفته

  ### هيكل المنتجات

  * **الكتالوج** → الفئات (ألعاب، بث، إلخ)
  * **المنتجات** → العناصر الفردية (PUBG، Netflix، إلخ)
  * **الأنواع** → الفئات السعرية (500 دج، 1000 دج، إلخ)

  → [هيكل الكتالوج في الخطوة 1](/ar/gift-card-guides/1-loading-catalog)

  ### حالة الطلب

  * `HANDLING` → استمر في الاستطلاع
  * `FULFILLED` → جميع البطاقات مسلَّمة ✅
  * `PARTIALLY_FILLED` → بعض البطاقات مسلَّمة، الباقي مستردّ ⚠️
  * `REFUNDED` → فشل الطلب، تم إصدار الاسترداد ❌

  → [التعامل مع الحالات في الخطوة 4](/ar/gift-card-guides/4-status-tracking)

  ### التنفيذ الجزئي

  إذا طلبت 5 بطاقات لكن 3 فقط متاحة، ستحصل على:

  * 3 بطاقات مسلَّمة
  * محاسَب فقط على 3
  * مستردّ للـ 2 تلقائيًا

  تحقق دائمًا من `fulfilled_quantity` مقابل `quantity`.

  → [التعامل مع الجزئي في الخطوة 4](/ar/gift-card-guides/4-status-tracking)

  ### التسعير

  طبّق هامش ربحك على أسعار الجملة قبل عرضها للعملاء.

  مثال: 490 دج بالجملة → البيع بـ 515 دج (هامش 5%) → الربح: 25 دج

  → [التسعير في الخطوة 2](/ar/gift-card-guides/2-checking-products)

  ## النقاط الرئيسية

  <CardGroup cols={2}>
    <Card title="فحص المخزون" icon="warehouse">
      تحقق من `available: true` قبل عرض المنتجات → [الخطوة
      2](/ar/gift-card-guides/2-checking-products)
    </Card>

    <Card title="تخزين الكتالوج مؤقتًا" icon="database">
      خزّن الكتالوج لمدة +24 ساعة لتقليل استدعاءات API → [الخطوة
      1](/ar/gift-card-guides/1-loading-catalog)
    </Card>

    <Card title="التعامل مع الجزئي" icon="triangle-exclamation">
      تحقق من الكمية المنفَّذة مقابل الكمية المطلوبة → [الخطوة
      4](/ar/gift-card-guides/4-status-tracking)
    </Card>

    <Card title="تشفير البطاقات" icon="lock">
      لا تخزن رموز البطاقات كنص صريح → [الخطوة
      5](/ar/gift-card-guides/5-secure-delivery)
    </Card>
  </CardGroup>

  ## مرجع API

  <CardGroup cols={2}>
    <Card title="الحصول على الكتالوج" icon="list" href="/ar/api-reference/gift-cards/get-catalog">
      GET /v3/gift-cards/catalog
    </Card>

    <Card title="فحص المنتج" icon="magnifying-glass" href="/ar/api-reference/gift-cards/check-product">
      GET /v3/gift-cards/checkProduct/:id
    </Card>

    <Card title="تقديم طلب" icon="cart-shopping" href="/ar/api-reference/gift-cards/place-order">
      POST /v3/gift-cards/placeOrder
    </Card>

    <Card title="فحص الطلب" icon="file-circle-check" href="/ar/api-reference/gift-cards/check-order">
      GET /v3/gift-cards/checkOrder/:id
    </Card>
  </CardGroup>

  ## الاختبار

  استخدم **وضع sandbox** للاختبار دون إنفاق رصيد حقيقي:

  * `TEST_REFUND` (type ID) → يحاكي طلبًا فاشلًا
  * `TEST_PARTIAL` (type ID) → يحاكي تنفيذًا بنسبة 50%

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

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

  <Card title="ابدأ بالخطوة 1: تحميل الكتالوج" icon="play" href="/ar/gift-card-guides/1-loading-catalog" 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="التواصل مع الدعم" icon="headset" href="/ar/contact">
      احصل على مساعدة من فريقنا
    </Card>
  </CardGroup>
</div>