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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر فوق Activate.

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

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

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

6. أضف VibeFox 99Minutos إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones تشمل المكسيك أو كولومبيا أو تشيلي أو بيرو.

الإعدادات

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

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

عند حفظ الإعدادات، تحذّرك الصفحة إذا كانت مصفوفة الأسعار فارغة، أو إذا اخترت وضعاً للتحقق من التغطية دون مفتاح API.

عام

Enable/Disable: يفعّل 99Minutos في جميع مناطق الشحن دفعة واحدة. يجب أيضاً إضافة الطريقة إلى منطقة شحن تشمل المكسيك أو كولومبيا أو تشيلي أو بيرو. الافتراضي: مفعّل.

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها.

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

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

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

Off — matrix price for every postcode: لا توجد طلبات API. الافتراضي.

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. مطلوب عند تفعيل التحقق من التغطية. الحقل مخفي بقناع.

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

الأسعار

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

Price matrix: جدول بلدان الوجهة والأسعار. انقر فوق + Add country لإضافة صف، وعلامة الإغلاق لحذفه. يحتوي كل صف على Country و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): يُخفي الطريقة إذا كانت السلة أثقل من ذلك. الافتراضي: 25. القيمة 0 تعني بلا حد.

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

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

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

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

متقدم

Debug log: يسجّل حسابات الأسعار في WooCommerce > Status > Logs (المصدر "vfd-99minutos"). تُسجَّل أخطاء API حتى عند إيقاف هذا الخيار. لا تُسجَّل مفاتيح API ولا أسماء العملاء وعناوينهم أبداً.

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

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

تُعرض الطريقة فقط عندما يكون بلد التوصيل المكسيك أو كولومبيا أو تشيلي أو بيرو (ويكون ضمن قائمة Countries إذا كان Restrict countries مفعّلاً). عندما يُدخل العميل عنوان التوصيل، تتحقق الإضافة من حدود وزن السلة، وMinimum subtotal، وExcluded shipping classes.

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

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

تعمل الطريقة في الدفع الكلاسيكي وفي كتلتي السلة والدفع. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

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

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

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

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

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

لا يظهر 99Minutos عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة عنوان العميل. يجب أن يكون بلد التوصيل المكسيك أو كولومبيا أو تشيلي أو بيرو. تأكد من أن Price matrix يحتوي على صف لذلك البلد أو صف * Default، وتحقق من حدود الوزن، وMinimum subtotal، وExcluded shipping classes، وRestrict countries.

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

الطريقة مخفية دائماً في وضع Strict: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs (المصدر "vfd-99minutos"). يعني خطأ HTTP 401 أو 403 أن مفتاح API قد رُفض: تحقق من المفتاح ومن تطابق Environment معه (مفاتيح بيئتي الاختبار والإنتاج مختلفة). استخدم وضع Soft إذا كان يجب أن يحصل العملاء على سعر المصفوفة حين تكون الواجهة غير متاحة.

السعر ليس كما توقعت: تحقق من Calculation (لكل طلب أو لكل عنصر)، وأوزان المنتجات، ووحدة الوزن في متجرك. يعود سعر الحجم الفارغ أو الذي قيمته 0 إلى Base price.

بلدان أخرى: يمكن للمطورين تغيير قائمة البلدان المدعومة باستخدام الفلتر vfd_99m_supported_countries.

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

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

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

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