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

المتطلبات

OpenCart: 3.0.x (تم اختباره على 3.0.5.0) أو 4.0.2 وما بعدها (تم اختباره على 4.1.0.3).

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم لكلا إصداري OpenCart. فُكّ ضغطه على جهاز الحاسوب. يحتوي على README.txt، وحزمة OpenCart 3 vfd_frenet-oc3-(version).ocmod.zip، وحزمة OpenCart 4 vfd_frenet.ocmod.zip. ثبّت فقط الحزمة الخاصة بإصدار OpenCart لديك. مفتاح الترخيص واحد لكلا الإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف vfd_frenet-oc3-(version).ocmod.zip. لا تضيف الإضافة أي تعديلات OCMOD، لذلك لا تحتاج إلى تحديث Extensions > Modifications. وبدلًا من المثبّت، يمكنك أيضًا نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر نوع الإضافة Shipping. ابحث عن VibeFox Frenet وانقر على Install (زر + الأخضر).

3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات.

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

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

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف vfd_frenet.ocmod.zip. لا تغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، والحزمة التي تُغيَّر تسميتها لا تعمل.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر نوع الإضافة Shipping. ابحث عن VibeFox Frenet، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوتين 4 و5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

بعد التثبيت تبقى الطريقة معطّلة حتى تفعّل Enable Frenet وتحفظ. وإذا أعدت تثبيت الإضافة بعد إلغاء تثبيتها، فستُستخدم من جديد إعدادات Frenet التي احتفظت بها.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. تظهر الأقسام في الجهة اليسرى. يحفظ زر Save واحد في الأسفل الصفحة كلها دون إعادة تحميلها. كما يمسح كل حفظ عروض Frenet المخزّنة مؤقتًا. تقبل حقول الأسعار النقطة والفاصلة كفاصل عشري. إذا كانت قيمة خاطئة، فلا يُحفظ شيء وتعرض الصفحة السبب، مثل Enter a valid method title (64 characters max, without < > ; = # { }). أو "…" must be a number. أو "…" must not be negative.. كما يُرفض BRL exchange rate الذي يساوي 0 أو أقل، وكذلك Minimum weight (kg) إذا كان أكبر من Maximum weight (kg). ولا يستطيع حفظ الإعدادات إلا مستخدمو الإدارة الذين لديهم صلاحية تعديل هذه الإضافة.

في أعلى الصفحة، وبعد كل حفظ، تعرض الإضافة تحذيرات: لا يوجد رمز API (تُستخدم الأسعار الثابتة فقط، أو لا تظهر الطريقة أبدًا إذا لم تكن هناك أسعار ثابتة أيضًا)، أو لا يوجد رمز CEP للمصدر، أو رمز CEP للمصدر ليس من 8 أرقام، أو العملة الافتراضية ليست BRL ولا يوجد سعر صرف. كما تحذّر إذا لم يكن في متجرك فئة وزن بوحدة kg أو فئة طول بوحدة cm. وعندها تُحوَّل أوزان المنتجات وأبعادها حسب اسم الوحدة في فئتها، وتُعامل الوحدات غير المعروفة على أنها kg أو cm. تحقق من System > Localisation > Weight Classes وLength Classes.

عام

تنطبق الإعدادات على كل المناطق الجغرافية. يمكنك قصر الطريقة على منطقة جغرافية في Conditions، أو استخدام Ignore shipping zones. ويأتي السعر دائمًا من هذه الإضافة.

Enable Frenet: يعرض Frenet عند الدفع أو يخفيه. الافتراضي: معطّل.

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وعند الدفع. الافتراضي: Frenet. حقل إلزامي، بحد أقصى 64 حرفًا، دون الأحرف < > ; = # { }.

Sort order: موقع Frenet بين طرق الشحن عند الدفع. عدد صحيح.

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

تقارن Frenet شركات الشحن المفعّلة في حسابك لدى Frenet (Correios وJadlog وLoggi وغيرها) وتعيد أسعارها للسلة. لا تُطلب الأسعار الفورية إلا للعناوين في البرازيل التي تحتوي على رمز CEP كامل من 8 أرقام. ويحتوي القسم على رابط إلى لوحة Frenet.

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

Origin CEP: الرمز البريدي (CEP) الذي تُرسل منه الطرود، مثل 01001-000. لا يوجد في OpenCart رمز بريدي للمتجر، لذلك تحتاج الأسعار الفورية إلى هذا الحقل. يُحفظ رمز 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. يُحوَّل العرض وقيمة الطلب المعلنة بهذا السعر. بدونه لا تُستخدم الأسعار الفورية. وعندما تكون عملتك الافتراضية BRL، يوضح الحقل أن أسعار Frenet تُستخدم كما هي.

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

تُستخدم عند عدم وجود رمز 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 (all other countries) لجميع الدول التي ليس لها صف خاص. تُحذف الصفوف التي لا تحتوي على أي سعر عند الحفظ.

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

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

الشروط

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

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

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

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

Tax class: فئة الضريبة المضافة إلى تكلفة الشحن، أو No tax. أسعار Frenet هي الأسعار النهائية لشركة الشحن. اختر No tax إذا لم ينبغي لـ OpenCart إضافة ضريبة عليها.

Geo zone: قدّم Frenet فقط للعناوين الموجودة في هذه المنطقة الجغرافية. All zones يعني بلا حد. لا يُستخدم مع Ignore shipping zones. تُدار المناطق الجغرافية في System > Localisation > Geo Zones.

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

عادةً تُعرض الطريقة في المنطقة الجغرافية المحددة في Conditions (في كل المناطق إذا لم تُحدَّد أي منطقة).

Ignore shipping zones: قدّم Frenet للدول المذكورة أدناه، أيًّا كانت المنطقة الجغرافية المطابقة. عندها لا يُتحقق من Geo zone في Conditions.

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

متقدم

Debug log: يسجّل كل طلب عرض سعر واستجابته في storage/logs/vfd_frn_debug.log.php (في OpenCart 4 system/storage/logs/vfd_frn_debug.log.php). لا يمكن قراءة الملف من الويب. وتُسجَّل أخطاء API دائمًا. لا يُسجَّل الرمز أبدًا، ويُختصر رمز CEP الخاص بالعميل. أوقفه عند الانتهاء. وعندما يبلغ الملف 5 MB يُنقل إلى vfd_frn_debug.old.log.php ويبدأ سجل جديد.

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

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

الاستيراد / التصدير

Export: انقر على Download JSON لحفظ الإعدادات في ملف JSON. لا يُصدَّر رمز API.

Import: الصق ملف JSON صُدِّر سابقًا وانقر على Import لاستعادة الإعدادات، مثلًا في متجر آخر. تُفحص القيم كما في الحفظ العادي. ويبقى رمز API المحفوظ كما هو.

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

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

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

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

في OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار Frenet في النافذة Shipping method options. تعمل الطريقة بالطريقة نفسها كما في OpenCart 3.

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

الطلبات

عندما يُقدَّم طلب باستخدام Frenet، تحفظ الإضافة طريقة احتساب سعر الشحن: بالضبط الخيار الذي رآه العميل في خطوة الشحن، دون طلب جديد إلى Frenet. ثم تعرض صفحة الطلب في Sales > Orders كتلة Frenet تحتوي على هذه الأسطر:

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

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

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

في OpenCart 4 تظهر الكتلة فوق History. يحدّث OpenCart 4 الطلب نفسه عندما يؤكده العميل مرة أخرى: تُحدَّث بيانات Frenet المحفوظة أيضًا، وإذا اختار العميل طريقة شحن أخرى، تُحذف بيانات Frenet الخاصة بالطلب.

تُعرض الكتلة أيضًا عندما تكون الإضافة معطّلة. وتبقى هذه البيانات عند إلغاء تثبيت الإضافة، حتى مع تفعيل Remove data on uninstall.

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

تعمل الإضافة مع مفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Frenet هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox Frenet > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُخفًى، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: opencart-shipping-frenet ورابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة. وتتبع نصوص الكتلة لغة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذر الوصول إلى خادم التراخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

يعمل مفتاح واحد على نطاق واحد فقط: عنوان المتجر من إعدادات OpenCart. لا يؤدي حذف المفتاح من المتجر إلى تحرير خانة النطاق. حرّرها في حسابك على vibefox.net.

بدون مفتاح نشط، لا تُعرض طريقة Frenet للعملاء عند الدفع، ولا يُحسب أي سعر. يرى مستخدم الإدارة المسجَّل الدخول إلى الإدارة في نفس المتصفح الطريقة في المتجر، مع الوسم (unlicensed — visible to admins only)، فيمكنك إعداد الإضافة واختبارها قبل شراء المفتاح. في OpenCart 4 هذه المعاينة غير متاحة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تبقى الطريقة مخفية عن الجميع دون مفتاح نشط. بعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاص بالإدارة. أغلقه بالزر × ليختفي لمدة 7 أيام. ولا تتأثر الطلبات الحالية.

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

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

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

لا تظهر الأسعار الفورية: فعّل 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 class على No tax.

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

تقول الصفحة "Warning: You do not have permission to modify VibeFox Frenet!": قد تكون مجموعة مستخدمي الإدارة لديك تستطيع عرض الإعدادات فقط. امنح المجموعة صلاحية التعديل على extension/shipping/vfd_frenet (OpenCart 3) أو extension/vfd_frenet/shipping/vfd_frenet (OpenCart 4) في System > Users > User Groups.

للمطورين: يمكن استبدال عنوان طلب عروض Frenet بالإعداد vfd_frn_api_url (للاختبارات)؛ وليس له حقل في صفحة الإعدادات.

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

انتقل إلى Extensions > Extensions، واختر النوع Shipping، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Frenet. يُحذف دائمًا مفتاح الترخيص وحالة الترخيص الخاصة بهذه الإضافة. يعيد OpenCart دائمًا ضبط Enable Frenet وSort order وTax class وGeo zone. تُحذف عروض الأسعار المخزّنة مؤقتًا دائمًا. يُحذف حدث OpenCart الخاص بالإضافة أيضًا (وفي OpenCart 4 الأحداث التي تحفظ بيانات Frenet للطلبات الجديدة أيضًا)، فلم تعد كتلة Frenet تظهر في صفحة الطلب. وتبقى بيانات Frenet المحفوظة مع الطلبات وتظهر من جديد بعد إعادة التثبيت. وإذا كان Remove data on uninstall مفعّلًا، تُحذف إعدادات Frenet وسجل التصحيح أيضًا. وإذا كان معطّلًا، تُحفظ الإعدادات الأخرى وتُستخدم من جديد عند إعادة تثبيت الإضافة. تحتفظ الطلبات الحالية بطريقة الشحن وتكلفتها.

في OpenCart 4، ولحذف ملفات الإضافة أيضًا، انتقل بعد إلغاء التثبيت إلى Extensions > Installer، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Frenet في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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