VibeFox Frenet for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Frenet (لأسعار الشحن الفورية فقط): أنشئ حسابا مجانيا في لوحة Frenet (painel.frenet.com.br)، وفعّل شركات الشحن التي تستخدمها، وانسخ رمز API الخاص بك. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى حساب Frenet.

المنتجات: أدخل الوزن والأبعاد للحصول على أسعار دقيقة. تُحسب المنتجات التي لا تحتوي عليها بوزن 0.3 كغ وأبعاد 16 × 11 × 2 سم (أصغر علبة لدى Correios).

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

التثبيت

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

2. انقر على Activate.

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

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

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

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

الإعدادات

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

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

تعرض الإضافة في أعلى الصفحة تحذيرات: لا يوجد رمز API (تُستخدم الأسعار الثابتة فقط، أو لا تظهر الطريقة إطلاقا إذا لم تكن هناك أسعار ثابتة أيضا)، أو لا يوجد رمز CEP لنقطة الانطلاق مكوّن من 8 أرقام، أو عملة المتجر ليست BRL دون سعر صرف. وفي كل مرة تحفظ الإعدادات، تُمسح عروض الأسعار المخزنة مؤقتا. وتقبل حقول الأسعار النقطة والفاصلة كفاصل عشري.

عام

Enable/Disable: يعطّل الطريقة أو يفعّلها في جميع المناطق دفعة واحدة. الافتراضي: on.

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

عروض أسعار Frenet الفورية

تقارن Frenet شركات الشحن المفعّلة في حسابك لدى Frenet، وتعيد أسعارها للسلة. ولا تُطلب عروض الأسعار الفورية إلا للعناوين في البرازيل التي تحتوي على رمز CEP كامل مكوّن من 8 أرقام.

API token: رمز Frenet API من لوحة Frenet. اتركه فارغا لاستخدام الأسعار الثابتة فقط.

Origin CEP: الرمز البريدي (CEP) الذي تُشحن منه الطرود، مثل 00000-000. اتركه فارغا لاستخدام الرمز البريدي للمتجر، إذا كان عنوان المتجر في البرازيل. ويُبلَّغ عن رمز CEP الذي لا يتكون من 8 أرقام عند الحفظ.

Service to offer: Cheapest service (الافتراضي) أو Fastest service. تعيد Frenet عدة خدمات، وتعرض الطريقة سعرا واحدا.

BRL exchange rate: تحسب Frenet بالريال البرازيلي. وإذا كانت عملة متجرك ليست BRL، فأدخل قيمة 1 BRL بعملة متجرك، مثلا 0.16. ويُحوَّل عرض السعر وقيمة الطلب المُعلنة بهذا السعر. وبدونه لا تُستخدم عروض الأسعار الفورية. ولا يلزم ذلك إذا كانت عملة المتجر BRL.

الأسعار الثابتة

تُستخدم عند عدم وجود رمز API، وللدول التي لا تخدمها Frenet، وكلما لم تُرجع Frenet سعرا (واجهة API غير متاحة، أو رمز CEP غير مخدوم).

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

Fallback cost: يُستخدم عندما لا يقدم كل من Frenet والجدول سعرا. اتركه فارغا لإخفاء الطريقة.

Fixed price applies: Per order يحتسب السعر مرة واحدة. Per item (price × quantity) يضربه في عدد العناصر. وينطبق هذا على الأسعار الثابتة والتكلفة الاحتياطية فقط. وعروض Frenet تغطي السلة كاملة بالفعل.

الشروط

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

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

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

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

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. أسعار Frenet هي الأسعار النهائية لشركة الشحن؛ اختر None إذا كان ينبغي ألا تضيف WooCommerce ضريبة عليها.

تُحوَّل أوزان المنتجات من وحدة متجرك إلى كغ.

التوفر بدون مناطق شحن

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

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

متقدم

Debug log: يسجل كل طلب لعرض سعر واستجابته في WooCommerce > Status > Logs، المصدر vfd-frenet. وتُسجَّل أخطاء API دائما. ولا يُسجَّل الرمز أبدا، ويُختصر رمز CEP الخاص بالعميل. أوقفه عند الانتهاء.

Remove data on uninstall: عند التفعيل، يؤدي حذف الإضافة إلى إزالة جميع إعدادات Frenet وطرق المناطق. ولا يحذف تعطيل الإضافة الإعدادات أبدا. وتُزال عروض الأسعار المخزنة مؤقتا دائما.

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

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

بالنسبة إلى عنوان في البرازيل برمز CEP كامل مكوّن من 8 أرقام، ترسل الإضافة إلى Frenet رمزي CEP لنقطة الانطلاق والوجهة، وكل عنصر في السلة (الوزن بالكغ، والأبعاد بالسم، والكمية، ورمز SKU والفئات)، وقيمة الطلب بالريال البرازيلي (BRL)، وأول كوبون مُطبَّق. ولا يُرسل أي طلب ما دام رمز CEP غير مكتمل. وتعيد Frenet خدمات شركات الشحن المفعّلة لديك. وتُتخطى الخدمات التي بها خطأ أو بدون سعر. وتختار الإضافة أرخص خدمة أو أسرعها، وتحوّل السعر إلى عملة متجرك. وتُحفظ شركة الشحن والخدمة ومدة التسليم مع سطر شحن الطلب، وتظهر في شاشة الطلب في لوحة الإدارة.

تُخزَّن كل استجابة مؤقتا لمدة ساعة واحدة لنفس السلة والعنوان. ويُتذكَّر الطلب الفاشل، أو رمز CEP الذي لا تخدمه أي شركة شحن مفعّلة، لمدة 10 دقائق. ومهلة انتظار API هي 10 ثوان. وفي هذه الحالات لا يرى العميل أي خطأ: تُستخدم السعر الثابت أو التكلفة الاحتياطية، أو تُخفى الطريقة إذا لم يكن أيٌّ منهما موجودا. وبالنسبة إلى العناوين خارج البرازيل تُستخدم الأسعار الثابتة فقط.

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

تحسب الإضافة الأسعار فقط. لا تنشئ شحنات، ولا تطبع ملصقات، ولا تتتبع الطرود؛ فهذه الميزات تقدمها Frenet في لوحتها الخاصة. وتعرض خدمة واحدة من Frenet لكل سلة، لا عدة خدمات، ولا توفر نقاط استلام أو خزائن. وتقدم Frenet عروض أسعار داخل البرازيل فقط؛ استخدم الأسعار الثابتة للدول الأخرى.

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

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

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

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

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

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

لا يظهر Frenet في صفحة الدفع: تحقق من أن الرخصة فعّالة، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). وراجع التحذيرات في أعلى صفحة الإعدادات، وحدود الوزن، وMinimum order amount وExcluded shipping classes. الأسباب الشائعة: أن العميل لم يدخل بعد رمز CEP كاملا مكوّنا من 8 أرقام ولا توجد أسعار ثابتة، أو أن Frenet لم تُرجع أي خدمة لذلك المسار ولا يوجد سعر ثابت.

لا تظهر عروض الأسعار الفورية: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs واختر المصدر vfd-frenet. سيوضح السجل السبب: رمز مرفوض (HTTP 401 أو 403)، أو عدم وجود رمز CEP لنقطة الانطلاق، أو عدم وجود سعر صرف BRL، أو عدم تفعيل أي شركة شحن في لوحة Frenet، أو رسائل الخدمات التي تم تخطيها.

متجري يبيع باليورو أو بالدولار: تجيب Frenet بالريال البرازيلي BRL. أدخل BRL exchange rate (قيمة 1 BRL بعملة متجرك).

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

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

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

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

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