VibeFox LP Express for OpenCart — المساعدة

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعدها (تم الاختبار على 4.1.0.3)، مع السمة الافتراضية وصفحة الدفع القياسية في OpenCart.

PHP: 8.0 أو أحدث.

LP Express: لا يلزم حساب API. ليس لدى LP Express واجهة برمجة عامة للأسعار، ولا تستخدم الإضافة واجهة Unisend البرمجية، لذلك تُدخل أسعارك (التعاقدية) الخاصة. أنشئ الطرود في حسابك لدى Unisend («Mano siuntos»).

قائمة محطات الطرود: تستخدم الإضافة قائمة LP Express المفتوحة للمحطات (https://www.lpexpress.lt/index.php?cl=terminals&fnc=getTerminals). لا يلزم أي مفتاح. إذا لم تكن هذه القائمة الإلكترونية متاحة، تستخدم الإضافة آخر نسخة مُنزَّلة إن وُجدت، وإلا فقائمتك الخاصة. كن مستعدًا لإدخال قائمتك الخاصة (انظر الإعدادات).

ليتوانيا: يجب تفعيل الدولة في System > Localisation > Countries.

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

التثبيت

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

OpenCart 3

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

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

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

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

5. املأ جدول الأسعار (صف واحد على الأقل؛ والصف الجديد الأول هو ليتوانيا) أو أدخل تكلفة احتياطية. تحقق من سطر الحالة الخاص بمحطات الطرود في أعلى الصفحة، وأضف قائمة محطاتك الخاصة إذا لم تكن القائمة الإلكترونية متاحة. فعّل Enable/Disable وانقر على Save.

OpenCart 4

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

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

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

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

عند التثبيت، تنشئ الإضافة جدولين صغيرين (المحطات المختارة وقائمة المحطات المخزنة مؤقتًا)، وتسجل أحداث OpenCart الخاصة بها لصفحة الدفع وصفحة الطلب. تبقى طريقة الشحن معطلة حتى تفعّل Enable/Disable وتحفظ. وإذا أعدت تثبيت الإضافة بعد إزالتها، فستُستخدم الإعدادات التي احتفظت بها من جديد.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox LP Express > Edit. تظهر الأقسام مدرجة على اليسار. يحفظ زر Save الواحد في الأسفل الصفحة بأكملها دون إعادة تحميلها. وكل حفظ يعيد تحميل قائمة المحطات أيضًا. ولا يستطيع حفظ الإعدادات إلا مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

في أعلى الصفحة، تعرض الإشعارات المشكلات وحالة المحطات. يظهر تحذير عندما لا يكون أي سعر محددًا أو لا تتوفر أي محطة طرود، لأن طريقة الشحن عندها لا تظهر في الدفع، وعندما لا تملك المتجر فئة وزن بوحدة kg، لأن أوزان المنتجات تُقرأ عندها حسب اسم وحدتها (kg وg وlb وoz)، وتُعامل أي وحدة أخرى على أنها kg. يعرض سطر المعلومات عدد محطات الطرود المتاحة في عدد المدن، والمصدر الذي تأتي منه: القائمة الإلكترونية، أو نسخة محفوظة من القائمة الإلكترونية (مع تاريخها)، أو قائمتك الخاصة.

عند الحفظ، يُرفض عنوان طريقة الشحن إذا كان فارغًا أو يحتوي على أحد الرموز < > ; = # { } ويظهر Enter a valid method title.، ويُرفض العنوان الذي يزيد على 64 حرفًا أيضًا. ويُرفض ترتيب العرض الذي ليس عددًا صحيحًا. وفي هذه الحالات لا يُحفظ شيء. ويُبلَّغ عن أي مبلغ أو وزن ليس رقمًا (أو سالب)، ويُحتفظ بقيمته السابقة. ويُبلَّغ أيضًا عن Minimum weight (kg) الذي يتجاوز Maximum weight (kg) (30 كغ عندما يكون الحد الأقصى فارغًا)، لأن طريقة الشحن لن تظهر أبدًا، ويحتفظ الوزنان بقيمتيهما السابقتين. وتُبلَّغ الأسعار غير الرقمية في الجدول وتُترك فارغة. وتُحفظ القيم الأخرى.

عام

Enable/Disable: يعرض LP Express في الدفع أو يخفيه (حالة هذه الإضافة). الافتراضي: off.

Method title: اسم طريقة الشحن الذي يراه العملاء في السلة وفي الدفع. الافتراضي: LP Express parcel terminal. مطلوب، بحد أقصى 64 حرفًا.

Tax class: --- None --- (الافتراضي) يعني أن الأسعار أدناه نهائية. مع فئة ضريبة، تضيف OpenCart ضريبة الشحن إلى الأسعار أدناه.

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

الأسعار (بعملة متجرك الافتراضية، وهي معروضة في عنوان القسم؛ ويمكن كتابة الكسور العشرية مثل 2.99 أو 2,99)

Price table: صف واحد لكل دولة وجهة. انقر على Add country لإضافة صف، وعلى زر الحذف لإزالة صف. اختر * Any other country لأي دولة ليس لها صف خاص. يحتوي كل صف على Base price وأعمدة وزن: XS حتى 1 كغ، وS حتى 2 كغ، وM حتى 3 كغ، وL حتى 5 كغ، وXL فوق 5 كغ. الوزن هو وزن السلة، أو وزن عنصر واحد مع Per item. يستخدم العمود الفارغ السعر الأساسي للصف. ويعني 0 مجانًا. ولا يُحفظ الصف الذي لا يحتوي على أي سعر.

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

Calculation: كيفية حساب السعر.

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

التوفر

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

Maximum weight (kg): يخفي طريقة الشحن عندما تكون السلة أثقل من ذلك. تقبل محطات LP Express طرودًا تصل إلى 30 كغ. الافتراضي: 30. ويعني 0 بلا حد. ويعني الفارغ 30 كغ، أو بلا حد عندما تكون Ignore shipping zones مفعّلة.

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

Geo zone: تُعرض طريقة الشحن فقط للعناوين الواقعة في هذه المنطقة الجغرافية. ويعني All Zones (الافتراضي) في كل مكان. وتُدار المناطق الجغرافية في System > Localisation > Geo Zones. ولا تُتحقق المنطقة الجغرافية عندما تكون Ignore shipping zones مفعّلة.

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

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

محطات الطرود

Terminal list: مصدر المحطات.

Own terminal list: محطة واحدة في كل سطر بالصيغة ID | Name | City | Address | ZIP، مثل 1234 | LP EXPRESS Akropolis | Vilnius | Ozo g. 25 | LT-07150. الحقلان ID وCity إلزاميان. تُتجاهل الأسطر التي تبدأ بـ #. استخدم معرّفات المحطات التي يتوقعها حسابك لدى Unisend.

متقدم

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

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

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

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

Export: انقر على Download JSON لحفظ الإعدادات كملف JSON.

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

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

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

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

الأسعار والمبالغ بعملة متجرك الافتراضية. يُقرَّب السعر إلى منازله العشرية ويُعرض للعميل بعملته، مع ضريبة Tax class المختارة.

تُخزَّن قائمة المحطات الإلكترونية مؤقتًا لمدة 24 ساعة. ويُتذكَّر التنزيل الفاشل لمدة 15 دقيقة، حتى لا تنتظر صفحة الدفع القائمة في كل تحديث. ومهلة التنزيل 10 ثوانٍ. ولا تُعرض إلا المحطات النشطة من القائمة. وتظهر المحطات التي لا تحمل مدينة ضمن Other.

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

لا تطلب الإضافة أسعار LP Express أو Unisend، ولا تنشئ شحنات، ولا تطبع بطاقات الشحن، ولا تستدعي مندوب توصيل، ولا تتتبع الطرود. أنشئ الطرود في حسابك لدى Unisend («Mano siuntos»). التوصيل إلى الباب عبر مندوب ليس جزءًا من هذه الطريقة.

نقاط الاستلام

عندما يختار العميل LP Express في خطوة طريقة التوصيل، يظهر أسفلها الكتلة LP Express parcel terminal مع قائمتين: -- Select city -- و-- Select parcel terminal --. لا تُحمَّل قائمة المحطات إلا عند اختيار LP Express. وتكون مدينة عنوان التوصيل محددة مسبقًا عندما تطابق إحدى مدن القائمة. ويُعرض كل محطة باسمها وعنوانها ورمزها البريدي. ويُحفظ الاختيار للدفع فورًا، فلا يضيع عند تحديث صفحة الدفع.

المحطة مطلوبة. عندما ينقر العميل على Continue، يتحقق الخادم من المحطة مقابل القائمة مرة أخرى. وبدون محطة تعرض صفحة الدفع Please select an LP Express parcel terminal. ويُرفض معرّف المحطة المزوَّر أو القديم برسالة The selected LP Express parcel terminal is not available any more. Please select a parcel terminal again. وإذا تعذر تحميل أي محطة، يرى العميل The LP Express parcel terminal list is temporarily unavailable. Please try again later or choose another shipping method.

في OpenCart 4، عندما يختار العميل LP Express، تظهر أسفل الخيار ضمن النافذة Shipping method options الكتلة LP Express parcel terminal مع قائمتين. ولا يتجاوز الزر Continue في النافذة دون محطة صالحة، وتظهر الرسائل نفسها.

يُحفظ معرّف المحطة واسمها ومدينتها مع الطلب. ويعرض اللوح LP Express parcel terminal في صفحة الطلب في لوحة الإدارة (Sales > Orders، معلومات الطلب) المدينة والمحطة وTerminal ID الخاص بها. وتعرض طريقة شحن الطلب عنوان الطريقة ونقطتين ثم المدينة والمحطة (مثلًا LP Express parcel terminal: Kaunas, …)، فتظهر في تفاصيل طلب العميل وفي رسائل البريد الإلكتروني للطلبات وفي الفاتورة. وإذا لم تكن لدى الطلب محطة، تعرض صفحة الطلب في لوحة الإدارة No parcel terminal was chosen for this order. ويظهر اللوح أيضًا للطلبات التي أُنجزت أثناء تعطيل الإضافة. وفي OpenCart 4 يظهر اللوح فوق History. يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه في كل مرة يؤكد فيها العميل مجددًا، وتُحدَّث محطة الطلب معه. وإذا حوّل العميل هذا الطلب إلى طريقة شحن أخرى، تُزال محطته.

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

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

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

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

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

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

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

لا يظهر LP Express في الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. وتحقق من Geo zone (أو من أن Ignore shipping zones مفعّل وأن الدولة مسموح بها). افتح صفحة الإضافة: يشرح التحذير ما إذا لم يكن هناك سعر محدد أو لم تتوفر محطة طرود. وتحقق أيضًا من حدود الوزن وMinimum cart total، ومن أن المنتجات لديها Requires Shipping مضبوط على Yes. ومع تفعيل Debug log، يوضح الحقل Log في صفحة الإضافة سبب إخفاء طريقة الشحن.

لا توجد محطات طرود: تعذر تحميل القائمة الإلكترونية، ولا توجد نسخة محفوظة ولا قائمة خاصة بك. تعيد الإضافة المحاولة كل 15 دقيقة. أدخل قائمتك الخاصة في Own terminal list، أو اختر Only my own list.

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

لا يستطيع العميل المتابعة: يجب اختيار محطة طرود. وإذا رأى العميل رسالة أن قائمة المحطات غير متاحة مؤقتًا، فلا توجد محطات متاحة الآن. أضف قائمتك الخاصة.

لا يظهر منتقي المحطات: يُضاف المنتقي إلى خطوة طريقة التوصيل في صفحة الدفع القياسية لـ OpenCart (وفي OpenCart 4 في النافذة Shipping method options)، وقد اختُبر مع السمة الافتراضية. وقد لا يظهر مع سمة معدّلة بشكل كبير أو مع إضافة دفع من طرف ثالث.

بأي عملة الأسعار: بعملة متجرك الافتراضية. ويرى العملاء الذين يدفعون بعملة أخرى السعر محوَّلًا بسعر صرف OpenCart.

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

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

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

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

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

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