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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 5.0 أو أحدث، مثبّت ومفعّل. ترفض الإضافة التفعيل بدونه.

PHP: 8.0 أو أحدث.

تعرفة 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. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، وانقر على Install Now. يمكنك أيضًا رفع مجلد vfd_smsa_express إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Shipping > VibeFox SMSA Express، أو انقر على Settings أسفل اسم الإضافة في صفحة الإضافات.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة، ثم انقر على Activate.

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

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

7. أضف VibeFox SMSA Express إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones (مثلًا "المملكة العربية السعودية")، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox SMSA Express. تنطبق على جميع مناطق الشحن. عند إضافة الطريقة إلى منطقة، تحتوي نافذة المنطقة على حقل واحد فقط:

Title (zone): الاسم الذي يراه العملاء لهذه المنطقة. اتركه فارغًا لاستخدام Method title العام.

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

عام

Enable/Disable: يفعّل الطريقة أو يعطّلها في جميع المناطق دفعة واحدة.

Method title: اسم طريقة الشحن الظاهر في السلة وصفحة الدفع. يمكن لأي منطقة أن تتجاوزه. الافتراضي: SMSA Express.

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

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

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

Ship-from city: المدينة التي تُرسل منها طرودك، بالكتابة نفسها التي تستخدمها SMSA، مثل Riyadh أو Jeddah أو Dammam. اتركه فارغًا لاستخدام مدينة المتجر من WooCommerce > Settings > General.

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

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

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

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

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

Price table: صف واحد لكل دولة وجهة. انقر على + Add country لإضافة صف، وعلى علامة الإغلاق (×) لحذف صف. يُطبَّق الصف * 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 (kg): يخفي الطريقة عندما تكون السلة أخف من هذا الوزن. 0 يعني بلا حد.

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

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

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

Excluded shipping classes: يخفي الطريقة عندما تحتوي السلة على منتج من أي فئة شحن من فئات WooCommerce هذه.

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. اختر None إذا كانت أسعارك (الجدول ورسوم SMSA) تتضمن الضريبة بالفعل، مثل ضريبة القيمة المضافة السعودية.

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

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

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

متقدم

Debug log: يسجل كل حساب للأسعار في WooCommerce > Status > Logs، بالمصدر vfd_smsa_express. لا تُسجَّل عناوين العملاء ولا المفاتيح. تُسجَّل أخطاء الرسوم المباشرة دائمًا حتى عند إيقاف هذا الخيار. أوقف السجل عند الانتهاء.

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

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

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

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

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

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي السلة والدفع. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce (HPOS). تتضمن ترجمة عربية.

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. تقع كتلة الترخيص أعلى WooCommerce > Settings > Shipping > VibeFox SMSA Express. الصق المفتاح في License key وانقر على Activate. تعرض الكتلة الحالة، مثل تاريخ انتهاء صلاحية الترخيص ونطاقك. استخدم Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك على vibefox.net.

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

بدون مفتاح نشط، لا تُعرض SMSA Express للعملاء عند الدفع. يرى مديرو المتجر الذين سجّلوا دخولهم هذه الطريقة، مع الإشارة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. يظهر تذكير في صفحة الإضافات وفي صفحات WooCommerce. لا تتأثر الطلبات الحالية.

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

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

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

يرى العملاء سعر الجدول بدلًا من رسم SMSA: تحتاج SMSA إلى مدينة العميل، لذا يُعرض سعر الجدول حتى يُدخَل. يُستخدم الجدول أيضًا عندما لا تستجيب SMSA، أو ترفض المفتاح أو المدينة، أو تُعيد الرسم بعملة بلا سعر صرف. افتح WooCommerce > Status > Logs، بالمصدر vfd_smsa_express، لمعرفة السبب.

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

مدينة العميل غير مقبولة: تتوقع SMSA كتابتها الخاصة للمدن. يمكن للمطورين تعديل الطلب، مثل اسم المدينة، باستخدام الفلتر vfd_smsa_express_live_request_fields.

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

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

تُظهر كتلة الترخيص خطأً: اتبع الرسالة الظاهرة في الكتلة. مثلًا، إذا كان المفتاح مستخدمًا في نطاق آخر، فحرّر خانة في حسابك على vibefox.net ثم انقر على Check now. إذا تغير عنوان الموقع، فانقر على Check now لتفعيل المفتاح للنطاق الجديد. إذا تعذر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

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

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

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