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

المتطلبات

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

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

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

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

التثبيت

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

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

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

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

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

الإعدادات

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

تعرض التحذيرات أعلى الصفحة مشكلات الإعداد: سعر تحويل مفقود، أو عدم وجود رمز وصول ولا سعر، وآخر خطأ في واجهة Mercado Envios البرمجية مع تاريخه، ووحدة وزن أو أبعاد للمتجر لا تعرفها الوحدة (فتُقرأ عندها كيلوغرامات أو سنتيمترات). وإذا حُذفت الشركة، يقول قسم General: The Mercado Envios carrier was not found — reset the module to create it again.

General

أضف مناطق عملائك إلى شركة Mercado Envios في Shipping > Carriers، أو استخدم Ignore shipping zones أدناه. تنطبق هذه الإعدادات على كل منطقة.

Enable Mercado Envios shipping: يُشغّل الشركة أو يوقفها. وهو المفتاح نفسه الذي يمثل حالة الشركة في Shipping > Carriers.

Name: اسم شركة الشحن الذي يراه العملاء عند الدفع. الافتراضي: Mercado Envios. حقل مطلوب، بحد أقصى 64 حرفًا.

Tax: قاعدة ضريبة الشركة، أو No tax (الافتراضي). تقدم Mercado Envios أسعارًا نهائية. يعرضها No tax كما هي، أما قاعدة الضريبة فتضيف ضريبة الشحن الخاصة بك فوقها.

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

Access token: رمز Access Token الخاص بالإنتاج في Mercado Pago (APP_USR-...). يُرسل إلى api.mercadopago.com فقط ولا يُسجَّل أبدًا. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره. لإيقاف استخدام الأسعار الفورية، ضع علامة على Remove the saved access token (only the prices below are used then) ثم احفظ.

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

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: الحد الأدنى لوزن السلة بالكيلوغرام حتى تظهر هذه الشركة. 0 يعني بلا حد.

Max weight: يخفي الشركة عندما يزيد وزن السلة عن هذا الحد، بالكيلوغرام. الفارغ يعني 25 كغ، و0 يعني بلا حد. يُرفض Min weight الذي يتجاوز Max weight عند الحفظ.

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

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

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

الشحن المجاني

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

متقدم

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

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

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

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

في خطوة الشحن، تطلب PrestaShop من الوحدة سعر Mercado Envios. لا تُحتسب إلا المنتجات المادية: فالمنتجات الافتراضية لا تضيف وزنًا ولا تدخل في المجموع الفرعي. تتحقق الوحدة أولًا من الشروط: البلدان المسموح بها (مع Ignore shipping zones)، ووزن السلة، والحد الأدنى للمجموع الفرعي. وإذا انطبق الشحن المجاني، يكون السعر 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 خطأ أو لا تُرجع أي خيار للعنوان. يُستخدم صف البلد (أو صف *)، وإلا فالتكلفة الاحتياطية. وإذا لم يوجد أي سعر، تُخفى الشركة. ولا يرى العميل خطأ الواجهة البرمجية أبدًا.

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

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

الطلبات

عندما يُوضع طلب بسعر فوري من Mercado Envios، تحتفظ الوحدة باسم الخدمة ومدة التوصيل المقدرة بالأيام والسعر الفوري. وفي لوحة الإدارة، تعرض صفحة الطلب كتلة Mercado Envios تضم Mercado Envios service وEstimated delivery وLive rate (excl. tax). ويرى العميل Mercado Envios service وEstimated delivery في صفحة تفاصيل الطلب في حسابه. ولا تتأثر الطلبات الحالية بتغييرات الأسعار اللاحقة.

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

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

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

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

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

لا تظهر Mercado Envios عند الدفع: تحقق من أن الترخيص نشط وأن Enable Mercado Envios shipping مفعّل. في Shipping > Carriers، تحقق من أن الشركة تغطي منطقة بلد العميل ومجموعة العميل (أو فعّل Ignore shipping zones وتحقق من Countries). تحقق من التحذيرات أعلى صفحة الوحدة، وحدود الوزن، وMinimum subtotal. تحتاج الشركة إلى سعر: رمز Access Token يعمل للعناوين في بلد Mercado Envios، أو Country prices، أو Fallback cost. كما قد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج.

لا تظهر الأسعار الفورية: فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى الحقل Log في صفحة الوحدة. الأسباب الشائعة: عدم وجود رمز، أو وجهة خارج بلد Mercado Envios، أو رمز بريدي مفقود أو غير صالح، أو Exchange rate مفقود، أو طرد يتجاوز حد الوزن، أو عدم وجود خيار Mercado Envios للعنوان.

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

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

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

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

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

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

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

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