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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox iMile > Configure. تنطبق على كل منطقة من مناطق شركة الشحن. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. كما يمسح كل حفظ التقديرات المخزنة مؤقتًا من iMile ورموز الوصول.

عندما يكون Live estimate مفعّلًا لكنه لا يستطيع العمل، تظهر تحذيرات فوق الإعدادات: حقل Customer ID أو Secret key فارغ، أو مدينة الشحن أو بلدها غير محدد (أو البلد ليس من أسواق iMile)، أو لا توجد أسعار صرف، أو جدول الأسعار فارغ ولا يوجد سعر للبلدان الأخرى. يظهر تحذير أيضًا عندما لا تتعرف الوحدة على وحدة وزن المتجر: عندئذٍ تُعامَل أوزان المنتجات بالكيلوغرام، لذا اضبط الوحدة في International > Localization (Local units). عند الحفظ، تتحقق الوحدة من أن Method title صالح (64 حرفًا كحد أقصى)، وأن حقول المبلغ والوزن أرقام أكبر من أو تساوي 0، وأن Minimum weight ليس أكبر من Maximum weight، وأن قاعدة الضريبة موجودة. وإلا تُظهر خطأ ولا تحفظ شيئًا.

عام

Enable iMile: يُفعِّل شركة الشحن أو يُعطّلها. وهو المفتاح نفسه لحالة شركة الشحن في Shipping > Carriers.

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 المحفوظ.

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

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

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

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

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) يُستخدم السعر الأساسي. السعر الأساسي 0 يعني شحنًا مجانيًا إلى ذلك البلد. يُقبل كل من "9.99" و"9,99". تُحذف الصفوف التي لا تحتوي أي سعر والأسعار السالبة عند الحفظ. يُحتفظ بصف واحد فقط لكل بلد.

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

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

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

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

الشروط

Minimum weight: يُخفي شركة الشحن عندما تكون السلة أخف من هذا الوزن، بالكيلوغرام. 0 يعني بلا حد.

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

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

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

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

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

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

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

متقدم

Debug log: يكتب حسابات الأسعار في logs/vfd_imle_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل أي مفاتيح أو عناوين عملاء. تُسجَّل طلبات iMile الفاشلة دائمًا، حتى مع إيقاف سجل التصحيح. أوقف السجل عندما تنتهي.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

أسماء المدن لا تتطابق: يجب أن تطابق أسماء المدن قائمة مدن iMile. يمكن للمطورين ربطها عبر الخطاف actionVfdImileLiveRequest، ورموز البلدان عبر الخطاف actionVfdImileLiveCountryCode.

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

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

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

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

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

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

iMile علامة تجارية مسجلة لمالكها. هذه الوحدة غير تابعة لـ iMile ولا يدعمها iMile.