التكامل مع سلاسه (Salasa)

تشرح هذه الصفحة طريقة ربط نما ERP بشركة سلاسه، شركة الخدمات اللوجستية (3PL) التي تخزّن بضاعتك في مستودعاتها وتشحن طلباتك: السجلّان اللذان تحتاج إلى إعدادهما، وكيف تصل تنبيهات سلاسه (Webhooks) إلى نما، وما المستند الذي يُنشأ أو يُحدَّث في نما مع كل حدث من سلاسه.

سلاسه ليست متجرًا إلكترونيًا، بل هي المستودع وشركة التوصيل اللذان يقفان خلف متاجرك. فبعد أن تستقر البضاعة في مستودع سلاسه، تقع الأحداث المهمة عندها: تصل دفعة توريد جديدة، أو يعيد عميل بضاعة، أو تنتقل شحنة من «قيد التجهيز» إلى «تم التسليم»، أو يصل طلب من جاهز. وفي كل حالة من هذه تتصل سلاسه بنما عبر تنبيه، فيحوّل نما الاتصال إلى مستند أو إلى تحديث على مستند قائم. نما لا يسأل سلاسه دوريًا عن الطلبات؛ والشيء الوحيد الذي يقرؤه نما من سلاسه عند الطلب هو لقطة من رصيد المخزون لديها، عن طريق مسار الكيان EAReadSalasaInventoryData.

سجلّان لكلٍّ منهما دور

يُعَدّ الربط على سجلّين:

1. موقع شحن الكتروني نوعه Salasa. هو السجل الرئيسي، وفيه بيانات الدخول إلى سلاسه، وقائمة التنبيهات، والمخزنان، ودفاتر وتوجيهات المستندات التي ينشئها نما من أحداث سلاسه. معظم الإعداد يتم هنا.
2. سجل على شاشة Magento Site نوعه (Site Type) هو Salasa. وله مهمة واحدة فقط: أن يكون إعداد استيراد الطلبات التي تحوّلها سلاسه من جاهز. فنما يحفظ هذه الطلبات تمامًا كما يحفظ طلبات أي متجر إلكتروني، ولذلك يحتاج إلى إعدادات الطلبات المعتادة (نوع المستند ودفتره وتوجيهه، والعملاء، وطرق الدفع، وربط الأصناف)، وهذه الإعدادات موجودة على شاشة Magento Site. تحمل الشاشة اسم Magento Site في اللغتين حتى لو لم يكن السجل متجر ماجنتو، وتحتاج إلى ترخيص magento.

يشير موقع الشحن إلى سجل Magento Site من خلال الحقل Save Salasa Orders Using Magento Site، لذلك أنشئ سجل Magento Site أولًا.

الخطوة 1: سجل Magento Site لطلبات جاهز

1. افتح شاشة Magento Site وأنشئ سجلًا واختر في Site Type القيمة Salasa. يُفرغ نما حقل رابط عند اختيار Salasa؛ اتركه فارغًا، لأن طلبات سلاسه لا تأتي من عنوان مسجّل على هذا السجل.
2. املأ إعدادات الطلبات كما تفعل لأي متجر إلكتروني: Order Info (نوع المستند الذي ينشئه نما ودفتره وتوجيهه)، وإعدادات العملاء، وسطور طرق الدفع، وربط الأصناف. يشرح دليل تكامل التجارة الإلكترونية كل واحد منها.
3. احفظ السجل.

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

الخطوة 2: موقع الشحن الإلكتروني

افتح تكامل التجارة الإلكترونية ← الملفات ← موقع شحن الكتروني وأنشئ سجلًا جديدًا. يبدأ حقل النوع بالقيمة Oto؛ غيّره إلى Salasa. كل ما يلي يُفحص عند الحفظ، فالأسهل أن تملأه كله مرة واحدة.

بيانات الدخول (صفحة الرئيسية)

الحقل	ما تُدخله
اسم المستخدم (Username)	رقم الحساب في سلاسه.
كلمة المرور (Password)	الرمز السري (secret) في سلاسه.
Nama API Key	مفتاح API من نما. يُسلَّم الرمز السري لهذا المفتاح إلى سلاسه عند إنشاء التنبيهات، وترسله سلاسه مع كل اتصال. لا يقبل نما الاتصال إلا بهذا المفتاح، وينفّذ العمل باسم المستخدم المرتبط به، لذلك يجب أن يملك هذا المستخدم صلاحية إنشاء سندات التحويل المخزني ومردودات المبيعات والصرف المخزني، وتعديل فواتير المبيعات وأوامر البيع.

حقل رابط غير مستخدم مع سلاسه، فنما يعرف عنوانها مسبقًا. يدخل نما إلى سلاسه برقم الحساب والرمز السري، ويحتفظ على السجل بمفتاح الوصول (access token) الذي تعيده سلاسه، ويعيد استخدامه حتى تنتهي صلاحيته.

جدول حالات لتشغيل مسار كيان (صفحة الرئيسية)

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

shipped، in transit، delivered، pending، processing، return، cancelled، backorder

مثال لجدول معتاد:

الحالة	تغيير حالة التوصيل إلي
processing	بإنتظار التوصيل
shipped	جارى التوصيل
in transit	جارى التوصيل
delivered	توصيل كلي
cancelled	ملغي

لا تستخدم سلاسه إلا هذين العمودين؛ اترك عمود مسار الكيان فارغًا. والحالة التي ليس لها سطر في الجدول تُسجَّل في السجل لكنها لا تغيّر شيئًا في المستند.

مجموعة الإنشاء التلقائي بواسطة سلاسه (صفحة Salasa)

الحقل	الغرض منه
Save Salasa Orders Using Magento Site	سجل Magento Site من الخطوة 1، ويجب أن يكون نوعه Salasa.
ملف ربط الأصناف بموقع ماجنتو	ملف الربط الذي يحوّل أكواد SKU في سلاسه إلى أصناف نما. يجب أن يكون كل SKU ترسله سلاسه موجودًا فيه مرة واحدة.
دفتر التحويل المخزني المنشأ بواسطة سلاسه / توجيه التحويل المخزني المنشأ بواسطة سلاسه	دفتر وتوجيه سند التحويل المخزني الذي ينشئه نما عند وصول دفعة توريد. حقلان إلزاميان.
المخزن / إلى مخزن	مخزنا سند التحويل: تنتقل البضاعة من المخزن إلى مخزن. مثلًا من مخزنك الرئيسي إلى مخزن باسم «سلاسه الرياض» يمثّل الرصيد الموجود لدى سلاسه. كلاهما إلزامي.
دفتر مردود المبيعات المنشأ بواسطة سلاسه / توجيه مردود المبيعات المنشأ بواسطة سلاسه	دفتر وتوجيه مردود المبيعات الذي ينشئه نما عند استلام سلاسه لمرتجع.
طريقة حفظ مردود المبيعات المنشأ	هل يُحفظ مردود المبيعات كمسودة (الافتراضي عندما يكون الحقل فارغًا) أم بـ الحفظ نهائياً.

جدول Salasa Webhooks (صفحة Salasa)

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

الحدث	ما يفعله نما به
replenishment_received	ينشئ سند تحويل مخزني للبضاعة التي استلمتها سلاسه.
return_received	ينشئ مردود مبيعات، وصرفًا مخزنيًا للبضاعة التالفة.
order_created	يحفظ طلب جاهز، أو يحدّث بيانات التوصيل للطلبات الأخرى.
order_updated	مثل order_created.
stock_updated	يحدّث بيانات التوصيل عندما يحمل الاتصال طلبًا.

يشرح القسم التالي كل حدث بالتفصيل.

إنشاء التنبيهات في سلاسه

احفظ السجل، ثم اضغط Create Webhook In Salasa في صفحة Salasa. لكل حدث في الجدول يطلب نما من سلاسه إنشاء تنبيه يتصل بخادم نما عند وقوع هذا الحدث، ويعطيها الرمز السري لمفتاح Nama API Key لترسله مع كل اتصال. يُبنى عنوان التنبيه من عنوان نظام نما العام على خادمك، فيجب أن تستطيع سلاسه الوصول إلى هذا العنوان عبر الإنترنت؛ وإن لم تكن متأكدًا من ضبطه فاسأل دعم نما.

يسألك الإجراء عن Force Generate New Access Token. اتركه دون تحديد في العادة، وحدّده إذا كنت قد غيّرت للتو اسم المستخدم أو كلمة المرور، أو إذا رفضت سلاسه المفتاح المحفوظ، حتى يدخل نما إلى سلاسه من جديد قبل إنشاء التنبيهات.

أعد الضغط على الإجراء كلما أضفت حدثًا إلى الجدول.

ماذا يفعل كل حدث من سلاسه

وصول دفعة توريد: سند تحويل مخزني مسودة

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

يُحفظ السند مسودة ليراجعه أحد المستخدمين ثم يحفظه نهائيًا. فإذا أبلغت سلاسه عن استلام 120 وحدة من TSHIRT-RED-M و40 وحدة من TSHIRT-RED-L يظهر سند تحويل مسودة بهذين السطرين في انتظار الحفظ.

إذا لم يكن أحد أكواد SKU موجودًا في ملف الربط فلا يُنشأ أي سند، ويُرفض اتصال سلاسه بالرسالة:

Could not find sku {0} in linker file {1}

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

استلام مرتجع: مردود مبيعات وصرف مخزني

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

وعندما يجد الفاتورة ينشئ:

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

طلب من جاهز: مستند مبيعات من خلال سجل Magento Site

عندما يحمل الاتصال طلبًا منصته جاهز، يسلّمه نما إلى سجل Magento Site المحدد في Save Salasa Orders Using Magento Site، فيحفظه أمر بيع أو فاتورة مبيعات حسب Order Info، تمامًا كما يحفظ طلب أي متجر إلكتروني. الحدث order_created ينشئ الطلب وorder_updated يحدّثه، ويصبح رقم الطلب الأصلي في سلاسه هو رقم الطلب الإلكتروني للمستند.

أي حدث آخر: حالة التوصيل وشركة الشحن ورقم الشحنة

أي اتصال آخر — وغالبًا order_created أو order_updated أو stock_updated لطلب جاء من أحد متاجرك — يحدّث بيانات توصيل الطلب في نما. يجد نما المستند برقم الطلب الأصلي في سلاسه:

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

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

يُسجَّل كل اتصال من هذه الاتصالات في قائمة Salasa Shipping Event Log في صفحة الإحصائيات على موقع الشحن: المستند، وتاريخ الطلب، وحالة الطلب كما أرسلتها سلاسه، وحالة التوصيل وشركة التوصيل قبل التغيير وبعده. فإذا سأل عميل لماذا ما زالت فاتورته «جارى التوصيل»، أظهر لك هذا السجل آخر حالة أرسلتها سلاسه.

قراءة رصيد سلاسه في نما

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

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

تظهر هذه الرسائل بالإنجليزية في الواجهتين العربية والإنجليزية، باستثناء رسالة واحدة لها نص عربي يظهر في الجدول. أما الحقول الإلزامية الناقصة (Nama API Key، وملف ربط الأصناف بموقع ماجنتو، وSave Salasa Orders Using Magento Site، والمخزن، وإلى مخزن، ودفتر وتوجيه التحويل المخزني المنشأ بواسطة سلاسه) فتظهر لها رسالة الحقل الإلزامي المعتادة.

الرسالة	السبب	ما العمل
«الحقل {0} في السطور لا يمكن أن يكون فارغاً»	جدول حالات لتشغيل مسار كيان لا يحتوي على أي حالة.	أضف حالة واحدة على الأقل من حالات سلاسه مع حالة التوصيل المقابلة.
Status: {0} is not a salasa status	إحدى الحالات في الجدول ليست مما ترسله سلاسه، وغالبًا بسبب خطأ في الكتابة أو حالة الأحرف.	اختر الحالة من قائمة الاقتراحات.
Salasa webhooks grid can not be empty	جدول Salasa Webhooks فارغ.	أضف الأحداث التي تريد أن ترسلها سلاسه.
Event: {0} is not a salasa webhook event	أحد الأحداث في جدول التنبيهات مكتوب خطأ.	استخدم أحد أسماء الأحداث الخمسة أعلاه بأحرف صغيرة وشرطة سفلية.
The site type in {0} is {1}. It should be of type {2}	الحقل Save Salasa Orders Using Magento Site يشير إلى سجل Magento Site نوعه ليس Salasa.	اختر سجلًا نوعه (Site Type) هو Salasa، أو غيّر نوع ذلك السجل.
Can not generate salasa access token	رفضت سلاسه رقم الحساب والرمز السري عند الضغط على Create Webhook In Salasa.	تحقّق مع سلاسه من اسم المستخدم (رقم الحساب) وكلمة المرور (الرمز السري).
Failed to generate salasa webhook for event: {0}. message: {1}	رفضت سلاسه إنشاء التنبيه لهذا الحدث، و{1} هو السبب كما أرسلته سلاسه.	عالج السبب الذي ذكرته سلاسه، ثم اضغط Create Webhook In Salasa مرة أخرى.
Could not find sku {0} in linker file {1}	دفعة توريد تحتوي على SKU غير موجود في ملف ربط الأصناف بموقع ماجنتو.	أضف الكود إلى ملف الربط وأدخل هذا التحويل يدويًا.