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

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعدها (تم الاختبار على 4.1.0.3).

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم لكلا إصداري OpenCart. فُكّه على جهاز الكمبيوتر الخاص بك. ويحتوي على README.txt، وحزمة OpenCart 3 vfd_smsa_express-oc3-(version).ocmod.zip، وحزمة OpenCart 4 vfd_smsa_express.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. ومفتاح الترخيص هو نفسه لكلا الإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف vfd_smsa_express-oc3-(version).ocmod.zip. لا تضيف الإضافة أي تعديلات OCMOD، لذلك لا تحتاج إلى تحديث Extensions > Modifications. وبدلًا من Installer، يمكنك نسخ محتويات المجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر نوع الإضافة Shipping. ابحث عن VibeFox SMSA Express واضغط Install (الزر الأخضر +).

3. اضغط Edit (زر القلم الرصاص) لفتح صفحة الإعدادات.

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

5. أدخل أسعار SMSA Express الخاصة بك في جدول الأسعار.

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

7. فعّل Enable SMSA Express واضغط Save.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف vfd_smsa_express.ocmod.zip. لا تغيّر اسم الملف: إذ يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة التي يُغيَّر اسمها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. اضغط Install (الزر الأخضر +) بجانبها.

3. انتقل إلى Extensions > Extensions، واختر نوع الإضافة Shipping. ابحث عن VibeFox SMSA Express، واضغط Install (الزر الأخضر +)، ثم Edit (زر القلم الرصاص).

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوات من 4 إلى 7 لـ OpenCart 3. وصفحة الإعدادات وحقولها متطابقة في الإصدارين.

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

الإعداد

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

عندما تكون الرسوم الفورية مفعّلة، تخبرك التحذيرات فوق الإعدادات بوجود passKey أو مدينة إرسال أو سعر صرف مفقود، أو بأن جدول الأسعار فارغ. ويظهر تحذير أيضًا إذا لم تكن لدى المتجر فئة وزن بوحدة kg، وكانت وحدة الوزن الافتراضية فيه غير معروفة للإضافة (عندئذٍ تُقرأ أوزان المنتجات بوحدة kg). أضف فئة وزن بوحدة kg في System > Localisation > Weight Classes.

عام

تنطبق الإعدادات على كل المناطق الجغرافية. ويمكنك قصر الطريقة على منطقة جغرافية في Conditions، أو على قائمة دول باستخدام Ignore shipping zones.

Enable SMSA Express: يُظهر SMSA Express في صفحة الدفع أو يخفيه. الافتراضي: معطل.

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وصفحة الدفع. الافتراضي: SMSA Express. حقل إلزامي، بحد أقصى 64 حرفًا، دون الأحرف < > ; = # { }.

Sort order: موضع SMSA Express بين طرق الشحن في صفحة الدفع. عدد صحيح.

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

Live charges: الحصول على رسوم الشحن من SMSA Express. وعند تعطيله، لا يُرسل شيء إلى SMSA أثناء الدفع. الافتراضي: معطل.

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. وهي مطلوبة للرسوم الفورية: لا توجد في OpenCart مدينة للمتجر، لذلك لا تُؤخذ أبدًا من عنوان المتجر.

Ship-from country: الدولة التي تُرسل منها طرودك. يستخدم الخيار الأول Store country دولة متجرك من System > Settings > Store > Local. وهذا هو الافتراضي.

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

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

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

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

Price table: صف واحد لكل دولة مقصودة. اضغط Add country لإضافة صف. ويُطبَّق الصف * All other countries على الدول التي ليس لها صف خاص بها. ويحتوي كل صف على سعر Base وأعمدة وزن: XS ≤1 kg، وS ≤2 kg، وM ≤3 kg، وL ≤5 kg، وXL >5 kg. وعمود الوزن الفارغ أو الذي قيمته 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 أوزان مختلفة للعناصر في كل سلة. وإلا يُستخدم جدول الأسعار.

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

الشروط

Minimum weight (kg): إخفاء الطريقة عندما يكون وزن السلة أقل من ذلك. والقيمة 0 تعني عدم وجود حد (الافتراضي).

Maximum weight (kg): إخفاء الطريقة عندما يكون وزن السلة أكبر من ذلك. الافتراضي: 30. والقيمة 0 أو الحقل الفارغ تعني عدم وجود حد.

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

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

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

Geo zone: اعرض SMSA Express فقط للعناوين الواقعة في هذه المنطقة الجغرافية. وAll zones (الافتراضي) تعني عدم وجود حد. ولا يتم التحقق منها ما دام Ignore shipping zones مفعّلًا. وتُدار المناطق الجغرافية في System > Localisation > Geo Zones.

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

عادةً ما تُعرض الطريقة للعناوين الواقعة في المنطقة الجغرافية المختارة في Conditions.

Ignore shipping zones: اعرض SMSA Express للدول المذكورة أدناه، بصرف النظر عن المنطقة الجغرافية. وعندما يكون معطلًا، تقرر المنطقة الجغرافية، ولا تُستخدم قائمة الدول.

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

متقدم

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

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

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

الاستيراد / التصدير

Export: اضغط Download JSON لحفظ الإعدادات كملف JSON. ولا يتم تصدير passKey.

Import: ألصق ملف JSON صُدِّر سابقًا، واضغط Import لاستعادة الإعدادات، مثلًا في متجر آخر. وتُفحص القيم كما في الحفظ العادي. ويُحتفظ بـ passKey المحفوظ.

كيف تعمل في صفحة الدفع

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر SMSA Express. وإذا كانت Geo zone مضبوطة (وIgnore shipping zones معطل) وكان العنوان خارجها، فلا يُعرض SMSA Express. ولا يُحتسب إلا المنتجات التي يكون فيها Requires Shipping على Yes؛ أما المنتجات الأخرى فلا تضيف وزنًا ولا تدخل في مبلغ الطلب. ثم تتحقق الإضافة من الشروط: الدول الموجودة في Ignore shipping zones (إذا كان مفعّلًا)، ووزن السلة، والحد الأدنى لمبلغ الطلب. ولا تُؤخذ شهادات الهدايا ونقاط المكافآت ورصيد المتجر في الحسبان. وإذا كان الشحن المجاني ينطبق، يصبح السعر 0 ولا يُرسل أي طلب إلى SMSA.

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

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

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

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

في OpenCart 4، ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار SMSA Express في نافذة Shipping method options. وتعمل الطريقة بالطريقة نفسها كما في OpenCart 3.

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

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

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

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

من دون مفتاح نشط، لا يُعرض SMSA Express للعملاء في صفحة الدفع ولا تُحسب أي تسعيرة. ويرى المستخدم المسؤول الذي سجّل الدخول إلى لوحة الإدارة في المتصفح نفسه الطريقة في المتجر، معلَّمة بـ (unlicensed — visible to admins only)، لتتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. وفي OpenCart 4 لا تتوفر هذه المعاينة: إذ لا يرى المتجر تسجيل دخول الإدارة، لذلك تُخفى الطريقة عن الجميع من دون مفتاح نشط. وبعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاصة بلوحة الإدارة. أغلقه بـ × لإخفائه لمدة 7 أيام. ولا تتأثر الطلبات الحالية.

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

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

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

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

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

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

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

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

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

تقول الصفحة "Warning: You do not have permission to modify VibeFox SMSA Express!": قد تتيح مجموعة المستخدمين المسؤولين لديك عرض الإعدادات فقط. امنح المجموعة صلاحية التعديل لـ extension/shipping/vfd_smsa_express (OpenCart 3) أو extension/vfd_smsa_express/shipping/vfd_smsa_express (OpenCart 4) في System > Users > User Groups.

للمطورين: يمكن استبدال عنوان خدمة SMSA الإلكترونية بالإعداد vfd_smsa_api_url (للاختبارات)؛ ولا يوجد له حقل في صفحة الإعدادات.

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

انتقل إلى Extensions > Extensions، واختر النوع Shipping، ثم اضغط Uninstall (الزر الأحمر −) بجوار VibeFox SMSA Express. ويُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. يعيد OpenCart دائمًا ضبط Enable SMSA Express وSort order وTax class وGeo zone. وتُحذف الرسوم المخزنة مؤقتًا دائمًا. وإذا كان Remove data on uninstall مفعّلًا، تُحذف أيضًا إعدادات SMSA Express وسجل التصحيح. وإذا كان معطلًا، تُحفظ الإعدادات الأخرى وتُستخدم من جديد عند إعادة تثبيت الإضافة. وتحتفظ الطلبات الحالية بطريقة الشحن وتكلفتها.

في OpenCart 4، ولإزالة ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، واضغط في قائمة الإضافات المثبتة على Uninstall (الزر البرتقالي −) بجوار VibeFox SMSA Express، ثم اضغط Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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