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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

الوصول إلى واجهة برمجة 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. في الواجهة الخلفية، انتقل إلى Modules > Module Manager واضغط Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند اكتمال الرفع، اضغط Configure، أو ابحث لاحقًا عن VibeFox J&T Express في قائمة الوحدات واضغط Configure.

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

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

عند التثبيت تُنشئ الوحدة شركة الشحن J&T Express مع نص مدة التوصيل Courier delivery. تُخصَّص شركة الشحن لجميع المناطق ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox J&T Express > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. كل حفظ يمسح أيضًا الأسعار المخزنة مؤقتًا من J&T. إذا كانت الأسعار الفورية مُعدّة جزئيًا، فسيعرض تنبيه أعلى الصفحة الإعدادات الناقصة أو يخبرك بأن سعر تحويل العملة مفقود. تُرفض المبالغ التي ليست رقمًا أكبر من أو يساوي 0 مع خطأ، وكذلك Currency conversion rate الذي يساوي 0، وMin weight الذي يتجاوز Max weight. إذا لم تُتعرَّف وحدة وزن متجرك، يطلب منك تنبيه ضبط وحدة قياسية في International > Localization.

عام

تسري الإعدادات في هذه الصفحة على جميع المناطق. تُحدَّد مناطق شركة الشحن ومجموعات العملاء وحدود الحجم في Shipping > Carriers (أو استخدم Ignore shipping zones أدناه).

Enable J&T Express: يُشغّل شركة الشحن أو يوقفها. هذا هو نفس مفتاح حالة شركة الشحن في Shipping > Carriers.

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

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

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

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

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

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

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

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

Currency conversion rate: أسعار J&T Express Malaysia بالعملة MYR. إذا لم تكن العملة الافتراضية لمتجرك هي MYR، فأدخل كم وحدة من عملتك تساوي ميرينغيت واحد (1 MYR = X). بدونه لا تُستخدم الأسعار الفورية، ويُستخدم بدلًا منها جدول الأسعار أو التكلفة الاحتياطية. إذا كانت عملتك الافتراضية هي 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: أخفِ شركة الشحن عندما يكون وزن السلة أقل من ذلك، بالكيلوغرام. تُحوَّل أوزان المنتجات من وحدة وزن متجرك. 0 يعني بلا حد. لا يمكن أن يكون أكبر من Max weight.

Max weight: أخفِ شركة الشحن عندما يكون وزن السلة أكثر من ذلك، بالكيلوغرام. الافتراضي: 50. 0 يعني بلا حد.

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

J&T Express علامة تجارية تعود لمالكها. هذه الوحدة غير تابعة لـ J&T Express ولا معتمدة منها.