VibeFox Mercado Envios for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Mercado Pago (للأسعار الفورية فقط): تأتي الأسعار الفورية من حاسبة Mercado Envios في حساب Mercado Pago الخاص بك في الأرجنتين أو البرازيل أو المكسيك. يجب تفعيل Mercado Envios للحساب. وتُحسب أسعار الطرود بالاستناد إلى عنوان الشحن المضبوط في ذلك الحساب. تحتاج إلى رمز الوصول Access Token الخاص بالإنتاج (يبدأ بـ APP_USR-): في لوحة مطوّري Mercado Pago، افتح تطبيقك وبيانات اعتماد الإنتاج الخاصة به. لا يوجد زر تسجيل دخول: تلصق الرمز في الإعدادات. وإذا كنت تستخدم الأسعار حسب البلد فقط، فلا تحتاج إلى حساب Mercado Pago.

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

التثبيت

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

2. انقر على Activate.

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

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

5. للأسعار الفورية، الصق Access Token، واختر بلد Mercado Envios، وإذا لم تكن عملة متجرك ARS أو BRL أو MXN فأدخل سعر الصرف. ويمكنك اختياريًا تعبئة Country prices وFallback cost (وتُستخدمان من دون أسعار فورية).

6. أضف VibeFox Mercado Envios إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر البلدان.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Mercado Envios. وتنطبق على جميع مناطق الشحن. وعند إضافة الطريقة إلى منطقة، لا تحتوي نافذة المنطقة إلا على حقل واحد:

Title (zone): اسم هذا الخيار عند الدفع. اتركه فارغًا لاستخدام Name العام.

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

عام

Enable/Disable: يفعّل خدمة شحن Mercado Envios أو يعطّلها في جميع المناطق دفعة واحدة.

Name: اسم طريقة الشحن الذي يراه العملاء عند الدفع. القيمة الافتراضية: Mercado Envios.

Tax status: تقدّم Mercado Envios أسعارًا نهائية. None يعرضها كما هي، وTaxable يضيف فوقها ضريبة الشحن في WooCommerce.

واجهة برمجة Mercado Envios (الأسعار الفورية) (من دون رمز، تُستخدم الأسعار أدناه فقط)

Access token: رمز الوصول Access Token الخاص بالإنتاج في Mercado Pago (APP_USR-...). يُرسل إلى Mercado Pago فقط، ولا يُسجَّل في السجل أبدًا.

Mercado Envios country: بلد حساب Mercado Pago الخاص بك: Argentina (ARS) (الافتراضي)، أو Brazil (BRL)، أو Mexico (MXN). تُطلب الأسعار الفورية فقط للوجهات في هذا البلد، وتُعرض بعملته.

Exchange rate: لا يلزم إلا إذا كانت عملة متجرك تختلف عن عملة Mercado Envios: سعر 1 ARS أو BRL أو MXN بعملة متجرك، مثل 0.001. ومن دونه لا تُستخدم الأسعار الفورية. ويُقبل كل من النقطة والفاصلة كفاصل عشري.

أسعار من دون أسعار فورية

تُستخدم هذه الأسعار عند عدم وجود رمز وصول، وللوجهات خارج بلد Mercado Envios، وعندما لا تعيد الواجهة أي سعر.

Country prices: أسعار بعملة متجرك. انقر على + Add country لإضافة صف، وعلى علامة الإغلاق لحذف صف. اختر * All other countries لجميع البلدان التي ليس لها صف خاص. وPrice هو سعر البلد. وتحل الأعمدة XS (حتى 1 كغ)، وS (1-2 كغ)، وM (2-3 كغ)، وL (3-5 كغ)، وXL (أكثر من 5 كغ) محلها عند وزن السلة المقابل. ويُستخدم Price في العمود الفارغ أو الذي قيمته 0. والقيم التي ليست أرقامًا تُعرض بعد الحفظ ثم تُمسح. أما الصفوف التي لا يوجد فيها أي سعر فتُحذف عند الحفظ.

Fallback cost: يُستخدم عندما لا تعطي واجهة البرمجة ولا Country prices أي سعر. اتركه فارغًا لإخفاء الطريقة في هذه الحالة.

Calculation type: Per order يحصّل السعر مرة واحدة. أما Per item (each item priced by its own weight x quantity) فيبحث في Country prices (أو في Fallback cost) عن السعر المناسب لوزن كل منتج ويضربه في الكمية. وأسعار Mercado Envios الفورية تكون دائمًا للطرد كاملًا.

التوفر

Min weight (kg): الحد الأدنى لوزن السلة لكي تظهر هذه الطريقة. والقيمة 0 تعني من دون حد.

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

Minimum subtotal: يعرض الطريقة فقط عندما يبلغ المجموع الفرعي للسلة هذا المبلغ على الأقل. اتركه فارغًا لعرضها دائمًا.

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

Ignore shipping zones: يعرض الطريقة للبلدان المذكورة أدناه حتى من دون إضافتها إلى منطقة شحن.

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

شحن مجاني

Free shipping from: المجموع الفرعي للسلة الذي تصبح عنده هذه الطريقة مجانية. وفي هذه الحالة لا يُرسل أي طلب إلى Mercado Envios. اتركه فارغًا للتعطيل.

متقدم

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

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

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

عندما يُدخل العميل عنوان التسليم، يطلب WooCommerce من الإضافة سعرًا. وتتحقق الإضافة أولًا من الشروط: وزن السلة، والحد الأدنى للمجموع الفرعي، وفئات الشحن المستثناة. فإذا انطبق الشحن المجاني، تكون تكلفة الطريقة 0 ولا يُرسل أي طلب إلى Mercado Envios.

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

يُخزَّن كل عرض سعر مؤقتًا لمدة ساعة، حتى لا تُطلق السلة نفسها طلبًا جديدًا. ولا يُعاد إرسال عرض السعر الفاشل لمدة 5 دقائق. وإذا تعذر الوصول إلى Mercado Pago أو رفض الرمز، تُوقف جميع أسعار الطلبات الفورية لمدة 5 دقائق، حتى لا تنتظر صفحة الدفع الواجهة عند كل تحديث. ومهلة واجهة البرمجة 10 ثوانٍ.

تُستخدم الأسعار من دون أسعار فورية بدلًا منها عندما لا يوجد رمز، أو تكون الوجهة خارج بلد Mercado Envios، أو يكون الرمز البريدي مفقودًا أو غير صالح، أو يغيب سعر الصرف، أو يتجاوز الطرد حد الوزن في Mercado Envios للبلد (25 كغ في الأرجنتين، و15 كغ في البرازيل، و30 كغ في المكسيك)، أو تعيد Mercado Envios خطأ أو لا تعيد أي خيار للعنوان. وتُستخدم صف البلد (أو صف *)، وإلا فالتكلفة الاحتياطية. وإذا لم يوجد أي سعر، تُخفى الطريقة. ولا يرى العميل أي خطأ في واجهة البرمجة أبدًا.

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

تحسب الإضافة الأسعار فقط. ولا تنشئ شحنات، ولا تطبع ملصقات، ولا تتتبع الطرود. أنشئ الشحنة في حسابك على Mercado Libre أو Mercado Pago. وتعرض سعرًا واحدًا لكل طريقة، وهو أرخص خيار من Mercado Envios، لا اختيارًا بين جميع الخيارات، ولا تتضمن محددًا لنقطة الاستلام (الوكالة).

الطلبات

عندما يُقدَّم الطلب بسعر فوري، يُحفظ اسم الخدمة ومدة التوصيل المقدرة بالأيام في بند شحن الطلب بوصفهما Mercado Envios service وEstimated delivery. وتحتفظ الطلبات الحالية ببنود شحنها.

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

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

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

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

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

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

لا يظهر Mercado Envios عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة بلد العميل (أو أن Ignore shipping zones مفعّل والبلد مسموح به). وراجع التحذيرات أعلى صفحة الإعدادات، وحدود الوزن، وMinimum subtotal، وExcluded shipping classes. تحتاج الطريقة إلى سعر: رمز وصول صالح لعناوين في بلد Mercado Envios، أو Country prices، أو Fallback cost.

لا تظهر الأسعار الفورية: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs، والمصدر vfd-mercado-envios. الأسباب الشائعة: عدم وجود رمز، أو وجهة خارج بلد Mercado Envios، أو رمز بريدي مفقود أو غير صالح، أو عدم وجود Exchange rate، أو طرد يتجاوز حد الوزن، أو عدم وجود خيار Mercado Envios للعنوان.

HTTP 401 أو 403 في التحذيرات: رمز الوصول غير صالح أو منتهي الصلاحية. انسخ رمز الوصول Access Token الخاص بالإنتاج من جديد من لوحة مطوّري Mercado Pago.

ردّت Mercado Envios بعملة أخرى: بلد الحساب لا يطابق Mercado Envios country. اختر بلد حساب Mercado Pago الخاص بك.

بأي عملة الأسعار: Country prices وFallback cost بعملة متجرك. وتصل الأسعار الفورية بعملة حساب Mercado Pago الخاص بك، وتُحوَّل باستخدام Exchange rate عندما يستخدم المتجر عملة أخرى.

تبدو الأسعار قديمة بعد تغيير: احفظ صفحة الإعدادات. وهذا يمسح الأسعار المخزنة مؤقتًا.

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

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

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

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