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

Discounts

تتيح لك وحدة Discounts قراءة الخصومات، والتحقق من القسائم، والاطلاع على رصيد مكافآت المستخدم.

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


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

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

بدء سريع​

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


const { } = defineOneEntry(
, {
}
);

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

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

if ('statusCode' in result) {
console.error(result.message); // IError: the request failed
} else if (result.valid) {
console.log("Coupon applied:", result.coupon);
} else {
console.log("Invalid coupon:", result.error); // e.g. "Coupon not found"
}

كائن الخصم​

الخصم (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: [
{ id: 1, conditionType: 'MIN_CART_AMOUNT', entityIds: null, value: { amount: 50 } }
]
}

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

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

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

تُضبط طريقة حساب التخفيض في discountValue.discountType:

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

الطرق​

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

تطبيق الخصم عند الدفع​

تحقّق من الرمز الذي يُدخله العميل باستخدام validateDiscountsCoupon()، ثم مرّره بوصفه couponCode إلى Orders.previewOrder() للحصول على الإجماليات بعد الخصم، وإلى Orders.createOrder() عند تقديم الطلب. لتطبيق خصم بدون قسيمة، مرّر علامته في additionalDiscountsMarkers. تطبّق المنصة الخصومات والقسائم عند حساب الطلب، لذا لا تُعِد حساب الأسعار على جانب العميل. استخدم getDiscountByMarker() فقط لعرض خصم (مثلًا، discountValue الخاص به). تتطلب createOrder() تفويض المستخدم.

تُعيد validateDiscountsCoupon() الكائن ICouponValidationResult: { valid: boolean; coupon?; error? }. إذا لم تكن القسيمة موجودة أو كانت قسيمة الاستخدام الواحد قد استُخدمت بالفعل، تكون valid بقيمة false ويحتوي error على السبب (مثل "Coupon not found"). لا يتحقق التحقق من القسيمة من startDate/endDate الخاصين بالخصم، لذا تحقّق منهما بنفسك (راجع فترة الصلاحية).

فترة الصلاحية​

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

شارات الخصم على المنتجات​

اجلب جميع الخصومات باستخدام getAllDiscounts()، وطابقها مع المنتجات وفق منطق عملك الخاص، واعرض شارة من localizeInfos.title وdiscountValue.value. نادرًا ما تتغير الخصومات، لذا خزّنها مؤقتًا عند التحميل بدلًا من استدعاء API مرارًا. للأسماء متعددة اللغات، استخدم localizeInfos.


ذات صلة​

  • Products: المنتجات التي تُطبق عليها الخصومات
  • Orders: معاينة الطلبات وإنشاؤها مع تطبيق الخصومات
  • Payments: مدفوعات الطلبات المخفّضة
  • Locales: أسماء الخصومات متعددة اللغات