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

المتطلبات

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

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

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

المحافظات الصينية (للأسعار الفورية فقط): يتطلب السعر الفوري محافظة عنوان التسليم. ولا تتضمن PrestaShop محافظات صينية افتراضياً. وتستطيع الوحدة إضافتها لك (انظر Chinese provinces أدناه).

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

التثبيت

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

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

3. أدخل مفتاح ترخيص VibeFox في License key داخل كتلة الترخيص أعلى صفحة Configure وانقر على Activate (انظر مفتاح الترخيص).

4. املأ جدول الأسعار و/أو التكلفة الاحتياطية، ثم انقر على Save.

5. للأسعار الفورية في البر الرئيسي للصين، أدخل رمز العميل وcheckword، ومحافظة المُرسِل ومدينته (أو عيّن عنوان متجر في الصين)، وإذا لم تكن عملة متجرك اليوان الصيني (CNY) فأدخل سعر صرف العملة. انقر على Add Chinese provinces إذا طلبت الصفحة ذلك. وجرّب أولاً باستخدام Sandbox وبيانات اعتماد sandbox.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox SF Express > Configure. وهي تُطبَّق على جميع مناطق شركة الشحن. ولكل قسم زر Save خاص به، يحفظ الصفحة كاملة. وكل عملية حفظ تمسح أيضاً الأسعار المخزنة مؤقتاً من SF Express.

عند الحفظ، تتحقق الوحدة من الأرقام. فالقيمة غير الرقمية، أو المبلغ أو الوزن السالب، أو سعر الصرف الذي يساوي 0، أو Min weight أعلى من Max weight، أو سعر خاطئ في جدول الأسعار، يُرفض مع رسالة، ولا يُحفظ شيء حتى تصححه. وتخبرك التحذيرات فوق الإعدادات عندما تكون الأسعار الفورية مُعدّة جزئياً (تُدرج الإعدادات الناقصة)، أو عندما يكون سعر صرف العملة مفقوداً، أو عندما لا يحتوي العنوان الصيني على حقل محافظة، أو عندما لا تعرف الوحدة وحدة الوزن أو الأبعاد في متجرك. وتُضبط الوحدات في International > Localization (Local units).

عام

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

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

Tax: قاعدة الضريبة لشركة الشحن، أو No tax. مع قاعدة ضريبية تُضاف ضريبة شحن متجرك إلى التكلفة. اختر No tax إذا كان سعر SF Express يتضمن بالفعل كل ما تريد تحصيله.

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

Customer code (partnerID): رمز العميل (顾客编码) لتطبيق FengQiao الخاص بك. وتؤدي إزالته إلى مسح checkword المحفوظ أيضاً، حتى تتمكن من حذف بيانات الاعتماد.

Checkword: checkword (校验码) للبيئة نفسها. يُستخدم فقط لتوقيع الطلبات، ولا يُرسل أو يُسجَّل أبداً. بعد الحفظ يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره.

Sandbox: يستخدم بيئة الاختبار الخاصة بـ FengQiao (sfapi-sbox.sf-express.com) للاختبار ببيانات اعتماد sandbox. أسعار sandbox ليست حقيقية. أوقفه في متجر إنتاج. الافتراضي: معطّل.

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

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

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

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

Chinese provinces: يُظهر ما إذا كان بإمكان العناوين الصينية أن تحتوي على محافظة. وإذا لم تكن كذلك، فانقر على Add Chinese provinces. يضيف الزر المحافظات الـ 32 والمناطق ذاتية الحكم والبلديات بوصفها ولايات للصين (رموز ISO مثل GD وBJ، وأسماء مثل "Guangdong / 广东")، ويُفعّل "Contains states" للصين، ويضيف حقل الولاية إلى نموذج العنوان الصيني. ولا تُضاف المحافظات الموجودة مسبقاً مرة أخرى. ولا يتغير شيء دون هذا النقر.

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

Country prices: جدول يحتوي على سعر أساسي لكل دولة. انقر على Add country لإضافة صف، وعلى أيقونة سلة المهملات لحذف صف. ويُطبَّق الصف * All other countries على جميع الدول التي ليس لها صف خاص بها. ويحل سعر فئة الوزن الأعلى من 0 محل السعر الأساسي للطرود في تلك الفئة: XS ≤1 kg، وS ≤2 kg، وM ≤3 kg، وL ≤5 kg، وXL >5 kg. والسعر الأساسي 0 يعني شحناً مجانياً. والسعر الأساسي الفارغ يعني أنه لا يوجد سعر لهذه الدولة، وتُستخدم التكلفة الاحتياطية. ويُقبل كل من "9.99" و"9,99". ولا يُحفظ الصف الذي لا يحتوي على أي سعر.

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

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

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

الشروط

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

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

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

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

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

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

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

متقدم

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

Log: يُظهر حجم السجل وأحدث إدخالاته. انقر على Clear log لتفريغه.

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

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

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

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

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

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

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

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

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

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox SF Express هي أول كتلة في Modules > Module Manager > VibeFox SF Express > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفياً، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-shipping-sf-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.

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

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

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

لا تظهر SF Express عند الدفع: تحقق من أن الترخيص نشط، وأن Enable SF Express مُفعّل. وفي Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعة العميل (أو فعّل Ignore shipping zones وتحقق من Countries). وتحقق من حدود الوزن وMinimum subtotal. وتحقق من أن الجدول أو Fallback cost لديه سعر للدولة. وقد تكون المنتجات مقيدة بشركات شحن معينة في صفحة المنتج أيضاً.

السعر يأتي من الجدول، وليس من SF Express: تحتاج الأسعار الفورية إلى رمز العميل وcheckword، ومحافظة ومدينة للمُرسِل، وعنوان تسليم في البر الرئيسي للصين مع محافظة واسم مدينة صينية، وإلى سعر صرف العملة (لمتاجر غير CNY). اقرأ التحذيرات أعلى صفحة الوحدة، ثم فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى حقل Log لمعرفة السبب. ويُعاد الطلب الفاشل بعد 10 دقائق.

نموذج العنوان للصين لا يحتوي على محافظة: انقر على Add Chinese provinces في قسم API في صفحة الوحدة.

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

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

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

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

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

للمطورين: يغيّر الـ hook actionVfdSfExpressQuoteRequest طلب السعر، مثلاً إلى رمز منتج آخر. ويغيّر actionVfdSfExpressApiUrl عنوان URL للبوابة.

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

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

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