VibeFox 99Minutos for OpenCart — المساعدة

المتطلبات

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

PHP: 8.0 أو أحدث.

مفتاح واجهة برمجة 99minutos (لفحص التغطية فقط): احصل عليه من مدير حسابك لدى 99minutos أو من بوابة المطورين الخاصة بـ 99minutos (developers.99minutos.com). مفاتيح بيئة الاختبار (sandbox) ومفاتيح الإنتاج مختلفة. إذا كنت تستخدم مصفوفة الأسعار فقط، فلا تحتاج إلى مفتاح واجهة برمجة.

البلدان: تقدم 99minutos خدمة التوصيل إلى المكسيك وكولومبيا وتشيلي وبيرو. يجب تفعيل البلدان التي تشحن إليها في System > Localisation > Countries.

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

التثبيت

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

OpenCart 3

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

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

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

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

5. املأ Price matrix (صف واحد على الأقل، مثل "* Default")، واختياريًا مفتاح واجهة البرمجة ووضع فحص التغطية (انظر الإعداد). فعّل Enable 99Minutos واضغط على Save.

OpenCart 4

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

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

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

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

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

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit. تظهر الأقسام في الجهة اليسرى. يحفظ زر Save واحد الصفحة كاملة دون إعادة تحميلها. ويمسح كل حفظ أيضًا نتائج التغطية المخزنة مؤقتًا. وإذا كانت قيمة ما خاطئة، فلن يُحفظ أي شيء وتعرض الصفحة السبب، مثل Enter a method title (1 to 64 characters).، أو رسالة تفيد بأن الحقل يجب أن يكون رقمًا يساوي 0 أو أكبر، أو أن Min weight (kg) لا يمكن أن يكون أكبر من Max weight (kg). وبعد الحفظ، تخبرك التحذيرات فوق الإعدادات بالحالات التي لا تستطيع فيها الطريقة العمل بالإعداد الحالي: مصفوفة الأسعار فارغة، أو اختير وضع فحص تغطية دون مفتاح واجهة برمجة، أو تحتوي المصفوفة على صفوف لبلدان لا تخدمها 99minutos، أو لا تملك المتجر فئة وزن "kg" وكانت وحدة الوزن غير معروفة للإضافة (وتُعامل الأوزان حينها على أنها كيلوغرامات). ولا يمكن حفظ الإعدادات إلا من قبل مستخدمي الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

عام

تنطبق الإعدادات على كل المناطق الجغرافية. تُعرض خدمة 99Minutos فقط للمكسيك وكولومبيا وتشيلي وبيرو كبلدان وجهة.

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

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وعند الدفع. الافتراضي: 99Minutos. حقل مطلوب، حتى 64 حرفًا.

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

Sort order: ترتيب ظهور 99Minutos بين طرق الشحن عند الدفع. رقم صحيح.

واجهة برمجة 99minutos (فحص التغطية) (اختياري)

تُستخدم واجهة البرمجة فقط للتحقق مما إذا كانت 99minutos تقدم التوصيل إلى الرمز البريدي للعميل. ويأتي السعر دائمًا من المصفوفة.

Coverage check: ما إذا كان الرمز البريدي سيُفحص، وكيف.

مع فحص التغطية، لا تظهر الطريقة إلا بعد أن يدخل العميل رمزًا بريديًا. تُخزَّن النتائج مؤقتًا: مشمول لمدة 6 ساعات، وغير مشمول لمدة 30 دقيقة، وخطأ في واجهة البرمجة لمدة 5 دقائق، لكن لا يتجاوز ذلك مدة صلاحية ذاكرة OpenCart المؤقتة (ساعة واحدة افتراضيًا). لا يُرسل إلى 99minutos سوى الرمز البريدي، بأحرف كبيرة ومكوّنًا من الحروف والأرقام فقط.

API key: مفتاح واجهة برمجة 99minutos الخاص بك، ويُرسل كرمز Bearer إلى نقطة فحص التغطية لدى 99minutos. مطلوب عند تفعيل فحص التغطية. وبعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره. يُحفظ المفتاح كما أدخلته، وتُزال فقط المسافات المحيطة به.

Remove the saved API key: يظهر فقط عندما يكون هناك مفتاح محفوظ. فعّله ثم اضغط على Save لحذف المفتاح.

Environment: Sandbox (test) (الافتراضي) أو Production. تستخدم بيئتا الاختبار والإنتاج مفاتيح واجهة برمجة مختلفة، لذا اختر البيئة التي تناسب مفتاحك.

التعرفة

الأسعار بعملة المتجر الافتراضية، دون الضريبة، وتُستخدم كما أُدخلت. ويُعرض السعر النهائي بعملة العميل.

Price matrix: جدول لبلدان الوجهة والأسعار. اضغط على Add country لإضافة صف، وعلى زر × لحذفه. يحتوي كل صف على Country (* Default، أو المكسيك، أو كولومبيا، أو تشيلي، أو بيرو)، وBase price، وأسعار للأحجام XS (حتى 1 كغ)، وS (حتى 2 كغ)، وM (حتى 3 كغ)، وL (حتى 5 كغ)، وXL (أكثر من 5 كغ). ويُستخدم Base price عندما يكون سعر الحجم فارغًا أو يساوي 0. ينطبق صف * Default على البلدان التي ليس لها صف خاص بها. وإذا كان لبلد عدة صفوف، فيُستخدم الأول. يُقبل كل من النقطة والفاصلة كفاصل عشري؛ وتُحفظ الأسعار الفارغة أو غير الصالحة أو السالبة كقيمة 0. وإلى أن تحتوي المصفوفة على صف واحد على الأقل، لا تظهر الطريقة عند الدفع.

Calculation: Per order — size by the total cart weight (الافتراضي) يفرض سعرًا واحدًا لحجم طرد السلة بأكملها. وPer item — each unit priced by its own weight يسعّر كل وحدة بحسب حجم وزنها الخاص ويجمع الأسعار.

Free shipping: يفعّل الشحن المجاني من مبلغ طلب معين.

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

القيود

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

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

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

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

Restrict countries: تُقدَّم الطريقة فقط للبلدان المذكورة أدناه. وهو فلتر إضافي فوق Geo zone.

Countries: اختيار من بلدان 99minutos (المكسيك، وكولومبيا، وتشيلي، وبيرو). يُستخدم فقط عندما يكون Restrict countries مفعّلًا. اتركه فارغًا للسماح بجميع بلدان 99minutos.

متقدم

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

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

Remove data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات 99minutos وذاكرة التغطية المؤقتة والسجل. وعند تعطيله (الافتراضي) تُحفظ لإعادة التثبيت. وتبقى الطلبات محفوظة في جميع الأحوال.

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

Export: اضغط على Download JSON لحفظ الإعدادات في ملف JSON. لا يُصدَّر مفتاح واجهة البرمجة.

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

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

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر 99Minutos. إذا كانت Geo zone مضبوطة وكان العنوان خارجها، فلن تُعرض 99Minutos. ولا يُحتسب إلا المنتجات التي ضُبط فيها Requires Shipping على Yes؛ أما المنتجات الأخرى فلا تضيف وزنًا ولا تدخل في مبلغ الطلب. تُعرض الطريقة فقط عندما يكون بلد التوصيل هو المكسيك أو كولومبيا أو تشيلي أو بيرو (وأن يكون ضمن قائمة Countries إذا كان Restrict countries مفعّلًا). ثم تتحقق الإضافة من حدود الوزن وMinimum subtotal. ومبلغ الطلب هو سعر المنتجات التي تحتاج إلى شحن، بعد خصم القسيمة وقبل الضريبة. ولا تُؤخذ في الحسبان شهادات الهدايا ونقاط المكافآت وائتمان المتجر.

إذا كان فحص التغطية مفعّلًا، تسأل الإضافة واجهة برمجة 99minutos عما إذا كان الرمز البريدي مشمولًا بالخدمة. ومهلة الطلب 10 ثوانٍ، ويُخزَّن الرد مؤقتًا، فلا يؤدي الرمز البريدي نفسه إلى طلب جديد. ولا تُعرض أخطاء واجهة البرمجة على العميل أبدًا: ففي وضع Strict تُخفى الطريقة، وفي وضع Soft يُستخدم سعر المصفوفة. ولا يتجاوز الشحن المجاني فحص التغطية.

يُؤخذ السعر من صف المصفوفة لبلد التوصيل، أو من صف * Default. وإذا لم يوجد أيٌّ منهما، تُخفى الطريقة. وإذا كان Free shipping مفعّلًا وبلغ مبلغ الطلب Free shipping from، تكون التعرفة 0. يُحسب السعر بعملة المتجر الافتراضية، ويُقرَّب إلى منازله العشرية، ويُعرض للعميل بعملته مع الضريبة الخاصة بـ Tax class المختارة.

لا تحصل الإضافة على أسعار شحن فورية من 99minutos: الأسعار تأتي دائمًا من مصفوفتك. ولا تنشئ شحنات أو طلبات لدى 99minutos، ولا تطبع ملصقات (guides)، ولا تتتبع الطرود، ولا تقدم نقاط استلام Punto99، ولا تدعم الدفع عند الاستلام. ولا تضيف شيئًا إلى الطلبات: يعرض الطلب اسم الطريقة وتكلفة الشحن كأي طريقة شحن أخرى في OpenCart. أنشئ الشحنات في حسابك لدى 99minutos كالمعتاد.

على OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار 99Minutos في النافذة Shipping method options. تعمل الطريقة كما في OpenCart 3.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox 99Minutos هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit، فوق الإعدادات. أدخل المفتاح في License key واضغط على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا جزئيًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-shipping-99minutos والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يمكن تغيير المفتاح إلا لمستخدمي الإدارة الذين لديهم صلاحية Modify لهذه الإضافة. وتتبع نصوص الكتلة لغة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تعرض الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، اضغط على Check now. وإذا تعذر الوصول إلى خادم التراخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

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

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

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

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

لا تظهر 99Minutos عند الدفع: تحقق من أن الترخيص نشط وأن Enable 99Minutos مفعّل. ويجب أن يكون بلد التوصيل المكسيك أو كولومبيا أو تشيلي أو بيرو، ومفعّلًا في System > Localisation > Countries. تحقق من Geo zone وRestrict countries. تحقق من أن Price matrix تحتوي على صف لذلك البلد أو صف * Default، وتحقق من حدود الوزن وMinimum subtotal. تحقق من أن المنتجات ضُبط فيها Requires Shipping على Yes. وتشير التحذيرات التي تظهر بعد Save إلى الإعدادات التي تخفي الطريقة.

تظهر الطريقة فقط بعد إدخال الرمز البريدي: هذا متوقع مع فحص التغطية. وفي وضع Strict لا تظهر إلا عندما تؤكد واجهة البرمجة التغطية.

الطريقة مخفية دائمًا في وضع Strict: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم انظر إلى الحقل Log في صفحة الإضافة. يعني خطأ HTTP 401 أو 403 أن مفتاح واجهة البرمجة قد رُفض: تحقق من المفتاح ومن أن Environment يطابقه (مفاتيح بيئة الاختبار والإنتاج مختلفة). استخدم وضع Soft إذا كان يجب أن يحصل العملاء على سعر المصفوفة بينما واجهة البرمجة غير متاحة.

السعر ليس كما توقعت: تحقق من Calculation (لكل طلب أو لكل منتج)، ومن أوزان المنتجات وفئات الأوزان. ويُستخدم Base price عندما يكون سعر الحجم فارغًا أو يساوي 0. ومع Tax class تُضاف الضريبة إلى سعر المصفوفة.

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

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

للمطورين: يمكن استبدال عنوان واجهة برمجة 99minutos بالإعداد vfd_99m_api_url (للاختبارات)؛ ولا يوجد له حقل في صفحة الإعدادات.

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

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

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

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