VibeFox GLS ParcelShop for OpenCart — المساعدة

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

GLS: لا تستخدم الإضافة حساب GLS أو مفتاح API ولا تحتاجهما. خريطة ParcelShop عامة. تحتاج إلى عقد مع GLS لشحن الطرود إلى ParcelShops المختارة.

سياسة أمان المحتوى: إذا كان متجرك يرسل سياسة أمان المحتوى (Content Security Policy)، فاسمح بالنطاق map.gls-croatia.com، الذي يُحمَّل منه سكربت خريطة GLS.

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

التثبيت

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

OpenCart 3

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

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

3. اضغط Edit (زر القلم) لفتح صفحة الإعدادات.

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

5. حدّد أسعارك: صف واحد على الأقل في Country prices (مثل * Default) أو Fallback cost (انظر الإعدادات). فعّل Enable/Disable واضغط Save.

OpenCart 4

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

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

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

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

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

الإعدادات

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

تشير التحذيرات في أعلى الصفحة، وتظهر من جديد بعد كل حفظ، إلى مشكلات في الإعدادات: لم يُحدَّد أي سعر، أو أن بعض أو كل Countries (ignore zones mode) المختارة غير مشمولة بخريطة GLS، أو أن وحدة الوزن في المتجر غير معروفة للإضافة ولا توجد فئة وزن بوحدة kg (أضفها في System > Localisation > Weight Classes). يُرفض الرقم غير الصالح أو السالب برسالة تذكر الحقل، مثل Fallback cost: "abc" is not a valid number of 0 or more - the previous value was kept. تُحفَظ الحقول الأخرى. ويُرفض كذلك Name أو ترتيب الفرز أو فئة الضريبة أو المنطقة الجغرافية غير الصالحة بالطريقة نفسها.

عام

يسرد هذا القسم الدول المشمولة بخريطة GLS: النمسا، وبلجيكا، وبلغاريا، وكرواتيا، والتشيك، والدنمارك، وفنلندا، وفرنسا، وألمانيا، واليونان، والمجر، وإيطاليا، ولوكسمبورغ، وهولندا، وبولندا، والبرتغال، ورومانيا، وصربيا، وسلوفاكيا، وسلوفينيا، وإسبانيا. لا تُقدَّم الطريقة لدول الوجهة الأخرى.

Enable/Disable: يُظهر GLS ParcelShop عند الدفع أو يُخفيه. الافتراضي: مُعطّل.

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

Tax status: None (shipping is not taxed)، أو فئة الضريبة التي تُطبَّق عندما يخضع الشحن للضريبة.

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

الأسعار

تُدخل الأسعار بالعملة الافتراضية لمتجرك دون الضريبة. ويمكن استخدام الفاصلة أو النقطة للكسور العشرية (4,99 أو 4.99). يُعرض السعر للعميل بعملته.

Calculation type: كيفية تطبيق السعر.

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

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

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

التوفر

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

Maximum weight (kg): يُخفي الطريقة عندما تكون السلة أثقل من ذلك. الافتراضي: 20. تقبل ParcelShops التابعة لـ GLS عادةً طروداً حتى 20 كغ، فتحقق من عقدك مع GLS. القيمة الفارغة أو 0 تعني عدم وجود حد. إذا كان الحد الأدنى أكبر من الحد الأقصى، يُرفض الوزنان برسالة وتبقى القيم السابقة.

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

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

Ignore shipping zones: عند التفعيل، تُعرض الطريقة للدول المختارة أدناه (جميع دول خريطة GLS إذا كانت القائمة فارغة)، بصرف النظر عن المنطقة الجغرافية. وعند التعطيل، تُعرض فقط ضمن المنطقة الجغرافية المحددة أعلاه. الافتراضي: مُعطّل.

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

متقدم

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

Log: يعرض حجم أحدث مدخلات سجل التصحيح. اضغط Clear log لتفريغه.

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

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

Export: اضغط Download JSON لحفظ الإعدادات كملف JSON.

Import: الصق ملف JSON مُصدَّراً سابقاً واضغط Import لاستعادة الإعدادات، مثلاً في متجر آخر. تُبلَّغ القيم غير الصالحة ولا تُستورد.

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

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر GLS ParcelShop. إذا كانت Geo zone محددة (وIgnore shipping zones معطّلة) وكان العنوان خارجها، فلا تُعرض الطريقة. لا تُحتسب إلا المنتجات التي تكون Requires Shipping فيها مضبوطة على Yes: فالمنتجات الأخرى لا تضيف وزناً ولا تدخل في المجموع الفرعي للسلة. والمجموع الفرعي هو سعر هذه المنتجات بعد خصم القسيمة، دون الضريبة. ثم تتحقق الإضافة من الشروط: أن تكون دولة التوصيل مشمولة بخريطة GLS (وأن تكون مختارة في Countries (ignore zones mode) عندما يكون هذا الوضع مفعّلاً)، ووزن السلة، والحد الأدنى للمجموع الفرعي. إذا وصل المجموع الفرعي إلى Free shipping from، فالتوصيل مجاني. وإلا يُؤخذ السعر من صف الدولة (أو صف * Default) ومن عمود الوزن، أو من Fallback cost. وإذا لم يُعثر على سعر، تُخفى الطريقة. يُقرَّب السعر إلى الخانات العشرية للعملة الافتراضية ويُعرض مع ضريبة Tax status المختارة.

عندما يختار العميل GLS ParcelShop، يظهر أسفل الطريقة مربع GLS ParcelShop فيه زر Select GLS ParcelShop. يفتح الزر خريطة GLS ParcelShop الرسمية لدولة التوصيل. يُرفض ParcelShop من دولة أخرى فوراً. بعد اختيار ParcelShop، يظهر اسمه وعنوانه ويتحول الزر إلى Change ParcelShop. يُحفظ الاختيار في جلسة العميل، لذا يبقى عند إعادة تحميل خطوة الشحن. وإذا تغيّر عنوان التوصيل إلى دولة أخرى، فيجب على العميل اختيار ParcelShop مرة أخرى.

عندما يضغط العميل Continue في خطوة طريقة التوصيل، تتحقق الإضافة من أنه تم اختيار ParcelShop وأنه يقع في دولة التوصيل. وإلا يرى العميل Please select a GLS ParcelShop. أو The selected GLS ParcelShop is not in your shipping country. Please choose a ParcelShop again. ويبقى في تلك الخطوة. وإذا تعذّر حفظ ParcelShop، يرى العميل The ParcelShop could not be saved. Please try again. وإذا تعذّر تحميل سكربت خريطة GLS، يرى العميل The GLS ParcelShop map could not be loaded. Please reload the page or choose another shipping method.

في OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن بصفحة الدفع، ويختار GLS ParcelShop في النافذة Shipping method options. يظهر مربع GLS ParcelShop الذي فيه زر Select GLS ParcelShop داخل تلك النافذة أسفل الطريقة، وتُفتح خريطة GLS فوق النافذة. لا يتابع زر Continue الخاص بالنافذة دون ParcelShop صالح، وتظهر الرسائل نفسها. يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه في كل مرة يؤكد فيها العميل من جديد، ويُحدَّث ParcelShop الطلب معه.

تعمل خريطة GLS في متصفح العميل. في صفحة الدفع تحمّل الإضافة سكربت خريطة GLS من map.gls-croatia.com، وتحمّل الخريطة من GLS بيانات ParcelShop وبلاطات الخريطة. تتلقى GLS بيانات الطلب المعتادة للزائر (عنوان IP والمتصفح). ولا يُرسَل شيء من خادمك إلى GLS. ولا يوقف خطأ في الإضافة الدفع لطرق الشحن الأخرى أبداً؛ بل يُكتب في السجل.

لا تجلب الإضافة أسعار الشحن الحية من GLS، ولا تنشئ شحنات GLS، ولا تطبع الملصقات، ولا تتتبع الطرود. ليست لدى خادمك قائمة بـ ParcelShops، لذلك لا يمكنها التحقق من معرّف ParcelShop مقابل GLS. انقل معرّف ParcelShop من الطلب إلى GLS بالطريقة المعتادة لديك (MyGLS، أو برنامج GLS الخاص بك، أو إضافة أخرى).

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

عند تقديم الطلب، يُحفَظ ParcelShop المختار عند الدفع مع الطلب: معرّفه، واسمه مع العنوان، ودولته. وبعد اكتمال الطلب يُمسح الاختيار، فتبدأ السلة التالية دون ParcelShop.

Shipping method name: يُضاف ParcelShop إلى اسم طريقة الشحن في الطلب، مثل GLS ParcelShop: name, address (اسم الطريقة ثم ParcelShop) (يحتفظ OpenCart 3 بحد أقصى 128 حرفاً منه، ويحتفظ OpenCart 4 بحد أقصى 255 حرفاً). وبذلك يظهر ParcelShop في بريد تأكيد الطلب المُرسَل إلى العميل، وفي صفحة الطلب ضمن Order History لدى العميل، وفي Sales > Orders. لا يعرض OpenCart طريقة الشحن في صفحة نجاح الطلب.

Admin order page: في Sales > Orders، تعرض لوحة GLS ParcelShop اسم ParcelShop وعنوانه مع ParcelShop ID والدولة. وإذا لم يكن لطلب GLS ParcelShop أي ParcelShop، تعرض اللوحة No ParcelShop was selected for this order. وتعرض اللوحة ParcelShop فقط؛ ولا يمكن تغييره من هناك.

بريد التاجر الإلكتروني: يتضمن بريد تنبيه الطلب الجديد المُرسَل إلى المتجر ParcelShop مع ParcelShop ID الخاص به في كتلة التعليقات.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox GLS ParcelShop هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox GLS ParcelShop > Edit، فوق الإعدادات. الصق المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مخفياً، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-shipping-gls-parcelshop والرابط 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.

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

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

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

لا يظهر GLS ParcelShop عند الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. تحقق من Geo zone، أو من Ignore shipping zones وCountries (ignore zones mode). تحقق من أن دولة الوجهة من دول خريطة GLS ولها سعر (صف للدولة، أو صف * Default، أو Fallback cost). تحقق من حدود الوزن وMinimum cart subtotal، ومن أن المنتجات مضبوطة على Requires Shipping بقيمة Yes. فعّل Debug log وانظر إلى الحقل Log لمعرفة السبب.

الخريطة لا تفتح: يرى العميل "The GLS ParcelShop map could not be loaded..." عندما يُحظر سكربت GLS، مثلاً بسبب مانع إعلانات أو مانع للخصوصية، أو سياسة أمان المحتوى، أو تعطل لدى GLS. اسمح بالنطاق map.gls-croatia.com في سياسة أمان المحتوى لديك.

مربع ParcelShop لا يظهر أسفل الطريقة: تم اختبار الإضافة مع القالب الافتراضي لـ OpenCart وصفحة الدفع الخاصة به. وقد لا يظهر المربع مع قالب أو إضافة دفع تستبدل خطوة طريقة الشحن.

التوصيل مجاني لدولة بالخطأ: تحقق من صف تلك الدولة في Country prices. الصف الذي يكون فيه Price وكل أعمدة الوزن 0 يعني توصيلاً مجانياً.

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

يعرض طلب الرسالة No ParcelShop was selected for this order: تم تقديم الطلب دون ParcelShop في دولة التوصيل. السبب مكتوب في السجل. اطلب ParcelShop من العميل وسلّمه إلى GLS يدوياً.

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

للمطوّرين: يمكن استبدال عنوان سكربت خريطة GLS بالإعداد vfd_glps_widget_url؛ وليس لهذا الإعداد حقل في صفحة الإعدادات.

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

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

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

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