VibeFox iMile for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

تعرفة iMile: الأسعار التي اتفقت عليها مع فريق المبيعات في iMile. أدخلها في جدول الأسعار بعملة متجرك.

حساب iMile API (للتقدير المباشر فقط): يستخدم التقدير المباشر خدمة "Estimated order delivery costs" في OpenAPI الخاصة بـ iMile. تحتاج إلى Customer ID وSecret key (مفتاح API الذي تصدره iMile مع Customer ID). للعميل التجريبي، سجّل في بوابة مطوري iMile (developer.imile.com). تأتي مفاتيح الإنتاج من مدير حسابك لدى iMile. إذا كنت تستخدم جدول الأسعار فقط، فلا تحتاج إلى مفاتيح API.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل أسعار iMile في Price table. ويمكنك اختياريًا ملء قسم Live rates (API) وتفعيل Live estimate (انظر الإعداد).

6. أضف VibeFox iMile إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones (مثلًا "United Arab Emirates")، أو فعّل Ignore shipping zones واختر البلدان.

الإعداد

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

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

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

عام

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

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

أسعار مباشرة (API) (اختياري)

إذا لم تُعِد iMile أي تقدير (لا توجد مفاتيح، أو لم تُدخل المدينة بعد، أو حدث خطأ، أو انتهت المهلة، أو لا يوجد سعر صرف)، يُستخدم جدول الأسعار.

Live estimate: فعّله للحصول على تكلفة الشحن من iMile. الافتراضي: مُعطّل. ومع إيقاف التقدير المباشر لا يُرسل شيء إلى iMile أثناء الدفع.

Environment: Production (openapi.imile.com) (الافتراضي) أو Test (test-openapi.52imile.cn). تعمل مفاتيح الاختبار مع خادم الاختبار فقط، وتعطي أسعار اختبار.

Customer ID: رمز العميل (customerId) الذي تصدره iMile، مثل C2102192601.

Secret key: المفتاح السري (مفتاح API) الذي تصدره iMile مع Customer ID. يُستخدم لتوقيع الطلبات.

Signature: طريقة توقيع الطلبات.

Ship-from country: البلد الذي تشحن منه. افتراضيًا هو بلد متجرك. تحتوي القائمة على البلدان التي تتوفر لدى الإضافة رموز بلدانها في iMile.

Ship-from city: المدينة التي تُرسل منها طرودك، مكتوبة كما في قائمة مدن iMile (مثل Dubai وRiyadh). اتركه فارغًا لاستخدام مدينة المتجر من WooCommerce > Settings > General.

Ship-from province: اختياري، مثل Dubai أو Riyadh Province.

iMile service: نوع الطلب المُرسل إلى iMile: Delivery order (100) (الافتراضي) أو Express order (1100). يجب تفعيل Express لحسابك وبلدك.

Goods category: نوع البضائع المُرسلة إلى iMile: Normal goods (الافتراضي)، أو Sensitive (cosmetics, liquids...)، أو With battery، أو Batteries / power banks، أو Documents، أو Parcel.

Exchange rates: تُصدر iMile تقديراتها بعملة بلد الوجهة. أدخل سطرًا لكل عملة مع سعر وحدة واحدة بعملة متجرك، مثل "AED = 0.25" أو "SAR = 0.24". ويُقبل الفاصل العشري النقطة أو الفاصلة. لا تحتاج عملة المتجر نفسها إلى سعر صرف. وبدون سعر صرف لا تُستخدم التقديرات بتلك العملة، ويُستخدم جدول الأسعار بدلًا منها. ويحوّل السعر نفسه قيمة السلة المُعلنة إلى iMile. وتُحذف الأسطر غير الصالحة عند الحفظ.

الأسعار (يُستخدم عند إيقاف التقدير المباشر، وكبديل عندما لا تُعيد iMile أي تقدير)

أدخل تعرفة iMile بعملة المتجر. وإذا كانت بعملة AED أو SAR أو غيرها، فحوّلها أولًا.

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

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

Price applies: طريقة احتساب سعر الجدول.

ينطبق الخيار نفسه على التقدير المباشر: لكل طلب، تُرسل شحنة واحدة تضم السلة كاملة؛ ولكل منتج، يُطلب تقدير لكل طرد مختلف ويُضرب في عدد الوحدات. وإذا احتوت السلة على أكثر من 5 طرود مختلفة، يُستخدم جدول الأسعار.

تُحوَّل أوزان المنتجات من وحدة الوزن في متجرك إلى كيلوغرامات.

الشروط

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

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

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

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

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

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

الإتاحة بدون مناطق الشحن

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

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

متقدم

Debug log: يكتب حسابات الأسعار في WooCommerce > Status > Logs (المصدر "vfd_imile"). لا تُسجَّل المفاتيح ولا عناوين العملاء. وتُسجَّل طلبات iMile الفاشلة دائمًا حتى مع إيقاف سجل التصحيح. أوقف السجل عند الانتهاء.

Remove data on uninstall: عند التفعيل، يؤدي حذف الإضافة إلى إزالة كل إعدادات iMile وطرق المناطق والتقديرات المخزنة مؤقتًا. أما تعطيل الإضافة فلا يحذف شيئًا أبدًا.

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

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

مع تفعيل التقدير المباشر، ترسل الإضافة إلى iMile بلد الشحن ومحافظته ومدينته، وبلد الوجهة وولايتها ومدينتها ورمزها البريدي، ووزن السلة بالكيلوغرام، والحجم بالسنتيمتر المكعب (من أبعاد المنتجات)، وقيمة السلة، وخدمة iMile، وفئة البضائع. ويُطلب التقدير دائمًا كمدفوع مسبقًا، لذلك لا تُدرج رسوم الدفع عند الاستلام. ولا يُطلب التقدير المباشر إلا بعد أن يُدخل العميل مدينة، وفقط عندما يكون لكل طرد وزن. وتُخزَّن كل إجابة مؤقتًا لمدة ساعة. ويُخزَّن الطلب الفاشل مؤقتًا لمدة 5 دقائق. وبعد انتهاء المهلة أو خطأ في الخادم، لا يُطلب من iMile شيء لمدة دقيقتين؛ وبعد رفض المفاتيح، لمدة 5 دقائق، حتى لا ينتظر الدفع iMile عند كل تحديث. ومهلة API هي 12 ثانية. ويُجدَّد رمز الوصول المنتهي تلقائيًا.

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

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

تحسب الإضافة الأسعار فقط. ولا تُنشئ شحنات iMile، ولا تطبع ملصقات AWB، ولا تطلب الاستلام، ولا تتتبع الطرود، ولا تُطابق مبالغ الدفع عند الاستلام، ولا تقدم نقاط الاستلام أو الخزائن. استخدم بوابة iMile للشحنات.

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

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

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

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

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

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

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

يظهر سعر الجدول بدلًا من تقدير iMile: افتح WooCommerce > Status > Logs، وحدد المصدر "vfd_imile"، وفعّل Debug log لعرض التفاصيل. الأسباب الشائعة: Live estimate مُعطّل، أو المفاتيح مفقودة، أو لم يُدخل العميل المدينة بعد، أو لا يتعرف iMile على كتابة اسم المدينة، أو المنتجات بلا وزن، أو لا يوجد سعر صرف لعملة الوجهة، أو حدث خطأ في API. وراجع أيضًا التحذيرات أعلى الإعدادات.

"sign is invalid" في السجل: تحقق من Secret key، ثم جرّب Signature = SimpleKey.

تُرفض المفاتيح: تحقق من Customer ID وSecret key وEnvironment. تعمل مفاتيح الاختبار مع خادم الاختبار فقط.

أسماء المدن غير متطابقة: يجب أن تطابق أسماء المدن قائمة مدن iMile. ويمكن للمطورين ربطها بفلتر vfd_imile_live_request، وربط رموز البلدان بفلتر vfd_imile_live_country_code.

الأسعار بعملة خاطئة: جدول الأسعار بعملة المتجر (WooCommerce > Settings > General). حوّل تعرفة AED أو SAR أو MXN عند إدخالها. وتُحوَّل التقديرات المباشرة باستخدام Exchange rates.

تُفرض الضريبة مرتين على الشحن: إذا كانت أسعارك تتضمن VAT بالفعل، فاضبط Tax status على None.

تبدو التقديرات قديمة بعد تغيير: احفظ صفحة الإعدادات. وهذا يمسح تقديرات iMile المخزنة مؤقتًا.

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

الإلغاء

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

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