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

المقدمة

تتيح لك وحدة الخصومات إدارة وتطبيق الخصومات على المنتجات والطلبات

مزيد من المعلومات حول واجهة المستخدم الخاصة بالوحدة https://doc.oneentry.cloud/docs/category/discounts

🎯 ماذا تفعل هذه الوحدة؟​

تتيح لك وحدة الخصومات استرداد الخصومات والتحقق من رموز القسائم — تخفيضات بنسبة مئوية أو بمبلغ ثابت، تراكم نقاط المكافآت، وخصومات شخصية. تقوم بتعريف قواعد الخصم في لوحة إدارة OneEntry؛ تسترجع هذه الوحدة القواعد، تتحقق من القسائم عند الخروج، وتقرأ رصيد المكافآت وتاريخ المستخدم الحالي.

SDK هو للقراءة فقط: يتم إنشاء الخصومات وتكوينها في لوحة الإدارة.

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

قم بتهيئة الوحدة من defineOneEntry:


const { Discounts } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

تحقق من رمز القسيمة عند الخروج واقرأ النتيجة:

// Validate a coupon code entered by the customer.
const result = await Discounts.validateDiscountsCoupon("SUMMER20");

if (result.valid) {
  console.log("Coupon applied:", result.coupon);
} else {
  console.log("Invalid coupon:", result.error);
}

✨ المفاهيم الأساسية​

ما هو الخصم؟​

الخصم (IDiscountsEntity) هو قاعدة تسعير تقلل من تكلفة المنتجات أو الطلبات:

  • type — DISCOUNT، BONUS، أو PERSONAL_DISCOUNT
  • discountValue — كيفية حساب التخفيض: discountType (PERCENT أو FIXED_AMOUNT)، قيمة عددية value، applicability (TO_PRODUCT أو TO_ORDER)، ومبلغ أقصى اختياري maxAmount
  • identifier — علامة فريدة للتصفية والإشارة
  • startDate / endDate — فترة صلاحية اختيارية
  • conditions — قواعد تحدد متى ينطبق الخصم (حسب المنتج، الفئة، مبلغ السلة، المستخدم، …)

هيكل الخصم​

{
  id: 1,
  identifier: 'summer_sale',
  localizeInfos: {
    title: 'Summer Sale'
  },
  type: 'DISCOUNT',
  startDate: '2025-06-01T00:00:00.000Z',
  endDate: '2025-08-31T23:59:59.999Z',
  discountValue: {
    applicability: 'TO_ORDER',
    discountType: 'PERCENT',
    value: 20,
    maxAmount: 100
  },
  conditionLogic: 'AND',
  conditions: [
    { type: 'MIN_CART_AMOUNT', value: '50' }
  ]
}

أنواع الخصومات​

يصنف حقل type الخصم:

typeالوصف
DISCOUNTخصم قياسي يُطبق على المنتجات/الطلبات
BONUSتراكم نقاط المكافآت (الولاء)
PERSONAL_DISCOUNTخصم موجه لمستخدمين أو مجموعات محددة

كيفية حساب التخفيض موجودة في discountValue.discountType:

discountValue.discountTypeالوصفمثال
PERCENTتقليل السعر بنسبة مئوية20% خصم على جميع عناصر الصيف
FIXED_AMOUNTتقليل السعر بمبلغ ثابت10 دولارات خصم على الطلبات التي تزيد عن 50 دولار

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

يتم إنشاء الخصومات في لوحة الإدارة​

لا يمكنك إنشاء خصومات عبر SDK — يتم إنشاؤها في لوحة إدارة OneEntry. عند إنشاء واحدة، تقدم اسمًا، وعلامة (identifier)، ونوع (DISCOUNT، BONUS، أو PERSONAL_DISCOUNT)، و**discountValue** (PERCENT أو FIXED_AMOUNT بالإضافة إلى القيمة العددية value)، وفترة صلاحية اختيارية (startDate / endDate)، وشروط اختيارية.

ماذا تفعل الوحدة​

  • ✅ استرداد جميع الخصومات — getAllDiscounts()
  • ✅ استرداد خصم محدد بواسطة العلامة — getDiscountByMarker()
  • ✅ التحقق من رموز القسائم عند الخروج — validateDiscountsCoupon()
  • ✅ قراءة رصيد المكافآت وتاريخ المستخدم الحالي
  • ❌ لا تقوم بإنشاء أو تعديل الخصومات (استخدم لوحة الإدارة)

📊 جدول المرجع السريع​

الطريقةالوصف
getAllDiscounts()الحصول على جميع الخصومات
getDiscountByMarker()الحصول على خصم واحد بواسطة العلامة
validateDiscountsCoupon()التحقق من رمز قسيمة الخصم
getBonusBalance()الحصول على رصيد المكافآت للمستخدم الحالي
getBonusHistory()الحصول على تاريخ معاملات المكافآت للمستخدم الحالي

❓ الأسئلة الشائعة (FAQ)​

كيف يمكنني تطبيق خصم عند الخروج؟​

استرد الخصم باستخدام getDiscountByMarker() أو تحقق من قسيمة باستخدام validateDiscountsCoupon()، ثم استخدم قيمة الخصم المعادة لحساب السعر المخفض.

هل يمكن أن يكون للخصم تاريخ انتهاء؟​

نعم. يمكن أن تحتوي الخصومات على حقول startDate و endDate اختيارية — تحقق منها قبل عرض الخصم للتأكد من أنه نشط حاليًا.

كيف يمكنني عرض شارات الخصم على المنتجات؟​

استرد جميع الخصومات باستخدام getAllDiscounts()، ووافقها مع المنتجات وفقًا لمنطق عملك، وقدم شارة من localizeInfos.title و discountValue.value.

ماذا يحدث إذا كان رمز القسيمة غير صالح؟​

تُرجع validateDiscountsCoupon() نتيجة ICouponValidationResult — { valid: boolean; coupon?; error? }. عندما لا توجد القسيمة أو انتهت صلاحيتها، تكون valid هي false ويتم توفير رسالة error. تحقق من result.valid وقدم رسالة مناسبة.

🎓 أفضل الممارسات​

  • تخزين الخصومات عند التحميل — فهي تتغير نادرًا؛ تجنب المكالمات المتكررة لواجهة برمجة التطبيقات.
  • تحقق من القسائم قبل التطبيق — دائمًا اتصل بـ validateDiscountsCoupon() قبل تسعير الطلب.
  • التعامل مع الخصومات المنتهية — تحقق من endDate قبل عرض الخصم.
  • استخدم علامات وصفية — summer_sale_2025، وليس discount1.
  • ترجمة أسماء الخصومات — استخدم localizeInfos لدعم اللغات المتعددة.

🔗 الوثائق ذات الصلة​