الانتقال إلى المحتوى الرئيسي

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.

​
مقدمة

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

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

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

1

تحميل الكتالوج

جلب المنتجات المتاحة مصنفةً حسب الفئات (ألعاب، بث، إلخ). → انظر الخطوة 1: تحميل الكتالوج
2

فحص المنتج

الحصول على الفئات السعرية والتسعير والمخزون الفعلي لمنتج محدد. → انظر الخطوة 2: فحص المنتجات
3

تقديم الطلب

إرسال الطلب مع معرّف المنتج ومعرّف النوع (الفئة السعرية) والكمية. → انظر الخطوة 3: تقديم الطلبات
4

تتبع الحالة

استطلاع حالة الطلب كل 5-10 ثوانٍ حتى الاكتمال. → انظر الخطوة 4: تتبع الحالة
5

تسليم البطاقات

استرداد رموز/أرقام تسلسل البطاقات وتسليمها بأمان إلى العميل. → انظر الخطوة 5: التسليم الآمن

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

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

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

​
حالة الطلب

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

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

إذا طلبت 5 بطاقات لكن 3 فقط متاحة، ستحصل على:
  • 3 بطاقات مسلَّمة
  • محاسَب فقط على 3
  • مستردّ للـ 2 تلقائيًا
تحقق دائمًا من fulfilled_quantity مقابل quantity.→ التعامل مع الجزئي في الخطوة 4

​
التسعير

طبّق هامش ربحك على أسعار الجملة قبل عرضها للعملاء.مثال: 490 دج بالجملة → البيع بـ 515 دج (هامش 5%) → الربح: 25 دج→ التسعير في الخطوة 2

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

فحص المخزون

تحقق من available: true قبل عرض المنتجات → الخطوة 2

تخزين الكتالوج مؤقتًا

خزّن الكتالوج لمدة +24 ساعة لتقليل استدعاءات API → الخطوة 1

التعامل مع الجزئي

تحقق من الكمية المنفَّذة مقابل الكمية المطلوبة → الخطوة 4

تشفير البطاقات

لا تخزن رموز البطاقات كنص صريح → الخطوة 5

​
مرجع API

الحصول على الكتالوج

GET /v3/gift-cards/catalog

فحص المنتج

GET /v3/gift-cards/checkProduct/:id

تقديم طلب

POST /v3/gift-cards/placeOrder

فحص الطلب

GET /v3/gift-cards/checkOrder/:id

​
الاختبار

استخدم وضع sandbox للاختبار دون إنفاق رصيد حقيقي:
  • TEST_REFUND (type ID) → يحاكي طلبًا فاشلًا
  • TEST_PARTIAL (type ID) → يحاكي تنفيذًا بنسبة 50%
فعّل sandbox في إعدادات لوحة التحكم.

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

ابدأ بالخطوة 1: تحميل الكتالوج

ابدأ بتحميل كتالوج المنتجات مع أمثلة الكود

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

دليل البدء السريع

ابدأ خلال 5 دقائق

المصادقة

تعلم كيفية مصادقة الطلبات

أفضل ممارسات الأمان

أمّن تكاملك

التواصل مع الدعم

احصل على مساعدة من فريقنا