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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

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

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

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

6. أضف VibeFox Ninja Van إلى منطقة شحن (مثل «Singapore») في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

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

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

عام

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

Method title: اسم طريقة الشحن الذي يظهر في السلة وفي صفحة الدفع. ويمكن لمنطقة أن تتجاوزه. الافتراضي: Ninja Van.

الأسعار (بعملة متجرك)

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

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

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

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

الشروط

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

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

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

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

Excluded shipping classes: يُخفي الطريقة عندما تحتوي السلة على منتج من أي فئة شحن من فئات WooCommerce هذه.

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. اختر None إذا كانت الأسعار في الجدول تتضمن الضريبة مسبقًا (GST أو SST أو VAT).

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

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

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

متقدم

Debug log: يسجل حسابات الأسعار في WooCommerce > Status > Logs (المصدر vfd_ninja_van). ولا تُسجَّل عناوين العملاء. وتُسجَّل طلبات Tariff API الفاشلة حتى عند إيقاف هذا الخيار. أوقفه بعد الانتهاء.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

للمطورين: يمكن للموقع الذي يملك حقل حي (Kecamatan) خاصًا به في صفحة الدفع أن يوفر رموز المناطق عبر المرشح vfd_njvn_tariff_zone.

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

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

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

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