VibeFox J&T Express for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

الوصول إلى واجهة برمجة J&T Express Malaysia (للأسعار الفورية فقط): الأسعار الفورية متاحة فقط لـ J&T Express Malaysia، ولعناوين التوصيل داخل ماليزيا. تحتاج إلى أربع قيم. قدّم طلبًا للحصول على حساب VIP لدى J&T من موقع J&T Express Malaysia (تحتوي صفحة الإعدادات على رابط): تزودك J&T برمز العميل VIP ومفتاح API الخاص بـ VIP. يصدر J&T حساب API والمفتاح الخاص لتوقيع الطلبات من أجل التكامل عبر API. اطلبها من مدير حسابك لدى J&T. لا تتوفر لدى J&T الفلبين وإندونيسيا والدول الأخرى واجهة عامة للأسعار، لذا استخدم جدول الأسعار لها. إذا كنت تستخدم جدول الأسعار والتكلفة الاحتياطية فقط، فلا تحتاج إلى الوصول إلى واجهة J&T.

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

التثبيت

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

2. انقر على Activate.

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

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

5. املأ جدول الأسعار و/أو التكلفة الاحتياطية. للأسعار الفورية الماليزية، أدخل أيضًا بيانات اعتماد J&T API، والرمز البريدي للمرسِل، وإذا كانت عملة متجرك غير MYR فأدخل سعر تحويل العملة (راجع قسم الإعدادات).

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

الإعدادات

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

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

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

عام

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

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

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

واجهة J&T Express Malaysia API (الأسعار الفورية) (اختياري، لعناوين التوصيل في ماليزيا؛ البيانات الأربع مطلوبة جميعها)

VIP customer code: رمز عميل J&T Express VIP الخاص بك.

VIP API key: مفتاح API (كلمة المرور) الذي منحته لك J&T Express مع رمز VIP. لا يُسجَّل في السجل أبدًا.

API account: اسم حساب API الخاص بك لدى J&T Express.

API private key: المفتاح الخاص لحساب API. يُستخدم فقط لتوقيع الطلبات (SHA-256). لا يُرسل إلى J&T ولا يُسجَّل أبدًا.

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

Currency conversion rate: أسعار J&T Express Malaysia بالرينغيت الماليزي (MYR). إذا لم تكن عملة متجرك MYR، فأدخل كم وحدة من عملتك تعادل رينغيتًا واحدًا (1 MYR = X). بدون هذه القيمة لا تُستخدم الأسعار الفورية، ويُستخدم بدلًا منها جدول الأسعار أو التكلفة الاحتياطية. إذا كانت عملة متجرك MYR، فاتركه فارغًا: تُستخدم الأسعار كما هي. يُقبل كل من النقطة والفاصلة كفاصل عشري.

جدول الأسعار والاحتياطي (يُستخدم للدول غير ماليزيا، عندما لا تكون الأسعار الفورية مُعدّة، أو عندما لا تقدم J&T أي سعر؛ الأسعار بعملة متجرك)

Country prices: جدول بصف واحد لكل دولة. انقر على Add country لإضافة صف، وعلى علامة الضرب لحذفه. اختر * Any other country لجميع الدول التي ليس لها صف خاص. يحتوي كل صف على Base price وخمس فئات وزن: XS حتى 1 كجم، وS حتى 2 كجم، وM حتى 3 كجم، وL حتى 5 كجم، وXL أكثر من 5 كجم. إذا كان سعر الفئة أكبر من 0، فإنه يحل محل السعر الأساسي لسلال تلك الفئة. وإذا كان سعر الفئة 0، يُستخدم السعر الأساسي. السعر الأساسي 0 يعني شحنًا مجانيًا، وتُحفظ القيمة الأساسية الفارغة كـ 0. الدول التي ليس لها صف (عندما لا يوجد صف *) لا تحصل على سعر من الجدول.

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

Table / fallback price is: Per order يحصّل السعر مرة واحدة. Per item (multiplied by the number of items) يضربه في عدد العناصر في السلة. أسعار J&T الفورية تنطبق دائمًا على الطلب كاملًا.

الشروط

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

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 > Status > Logs، بالمصدر vfd-jt-express. تُسجَّل أخطاء J&T API دائمًا، حتى عند إيقاف هذا الخيار. لا تُكتب أي مفاتيح أو كلمات مرور أو رموز بريدية للعملاء. أوقف السجل عند الانتهاء.

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

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

عندما يُدخل العميل عنوان التوصيل، يطلب WooCommerce من الإضافة سعرًا. تتحقق الإضافة أولًا من الشروط: دولة التوصيل، ووزن السلة، والحد الأدنى للمجموع الفرعي، وفئات الشحن المستثناة. إذا وصل المجموع الفرعي للسلة إلى Free shipping from، تُعرض الطريقة بتكلفة 0، ولكن فقط إذا كان للدولة سعر: صف في Country prices، أو Fallback cost، أو سعر فوري من J&T. لا يُستعلم من J&T إلا عندما لا يعطي الجدول والتكلفة الاحتياطية أي سعر.

وإلا تُؤخذ التكلفة من أول مصدر يعطي سعرًا:

1. سعر J&T الفوري: فقط عندما تكون بيانات API الأربع والرمز البريدي للمرسِل مُعدّة، وتكون دولة التوصيل ماليزيا، وأدخل العميل رمزًا بريديًا من 5 أرقام، وعند وجود سعر صرف للمتاجر غير MYR. ترسل الإضافة الرموز البريدية للمرسِل والمستلم ووزن السلة (لا يقل عن 0.1 كجم) إلى J&T للخدمة القياسية EZ، طرد واحد، وتحوّل السعر المُعاد بالرينغيت إلى عملة متجرك.

2. Country prices: صف دولة التوصيل، أو صف *، مع سعر فئة وزن السلة.

3. Fallback cost.

إذا لم يعطِ أيٌّ من هذه المصادر سعرًا، تُخفى الطريقة. ويُطبَّق Per item على أسعار الجدول والتكلفة الاحتياطية فقط.

تُخزَّن كل استجابة من J&T مؤقتًا لمدة ساعة، فلا تُطلب الاستجابة نفسها لنفس السلة مرة أخرى. ويُخزَّن الطلب الفاشل مؤقتًا لمدة 10 دقائق، حتى لا ينتظر الدفع J&T عند كل تحديث. مهلة الطلب 10 ثوانٍ. إذا أعادت J&T خطأً، أو سعرًا صفريًا، أو لم تستجب، فلن يرى العميل أي خطأ. يُستخدم سعر الجدول أو التكلفة الاحتياطية، ويُكتب السبب في السجل.

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

تحسب الإضافة تكاليف الشحن فقط. لا تنشئ بوالص شحن أو إيصالات أو ملصقات، ولا تحجز مواعيد الاستلام، ولا تلغي الشحنات أو تتتبعها، ولا تتيح للعملاء اختيار نقطة استلام. أنشئ الشحنات وتابعها في حسابك لدى J&T كالمعتاد. وقد طُوّرت الإضافة وفق تنسيق الطلبات في الإضافة الرسمية J&T Express Malaysia. تحقق من الأسعار مع حسابك لدى J&T قبل تشغيل المتجر فعليًا.

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

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

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

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

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

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

لا يظهر J&T Express عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقق من حدود الوزن، وMinimum subtotal، وExcluded shipping classes. تحقق من أن Country prices يحتوي على صف للدولة أو صف *، أو أن Fallback cost مُعدّ. فعّل Debug log وراجع WooCommerce > Status > Logs.

السعر يأتي من الجدول وليس من J&T: تتطلب الأسعار الفورية بيانات API الأربع، ورمزًا بريديًا للمرسِل، وعنوان توصيل ماليزيًا برمز بريدي من 5 أرقام، وبالنسبة للمتاجر غير MYR، تتطلب Currency conversion rate. راجع التحذيرات في أعلى صفحة الإعدادات. إذا رفضت J&T الطلب أو لم تستجب، يُسجَّل الخطأ ويُستخدم سعر الجدول أو التكلفة الاحتياطية. يُعاد الطلب الفاشل بعد 10 دقائق.

لا توجد أسعار فورية للفلبين أو إندونيسيا: لا توفر J&T واجهة عامة للأسعار لهاتين الدولتين. استخدم جدول الأسعار والتكلفة الاحتياطية لهما.

تحصل دولة على شحن مجاني بالخطأ: صفها له سعر أساسي 0 (تُحفظ القيمة الأساسية الفارغة كـ 0). أدخل سعرًا أساسيًا أو احذف الصف.

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

خطافات المطورين: يغيّر الفلتر vfd_jtex_quote_request محتوى طلب السعر (مثل نوع الخدمة)، ويغيّر vfd_jtex_api_url نقطة نهاية الأسعار، ويتحكم الفلتر القياسي woocommerce_shipping_vfd_jt_express_is_available في التوافر.

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

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

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

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