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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

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

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

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

6. أضف منطقة للبرازيل في WooCommerce > Settings > Shipping > Shipping zones، وأضف إليها VibeFox Melhor Envio، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

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

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

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

عام

Enable/Disable: يشغّل أو يوقف شحن Melhor Envio في كل المناطق دفعة واحدة.

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

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

واجهة Melhor Envio البرمجية

Access token: رمز البيئة المختارة أدناه. لا يُكتب في السجل أبداً.

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

Contact e-mail: بريد تواصل تقني يُرسل إلى Melhor Envio مع كل طلب. تشترطه Melhor Envio في كل تكامل.

Origin CEP: رمز CEP (8 أرقام) الذي تُشحن منه الطرود، مثلاً 01310-100. وبدون رمز 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. وبدونه لا تُستخدم أسعار العروض الفورية. وتُحوَّل القيمة المصرّح بها إلى BRL بالسعر نفسه.

Default product weight (kg): يُستخدم للمنتجات التي لا وزن لها، في العروض وفي حدود الوزن. الافتراضي: 0.3.

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

Fallback prices (بعملة متجرك)

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

Fallback price table: سعر حسب الدولة ووزن السلة. انقر + Add country لإضافة صف، وعلامة × لحذف صف. اختر * Any country لكل دولة ليس لها صف خاص. لكل صف Price وأعمدة للوزن: XS حتى 1 كغ، وS من 1 إلى 2 كغ، وM من 2 إلى 3 كغ، وL من 3 إلى 5 كغ، وXL أكثر من 5 كغ. يستخدم العمود الفارغ أو الذي قيمته 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 تشمل كل العناصر أصلاً.

Availability

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

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

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

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

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

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

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

متقدم

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

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

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

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

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

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

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي السلة والدفع. وهي متوافقة مع HPOS (تخزين الطلبات عالي الأداء) في WooCommerce.

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

الطلبات

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

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

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

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

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

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

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

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

لا تظهر إلا الأسعار الاحتياطية: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs، المصدر vfd-melhor-envio. الأسباب الشائعة: لا يوجد رمز، أو رمز CEP لنقطة الإرسال لا يتكون من 8 أرقام، أو لا يوجد BRL exchange rate لعملة متجر غير BRL، أو لا يوجد بعد رمز CEP للوجهة، أو لا توجد خدمة تغطي المسار.

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

السعر الذي يراه العملاء: مع خيار واحد، أرخص خدمة تعيدها Melhor Envio. ومع خيار لكل خدمة، كل خدمة تغطي المسار. ولا ينطبق Per item إلا على الأسعار الاحتياطية.

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

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

الإلغاء

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

Melhor Envio علامة تجارية مملوكة لصاحبها. وهذه الإضافة غير تابعة لـ Melhor Envio ولا معتمدة منها.