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

المتطلبات

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

PHP: ‏8.0 أو أحدث.

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

الإعداد

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

تشير التحذيرات أعلى الإعدادات (وتظهر مجددًا بعد كل حفظ) إلى أن عروض الأسعار الفورية مُعدّة جزئيًا: فهي تسرد إعدادات API الناقصة، أو تذكر أن عملة متجرك ليست MYR وأن سعر الصرف مفقود. ويظهر تحذير آخر إذا لم يكن لدى متجرك فئة وزن بوحدة kg في System > Localisation > Weight Classes. عندها تُحوَّل أوزان المنتجات حسب اسم وحدتها (kg وg وlb وoz)، وتُقرأ الوحدات الأخرى على أنها كيلوغرامات.

عام

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

Enable J&T Express: يُظهر الطريقة في الدفع أو يخفيها (حالة هذه الإضافة). الافتراضي: معطّل.

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

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

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

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

يُطلب السعر من J&T Express Malaysia لكل رمز بريدي ماليزي ويُخزَّن مؤقتًا لمدة ساعة. ومن دون بيانات الاعتماد، وللدول الأخرى، يُستخدم جدول الأسعار والتكلفة الاحتياطية.

VIP customer code: رمز VIP الخاص بك لدى J&T Express. مسحه يمسح أيضًا مفتاح واجهة VIP المحفوظ.

VIP API key: مفتاح الواجهة البرمجية (كلمة المرور) الذي منحتك إياه J&T Express مع رمز VIP. لا يُسجَّل في السجل أبدًا. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره. ولإزالته، امسح VIP customer code واحفظ.

API account: اسم حساب واجهة J&T Express البرمجية الخاص بك. مسحه يمسح أيضًا المفتاح الخاص المحفوظ.

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

Sender postcode: الرمز البريدي الماليزي الذي تُرسَل منه الطرود، على سبيل المثال 50000. مطلوب لعروض الأسعار الفورية: عنوان المتجر في OpenCart نص حر، لذلك لا يُؤخذ الرمز البريدي منه أبدًا.

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

جدول الأسعار والاحتياطي (يُستخدم للدول غير ماليزيا، عندما لا تكون عروض الأسعار الفورية مُعدّة أو عندما لا تقدم 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 ولا الجدول سعرًا. اتركه فارغًا لإخفاء الطريقة في هذه الحالة. 0 يعني شحنًا مجانيًا.

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).

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

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

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

Ignore shipping zones: اعرض الطريقة للدول المدرجة أدناه، بغض النظر عن المنطقة الجغرافية. الافتراضي: معطّل.

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

متقدم

Debug log: يكتب حسابات الأسعار في storage/logs/vfd_jtex_debug.log.php (وفي OpenCart 4 يكون الملف في system/storage/logs/vfd_jtex_debug.log.php). لا يمكن قراءة الملف من الويب. تُسجَّل أخطاء J&T API دائمًا، حتى مع إيقاف هذا الخيار. لا تُكتب أي مفاتيح أو كلمات مرور أو رمز العميل أو الرموز البريدية للعملاء. أوقف السجل عند الانتهاء. عندما يصل الملف إلى 5 ميغابايت يُنقل إلى vfd_jtex_debug.old.log.php ويبدأ سجل جديد.

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

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

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

Export: اضغط Download JSON لحفظ الإعدادات كملف JSON. لا يُصدَّر مفتاح واجهة VIP والمفتاح الخاص.

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

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

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

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

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

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

3. التكلفة الاحتياطية.

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

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

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

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox J&T Express هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox J&T Express > Edit، فوق الإعدادات. أدخل المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مُقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-shipping-jt-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.

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

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

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

لا تظهر J&T Express عند الدفع: تحقق من أن الترخيص نشط وأن Enable J&T Express مفعّل. تحقق من Geo zone (أو من أن Ignore shipping zones مفعّل وأن الدولة موجودة في Countries)، وحدود الوزن، وMinimum subtotal. تحقق من أن Country prices يحتوي على صف للدولة أو صف *، أو أن Fallback cost مُعيّنة. تحقق من أن المنتجات تحمل Requires Shipping على Yes. فعّل Debug log وانظر إلى حقل Log في صفحة الإضافة.

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

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

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

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

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

للمطورين: يمكن لإضافات أخرى تغيير نص طلب عرض السعر (مثل نوع الخدمة) عبر حدث OpenCart vfd_jt_express/quote_request، وتغيير نقطة نهاية عرض السعر عبر vfd_jt_express/api_url.

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

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

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

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