التكامل مع سلة (Salla)

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

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

ما الذي ينتقل في كل اتجاه

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

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

ربط المتجر

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

أياً كانت الطريقة فالبداية واحدة. أنشئ Magento Site جديداً واختر في Site Type القيمة Salla Site. عندها يملأ نما بنفسه حقلي رابط وRedirect URL (في تبويب Salla Site)، فاتركهما كما هما. ويضم تبويب Salla Site أيضاً كل الحقول الأخرى الخاصة بسلة.

عن طريق تطبيق نماسوفت (الطريقة المعتمدة)

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

1. يثبّت التاجر تطبيق نماسوفت من متجر تطبيقات سلة. بعد التثبيت تفتح سلة صفحة من نماسوفت تطلب معرف رخصة نما، فيكتبه التاجر ويضغط حفظ معرف الرخصه. بدون هذه الخطوة لن يستطيع خادم العميل استلام الرمز لاحقاً.
2. يحتفظ التاجر برسالة التثبيت. تصل رسالة عنوانها "Nama ERP Salla installation registered" إلى البريد الإلكتروني لحساب التاجر في سلة، وفيها Merchant ID الخاص بالمتجر.
3. راجع معرف الرخصة على الخادم. معرف الرخصة الذي كتبه التاجر يجب أن يطابق الإعداد العام serverid (في ملف nama.properties) على خادم نما الخاص بالعميل، فبهذه المطابقة تتعرف البوابة على المتجر الصحيح.
4. املأ بيانات Magento Site.
   • إسم المستخدم (Consumer Key) وكلمة المرور (Consumer Secret): بيانات تطبيق نماسوفت، ويوفرها لك الدعم الفني لنماسوفت.
   • Merchant Id: الرقم الوارد في رسالة التثبيت. لا يملؤه نما بنفسه.
   • في تبويب Salla Site: يكون Gateway URL (Server Url) مملوءاً بعنوان بوابة نماسوفت، أما Gateway Client ID وGateway Client Secret فيوفرهما الدعم الفني لنماسوفت.
5. احفظ، ثم اضغط Read Ecommerce Access Token في التبويب الرئيسي، ويُفضَّل أن يكون ذلك بعد تثبيت التاجر للتطبيق بوقت قصير. يجلب نما رمز المتجر من البوابة ويحفظه في Refresh Token، وبعدها يستطيع الموقع قراءة الطلبات وتحديث المنتجات.

لا تترك اسم المستخدم وكلمة المرور فارغين

رموز سلة تنتهي صلاحيتها. يجدّدها نما تلقائياً، ويستخدم في ذلك إسم المستخدم (Consumer Key) وكلمة المرور (Consumer Secret). فإذا كان الحقلان فارغين يعمل الموقع إلى أن تنتهي صلاحية أول رمز فقط، وبعدها يفشل كل اتصال برسالة "User Name is missing" أو "Password is missing".

عن طريق تطبيق سلة خاص بالعميل

يستطيع العميل الذي سجّل تطبيقاً خاصاً به لدى سلة أن يربطه مباشرة.

1. ضع Client ID الخاص بالتطبيق في إسم المستخدم (Consumer Key)، وClient Secret في كلمة المرور (Consumer Secret).
2. اجعل Redirect URL هو رابط الرجوع (Callback URL) المسجّل في تطبيق سلة. ويمكن أن يخبرك الدعم الفني لنماسوفت بالرابط الذي تسجّله.
3. احفظ، ثم اضغط Request Token في التبويب الرئيسي. وعندما يسألك Use Gateway Server أجب بـ لا.
4. تُفتح صفحة الموافقة الخاصة بسلة في نافذة جديدة. سجّل الدخول ووافق على التطبيق. بعدها يعرض المتصفح "Authorization updated"، ويحفظ نما الرموز في Authorization Code وRefresh Token في تبويب Salla Site.

ويجري التجديد هنا كما يجري مع تطبيق نماسوفت، أي يجب أن تبقى بيانات التطبيق في إسم المستخدم (Consumer Key) وكلمة المرور (Consumer Secret).

الطلبات الواردة إلى نما

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

المستند الذي ينشئه نما، ودفتره وتوجيهه، يتحددان من Order Info والإعدادات المرتبطة بها كما يشرح الدليل المشترك، ولا شيء خاص بسلة في ذلك. ويحمل كل مستند رقم الطلب الذي يراه التاجر في سلة، فيسهل الوصول إلى الطلب من الجهتين.

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

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

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

السطور والمنتجات المجمّعة والشحن والمدفوعات

• الأصناف تُطابق بالـ SKU عن طريق ملف ربط الأصناف بموقع ماجنتو أو كود الصنف، تماماً كما يشرح الدليل المشترك. ويؤخذ سعر كل سطر وخصمه وضريبته من مبالغ السطر في سلة.
• المنتجات المجمّعة. المنتج المجمّع في سلة ("group products") لا يصل كسطر واحد، بل يصل سطراً لكل منتج داخله، ويُوزَّع خصم المنتج المجمّع وضريبته على تلك السطور. لذلك يحتاج كل منتج داخلي إلى SKU مربوط في نما.
• تكلفة الشحن تصبح سطر خدمة الشحن. ويُكتب اسم شركة الشحن كوصف الشحن في الطلب، فيمكنك أن تستخدمه لاختيار صنف شحن مختلف لكل شركة. أما رسوم الدفع عند الاستلام في سلة فتصبح سطر صنف خدمة الإستلام.
• العميل والعنوان. اسم العميل وبريده الإلكتروني من بيانات العميل في سلة. والعنوان من بيانات مستلم الشحنة: الاسم والهاتف والبريد والمدينة والدولة وسطر العنوان ورقم الشارع والرمز البريدي. ولا ترسل سلة عنوان فوترة منفصلاً.
• المدفوعات. كل طريقة دفع استُخدمت في الطلب تصل كدفعة مستقلة باسمها ومبلغها ومرجع العملية، وتُطابق طرق الدفع كما يشرح الدليل المشترك. ولا ترسل سلة عمليات الدفع (Transactions)، لذلك لا يتطابق مع طلبات سلة أي سطر من سطور طرق الدفع يعتمد على أنواع العمليات. اترك Validate Order Payment Transactions غير مفعّل مع سلة.

عندما يفشل طلب

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

وعندما ترفض سلة نفسها طلباً، يعرض نما رسالة الخطأ كما كتبتها سلة.

الأسعار والكميات المرسلة إلى سلة

لا يُرسل شيء قبل أن يسمح الخادم بذلك

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

يبحث نما عن المنتج في سلة بالـ SKU: الـ SKU الموجود في ملف ربط الأصناف بموقع ماجنتو، وإلا فكود الصنف.

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

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

الكميات لكل فرع في سلة

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

وبمجرد أن يحتوي الجدول على صفوف:

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

مثال: مخزن الرياض مربوط بالفرع 1873245، ومخزن جدة بالفرع 1873246. البيع من مخزن جدة يحدّث فرع جدة وحده في سلة.

استقبال الطلبات فوراً (Webhooks)

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

خطوات الإعداد

1. اطلب من الدعم الفني لنماسوفت تفعيل تحويل التنبيهات لمتجرك. سيحتاجون إلى Merchant Id الخاص بالمتجر، ويعطونك القيمة التي تكتبها في Webhook URL.
2. في تبويب Salla Site املأ Webhook URL وفعّل Pull Webhook Events From Gateway. لا يُحفظ الموقع وهذا الخيار مفعّل إلا إذا كانت الحقول Merchant Id وGateway URL (Server Url) وGateway Client ID وGateway Client Secret مملوءة.
3. احفظ، ثم اضغط تفعيل التنبيهات في تبويب Salla Site. يشترك المتجر بذلك في أحداث الطلبات الأربعة المذكورة في الجدول التالي.
4. يمكنك اختيار مستخدم في حفظ الأوامر كمستخدم، فتُحفظ الطلبات الواردة بالتنبيهات باسمه. وإذا تركته فارغاً تُحفظ باسم admin.

ويوضح حقل Last Gateway Read Date Time في تبويب Salla Site إلى أين وصلت القراءة. وتُعالج الأحداث بترتيب وصولها، الأقدم فالأحدث.

ماذا يفعل كل حدث

الحدث في سلة	ما يفعله نما
إنشاء طلب	يحفظ الطلب كما يحفظه زر قراءة المبيعات
تحديث طلب	مثل إنشاء الطلب. وبهذا الحدث يصل الطلب الذي تخطّاه نما من قبل بعد أن يصبح جاهزاً (انظر أدناه)
إلغاء طلب	يلغي مستند الطلب في نما. ولكي يحدث ذلك أضف صفاً في سطور إنشاء مستندات بناءا على تطابق من الأمر يكون فيه نوع مستند ماجنتو = Cancel Or Reject Order واستيراد كـ = مستند إلغاء مستند. وإذا لم يكن الطلب الأصلي موجوداً في نما يُتجاهل الحدث
استرداد طلب	ينشئ مستند مرتجع بإعدادات Return Info، أو بصف يكون فيه نوع مستند ماجنتو = Order Return

يُبنى الطلب من بيانات الحدث نفسه، ولا يعيد نما قراءته من سلة.

يؤخّر الخيار Do Not Save Webhook Order Without Shipment الطلبات إلى أن تُنشئ سلة شحنة لها. فعند تفعيله تُتخطّى أحداث الإنشاء والتحديث ما دام الطلب بلا شحنة، فيصل الطلب مع حدث "تحديث طلب" لاحق. استخدمه إذا كانت مستنداتك تحتاج إلى رقم الشحنة أو شركة الشحن.

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

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

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

الرسالة	السبب	ما العمل
Please set General Setting serverid	ضُغط Read Ecommerce Access Token والخادم ليس فيه الإعداد العام serverid.	اضبط serverid على معرف الرخصة الذي حفظه التاجر أثناء التثبيت.
No installation matched the supplied license id (تظهر بعد "Gateway returned" ورقم حالة)	لا يوجد في البوابة تثبيت مسجّل بمعرف رخصة هذا الخادم. إما أن التاجر لم يضغط حفظ معرف الرخصه، أو أنه كتب معرفاً مختلفاً عن serverid.	اجعل القيمتين متطابقتين، وعند الحاجة اطلب من التاجر فتح صفحة التطبيق مرة أخرى وحفظ معرف الرخصة.
Gateway did not return a token	ردّت البوابة لكنها لم ترسل رمزاً.	اطلب من الدعم الفني لنماسوفت مراجعة تثبيت المتجر.
Please fill field Gateway URL	حقل Gateway URL (Server Url) فارغ.	أعد عنوان البوابة، أو اطلبه من الدعم الفني لنماسوفت.
Please set Gateway Client Id / Please set Gateway Client Secret	إحدى بيانات البوابة ناقصة في تبويب Salla Site.	أدخل القيم التي أعطاك إياها الدعم الفني لنماسوفت.
User Name is missing / Password is missing	حاول نما تجديد رمز سلة، لكن إسم المستخدم (Consumer Key) أو كلمة المرور (Consumer Secret) فارغ.	املأ الحقلين ببيانات التطبيق.
Please provide webhook url	ضُغط تفعيل التنبيهات وحقل Webhook URL فارغ.	أدخل القيمة التي أعطاك إياها الدعم الفني لنماسوفت.
«لا يمكن استخدام الزرار الا لمتجر زد وسلة»	ضُغط Request Token في موقع ليس من نوع سلة أو زد.	راجع Site Type.