التكامل مع زد (Zid)

تشرح هذه الصفحة ربط متجر على منصة زد (zid.sa) بنظام نما ERP: طريقتا تفويض الاتصال، وكيف تُقرأ طلبات زد إلى نما، وما يرسله نما إلى زد من أسعار وكميات، وكيف تُجمع السلال المتروكة.

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

قبل أن تبدأ

لا تعطي زد نظام نما اسم مستخدم وكلمة مرور، بل تمنحه رمز وصول (Access Token) بعد أن يوافق صاحب المتجر على الربط، ثم يجدد نما هذا الرمز بنفسه بعد ذلك. وللحصول على الرمز أول مرة طريقتان، والفرق بينهما في صاحب التطبيق المسجَّل لدى زد:

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

وأيًّا كانت الطريقة، لا يُحفظ السجل قبل تعبئة حقلين في التبويب الذي يحمل اسم زد:

الحقل	ما تكتبه فيه
معرف المخزن الإلكتروني (Ecommerce Store ID)	رقم المتجر الذي تعطيه زد للمتجر. يرسله نما مع كل طلب يخص المنتجات والمخزون.
كلمة مرور التطبيق الإلكتروني (Ecommerce App Token)	تشترط الشاشة وجود قيمة فيه، لكن الربط لا يستخدمه، فأي قيمة تصلح.

عند اختيار Zid Site يملأ نما حقل رابط بالقيمة https://api.zid.sa/، وحقل Redirect URL بعنوان بوابة نماسوفت الخاص بزد. اترك حقل رابط كما هو.

الربط عبر بوابة نماسوفت

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

1. اطلب من دعم نماسوفت بيانات البوابة: Gateway URL (Server Url) وGateway Client ID وGateway Client Secret.
2. تأكد أن الإعداد العام serverid مضبوط في ملف nama.properties على خادم نما لديك. قيمته هي رقم ترخيص نما الذي سيكتبه التاجر في الخطوة التالية.
3. يثبّت التاجر تطبيق نماسوفت من لوحة تحكم متجره في زد ويوافق عليه، فتُفتح صفحة تطلب رقم ترخيص نما. يكتب التاجر القيمة نفسها الموجودة في serverid ويحفظها.
4. افتح شاشة Magento Site في نما وأنشئ السجل: Site Type = Zid Site، مع معرف المخزن الإلكتروني وكلمة مرور التطبيق الإلكتروني كما سبق.
5. املأ حقول البوابة الثلاثة من الخطوة الأولى. هذه الحقول ليست في تبويب زد، بل في التبويب الذي يحمل اسم سلة (Salla)، لأن سلة وزد تستخدمان البوابة نفسها. ثم احفظ السجل.
6. اضغط Read Ecommerce Access Token. يطلب نما من البوابة الرمز الناتج عن التثبيت ويحفظه في السجل، ومن بعدها يجدد الرمز بنفسه.

وإذا توقفت زد لاحقًا عن قبول الاتصال، فالضغط على Read Ecommerce Access Token مرة أخرى يجلب الرمز الحالي من البوابة.

الربط بتطبيق العميل الخاص على زد

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

1. من حساب العميل في بوابة شركاء زد، أنشئ تطبيقًا واحتفظ بقيمتي Client ID وClient Secret. وسجّل العنوان https://www.namasoft.com/googleauth.html عنوانًا لإعادة التوجيه (Callback URL) في التطبيق.
2. أنشئ سجل Magento Site واختر Site Type = Zid Site، ثم املأ:
   • إسم المستخدم (Consumer Key): قيمة Client ID للتطبيق.
   • كلمة المرور (Consumer Secret): قيمة Client Secret للتطبيق.
   • Redirect URL: غيّره إلى https://www.namasoft.com/googleauth.html. القيمة التي يملؤها نما تلقائيًا هي عنوان بوابة نماسوفت، ولا تعمل إلا مع تطبيق نماسوفت نفسه.
   • معرف المخزن الإلكتروني وكلمة مرور التطبيق الإلكتروني كما سبق.
3. احفظ السجل، ثم اضغط Request Token. وعندما يسألك نما Use Gateway Server أجب بـ لا.
4. تُفتح نافذة جديدة على صفحة التفويض في زد. سجّل الدخول بصفتك صاحب المتجر ووافق على التطبيق. تعود زد بعدها إلى صفحة نماسوفت، فتظهر عبارة "Response sent correctly" حين يستلم خادم نما الموافقة، ثم تُغلق الصفحة نفسها بعد عشر ثوانٍ. حدّث السجل، وستجد حقلي Authorization Code وRefresh Token قد امتلآ.

يجدد نما الرمز بنفسه مستخدمًا Client ID وClient Secret، فلا تمسح إسم المستخدم (Consumer Key) وكلمة المرور (Consumer Secret) بعد نجاح الربط.

كيف تصل طلبات زد إلى نما

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

أي الطلبات تُقرأ

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

الرمز	معناه في زد
new	طلب جديد
preparing	جاري التجهيز
ready	جاهز للشحن
indelivery	جاري التوصيل
delivered	تم التوصيل
cancelled	ملغي

فمثلًا القيمة ready,delivered تُدخل الطلب إلى نما متى صار جاهزًا للشحن، وتترك الطلبات الجديدة والملغاة في زد. وإذا تُرك الحقل فارغًا قُرئت الطلبات أيًّا كانت حالتها.

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

كم يُقرأ في المرة الواحدة

• يحدد Max Orders Per Read عدد الطلبات التي يطلبها نما من زد في الصفحة الواحدة. حدّ زد هو 100، فأي قيمة أكبر تُعامل على أنها 100.
• تغطي القراءة الواحدة 100 يوم على الأكثر. يبدأ زر قراءة المبيعات من تاريخ من التاريخ الذي تدخله، أما قراءة المبيعات والقراءة المجدولة فتكملان من تم التحديث حتى تاريخ، وهو تاريخ أحدث طلب سبقت قراءته. وتصفّي زد بالتاريخ وحده دون الوقت.
• اجعل أول قراءة بزر قراءة المبيعات من تاريخ. فما دام تم التحديث حتى تاريخ فارغًا، يطلب زر قراءة المبيعات من زد كامل تاريخ طلبات المتجر.
• يجلب نما تفاصيل كل طلب على حدة، وإذا طلبت منه زد أن يبطئ انتظر بضع ثوانٍ ثم أكمل، لذا قد تستغرق القراءة الأولى الكبيرة بعض الوقت.

يتعرف نما على طلب زد برقم الطلب في زد، فإعادة قراءة الطلب نفسه لا تنشئ مستندًا ثانيًا. ويشرح الدليل المشترك ما يحدث إذا تغيّر طلب سبقت قراءته.

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

ما يأتي مع كل طلب

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

تجيب زد نظام نما باللغة العربية، لذا تصل أسماء المدن وأسماء طرق الدفع والشحن بالعربية.

وهناك بيانات لا تأتي من زد: الشارع والحي ورقم المبنى والرمز البريدي في العنوان، واسم عائلة العميل، وحركات الدفع وأرقامها، وخيارات المنتج مثل المقاس واللون.

ما يرسله نما إلى زد

يجد نما منتج زد المقابل للصنف عن طريق الـ SKU، لذا يجب أن يطابق الـ SKU في زد الـ SKU المحفوظ للصنف في نما (يشرح الدليل المشترك ربط الأصناف). ثم يحدّث نما في ذلك المنتج ما يلي:

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

ويشرح الدليل المشترك متى تُرسل الأسعار والكميات، وكيف يعيد زر تحديث كميات جميع الأصناف إرسال كل الكميات. ولا يرسل نما إلى زد التصنيفات ولا الصور ولا الأوصاف ولا العملاء.

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

لا يُرسل أي شيء إلى أي متجر ما لم يحتوِ ملف nama.properties على الخادم على السطر send-ecommerce-data=true.

الكميات لكل موقع مخزون في زد

إذا كان المتجر يحتفظ بمخزونه في أكثر من موقع مخزون (Inventory Location) في زد، فيمكنك إرسال كمية مستقلة لكل موقع. املأ جدول ربط معرفات المخازن الإلكترونية بنما: سطر لكل مخزن في نما، وفي عمود معرف مخزن الموقع موقع زد المقابل. ولموقع زد يعرض هذا العمود قائمة بمواقع المتجر في زد، فتختار الموقع بدل كتابة رقمه.

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

السلال المتروكة

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

تُحفظ كل سلة مستندًا يُحدَّد نوعه من خلال جدول سطور إنشاء مستندات بناءا على تطابق من الأمر. أضف سطرًا قيمة نوع مستند ماجنتو فيه Abandoned Cart، وحدد له في استيراد كـ نوع المستند ودفتره وتوجيهه الذي تريد حفظ السلال به، كعرض سعر مثلًا. وبدون هذا السطر تُحفظ السلال بإعدادات Order Info، أي كما تُحفظ الطلبات الحقيقية.

تقرأ كل مرة حتى 100 يوم من السلال بدءًا من Last Abandoned Cart Read Date في السجل، وتقدّم هذا التاريخ كلما حُفظت سلال.

رسائل قد تظهر لك

لا توجد ترجمة عربية لهذه الرسائل، عدا الرسالتين المشار إليهما في الجدول، لذا تظهر بالإنجليزية في الواجهة العربية أيضًا.

الرسالة	السبب	ما العمل
«لا يمكن استخدام الزرار الا لمتجر زد وسلة»	ضُغط زر Request Token في سجل ليس من نوع زد ولا سلة.	اختر Zid Site في Site Type أولًا.
«من فضلك ادخل قيمه الحقل Gateway URL» (من زر Request Token)، وتظهر من زر Read Ecommerce Access Token بالإنجليزية: Please fill field Gateway URL	عنوان البوابة غير موجود.	املأ Gateway URL (Server Url) في التبويب الذي يحمل اسم سلة.
Please set General Setting serverid	لا يوجد على الخادم رقم ترخيص يرسله إلى البوابة.	اضبط الإعداد العام serverid على رقم ترخيص نما.
Please set Gateway Client Id / Please set Gateway Client Secret	أحد بيانات اعتماد البوابة فارغ.	املأه بالقيمة التي قدمها دعم نماسوفت.
رسالة تبدأ بـ Gateway returned يتبعها رمز حالة وسبب الرفض من البوابة	رفضت البوابة الطلب. فإذا كان السبب مثلًا No installation matched the supplied license id فمعناه أنه لا يوجد تثبيت لزد مسجل برقم ترخيصك.	تأكد أن التاجر ثبّت تطبيق نماسوفت وكتب رقم الترخيص نفسه الموجود في serverid، وأن بيانات اعتماد البوابة صحيحة.
Gateway did not return a token	ردّت البوابة لكن لم يكن لديها رمز لهذا المتجر.	تأكد أن التاجر أكمل تثبيت التطبيق، ثم اضغط Read Ecommerce Access Token مرة أخرى.
Failed to {0} error code: {1} message: {2}	رفضت زد طلبًا، مثل تحديث سعر أو كمية. يذكر {0} العملية، و{2} هو تفسير زد نفسها.	تصرّف حسب تفسير زد. وعدم العثور على المنتج يعني غالبًا أن الـ SKU في زد لا يطابق الصنف.
method readReturns not implemented for site of type {0}	ضُغط زر قراءة المردودات في موقع زد.	المرتجعات تدخل عبر قراءة الأوامر كمرتجع إذا كانت إحدى الحالات الأتية عند قراءة المبيعات.
The method readAbandonedCart is available for sites with type ZID only	شُغّل مسار كيان السلال المتروكة لموقع ليس من نوع زد.	مرّر كود موقع من نوع زد.
Another readAbandonedCarts is already running for site {0} ; skipping to avoid blocking on long-running JDBC work.	كانت قراءة سابقة للسلال المتروكة للموقع نفسه ما زالت تعمل.	لا شيء، فالتشغيل التالي يكمل. وإذا تكرر ذلك كثيرًا فباعد بين مرات الجدولة.
Can not find site with code {0}	كود الموقع المُمرَّر لمسار الكيان غير موجود.	صحّح الكود في مدخلات المهمة المجدولة.