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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

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

البلدان: توصّل 99minutos الطلبات إلى المكسيك وكولومبيا وتشيلي وبيرو. يجب أن تكون البلدان التي تشحن إليها مفعّلة في International > Locations.

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

التثبيت

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

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

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

4. املأ Price matrix (صف واحد على الأقل، مثل «* Default») وأدخل اختيارياً مفتاح API ووضع التحقق من التغطية (راجع الإعدادات). انقر على Save.

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

الإعدادات

كل الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox 99Minutos > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. كل حفظ يمسح أيضاً نتائج التغطية المخزنة مؤقتاً. بعد الحفظ، تحذّر الصفحة إذا كانت مصفوفة الأسعار فارغة، أو إذا كانت تحتوي على صفوف لبلدان لا تخدمها 99minutos، أو إذا اختير وضع التحقق من التغطية دون مفتاح API، أو إذا كانت الوحدة لا تعرف وحدة الوزن في المتجر (عندئذ تُعامل الأوزان على أنها كيلوغرامات). لا يُحفظ شيء، ويظهر خطأ، إذا تجاوز Method title 64 حرفاً، أو إذا لم يكن حقل وزن أو مبلغ رقماً يساوي 0 أو أكبر، أو إذا كان Min weight (kg) أكبر من Max weight (kg). إذا عرضت الصفحة The 99Minutos carrier was not found — reset the module to create it again.، فراجع قسم استكشاف الأخطاء وإصلاحها.

عام

Enable 99Minutos: يُشغّل شركة الشحن أو يوقفها. هذا هو المفتاح نفسه الذي يُحدد حالة شركة الشحن في Shipping > Carriers.

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

Tax: قاعدة الضريبة لشركة الشحن، أو No tax. مع قاعدة ضريبة، تضيف PrestaShop الضريبة إلى سعر الشحن من المصفوفة.

API 99minutos (التحقق من التغطية) (اختياري)

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

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

Off — matrix price for every postcode: لا تُرسل أي طلبات إلى الواجهة. الافتراضي.

Strict — show only if the API confirms coverage: تظهر شركة الشحن فقط عندما تؤكد واجهة 99minutos أن الرمز البريدي مشمول بالتغطية. إذا كانت الواجهة غير متاحة، أو لم يُدخل رمز بريدي، أو لم يُعيَّن مفتاح API، تُخفى شركة الشحن.

Soft — hide if not covered; if the API is unavailable, still show the matrix price: تُخفى شركة الشحن فقط عندما تجيب الواجهة بأن الرمز البريدي غير مشمول. عند أخطاء الواجهة، أو بدون رمز بريدي، أو بدون مفتاح API، يُستخدم سعر المصفوفة.

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

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

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

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

الأسعار

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

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

Restrict countries: تُعرض شركة الشحن فقط للبلدان المذكورة أدناه. هذا فلتر إضافي فوق مناطق شركة الشحن. مفيد عندما تشمل منطقة واحدة عدة بلدان.

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

متقدم

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

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

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

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

في خطوة الشحن، تطلب PrestaShop من الوحدة سعر 99Minutos. تُحسب المنتجات المادية فقط: المنتجات الافتراضية لا تضيف وزناً ولا تدخل في المجموع الفرعي للسلة. لا تُعرض شركة الشحن إلا عندما يكون بلد التسليم المكسيك أو كولومبيا أو تشيلي أو بيرو (وأن يكون في قائمة Countries إذا كان Restrict countries مفعّلاً). ثم تتحقق الوحدة من حدود الوزن وMinimum subtotal.

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

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

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

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

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

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

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

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

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

لا تظهر 99Minutos عند الدفع: تحقق من أن الترخيص نشط وأن Enable 99Minutos مفعّل. يجب أن يكون بلد التسليم المكسيك أو كولومبيا أو تشيلي أو بيرو، ومفعّلاً في International > Locations. في Shipping > Carriers، تحقق من أن شركة الشحن تغطي منطقة بلد العميل ومجموعته. تحقق من أن Price matrix فيها صف لذلك البلد أو صف * Default، وراجع حدود الوزن وMinimum subtotal وRestrict countries. قد تكون المنتجات أيضاً مقيّدة بشركات شحن معينة في صفحة المنتج.

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

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

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

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

تقول الصفحة إن شركة الشحن 99Minutos غير موجودة: حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإنشائها من جديد. وينطبق الأمر نفسه على الرسالة The settings were saved, but the carrier could not be updated. Reset the module to create it again.

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

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

99minutos علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لشركة 99minutos ولا تحظى باعتمادها.