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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

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

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

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

التثبيت

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Frenet > Configure. وهي تنطبق على كل منطقة من مناطق شركة الشحن. لكل قسم زر Save خاص به، وهو يحفظ الصفحة بأكملها. وكل عملية حفظ تمسح أيضا عروض Frenet المخزنة مؤقتا. تقبل حقول الأسعار النقطة والفاصلة كفاصل عشري؛ والقيمة التي ليست رقما تُرفض مع الرسالة "…" must be a number. وتُرفض أيضا المبالغ والأوزان السالبة، وBRL exchange rate بقيمة 0 أو أقل، وMinimum weight الذي يتجاوز Maximum weight. عند وجود خطأ لا يُحفظ شيء.

تعرض الوحدة في أعلى الصفحة تحذيرات: لا يوجد مفتاح API (تُستخدم الأسعار الثابتة فقط، أو لا تظهر شركة الشحن أبدا إذا لم توجد أسعار ثابتة أيضا)، أو لا يوجد رمز CEP لنقطة الانطلاق من 8 أرقام، أو تكون العملة الافتراضية غير BRL دون سعر صرف. كما تحذر إذا كانت وحدة الوزن أو الأبعاد في متجرك غير معروفة للوحدة؛ وتُعامَل مثل هذه الوحدة كـ kg أو cm. اضبط وحدة قياسية (kg أو g أو lb أو oz؛ cm أو mm أو m أو in) في International > Localization (Local units).

عام

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

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

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

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

API token: مفتاح API الخاص بـ Frenet من لوحة Frenet. اتركه فارغا لاستخدام الأسعار الثابتة فقط. بعد الحفظ يبقى الحقل فارغا ويعرض A token is saved — leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها. لحذف المفتاح المحفوظ، ضع علامة على Remove the saved token ثم احفظ.

Origin CEP: الرمز البريدي (CEP) الذي تُشحن منه الطرود، مثل 00000-000. اتركه فارغا لاستخدام الرمز البريدي للمتجر من Shop Parameters > Contact > Stores، إذا كان عنوان المتجر في البرازيل. يُحفظ رمز CEP الذي يقل عن 8 أرقام كما أُدخل، وتعرض الصفحة Frenet: the origin CEP must have 8 digits.

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

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

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

تُستخدم عندما لا يوجد مفتاح API، وللدول التي لا تخدمها Frenet، وكلما لم تُرجع Frenet سعرا (الواجهة غير متاحة، أو رمز 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: يخفي شركة الشحن إذا كان وزن السلة أقل من هذه القيمة، بالكيلوغرام. 0 يعني بلا حد.

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

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

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

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

تُحوَّل أوزان المنتجات وأبعادها من وحدات متجرك إلى kg وcm.

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

عادة تُعرض شركة الشحن في المناطق المعيّنة لها في Shipping > Carriers.

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

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

متقدم

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

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

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

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

في خطوة الشحن يطلب PrestaShop من الوحدة سعر Frenet. تُحتسب المنتجات المادية فقط: المنتجات الافتراضية لا تضيف وزنا ولا تدخل في مبلغ الطلب. قبل أن يُدخل العميل عنوانا، تستخدم الوحدة الدولة التي يقدّرها المتجر للزائر. تتحقق الوحدة أولا من قائمة الدول (عندما يكون Ignore shipping zones مفعّلا)، ثم من وزن السلة والحد الأدنى لمبلغ الطلب. إذا انطبق الشحن المجاني يكون السعر 0 ولا يُرسل أي طلب إلى Frenet.

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

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

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

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

الطلبات

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

Carrier: شركة الشحن Frenet والخدمة، مثل خدمة Correios أو Jadlog. تُعرض للأسعار الفورية.

Delivery time: مدة التسليم بأيام العمل التي أرجعتها Frenet. تُعرض للأسعار الفورية.

Price source: Live Frenet quote أو Fixed price (price per country) أو Fallback cost أو Free shipping.

تبقى هذه البيانات عند إلغاء تثبيت الوحدة، وكذلك مع Remove data on uninstall.

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

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

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

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

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

لا تظهر Frenet عند الدفع: تحقق من أن الترخيص نشط وأن Enable Frenet مفعّل. في Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته، أو أن Ignore shipping zones مفعّل والدولة مسموح بها. راجع التحذيرات أعلى صفحة الوحدة، وحدود الوزن، وMinimum order amount. الأسباب الشائعة: لم يُدخل العميل رمز CEP كاملا من 8 أرقام بعد ولا توجد أسعار ثابتة، أو لم تُرجع Frenet أي خدمة لهذا المسار ولا يوجد سعر ثابت. كما قد تكون المنتجات مقصورة على شركات شحن معيّنة في صفحة المنتج.

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

يقول السجل إن مفتاح API رُفض (HTTP 401 أو 403): انسخ المفتاح من لوحة Frenet مرة أخرى والصقه في API token.

يقول السجل إن Frenet لم تُرجع أي خدمة: فعّل شركة شحن واحدة على الأقل في لوحة Frenet.

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

تُفرض ضريبة فوق سعر Frenet: أسعار Frenet هي الأسعار النهائية لشركة الشحن. اضبط Tax على No tax.

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

تقول الصفحة إن شركة الشحن Frenet غير موجودة: حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإنشائها من جديد. حتى ذلك الوقت يعرض الحفظ الرسالة The settings were saved, but the carrier could not be updated.

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

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

Frenet علامة تجارية تعود لمالكها. هذه الوحدة غير تابعة لـ Frenet ولا تحظى بتأييدها.