التكامل مع ووكومرس (WooCommerce)

تشرح هذه الصفحة ربط متجر ووكومرس بنظام نما: استيراد طلبات المتجر كمستندات مبيعات، وإرسال الأصناف والأسعار والكميات إلى المتجر، وإعادة كتابة حالة الطلب وملاحظاته فيه، وتوحيد رصيد نقاط المكافأة للعميل بين نما والمتجر.

يُعَدّ ووكومرس على الشاشة نفسها التي تُعَدّ عليها كل المتاجر، واسمها على الشاشة Magento Site لكل المنصات وليس لماجنتو وحده، وتحتاج إلى ترخيص magento لفتحها. أما ما تشترك فيه المنصات كلها — بيانات توليد الطلبات والمرتجعات، والدفاتر والتوجيهات، والعملاء، وسطور طرق الدفع، وملف ربط الأصناف بموقع ماجنتو، والقراءة المجدولة — فمشروح في دليل تكامل التجارة الإلكترونية، وتقتصر هذه الصفحة على ما يخص ووكومرس.

كيف يتخاطب النظامان

يتصل نما بووكومرس عبر واجهة REST القياسية للمتجر، فلا يلزم تثبيت أي شيء في ووردبريس من أجل الطلبات والأصناف والأسعار والكميات وحالات الطلبات. يطلب نما الطلبات الجديدة من المتجر عند الضغط على قراءة المبيعات (أو وفق جدول)، ويتصل بالمتجر كلما تغيّر في نما شيء مضبوط على إرساله.

الاستثناء الوحيد هو مزامنة نقاط المكافأة، فهي تحتاج إلى نقاط اتصال إضافية في ووردبريس، كما يأتي في قسم نقاط المكافأة أدناه.

ربط المتجر

أنشئ أولًا مفتاح REST API في ووكومرس من WooCommerce ← Settings ← Advanced ← REST API ← Add key بصلاحية Read/Write. يعرض لك ووكومرس عندها Consumer Key (يبدأ بـ ck_) وConsumer Secret (يبدأ بـ cs_)، فانسخهما قبل مغادرة الصفحة.

ثم أنشئ سجل Magento Site في نما:

1. اختر في Site Type القيمة Woo Commerce Site.
2. اكتب في رابط عنوان المتجر مع البادئة، مثل https://shop.example.com، ويضيف نما مسار الواجهة بنفسه.
3. الصق الـ Consumer Key في إسم المستخدم (Consumer Key)، والـ Consumer Secret في كلمة المرور (Consumer Secret).
4. اكتب في Date Pattern القيمة yyyy-MM-dd'T'HH:mm:ss. بهذه الصيغة يكتب ووكومرس تواريخه، وبها يقرأ نما تواريخ الطلبات ويرسل تواريخ أسعار التخفيض، فاعتبرها إعدادًا لازمًا لووكومرس.
5. املأ إعدادات الطلبات الموضحة أدناه وفي الدليل المشترك، ثم احفظ.

استخدم https

مع عنوان يبدأ بـ https:// يرسل نما المفتاح والسر كمصادقة قياسية عبر اتصال مشفّر. استخدم https لأي متجر متاح على الإنترنت.

قراءة الطلبات من المتجر

اختر حالة واحدة فقط

لكل طلب في ووكومرس حالة: pending أو processing أو on-hold أو completed أو cancelled أو refunded أو failed. اكتب في نقل فقط الأوامر التي حالتها احدي التالي حالة ووكومرس الواحدة التي تريد استيرادها — وهي في أغلب المتاجر processing، أي الحالة التي يعطيها ووكومرس للطلب المدفوع المنتظر للشحن. عندها يطلب نما من المتجر طلبات هذه الحالة وحدها.

وإذا تركت الحقل فارغًا قرأ نما الطلبات التي حالتها pending.

حجم الدفعة ونقطة البداية

يحدد Max Orders Per Read عدد الطلبات التي يطلبها نما في الطلب الواحد. القيمة الافتراضية 25، وأقصى ما يقبله ووكومرس 100، فأي قيمة أكبر تُعامل على أنها 100. ويستمر نما في الطلب صفحةً بعد صفحة حتى يقرأ كل ما هو أحدث من نقطة البداية.

كل قراءة المبيعات تكمل من حيث توقفت السابقة. أما أول قراءة فاستخدم لها قراءة المبيعات من تاريخ وحدد تاريخًا، ليبدأ نما منه بدل قراءة تاريخ طلبات المتجر كله.

يصبح كل طلب مستند مبيعات وفق إعدادات Order Info، ويُربط بعميله وبسطور طرق الدفع تمامًا كما يشرح الدليل المشترك. وطريقة الدفع التي يقرؤها نما من طلب ووكومرس هي الاسم المختصر للطريقة كما يخزنه ووكومرس (مثل cod أو bacs)، فاستخدم هذا النص في سطور طرق الدفع.

رسالة النجاح لا تعني أن كل الطلبات استُوردت

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

ما يرسله نما إلى المتجر

يجب تفعيل الإرسال على مستوى الخادم

لا يرسل نما شيئًا إلى أي متجر — لا أصناف ولا أسعار ولا كميات ولا حالات طلبات ولا ملاحظات — ما لم يحتوِ ملف nama.properties على الخادم على السطر send-ecommerce-data=true.

الأصناف

عند تأشير إرسال الأصناف إلي ماجنتو يُرسَل الصنف إلى المتجر عند حفظه (ويشرح الدليل المشترك أي الأصناف تُرسل). يبحث نما عن المنتج بالـ SKU: فإن لم يجد في المتجر منتجًا بهذا الـ SKU أنشأه، وإلا حدّث المنتج الموجود.

المتاجر التي تنشر كل منتج بأكثر من لغة (بإضافة ترجمة مثل WPML) تحتفظ بنسخة منفصلة من المنتج لكل لغة. وفي تبويب Woo Commerce Site حقلان يجعلان نما يحدّث هذه النسخ أيضًا:

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

الأسعار

تخرج الأسعار عبر مستند تحديث أسعار ماجنتو. يُكتب السعر في السعر العادي للمنتج مقرّبًا إلى خانتين عشريتين. أما السعر الخاص فيُرسل كسعر التخفيض في ووكومرس مع تواريخه، لذا أعطِ كل سعر خاص السعر الخاص من تاريخ والسعر الخاص إلى تاريخ معًا. وتعتمد تواريخ التخفيض على Date Pattern المضبوط عند ربط المتجر.

كميات المخزون

يرسل نما رصيد كل منتج ككمية إجمالية واحدة: يفعّل خيار Manage stock للمنتج في ووكومرس، ويضبط الكمية، ويضبط حالة التوفر. ويخزن ووكومرس المخزون بأعداد صحيحة، فيُسقَط الكسر: 7.6 وحدة في نما تصل 7.

اترك جدول ربط معرفات المخازن الإلكترونية بنما فارغًا في موقع ووكومرس. الكمية التي تُرسل هي الإجمالي الذي تحسبه إعدادات الكميات في الموقع (راجع الدليل المشترك)، والإجراء تحديث كميات جميع الأصناف يعيد إرسال كميات كل الأصناف دفعة واحدة.

إذا أُرسل سعر أو كمية لـ SKU لا يعرفه المتجر فشل الطلب بالرسالة التالية، وهي تظهر بالإنجليزية لأنه لا نص عربي لها:

Could not find product with sku {0}

أنشئ المنتج في المتجر (أو دع نما ينشئه بحفظ الصنف)، ثم أعد محاولة الطلب من قائمة طلبات الأسعار أو الكميات في تبويب الإحصائيات.

حالة الطلب وملاحظاته

يستطيع نما أن ينقل طلب ووكومرس إلى حالة جديدة عند اعتماد مستند المبيعات المقابل له في نما — مثل جعل الطلب completed بمجرد حفظ فاتورته.

1. أشّر على تحديث حالة الطلب في ماجنتو بعد حفظ مستند المبيعات.
2. أضف سطورًا في تحديث حالة طلب ماجنتو إلي. استخدم تطبيق عند التوافق مع الاستعلام (أو عمود المعايير) لتحديد المستندات التي ينطبق عليها السطر، واكتب في الحالة الاسم المختصر لحالة ووكومرس المطلوبة، مثل completed.
3. املأ ملاحظة إن أردت، فيضيفها نما إلى الطلب كـ ملاحظة طلب (order note)، ويمكن أن يستخدم نصها حقول المستند، مثل Invoiced in Nama as {code}. وأشّر على عرض الملحوظه للعميل لتُضاف كملاحظة موجهة للعميل بدل ملاحظة داخلية.

عند اعتماد المستند يقرأ نما الطلب من المتجر من جديد، ثم يضبط الحالة ويضيف الملاحظة. ولا يرسل الحالة إلا إذا اختلفت عن آخر حالة أرسلها لهذا المستند، ولا الملاحظة إلا إذا اختلف نصها عن آخر ملاحظة، فإعادة حفظ المستند لا تكررهما.

نقاط المكافأة (Reward Points)

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

ما يحتاجه المتجر

تعمل المزامنة مع إضافة YITH WooCommerce Points and Rewards في المتجر. ويستدعي نما كذلك نقطتي اتصال ليستا من ووكومرس القياسي: واحدة لقراءة نقاط العميل وأخرى لتعديلها. يجب أن تُثبَّت نقاط اتصال النقاط الخاصة بنما في ووردبريس — اطلبها من دعم نما.

الإعداد في نما

1. افتح إعدادات نقاط المكافأة التي تحكم النقاط (الأساسيات ← المستندات ← إعدادات نقاط المكافأة؛ وطريقة كسب النقاط مشروحة في نقاط مكافآت العملاء).
2. اختر في مزامنة نقاط المكافأة مع متجر ووكوميرس سجل Magento Site الخاص بووكومرس. لا يشارك في المزامنة إلا موقع نوعه Woo Commerce Site.
3. املأ دفتر قسيمة خصومات في الإعدادات نفسها، فنما يحتاجه لإنشاء القسائم الموضحة أدناه.
4. تأكد أن الموبايل لكل عميل في نما هو الرقم نفسه، وبالصيغة نفسها، الذي يستخدمه العميل كهاتف الفوترة في المتجر. فرقم الموبايل هو ما يتعرّف به النظامان على العميل نفسه، والعميل الذي ليس له موبايل في نما لا تتم مزامنته.

من نما إلى المتجر

يرسل نما تغيّر النقاط إلى المتجر عندما:

• يمنح مستندٌ العميلَ نقاطًا، أو تتغير نقاط ذلك المستند؛
• يتغير عميل المستند (فتنتقل النقاط من العميل القديم إلى الجديد)؛
• يُعكس المستند (فتُسترد النقاط)؛
• تُسترد أو تُلغى قسيمة خصومات في نما مرتبطة بالإعدادات.

يُرسل كل تغيّر كنقاط صحيحة مع سبب قصير بالإنجليزية، مثل From namasoft erp SalesInvoice: SI-000125.

وقبل الإرسال يتحقق نما مما إذا كان المتجر يعرف رقم هاتف العميل. فإن لم يعرفه وكان السجل عميلًا في نما، أنشأ نما العميل في المتجر أولًا باسمه وبريده الإلكتروني وهاتفه.

والفاتورة المستوردة أصلًا من متجر ووكومرس نفسه لا تُرسل نقاطها إليه، لأن المتجر منح العميل نقاط هذا الطلب بالفعل.

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

من المتجر إلى نما: تحويل النقاط إلى قسيمة

في YITH يستطيع العميل تحويل نقاطه إلى قسيمة خصم. ولكي تُخصم هذه النقاط في نما، أضف webhook في ووكومرس (WooCommerce ← Settings ← Advanced ← Webhooks ← Add webhook) بالموضوع Coupon created وبرابط التسليم التالي:

{عنوان نما لديك}/woo-points/{كود إعدادات نقاط المكافأة}

فمثلًا إذا كان المستخدمون يفتحون نما على https://erp.example.com/erp وكود الإعدادات RP-WEB، يكون الرابط https://erp.example.com/erp/woo-points/RP-WEB.

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

من المتجر إلى نما: إنفاق النقاط في طلب

يستطيع العميل أيضًا إنفاق نقاطه مباشرة عند الدفع. وعندما يستورد نما طلبًا فيه خصم نقاط من YITH، يسترد المبلغ نفسه من نقاط العميل في نما. وإذا استخدم الطلب قسيمة نقاط وصلت إلى نما من قبل عبر الـ webhook فلا يُخصم شيء إضافي، وإعادة قراءة الطلب نفسه لا تخصم مرتين أبدًا. والطلب المحفوظ كمسودة لا يخصم شيئًا.