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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

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

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

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

التثبيت

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

OpenCart 3

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

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

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

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

5. أدخل أسعار iMile في Price table. واختيارياً، املأ قسم Live rates (API) وفعّل Live estimate (انظر الإعدادات). فعّل Enable iMile واضغط Save.

OpenCart 4

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox iMile > Edit. تظهر الأقسام في الجهة اليسرى. يحفظ زر Save الصفحة كاملة دون إعادة تحميلها. وكل حفظ يمسح أيضاً التقديرات المخزنة مؤقتاً من iMile ورموز الوصول. يستطيع حفظ الإعدادات فقط مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

عند الحفظ، تتحقق الإضافة من أن Method title صالح (بحد أقصى 64 حرفاً، دون الحروف < > ; = # { })، وأن حقول السعر والمبلغ والوزن أرقام 0 أو أكبر، وأن Minimum weight (kg) ليس أكبر من Maximum weight (kg)، وأن Sort order رقم صحيح، وأن فئة الضريبة والمنطقة الجغرافية موجودتان. وإلا تعرض خطأً ولا تحفظ شيئاً.

تظهر تحذيرات فوق الإعدادات (وتظهر من جديد بعد الحفظ) عندما يكون Live estimate مفعّلاً لكنه لا يستطيع العمل: إذا كان Customer ID أو Secret key فارغاً، أو كانت مدينة الإرسال أو دولته ناقصة (أو كانت الدولة ليست سوقاً لـ iMile)، أو لا توجد أسعار صرف، أو كان جدول الأسعار فارغاً ولا يوجد سعر للدول الأخرى. ويظهر تحذير أيضاً عندما لا توجد لدى المتجر فئة وزن بوحدة kg وكانت وحدة فئة الوزن الافتراضية غير معروفة للإضافة: حينها تُعامَل أوزان المنتجات على أنها كيلوغرامات، لذا أضف فئة وزن kg في System > Localisation > Weight Classes.

عام

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

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

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وعند الدفع. الافتراضي: iMile. حقل مطلوب.

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

التعريفات الحية (API) (اختياري)

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

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

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

Customer ID: رمز العميل (customerId) الذي تصدره iMile، مثل C2102192601. مسح هذا الحقل يمسح أيضاً Secret key المحفوظ.

Secret key: المفتاح السري (مفتاح API) الذي تصدره iMile مع Customer ID. وهو يوقّع الطلبات. بعد الحفظ يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره.

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

Ship-from country: الدولة التي تشحن منها. الخيار الأول Store country يستخدم دولة متجرك. تحتوي القائمة على الدول التي تعرف الإضافة رموزها لدى iMile فقط.

Ship-from city: المدينة التي تُرسَل منها طرودك، مكتوبة كما في قائمة مدن iMile (مثل Dubai أو Riyadh). مطلوبة للتقدير الحي: لا يحتوي OpenCart على مدينة للمتجر، لذلك بدون هذا الحقل لا يُستخدم إلا جدول الأسعار.

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 طرود مختلفة، يُستخدم جدول الأسعار.

تُحوَّل أوزان المنتجات من فئة الوزن في OpenCart إلى كيلوغرامات، وأبعادها من فئة الطول إلى سنتيمترات.

الشروط

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

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

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

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

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

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

الدول

Ignore shipping zones: عند التفعيل، لا تُفحَص Geo zone، ويُعرض iMile للدول المذكورة أدناه. وعند التعطيل (الافتراضي) تسري Geo zone فقط.

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

متقدم

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

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

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

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

Export: اضغط Download JSON لحفظ الإعدادات كملف JSON. لا يُصدَّر Secret key.

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

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

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

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

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

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

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

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox iMile هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox iMile > Edit، فوق الإعدادات. أدخل المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مُقنّعاً، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، وأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: opencart-shipping-imile ورابط 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.

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

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

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

لا يظهر iMile عند الدفع: تحقق من أن الترخيص نشط وأن Enable iMile مفعّل. تحقق من Geo zone وIgnore shipping zones وCountries، وحدود الوزن، وMinimum order amount. تحقق من أن للدولة أو لـ * All other countries صفاً في Price table، أو أن Price for countries not in the table مُعدّ. تحقق من أن المنتجات مضبوطة على Requires Shipping بقيمة Yes.

يظهر سعر الجدول بدلاً من تقدير iMile: فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى الحقل Log في صفحة الإضافة. الأسباب الشائعة: Live estimate معطّل، أو المفاتيح مفقودة، أو Ship-from city فارغ، أو لم يُدخل العميل المدينة بعد، أو لا تعرف iMile كتابة المدينة، أو لا تملك المنتجات وزناً، أو لا يوجد سعر صرف للعملة المستهدفة، أو خطأ في الواجهة البرمجية. وتحقق أيضاً من التحذيرات فوق الإعدادات.

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

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

أسماء المدن غير متطابقة: يجب أن تطابق أسماء المدن قائمة مدن iMile. يستطيع المطوّرون تغيير الطلب عبر حدث OpenCart vfd_imile/live_request، وتغيير رموز الدول عبر الحدث vfd_imile/live_country_code.

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

الضريبة تُحتسب مرتين على الشحن: إذا كانت أسعارك تتضمن ضريبة القيمة المضافة بالفعل، فاضبط Tax class على No tax.

تبدو التقديرات قديمة بعد تغيير: اضغط Save في صفحة الإضافة. سيؤدي ذلك إلى مسح التقديرات المخزنة مؤقتاً من iMile.

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

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

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

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

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