VibeFox Ninja Van for OpenCart — المساعدة

المتطلبات

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

PHP: 8.0 أو أحدث.

جدول أسعار Ninja Van: أسعار حساب المرسل لديك في Ninja Van أو الأسعار التي يقدمها فريق مبيعات Ninja Van، وتُدخل في جدول الأسعار. لا تحتاج إلى مفاتيح API. تستخدم الأسعار الفورية الاختيارية داخل إندونيسيا واجهة Ninja Van Tariff API، وهي عامة ولا تتطلب مصادقة.

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

التثبيت

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

OpenCart 3

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

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

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

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

5. أدخل أسعار Ninja Van في جدول الأسعار. بالنسبة لإندونيسيا، يمكنك اختياريًا تفعيل Live rates (انظر الإعدادات). فعّل Enable Ninja Van واضغط Save.

OpenCart 4

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit. تُعرض الأقسام في الجانب الأيسر. يحفظ زر Save واحد في الأسفل الصفحة كاملة دون إعادة تحميلها. لا يُحفظ شيء ويظهر خطأ عندما يكون Method title فارغًا أو يتجاوز 64 حرفًا أو يحتوي على < > ; = # { }، أو عندما يحتوي حقل رقمي على نص أو عدد سالب، أو عندما تكون قيمة IDR conversion rate صفرًا، أو عندما يكون Minimum weight (kg) أكبر من Maximum weight (kg)، أو عندما لا يكون Sort order عددًا صحيحًا. وإذا لم تحتوِ متجرك على فئة وزن وحدتها kg، ولم تتعرف الإضافة على وحدة فئة الوزن الافتراضية، يظهر تحذير يفيد بأن أوزان المنتجات تُعامل بالكيلوغرام: أضف فئة وزن kg في System > Localisation > Weight Classes. ولا يستطيع حفظ الإعدادات سوى مستخدمي الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

عام

تنطبق الإعدادات على جميع المناطق الجغرافية. يمكنك قصر الطريقة على منطقة جغرافية في Conditions، أو استخدام Ignore shipping zones.

Enable Ninja Van: يُظهر Ninja Van عند الدفع أو يُخفيه. الافتراضي: معطل.

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وعند الدفع. الافتراضي: Ninja Van. مطلوب، بحد أقصى 64 حرفًا.

Tax class: فئة الضريبة لتكلفة الشحن، أو No tax (الافتراضي). اختر No tax إذا كانت الأسعار في الجدول تتضمن الضريبة بالفعل (GST أو SST أو VAT).

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

الأسعار (بعملة المتجر الافتراضية، دون الضريبة)

أدخل أسعار جدول Ninja Van الخاص بك بعملة المتجر الافتراضية. إذا كان جدولك بعملة SGD أو MYR أو IDR أو عملة أخرى، فحوّله أولًا. يُستخدم هذا الجدول لكل وجهة خارج إندونيسيا، وعندما لا يتوفر السعر الفوري.

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

Price for countries not in the table: يُستخدم عندما لا يكون في الجدول صف للدولة الوجهة (ولا صف *)، أو عندما لا يحتوي الصف على سعر لهذا الوزن. اتركه فارغًا لإخفاء الطريقة في هذه الحالة. والقيمة 0 تعني شحنًا مجانيًا.

Price applies: الطريقة التي تُحسب بها الأسعار. وينطبق هذا أيضًا على الأسعار الفورية.

Per order (one parcel, tier by total cart weight): سعر واحد للسلة، ويُختار عمود الوزن حسب الوزن الإجمالي للسلة. وهذا هو الافتراضي.

Per item (every item is a separate parcel, tier by its own weight): يُسعَّر كل منتج حسب وزنه الخاص وتُجمع الأسعار، فتكلفة 3 وحدات من منتج ما تساوي 3 أضعاف سعره. ومع الأسعار الفورية، يُسعَّر كل منتج من Ninja Van كطرد منفصل.

الأسعار الفورية (API) — إندونيسيا

تُعيد Ninja Van Tariff API رسوم التوصيل القياسية دون رسوم إضافية أو خصومات، للطرود المرسلة داخل إندونيسيا. وتقدمها Ninja Van لإندونيسيا فقط. عندما يكون Live rates مفعّلًا، تعرض أسطر الحالة أسفل عنوان القسم منطقة الشحن، وسعر تحويل مفقودًا، وآخر رد من Tariff API (البيئة والوقت والنتيجة). وتُحدَّث بعد كل حفظ.

Live rates: للحصول على الأسعار الفورية من Ninja Van للتوصيل داخل إندونيسيا. الافتراضي: معطل. وبدون هذا الخيار لا يُرسل شيء إلى Ninja Van أثناء الدفع.

Environment: Production (api.ninjavan.co) (الافتراضي) أو Sandbox — testing only (api-sandbox.ninjavan.co).

Service level: الخدمة التي يُطلب السعر لها: Standard (الافتراضي)، أو Express، أو Same day، أو Next day. إذا لم يكن لدى Ninja Van سعر للمسار والخدمة، يُستخدم جدول الأسعار.

Ship-from zone code L1 وShip-from zone code L2: رموز المستوى L1 وL2 للمنطقة التي تشحن منها، على سبيل المثال ID_A00007_01 وID_B00069_01، من ربط رموز مناطق Ninja Van (CSV) الذي يظهر عنوانه أسفل الحقل. أدخل الرمزين معًا: عنوان المتجر في OpenCart لا يحتوي على مدينة أو شارع منفصلين، لذلك لا يمكن استنتاج منطقة الشحن منه. تُحوَّل الرموز إلى حروف كبيرة. ويُمسح الرمز ذو الصيغة الخاطئة مع تحذير. وإذا أُدخل رمز واحد فقط، يطلب التحذير إدخال الرمزين، ويوضح سطر الحالة أن الأسعار الفورية غير مطلوبة. ويحذر سطر حالة آخر أيضًا عندما لا يشكل الرمزان زوجًا في ربط رموز المناطق.

IDR conversion rate: تُعيد Tariff API الرسوم بالروبية الإندونيسية (IDR). إذا كانت عملة المتجر الافتراضية هي IDR فاتركه فارغًا. وإلا فأدخل مقدار 1 IDR بعملة متجرك، على سبيل المثال 0.000058. ويجب أن تكون القيمة أكبر من 0. وبدونه لا تُستخدم الأسعار الفورية، ويُستخدم جدول الأسعار.

الشروط

Minimum weight (kg): يُخفي الطريقة عندما يكون وزن السلة أقل من ذلك. تُحوَّل أوزان المنتجات من فئة الوزن في OpenCart إلى كيلوغرامات. والقيمة 0 تعني بلا حد (الافتراضي).

Maximum weight (kg): يُخفي الطريقة عندما يكون وزن السلة أكبر من ذلك. الافتراضي: 30. والقيمة 0 أو الحقل الفارغ يعنيان بلا حد. لا يمكن أن يكون أقل من Minimum weight (kg).

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

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

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

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

Ignore shipping zones: اعرض Ninja Van للدول المذكورة أدناه بغض النظر عن Geo zone. وعندما يكون معطلًا (الافتراضي)، تحدد المنطقة الجغرافية الأمر، ولا تُستخدم قائمة الدول.

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

متقدم

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

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

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

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

Export: اضغط Download JSON لحفظ الإعدادات كملف JSON. لا تحتوي الإضافة على مفاتيح سرية، لذلك يُصدَّر كل شيء.

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

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

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

يأتي السعر من صف الدولة (أو صف *): أولًا عمود الوزن، ثم السعر الأساسي، ثم Price for countries not in the table. وإذا لم يوجد سعر، تُخفى الطريقة لتلك السلة. ويُحسب السعر بعملة المتجر الافتراضية، ويُقرَّب إلى منازله العشرية، ويُعرض للعميل بعملته مع ضريبة Tax class المختارة.

عندما يكون Live rates مفعّلًا، يُسعَّر التوصيل داخل إندونيسيا أولًا من Ninja Van. تحوّل الإضافة عنوان التوصيل إلى رموز مناطق Ninja Van: المنطقة (المحافظة) في العنوان، وحقل City (المدينة أو المقاطعة)، وبالنسبة للمدن التي لها عدة مناطق، الحي (Kecamatan) المكتوب في Address 1 أو Address 2. وترسل رموز الشحن الخاصة بك، ورموز التوصيل، والوزن، ومستوى الخدمة، وتحوّل الرسوم من IDR إلى عملة متجرك. ومع Per item، يُرسل طلب واحد لكل وزن مختلف للمنتج، بحد أقصى 5 لكل سلة. وإذا تجاوزت الأوزان المختلفة ذلك، يُستخدم جدول الأسعار.

تسمح Tariff API بـ 20 طلبًا في الدقيقة، لذلك تُخزَّن الردود مؤقتًا في جدول تابع للإضافة: الأسعار لمدة 6 ساعات، و"لا يوجد سعر لهذا المسار" لمدة ساعة، والأخطاء لمدة 5 دقائق. ولا يؤدي حفظ الإعدادات إلى مسح هذه الذاكرة المؤقتة. ولا ترسل الإضافة أكثر من 18 طلبًا في الدقيقة، وبعد رد HTTP 429 تتوقف مؤقتًا لمدة ساعة. ومهلة انتظار API هي 12 ثانية. وإذا لم ترد Ninja Van، أو أعادت خطأ، أو لم يكن لديها سعر للمسار، أو تعذرت مطابقة العنوان، يُستخدم سعر الجدول. وتذهب الأخطاء إلى السجل، ولا تُعرض أبدًا على العميل.

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

تحسب الإضافة الأسعار فقط. ولا تنشئ طلبات Ninja Van، ولا تطبع بوالص الشحن الجوي (AWB)، ولا تحجز استلامات، ولا تتبع الطرود، ولا تتعامل مع COD. استخدم لوحة Ninja Van Dashboard لذلك. لا يوجد محدد لنقاط الاستلام (Ninja Points): الطريقة توصيل حتى الباب. ولا تضيف الإضافة شيئًا إلى الطلبات: يعرض الطلب اسم الطريقة وتكلفة الشحن مثل أي طريقة شحن أخرى في OpenCart. والأسعار الفورية غير متوفرة خارج إندونيسيا.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Ninja Van هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit، فوق الإعدادات. أدخل المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مُخفى، والحالة (على سبيل المثال تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: opencart-shipping-ninja-van ورابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة. وتتبع نصوص الكتلة لغة الإدارة (الإنجليزية والروسية مضمنتان).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، على سبيل المثال Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، اضغط Check now. وإذا تعذر الوصول إلى خادم التراخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

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

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

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

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

لا تظهر Ninja Van عند الدفع: تحقق من أن الترخيص نشط وأن Enable Ninja Van مفعّل. وتحقق من Geo zone (أو Ignore shipping zones وCountries)، وحدود الوزن، وMinimum order amount، ومن أن الدولة أو صف * أو Price for countries not in the table يحتوي على سعر. وتأكد من أن المنتجات لديها Requires Shipping على Yes.

لا يُستخدم السعر الفوري لبعض العناوين: يجب مطابقة الوجهة مع منطقة Ninja Van: إندونيسيا، والمنطقة (المحافظة)، والمدينة أو المقاطعة في City، وبالنسبة للمدن التي لها عدة مناطق، الحي (Kecamatan) في أحد أسطر العنوان. وإلا فسيُستخدم سعر الجدول. فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى الحقل Log في صفحة الإضافة.

لا تُطلب الأسعار الفورية أصلًا: توضح أسطر الحالة أسفل Live rates (API) — Indonesia السبب: رموز مناطق الشحن مفقودة، أو لم يُدخل إلا أحد الرمزين، أو الرموز المدخلة لا تشكل زوجًا في ربط رموز المناطق، أو أن IDR conversion rate مفقود.

بلوغ حد الطلبات (HTTP 429): تتوقف الطلبات الفورية مؤقتًا لمدة ساعة، ويُستخدم جدول الأسعار في الأثناء. ولا ينهي حفظ الإعدادات هذا التوقف.

بأي عملة الأسعار: الجدول والشروط بعملة المتجر الافتراضية. والأسعار الفورية بالروبية (IDR)، وتُحوَّل باستخدام IDR conversion rate ما لم تكن عملة متجرك IDR.

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

للمطورين: يمكن لمتجر لديه حقل حي (Kecamatan) خاص به توفير رموز المناطق عبر حدث OpenCart vfd_ninja_van/tariff_zone (المشغل catalog/vfd_ninja_van/tariff_zone)، بما في ذلك منطقة الشحن. ويمكن استبدال عنوان Tariff API بالإعداد vfd_njvn_api_url (للاختبارات)؛ ولا يوجد له حقل في صفحة الإعدادات.

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

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

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

Ninja Van علامة تجارية تخص مالكها. وهذه الإضافة غير تابعة لـ Ninja Van ولا تحظى بتأييدها.