VibeFox SMSA Express for PrestaShop — المساعدة

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

جدول التعرفة في SMSA Express: تأتي أسعار جدول الأسعار من حسابك في SMSA أو من فريق مبيعات SMSA. أدخلها بعملة متجرك الافتراضية. إذا كان جدول التعرفة بالريال السعودي SAR أو بالدرهم الإماراتي AED أو بعملة أخرى، فحوّله أولًا.

passKey الخاص بـ SMSA (للأسعار الفورية فقط): تستخدم الأسعار الفورية خدمة SMSA الإلكترونية (SECOM، العملية getShipCharges). تصدر SMSA الـ passKey عند الطلب: اسأل مدير حسابك في SMSA، أو راسل info@smsaexpress.com واطلب الوصول إلى خدمة SMSA الإلكترونية مع ذكر رقم حسابك. قد يختلف passKey عن مفتاح API الخاص ببوابة SMSA للتجارة الإلكترونية. لا توجد لدى SMSA خادم تجريبي (sandbox) لهذه الخدمة.

مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل المفتاح الواحد على نطاق واحد.

التثبيت

1. في لوحة الإدارة، اذهب إلى Modules > Module Manager واضغط على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند اكتمال الرفع، اضغط على Configure، أو ابحث لاحقًا عن VibeFox SMSA Express في قائمة الوحدات واضغط على Configure.

3. أدخل مفتاح ترخيص VibeFox في الحقل License key داخل كتلة الترخيص أعلى صفحة الإعدادات، ثم اضغط على Activate (انظر مفتاح الترخيص).

4. أدخل أسعار SMSA Express في جدول الأسعار، واضغط على Save.

5. اختياريًا: ضمن Live rates (API) فعّل Live charges، وأدخل passKey الخاص بـ SMSA، ومدينة الشحن ودولته، وإذا لم تكن عملة متجرك الافتراضية SAR، فأدخل سعر الصرف.

عند التثبيت، تنشئ الوحدة شركة الشحن SMSA Express بنص مدة التوصيل SMSA Express courier. تُسند شركة الشحن إلى جميع المناطق وجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: يأتي السعر دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox SMSA Express > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. كما يمسح كل حفظ الأسعار المخزنة مؤقتًا من SMSA. تُرفض القيم غير الرقمية، والأرقام السالبة، وسعر الصرف 0، ورمز العملة الذي ليس مكونًا من 3 أحرف، أو Minimum weight الذي يتجاوز Maximum weight، برسالة خطأ، ولا يُحفظ شيء حتى تصحح القيمة.

عند تفعيل الأسعار الفورية، تنبهك التحذيرات أعلى الإعدادات إلى غياب passKey أو مدينة الشحن أو سعر الصرف، أو إلى كون جدول الأسعار فارغًا. كما يظهر تحذير إذا لم تتعرف الوحدة على وحدة وزن المتجر (فتُقرأ أوزان المنتجات حينئذ بالكيلوغرام). اضبط kg أو g أو lb أو oz في International > Localization (Local units).

عام

Enable SMSA Express: يفعّل شركة الشحن أو يعطّلها في جميع المناطق دفعة واحدة. وهو المفتاح نفسه المستخدم لحالة شركة الشحن في Shipping > Carriers.

Method title: اسم شركة الشحن الذي يظهر في السلة وعند الدفع. الافتراضي: SMSA Express. حقل مطلوب، بحد أقصى 64 حرفًا.

Tax: قاعدة ضريبة شركة الشحن، أو No tax. اختر No tax إذا كانت أسعارك (الجدول وأسعار SMSA) تتضمن الضريبة مسبقًا، مثل ضريبة القيمة المضافة السعودية.

الأسعار الفورية (API) (اختياري؛ إذا لم تُرجع SMSA سعرًا، يُستخدم جدول الأسعار)

Live charges: يحصل على سعر الشحن من SMSA Express. الافتراضي: مُعطّل.

SMSA passKey: مفتاح خدمة SMSA الإلكترونية (SECOM). بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ضع علامة على Remove the saved passKey لحذف المفتاح المحفوظ. إذا أظهر السجل "Invalid Passkey"، فهذا يعني أن الخدمة لا تقبل هذا المفتاح. اطلب من SMSA passKey لخدمة الويب.

Ship-from city: المدينة التي تُرسل منها طرودك، مكتوبة كما تكتبها SMSA، مثل Riyadh أو Jeddah أو Dammam. اتركها فارغة لاستخدام مدينة المتجر المحددة في Shop Parameters > Contact > Stores.

Ship-from country: البلد الذي تُرسل منه طرودك. وهو افتراضيًا بلد متجرك.

Shipment type: يُرسل إلى SMSA كنوع للشحنة. DLV (الافتراضي) هو التوصيل القياسي. غيّره فقط إذا أعطتك SMSA رمزًا آخر.

Currency of SMSA charges: تُرجع SMSA كل سعر مع رمز عملته، وعادةً SAR (الافتراضي). لا يُستخدم أي سعر بعملة غير هذه العملة وعملة متجرك الافتراضية.

Exchange rate: سعر وحدة واحدة من عملة SMSA بعملة متجرك الافتراضية، مثلًا 0.27. لا حاجة إليه عندما تكون العملتان متطابقتين. وبدونه، لا تُستخدم الأسعار بعملات أخرى، ويُطبَّق جدول الأسعار. يُقبل كل من النقطة والفاصلة كفاصل عشري.

الأسعار (جدول التعرفة الخاص بك في SMSA Express بعملة متجرك الافتراضية؛ يُستخدم عند تعطيل الأسعار الفورية، وكبديل عند عدم إرجاع SMSA لسعر)

Price table: سطر واحد لكل دولة وجهة. اضغط Add country لإضافة سطر، وأيقونة سلة المهملات لحذفه. ينطبق السطر * Default (all other countries) على الدول التي ليس لها سطر خاص بها. يحتوي كل سطر على سعر أساسي وأعمدة وزن: XS حتى 1 كجم، وS حتى 2 كجم، وM حتى 3 كجم، وL حتى 5 كجم، وXL أكثر من 5 كجم. إذا كان عمود الوزن فارغًا أو يساوي 0، يُستخدم السعر الأساسي. والسعر الأساسي 0 يعني شحنًا مجانيًا. لا تُحفظ الأسطر التي لا تحتوي على أي سعر. إذا كان لدولة سطران، يُستخدم الأول. ويُقبل كل من "9.99" و"9,99".

Price for countries not in the table: يُستخدم عندما لا يوجد في الجدول سطر لدولة الوجهة (ولا سطر *)، أو عندما لا يحتوي السطر على سعر لهذا الوزن. اتركه فارغًا لإخفاء شركة الشحن في تلك الحالة.

Price applies: كيفية احتساب السعر.

Per order (one parcel, tier by total cart weight): السلة طرد واحد. يستخدم الجدول الفئة المناسبة لوزن السلة الإجمالي. يُطلب السعر الفوري لوزن السلة.

Per item (every item is a separate parcel, tier by its own weight): كل وحدة طرد مستقل بوزنها، وتُجمع الأسعار. تُطلب الأسعار الفورية لما لا يزيد على 5 أوزان مختلفة للقطع في السلة. وإلا يُستخدم جدول الأسعار.

تُحوَّل أوزان المنتجات من وحدة وزن متجرك إلى كيلوغرامات.

الشروط

Minimum weight: يُخفي شركة الشحن عندما يكون وزن السلة أقل من هذا الحد، بالكيلوغرام. 0 يعني بلا حد.

Maximum weight: يُخفي شركة الشحن عندما يكون وزن السلة أكبر من هذا الحد، بالكيلوغرام. الافتراضي: 30. 0 أو حقل فارغ يعني بلا حد.

Minimum order amount: يعرض شركة الشحن فقط عندما يبلغ المجموع الفرعي للسلة (بعد الخصومات، قبل الضريبة) هذا المبلغ. اتركه فارغًا لعرضها دائمًا.

Free shipping from: المجموع الفرعي للسلة (بعد الخصومات، قبل الضريبة) الذي يصبح عنده الشحن عبر SMSA Express مجانيًا. عندما تبلغ السلة هذا المبلغ، يكون السعر 0 ولا يُرسل أي طلب إلى SMSA. اتركه فارغًا لعدم تقديم شحن مجاني أبدًا.

التوافر دون مناطق الشحن

عادةً تُعرض شركة الشحن في المناطق المسندة إليها في Shipping > Carriers.

Ignore shipping zones: يعرض SMSA Express للدول المذكورة أدناه، أيًا كانت المنطقة المطابقة. وعند التفعيل، تُضاف شركة الشحن إلى جميع المناطق، بما فيها المناطق التي تُنشأ لاحقًا. وعند إيقافه، تُزال المناطق المضافة بهذه الطريقة.

Countries: دول الوجهة لهذا الوضع. اتركه فارغًا لاستخدام جميع الدول النشطة في المتجر. لا يُستخدم هذا الحقل إلا عندما يكون Ignore shipping zones مفعّلًا.

متقدم

Debug log: يسجل حسابات الأسعار في logs/vfd_smsa_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل عناوين العملاء ولا المفاتيح. وتُسجَّل أخطاء الأسعار الفورية دائمًا حتى وإن كان هذا الخيار معطّلًا. أوقف السجل عند الانتهاء.

Log: يعرض حجم سجل التصحيح وآخر إدخالاته. اضغط Clear log لتفريغه.

Remove data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات SMSA Express وشركة الشحن والسجل. وعند التعطيل، يُحتفظ بكل شيء لإعادة التثبيت. تُحذف الأسعار المخزنة مؤقتًا دائمًا.

كيف تعمل عند الدفع

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر SMSA Express. تُحتسب المنتجات المادية فقط: فالمنتجات الافتراضية لا تضيف وزنًا ولا تُدرج في مبلغ الطلب. تتحقق الوحدة أولًا من الشروط: دول Ignore shipping zones (إن كان مفعّلًا)، ووزن السلة، والحد الأدنى لمبلغ الطلب. وإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى SMSA.

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

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

كلما لم تُرجع SMSA سعرًا صالحًا (لا يوجد passKey، أو لم تُدخل المدينة بعد، أو أوزان المنتجات مفقودة، أو المفتاح غير صالح، أو انتهت المهلة الزمنية، أو حدث خطأ، أو لا توجد خدمة إلى المدينة، أو العملة غير معروفة)، يُستخدم جدول الأسعار. وإذا لم يعطِ الجدول وPrice for countries not in the table أي سعر، تُخفى شركة الشحن. ولا يرى العميل أي خطأ أبدًا. ويُكتب السبب في السجل.

إذا عدّلت شركة الشحن في Shipping > Carriers بعد أن أصبح لها طلبات، يحفظها PrestaShop كنسخة جديدة من شركة الشحن. وتتبع الوحدة النسخة الجديدة تلقائيًا.

تحسب الوحدة سعر الشحن فقط. ولا تنشئ شحنات SMSA، ولا تطبع ملصقات AWB، ولا تعالج المرتجعات، ولا تتتبع الطرود. ولا يُدرج الدفع عند الاستلام ورسومه في السعر الفوري. ولا يوجد محدد لنقاط بيع SMSA: شركة الشحن توصيل إلى الباب.

مفتاح الترخيص

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox SMSA Express هي الكتلة الأولى في Modules > Module Manager > VibeFox SMSA Express > Configure، فوق الإعدادات. أدخل المفتاح في License key واضغط على Activate. بعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-shipping-smsa-express والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يستطيع تغيير المفتاح إلا الموظفون الذين لديهم صلاحية Configure لهذه الوحدة. وتتبع نصوص الكتلة لغة الواجهة الخلفية (تتضمن الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، اضغط على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: نطاق المتجر الرئيسي، وكذلك في إعداد المتاجر المتعددة. ولا تؤدي إزالة المفتاح من المتجر إلى تحرير خانة النطاق. حرّر الخانة في حسابك على vibefox.net.

بدون مفتاح نشط، لا تُعرض شركة الشحن SMSA Express للعملاء عند الدفع، ولا يُحسب أي سعر. ولا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى الواجهة الخلفية، لذلك تُخفى شركة الشحن عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager على تبويب Alerts. ولا تتأثر الطلبات الموجودة.

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

استكشاف الأخطاء وإصلاحها

لا يظهر SMSA Express عند الدفع: تحقق من أن الترخيص نشط، وأن Enable SMSA Express مفعّل. وفي Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقق من حدود الوزن وMinimum order amount. تحقق من أن الدولة أو * لها سعر، أو أن Price for countries not in the table مضبوط. كذلك قد تكون المنتجات مقيدة بشركات شحن معينة في صفحة المنتج.

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

"Invalid Passkey" في السجل: لا تقبل خدمة SMSA الإلكترونية هذا المفتاح. اطلب من SMSA passKey لخدمة الويب.

لا تُقبل مدينة العميل: تستخدم SMSA كتابتها الخاصة للمدن. تحقق من المدينة في عنوان التوصيل ومن Ship-from city.

لا تُحفظ الإعدادات ويظهر خطأ: يحتوي حقل رقمي على نص أو قيمة سالبة، أو سعر الصرف 0، أو رمز العملة ليس مكونًا من 3 أحرف، أو Minimum weight أكبر من Maximum weight. صحح القيمة المذكورة في الرسالة ثم اضغط Save مرة أخرى.

تُحسب الضريبة على الشحن مرتين: قد تتضمن تعرفتك أو أسعار SMSA ضريبة القيمة المضافة بالفعل. اضبط Tax على No tax.

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

تقول الصفحة إن شركة الشحن SMSA Express غير موجودة: حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإنشائها من جديد.

إلغاء التثبيت

اذهب إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox SMSA Express، واختر Uninstall. يُحذف مفتاح الترخيص وحالة الترخيص دائمًا. تُحذف الأسعار المخزنة مؤقتًا دائمًا. وإذا كان Remove data on uninstall مفعّلًا، تُحذف شركة الشحن (وتحتفظ الطلبات بسجلها)، وتُحذف الإعدادات والسجل. وإذا كان معطّلًا، تُعطَّل شركة الشحن فقط وتبقى جميع الإعدادات. إعادة تثبيت الوحدة أو Reset تعيد لشركة الشحن الحالة التي كانت عليها.

SMSA Express علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ SMSA Express ولا تحظى بتأييدها.