المرجع التقني لخصومات POS

تشرح هذه الصفحة كيفية تعامل WCPOS مع تعديلات أسعار البنود التي يُجريها أمين الصندوق — كيفية تخزينها، وكيفية تفاعلها مع قسائم WooCommerce، والمرشحات المتاحة. للاطلاع على التوثيق الموجّه للمستخدمين، راجع خصومات سلة التسوق والقسائم.

كيفية تخزين تعديلات أسعار POS

عندما يُحدّد أمين الصندوق سعر بند ما أو يُغيّره في نقطة البيع، تُخزَّن أسعار الوحدة في البيانات الوصفية للبند _woocommerce_pos_data بتنسيق JSON:

{
  "price": "16.00",
  "regular_price": "18.00",
  "tax_status": "taxable"
}

بالنسبة للمنتجات المتنوعة (المخصصة)، يمكن أن تحمل هذه البيانات الوصفية أيضًا حقول virtual وdownloadable وcategories المُستخدمة أثناء التحقق من صلاحية القسائم.

تُعدّ هذه البيانات الوصفية المصدر المرجعي لأسعار الوحدة للبند. يُشتق subtotal المُخزَّن في WooCommerce على البند من price * qty (مع استخلاص الضريبة والتقريب). قد يكون total المُخزَّن أقل عند تطبيق خصومات القسائم، لذا للحصول على دقة سعر الوحدة يجب دائمًا قراءة _woocommerce_pos_data.price وregular_price.

تسجل طلبات نقاط البيع الجديدة أيضًا إصدار إضافة الخادم في بيانات الطلب الوصفية الخاصة _woocommerce_pos_version. وهذا يوفر علامة إصدار صريحة لفحوصات التوافق المستقبلية. ومع ذلك، تظل حسابات الإيصال معتمدة على بنية بند الطلب المخزنة، إذ قد يقبل خادم أحدث طلبًا أُنشئ دون اتصال بواسطة تطبيق أقدم.

نموذج المجموع الفرعي (v1.9.0+)

اعتبارًا من الإصدار v1.9.0، يتوافق WCPOS مع دلالات سعر التخفيض الأصلية في WooCommerce:

• line_item.subtotal = price * qty حيث price هو سعر POS (بعد أي تعديل).
• line_item.total = subtotal - coupon_discount_for_line.
• يعكس order.discount_total خصومات القسائم فقط، وليس تعديلات أسعار POS.

يتطابق هذا مع طريقة معالجة WooCommerce لمنتج معروض للبيع: يصبح sale_price هو المجموع الفرعي، ويُخصَّص discount_total للقسائم. لا يوجد سطر منفصل لـ "خصم POS" في الطلب.

الترحيل من الإصدارات السابقة لـ 1.9.0

كانت الإصدارات السابقة ترسل subtotal = regular_price * qty، مما جعل WooCommerce يحسب discount_total = subtotal - total ويُدرج تعديلات أسعار POS كخصم. تم تغيير هذا لأنه تعارض مع حسابات القسائم: تستخدم recalculate_coupons() قيمة subtotal كسعر أساسي، وبالتالي كانت القسائم تُحسب على السعر الأصلي وتُنتج إجماليات غير صحيحة.

تمت إزالة الحل البديل السابق على جانب الخادم — فلتر woocommerce_order_item_get_subtotal النشط أثناء recalculate_coupons() — في الإصدار 1.9.0. راجع سجل القرار المعماري للاطلاع على التاريخ الكامل.

سلوك التفاعل مع القسائم

دعم القسائم هو ميزة في WCPOS Pro. عند تطبيق قسيمة على طلب يحتوي على عناصر مخفضة عبر POS:

1. تُحسب القسيمة على أساس السعر المخفض عبر POS (القيمة في _woocommerce_pos_data.price)، وليس على regular_price الأصلي.
2. عند إزالة القسيمة، يعود سطر العنصر إلى سعره المخفض عبر POS.

سلوك exclude_sale_items

تُعامَل العناصر المخفَّضة عبر نقطة البيع على أنها "معروضة للبيع" من قِبَل WooCommerce عندما يكون _woocommerce_pos_data.price < regular_price. لذلك ستتخطاها القسائم التي تم تفعيل exclude_sale_items فيها، وهذا يتوافق مع طريقة معالجة WooCommerce لأسعار التخفيض العادية.

إذا كنت بحاجة إلى سلوك مختلف، راجع فلتر woocommerce_pos_item_is_on_sale أدناه.

الفلاتر المتاحة

woocommerce_pos_item_is_on_sale

تجاوز ما إذا كان العنصر المخفَّض عبر نقطة البيع يُعتبر "معروضًا للبيع" لأغراض التحقق من صلاحية القسائم.

add_filter( 'woocommerce_pos_item_is_on_sale', function ( $is_on_sale, $product, $item, $pos_data ) {
    // Allow coupons with exclude_sale_items to apply to POS-discounted items
    return false;
}, 10, 4 );

المعاملات:

المعامل	النوع	الوصف
$is_on_sale	bool	ما إذا كان العنصر يُعتبر معروضًا للبيع (الافتراضي: price < regular_price)
$product	WC_Product	كائن المنتج
$item	WC_Order_Item_Product	بند الطلب
$pos_data	array	بيانات JSON المفكَّكة لـ _woocommerce_pos_data

نقطة نهاية REST API

توجد نقطة نهاية REST للقسائم في الإضافة المجانية على المسار /wp-json/wcpos/v1/coupons بحيث لا يتلقى تطبيق نقطة البيع خطأ 404 عند الاستعلام عن القسائم — حتى في المواقع التي لا تحتوي على WCPOS Pro. ومع ذلك، تتطلب ميزة القسائم الموجهة للمستخدم إصدار Pro.

يوسّع المتحكم WC_REST_Coupons_Controller بإضافات خاصة بنقطة البيع:

• معالجة UUID للمزامنة بأولوية عدم الاتصال
• صلاحية access_woocommerce_pos للتحقق من الأذونات
• مسار استعلام مُحسَّن للمعرّفات المجمّعة عند طلب posts_per_page=-1 وfields=id (أو fields=id,date_modified_gmt)

عرض بيانات الإيصال

يكشف منشئ بيانات الإيصال (Receipt_Data_Builder) عن:

• lines[].discounts، lines[].discounts_incl، lines[].discounts_excl — مبلغ الخصم لكل بند، يُحسب كـ subtotal - total. اعتبارًا من الإصدار v1.9.0 يعكس هذا خصومات القسائم فقط لتجاوزات أسعار نقطة البيع، حيث أن subtotal === total عند عدم تطبيق قسيمة.
• totals.discount_total، totals.discount_total_incl، totals.discount_total_excl — إجمالي خصم القسائم على مستوى الطلب من WC_Order::get_discount_total().
• totals.sale_savings_total وtotals.sale_savings_total_incl وtotals.sale_savings_total_excl — إجمالي التوفير المسجل نتيجة الفرق بين السعر العادي وسعر البيع في بنود المنتجات، بما في ذلك أسعار التخفيض في الكتالوج وتعديلات نقطة البيع.
• totals.total_saved وtotals.total_saved_incl وtotals.total_saved_excl — إجمالي خصومات WooCommerce والتوفير الناتج عن السعر العادي معًا. يستثني المُنشئ وفورات البنود الممثلة مسبقًا في إجمالي خصم WooCommerce لطلب سابق للإصدار v1.9.0.
• totals.total_saved_complete — تكون قيمته false إذا افتقر أي بند إلى ما يكفي من بيانات الأسعار المسجلة لإجراء تجميع موثوق؛ وتكون إجماليات الوفورات التي تقبل القيمة null بهذه القيمة في هذه الحالة.
• discounts[] — مصفوفة بنود القسائم تتضمن label وcode وtotal.

تُستبعد البيانات الوصفية لبند الطلب التي تبدأ بشرطة سفلية (بما فيها _woocommerce_pos_data) من lines[].meta بواسطة Receipt_Data_Builder::get_item_meta_pairs(). وبدلًا من ذلك، تعرض Receipt Data v1.1 السعر العادي المسجل وسعر البيع قبل القسيمة ووفورات البنود وإجمالي الوفورات عبر حقول أساسية موحدة. راجع عرض السعر العادي والوفورات والإجماليات للاطلاع على أمثلة النماذج.

ذو صلة

• خصومات سلة التسوق — دليل المستخدم لتطبيق الخصومات من قِبل أمين الصندوق
• القسائم — دليل المستخدم لقسائم WooCommerce في نقطة البيع (Pro)