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

المتطلبات

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

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

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

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

التثبيت

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

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

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

4. أدخل أسعار Ninja Van في جدول الأسعار. بالنسبة إلى إندونيسيا، يمكنك اختياريًا تفعيل Live rates (انظر الإعدادات). انقر على Save.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Ninja Van > Configure. وتُطبَّق على جميع مناطق شركة الشحن. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. لا يُحفظ شيء ويظهر خطأ عندما يحتوي حقل رقمي على نص أو رقم سالب، أو عندما يكون IDR conversion rate صفرًا، أو عندما يكون Minimum weight (kg) أكبر من Maximum weight (kg)، أو عندما يتجاوز Method title 64 حرفًا. وإذا لم تكن وحدة الوزن في متجرك إحدى الوحدات التي تعرفها الوحدة، فسيظهر تحذير بعد الحفظ يفيد بأن أوزان المنتجات تُعامَل بالكيلوغرامات.

عام

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

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

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

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

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

Price table: صف واحد لكل دولة وجهة. انقر على Add country لإضافة صف، وعلى أيقونة سلة المهملات لحذفه. اختر * All other countries لجميع الدول التي ليس لها صف خاص بها. يحتوي كل صف على Base price وأعمدة للوزن: 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: الطريقة التي تُحتسب بها الأسعار. وهذا ينطبق أيضًا على الأسعار الفورية.

الأسعار الفورية (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) الذي يظهر عنوانه أسفل الحقل. أدخل الرمزين معًا، أو اتركهما فارغين لاكتشافهما من عنوان المتجر في Shop Parameters > Contact > Stores: إندونيسيا، والولاية (state)، والمدينة، وإذا كانت المدينة تضم عدة مناطق، فالمنطقة الفرعية (Kecamatan) في سطر العنوان. يُمسح الرمز ذو التنسيق الخاطئ مع تحذير. وإذا أُدخل رمز واحد فقط، يطلب التحذير إدخال الرمزين، ويوضح سطر الحالة أن الأسعار الفورية لا تُطلب.

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

الشروط

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

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

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

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

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

Ignore shipping zones: يعرض Ninja Van للدول المذكورة أدناه حتى لو لم تكن شركة الشحن مرتبطة بمنطقتها. وعند التفعيل، ترتبط شركة الشحن بجميع المناطق النشطة، بما فيها المناطق التي تنشئها لاحقًا. وعند تعطيله، تستعيد شركة الشحن المناطق التي كانت مرتبطة بها سابقًا.

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

متقدم

Debug log: يسجّل حسابات الأسعار في logs/vfd_njvn_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. ولا تُسجَّل عناوين العملاء. وتُسجَّل طلبات Tariff API الفاشلة حتى عند تعطيل هذا الخيار. أوقفه عند الانتهاء.

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

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

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

في خطوة الشحن، تطلب PrestaShop من الوحدة سعر Ninja Van. ولا تُحتسب إلا المنتجات المادية: فالمنتجات الافتراضية لا تضيف وزنًا ولا تُدرج في مبلغ الطلب. وتتحقق الوحدة أولًا من الشروط: قائمة الدول الخاصة بـIgnore shipping zones (إذا كان مفعّلًا)، ووزن السلة، والحد الأدنى لمبلغ الطلب. وإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Ninja Van.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

للمطورين: يمكن لمتجر لديه حقل منطقة فرعية خاص به (Kecamatan) أن يوفّر رموز المناطق عبر الخطاف actionVfdNjvnTariffZone.

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

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

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