VibeFox Melhor Envio for PrestaShop — المساعدة

المتطلبات

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

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

حساب Melhor Envio (لعروض الأسعار الفورية فقط): تحتاج عروض الأسعار الفورية إلى رمز وصول. في حسابك على Melhor Envio، افتح صفحة الرموز (melhorenvio.com.br/painel/gerenciar/tokens) وأنشئ رمزاً له صلاحية «shipping-calculate». للاختبار، أنشئ رمزاً في بيئة الاختبار (sandbox) الخاصة بـ Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). رموز الإنتاج ورموز بيئة الاختبار مختلفة. لا يوجد زر «ربط»: تلصق الرمز في إعدادات الوحدة. وبدون رمز تستخدم شركة الشحن الأسعار الاحتياطية.

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

التثبيت

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

2. عند اكتمال الرفع، اضغط Configure، أو ابحث لاحقاً عن VibeFox Melhor Envio في قائمة الوحدات واضغط Configure.

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

4. الصق رمز الوصول وبريد الاتصال الإلكتروني والرمز البريدي (CEP) لنقطة الانطلاق. إذا لم تكن العملة الافتراضية لمتجرك هي BRL، فاضبط BRL exchange rate. واختيارياً املأ جدول الأسعار الاحتياطية (مثلاً للبرازيل) أو تكلفة احتياطية. اضغط Save.

عند التثبيت، تنشئ الوحدة شركة الشحن Melhor Envio مع نص مدة التوصيل Delivery by the carriers of your Melhor Envio account. تُعيَّن شركة الشحن إلى جميع المناطق وجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائماً من الوحدة.

الإعدادات

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

تُظهر التحذيرات أعلى الصفحة وجود إعداد غير مكتمل: رمز CEP لنقطة الانطلاق فارغ أو ليس من 8 أرقام، أو بريد الاتصال مفقود، أو سعر صرف BRL مفقود، أو آخر خطأ في واجهة برمجة Melhor Envio مع تاريخه، أو عدم وجود رمز، أو عدم وجود سعر احتياطي (وعندها لا تظهر شركة الشحن أبداً)، أو وحدة وزن أو أبعاد في المتجر لا تعرفها الوحدة (فتُقرأ عندها كيلوغرام أو سنتيمتر). وإذا احتوى حقل رقمي على شيء غير رقم يساوي 0 أو أكبر، أو كان Min weight أكبر من Max weight، أو لم يكن Default product size بصيغة الطول × العرض × الارتفاع، تعرض الصفحة خطأً ولا يُحفظ شيء.

General

Enable Melhor Envio shipping: يشغّل شركة الشحن أو يوقفها. وهو المفتاح نفسه الموجود في حالة شركة الشحن في Shipping > Carriers.

Name: اسم شركة الشحن الذي يراه العملاء عند الدفع. الافتراضي: Melhor Envio. حقل إلزامي، بحد أقصى 64 حرفاً.

Tax: قاعدة الضريبة لشركة الشحن، أو No tax. أسعار Melhor Envio هي الأسعار النهائية لشركة الشحن. اختر No tax إذا كان يجب ألا يضيف PrestaShop ضريبة عليها.

Melhor Envio API

Access token: رمز البيئة المختارة أدناه. يُرسل إلى Melhor Envio كرمز Bearer. بعد الحفظ يبقى الحقل فارغاً ويعرض A token is saved — leave empty to keep it. اكتب رمزاً جديداً فقط إذا أردت تغييره. لحذف الرمز المحفوظ، ضع علامة على Remove the saved token ثم احفظ. لا يُكتب الرمز في السجل أبداً.

Sandbox: يستخدم بيئة الاختبار (sandbox.melhorenvio.com.br) الخاصة بـ Melhor Envio للاختبار. استخدمه مع رمز بيئة اختبار. الافتراضي: مُعطّل.

Contact e-mail: بريد اتصال تقني يُرسل إلى Melhor Envio في ترويسة User-Agent لكل طلب. تطلبه Melhor Envio من كل تكامل. لا يُحفظ العنوان غير الصالح، ويظهر إشعار بذلك.

Origin CEP: الرمز البريدي (CEP) المكوّن من 8 أرقام الذي تُشحن منه الطرود، مثلاً 01310-100. يُحفظ بالصيغة 00000-000. بدون رمز CEP صالح لنقطة الانطلاق لا يُطلب أي عرض سعر.

Services: قائمة اختيارية من معرّفات خدمات Melhor Envio مفصولة بفواصل لعرض الأسعار، مثلاً 1 = Correios PAC، 2 = Correios SEDEX، 17 = Correios Mini Envios، 3 = Jadlog .Package، 4 = Jadlog .Com. اتركها فارغة لعرض أسعار كل خدمات حسابك.

Quotes at checkout: طريقة عرض أسعار الشحن.

Delivery time: يعرض عند الدفع تقدير مدة التوصيل من Melhor Envio، مثلاً «3-5 business days». الافتراضي: مُفعّل.

Declared value: يصرّح بقيمة المنتج (التأمين) في عروض الأسعار. عند الإيقاف تُحسب العروض بدون قيمة مُصرَّح بها: فتكون أرخص، لكن الطرود لا تكون مؤمَّنة. الافتراضي: مُفعّل.

BRL exchange rate: تُسعّر Melhor Envio بالريال البرازيلي. لا يلزم إلا إذا لم تكن العملة الافتراضية لمتجرك هي BRL: أدخل سعر 1 BRL بالعملة الافتراضية لمتجرك، مثلاً 0.17. وبدونه لا تُستخدم أسعار العروض الفورية. يجب أن تكون القيمة أكبر من 0. وتُحوَّل القيمة المُصرَّح بها إلى BRL بسعر الصرف نفسه. وإذا كانت عملتك الافتراضية BRL، يعرض الحقل Store currency is BRL.

Default product weight: بالكيلوغرام، للمنتجات التي لا وزن لها، وتُستخدم في عروض الأسعار وفي حدود الوزن. يجب أن يكون أكبر من 0. الافتراضي: 0.3.

Default product size: الطول × العرض × الارتفاع بالسنتيمتر، للمنتجات التي لا أبعاد لها. الافتراضي: 16x11x5.

الأسعار الاحتياطية (بالعملة الافتراضية لمتجرك)

تُستخدم الأسعار الاحتياطية عند عدم وجود رمز، أو غياب رمز CEP الوجهة، أو عدم إعطاء واجهة البرمجة عرض سعر (خطأ، انتهاء مهلة، عدم وجود تغطية).

Fallback price table: سعر حسب الدولة ووزن السلة. اضغط Add country لإضافة صف، وأيقونة سلة المهملات لحذف صف. اختر * Default كدولة لكل دولة ليس لها صف خاص بها. يحتوي كل صف على Price وأعمدة الوزن: XS حتى 1 kg، وS من 1-2 kg، وM من 2-3 kg، وL من 3-5 kg، وXL أكثر من 5 kg. العمود الفارغ أو الذي قيمته 0 يستخدم Price. يُقبل كلٌّ من «9.99» و«9,99». القيم التي ليست أرقاماً تُعرض بعد الحفظ وتُتجاهل.

Fallback cost: يُستخدم عندما لا يحتوي الجدول على سعر أيضاً. اتركه فارغاً لإخفاء شركة الشحن في هذه الحالة.

Fallback calculation: Per order يحتسب السعر الاحتياطي مرة واحدة. Per item (each item priced by its own weight x quantity) يبحث عن السعر الاحتياطي لوزن كل عنصر (الوزن الافتراضي إذا لم يكن له وزن) ويضربه في كميته. إذا لم يكن لعنصر سعر، تُخفى شركة الشحن. وهذا ينطبق على الأسعار الاحتياطية فقط. وأسعار Melhor Envio تشمل كل العناصر أصلاً.

التوفر

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

Max weight: يخفي شركة الشحن عندما تكون السلة أثقل من هذا الوزن، بالكيلوغرام. الافتراضي: 30. 0 تعني بلا حد. الحقل الفارغ يعني 30 kg في مناطق شركة الشحن، وبلا حد فقط للدول الموجودة في Ignore shipping zones خارج تلك المناطق.

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

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

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

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

متقدم

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

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

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

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر Melhor Envio. لا تُحتسب إلا المنتجات التي تحتاج إلى شحن: فالمنتجات الافتراضية لا تضيف وزناً ولا تدخل في المجموع الفرعي. تتحقق الوحدة أولاً من الشروط: الدول الموجودة في Ignore shipping zones، ووزن السلة، والحد الأدنى للمجموع الفرعي.

لعنوان توصيل في البرازيل برمز CEP من 8 أرقام، ترسل الوحدة إلى Melhor Envio رمزي CEP لنقطة الانطلاق والوجهة، وكل عنصر قابل للشحن مع وزنه وحجمه وكميته وقيمته المُصرَّح بها، إضافة إلى قائمة الخدمات إذا حددتها. تُحوَّل عروض الأسعار إلى العملة الافتراضية لمتجرك، وتُرتَّب حسب السعر، ثم تُعرض بعملة سلة العميل. وإذا انطبق الشحن المجاني، تكون أرخص خدمة بسعر 0.

مع One option - the cheapest service، تعرض شركة الشحن سعر أرخص خدمة، وسطر Delivery estimate: أسفل شركة الشحن إذا كان Delivery time مُفعّلاً. ومع One option per service، يرى العميل Choose a delivery service: أسفل شركة الشحن، مع زر اختيار لكل خدمة وسعرها وتقدير مدة التوصيل. يُحفظ الاختيار فوراً، ويتحدث سعر شركة الشحن وملخص السلة. وإذا لم تعد الخدمة متاحة للعنوان، يرى العميل This service is not available for your address any more. Please choose another one. ويعود الاختيار السابق.

يُخزَّن كل عرض سعر مؤقتاً لمدة ساعة واحدة لكل طرد ورمز CEP ورمز وصول وبيئة، لذلك لا تُطلق السلة نفسها طلباً جديداً. ويُتذكَّر الاستدعاء الفاشل لمدة 5 دقائق، حتى لا يبطئ تعطّل واجهة البرمجة كل تحديث لصفحة الدفع. مهلة واجهة البرمجة 12 ثانية.

إذا لم يكن هناك رمز، أو كان العنوان خارج البرازيل أو لم يكن له رمز CEP صالح بعد، أو كان سعر صرف BRL مفقوداً، أو أعادت Melhor Envio خطأً أو لم تُعد أي خدمة لهذا المسار، تُستخدم الأسعار الاحتياطية: صف الدولة (أو صف *)، وإلا فالتكلفة الاحتياطية. وإذا انطبق الشحن المجاني، تُعرض شركة الشحن مجاناً حتى بدون سعر. وإذا لم يوجد أي سعر، تُخفى شركة الشحن. ولا يرى العميل أي خطأ من واجهة البرمجة أبداً.

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

تحتسب الوحدة الأسعار فقط. فهي لا تشتري الملصقات أو تنشئها، ولا تضيف الشحنات إلى سلة Melhor Envio، ولا تتتبع الطرود، ولا تجدول الاستلام، ولا ترسل بيانات الفاتورة (NF-e). ولا تتيح اختيار وكالات Jadlog أو Azul أو LATAM (نقاط الإيداع)، ولا الخدمات الإضافية «التسليم باليد» و«إيصال الاستلام». أدِر الشحنات في لوحة Melhor Envio الخاصة بك. وتشحن Melhor Envio داخل البرازيل فقط. وتحصل الدول الأخرى على الأسعار الاحتياطية فقط.

الطلبات

عند إتمام طلب بعرض سعر فوري، تحفظ الوحدة خدمة Melhor Envio وتقدير مدة توصيلها مع الطلب. تعرض صفحة الطلب في الواجهة الخلفية كتلة Melhor Envio تتضمن Melhor Envio service (مع معرّف الخدمة) وDelivery estimate، لتعرف أي خدمة تشتري في Melhor Envio. ويرى العميل المعلومات نفسها في صفحة طلبه في حسابه. وتُضاف في رسالة تأكيد الطلب بعد اسم شركة الشحن. الطلبات التي أُنجزت بسعر احتياطي ليس لها خدمة. ولا تتأثر الطلبات الموجودة.

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

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

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

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

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

لا تظهر Melhor Envio عند الدفع: تحقق من أن الترخيص نشط وأن Enable Melhor Envio shipping مُفعّل. وفي Shipping > Carriers، تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته، أو فعّل Ignore shipping zones وتحقق من Countries. وراجع التحذيرات أعلى صفحة الوحدة، وحدود الوزن، وMinimum subtotal. وبدون رمز أو عرض سعر، تحتاج شركة الشحن إلى سعر احتياطي: صف في Fallback price table، أو Fallback cost. وقد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج أيضاً.

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

HTTP 401 أو 403 في السجل أو التحذيرات: رفضت Melhor Envio رمز الوصول. إما أنه غير صحيح أو منتهٍ أو مُلغى، أو أنه يتبع البيئة الأخرى. أنشئ رمزاً جديداً وتحقق من أن Sandbox يطابقه.

يرى العميل «The service could not be saved. Please try again.»: لم يصل الاختيار إلى المتجر، مثلاً بسبب خطأ في الشبكة. يمكن للعميل اختيار الخدمة مرة أخرى. وتُحفظ أيضاً الخدمة المحددة عندما ينقر العميل Continue.

تُضاف الضريبة إلى سعر Melhor Envio: اضبط Tax على No tax.

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

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

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

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

Melhor Envio علامة تجارية مسجلة لمالكها. هذه الوحدة غير تابعة لـ Melhor Envio ولا مُعتمدة منها.