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: أسماء الخصومات متعددة اللغات