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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب SF Express (للأسعار الفورية فقط): تعتمد الأسعار الفورية على منصة FengQiao المفتوحة التابعة لـ SF Express (open.sf-express.com). تحتاج إلى حساب SF Express شهري وحساب مطوّر على FengQiao. سجّل هناك، وأنشئ تطبيقاً، وأضف إليه واجهة البرمجة "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM)، ثم انسخ رمز العميل وcheckword. تختلف checkword الخاصة ببيئة الاختبار عن تلك الخاصة بالإنتاج. وإذا كنت تستخدم جدول الأسعار فقط، فلا تحتاج إلى حساب SF Express.

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة، ثم انقر Install Now. يمكنك أيضاً رفع مجلد vfd_sf_express إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

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

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

5. املأ جدول الأسعار و/أو التكلفة الاحتياطية.

6. للأسعار الفورية في البر الرئيسي للصين، أدخل رمز العميل وcheckword ومحافظة الإرسال ومدينته (أو حدّد عنوان متجر في الصين)، وإذا لم تكن عملة متجرك اليوان الصيني CNY فأدخل سعر الصرف. جرّب أولاً باستخدام Sandbox وبيانات اعتماد بيئة الاختبار.

7. أضف VibeFox SF Express إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

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

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

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

عام

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

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

Tax status: Taxable يضيف ضريبة شحن متجرك إلى التكلفة، وNone لا يضيفها. اختر None إذا كان سعر SF Express يتضمن بالفعل كل ما تريد تحصيله.

واجهة FengQiao API لـ SF Express (الأسعار الفورية) (اختياري، لعناوين التوصيل في البر الرئيسي للصين)

Customer code (partnerID): رمز العميل (顾客编码) لتطبيق FengQiao الخاص بك.

Checkword: الـ checkword (校验码) للبيئة نفسها. يُستخدم فقط لتوقيع الطلبات، ولا يُرسل أو يُسجَّل أبداً.

Sandbox: استخدم بيئة الاختبار FengQiao مع بيانات اعتماد بيئة الاختبار. أسعار بيئة الاختبار ليست حقيقية. أوقفها في متجر فعلي. الافتراضي: off.

SF Express product: سعر أي منتج من SF Express يُعرض.

Cheapest product offered by SF Express: الافتراضي. يُستخدم أقل سعر تعيده SF Express.

SF Express Priority (顺丰特快, code 1): سعر هذا المنتج فقط.

SF Standard Express (顺丰标快, code 2): سعر هذا المنتج فقط.

Sender province: المحافظة التي تُرسل منها الطرود. اتركه فارغاً لاستخدام محافظة عنوان المتجر في WooCommerce > Settings > General، عندما يكون المتجر في الصين.

Sender city: اسم المدينة الصينية القياسي، مثل 深圳市. اتركه فارغاً لاستخدام مدينة المتجر، عندما يكون المتجر في الصين.

Currency conversion rate: أسعار SF Express بالـ CNY (اليوان). إذا لم تكن عملة متجرك CNY، فأدخل عدد وحدات عملة متجرك التي تعادل يواناً واحداً. ومن دونه لا تُستخدم الأسعار الفورية. وإذا كانت عملة متجرك CNY، فتُستخدم الأسعار كما هي. ويُقبل كل من النقطة والفاصلة كفاصل عشري.

جدول الأسعار والتكلفة الاحتياطية (يُستخدم لهونغ كونغ وماكاو وتايوان ودول أخرى، عندما لا تكون الأسعار الفورية مُعدّة أو عندما لا تعيد SF Express سعراً؛ والأسعار بعملة متجرك)

Country prices: جدول بسعر أساسي لكل دولة. ينطبق الصف * Any other country على جميع الدول التي ليس لها صف خاص. وسعر فئة الوزن الأكبر من 0 يحل محل السعر الأساسي للطرود في تلك الفئة: ≤ 1 kg، ≤ 2 kg، ≤ 3 kg، ≤ 5 kg و> 5 kg. والسعر الأساسي 0 يعني شحناً مجانياً. والسعر الأساسي الفارغ يعني أنه لا يوجد سعر لهذه الدولة، وتُستخدم التكلفة الاحتياطية.

Fallback cost: تُستخدم عندما لا تعيد SF Express ولا الجدول سعراً. اتركها فارغة لإخفاء الطريقة في هذه الحالة.

Table / fallback price is: طريقة تحصيل أسعار الجدول والأسعار الاحتياطية.

Per order (tier by the total cart weight): سعر الفئة التي تطابق الوزن الإجمالي للسلة، ويُحصَّل مرة واحدة.

Per item (every item is priced by its own weight): يُسعَّر كل منتج حسب فئة وزنه الخاصة ويُضرب في كميته. وتُضرب التكلفة الاحتياطية في عدد المنتجات.

أسعار SF Express الفورية دائماً للطلب كاملاً.

الشروط

Free shipping from: المجموع الفرعي للسلة الذي يصبح الشحن عنده مجانياً. ولا يُعرض الشحن المجاني إلا حيث توجد للطريقة قيمة للوجهة: سعر فوري أو صف في الجدول أو Fallback cost. اتركه فارغاً لعدم عرض الشحن المجاني أبداً.

Minimum subtotal: لا تُعرض الطريقة إلا عندما يبلغ المجموع الفرعي للسلة هذا المبلغ. اتركه فارغاً لعرضها دائماً.

Min weight (kg): الحد الأدنى لوزن السلة بالكيلوغرام. تُحوَّل أوزان المنتجات من وحدة الوزن في متجرك. 0 يعني بلا حد.

Max weight (kg): الحد الأقصى لوزن السلة بالكيلوغرام. الافتراضي: 50. 0 يعني بلا حد.

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

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

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

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

متقدم

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

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

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

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

بالنسبة إلى عنوان توصيل في البر الرئيسي للصين، مع ضبط رمز العميل وcheckword، ترسل الإضافة إلى SF Express محافظة الإرسال ومدينته، ومحافظة العميل ومدينته، ووزن السلة، وحجم السلة (من المنتجات التي تحتوي أبعادها الثلاثة). ويُوقَّع الطلب بالـ checkword الخاص بك. تُعيد SF Express الأسعار بالـ CNY، وتحوّل الإضافة السعر المختار إلى عملة متجرك.

تتعرف SF Express على العناوين من خلال الأسماء الصينية القياسية. وتأتي محافظة العميل من حقل الولاية/المحافظة عند الدفع. ويجب كتابة اسم المدينة بالصينية، مثل 广州市. وبالنسبة إلى بكين وشنغهاي وتيانجين وتشونغتشينغ تُملأ المدينة تلقائياً. أما المدينة المكتوبة بالحروف اللاتينية، مثل "Guangzhou"، فتحصل على سعر الجدول.

يُخزَّن كل سعر مؤقتاً لمدة ساعة، فلا تُرسل السلة نفسها طلباً جديداً. ويُخزَّن الطلب الفاشل مؤقتاً لمدة 10 دقائق، فلا ينتظر الدفع SF Express عند كل تحديث. مهلة HTTP هي 10 ثوانٍ.

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

تعمل الطريقة في الدفع الكلاسيكي وفي كتلتي Cart وCheckout. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS). وتتوفر ترجمات بالإنجليزية وبالصينية المبسطة.

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

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

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

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

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

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

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

لا تظهر SF Express عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مُضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقق من حدود الوزن وMinimum subtotal وExcluded shipping classes. وتحقق من أن الجدول أو Fallback cost يحتوي على سعر للدولة.

يأتي السعر من الجدول لا من SF Express: تحتاج الأسعار الفورية إلى رمز العميل وcheckword، ومحافظة إرسال ومدينة، وعنوان توصيل في البر الرئيسي للصين مع محافظة واسم مدينة صيني، وإلى سعر الصرف (للمتاجر التي لا تستخدم CNY). افتح WooCommerce > Status > Logs، والمصدر vfd-sf-express، لمعرفة السبب. ويُعاد الطلب الفاشل بعد 10 دقائق.

الخطأ A1006 في السجل: توقيع غير صالح. الـ checkword خاطئ أو يخص البيئة الأخرى. تحقق من إعداد Sandbox.

الخطأ A1004 في السجل: واجهة برمجة الاستعلام عن الأسعار غير مُضافة إلى تطبيق FengQiao الخاص بك.

هونغ كونغ: تعمل مع جدول الأسعار والتكلفة الاحتياطية. واستعلام أسعار FengQiao مخصص لعناوين البر الرئيسي للصين فقط.

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

للمطورين: يغيّر الفلتر vfd_sfex_quote_request طلب السعر، مثلاً لاستخدام رمز منتج آخر. ويغيّر vfd_sfex_api_url عنوان URL للبوابة.

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

الإلغاء والحذف

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

SF Express علامة تجارية تخص مالكها. وهذه الإضافة غير تابعة لـ SF Express ولا معتمدة منها.