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

المتطلبات

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

PHP: 8.0 أو أحدث.

مفتاح API الخاص بـ Packeta: تجده في قسم العميل لدى Packeta (client.packeta.com) تحت Client support. يتكون من 16 حرفًا وأرقامًا. تحتاج الأداة إليه لتفتح أثناء الدفع، لذلك لا تُعرض طريقة الشحن للعملاء إلا بعد إدخال مفتاح API.

الدول: يجب أن تكون جمهورية التشيك أو سلوفاكيا أو المجر أو رومانيا دولًا مفعّلة في متجرك. وهي موجودة في بيانات OpenCart القياسية. لا تملك المجر مناطق في OpenCart، لذلك يبقى حقل المنطقة في العنوان فارغًا، وهذا لا يؤثر في شيء.

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

التثبيت

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

OpenCart 3

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

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

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

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

5. أدخل API key الخاص بـ Packeta وأسعارك: صف واحد على الأقل من Country prices (مثل * Default) أو Fallback cost. فعّل Enable/Disable واضغط Save. تُظهر الصفحة ما إذا كانت Packeta قد قبلت المفتاح.

OpenCart 4

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

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

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

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

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

الإعداد

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

تُعرض الطريقة فقط للدول الموجودة في شبكة نقاط الاستلام الخاصة بـ Packeta: CZ وSK وHU وRO. وفوق الإعدادات تعرض الصفحة نتيجة التحقق من مفتاح API وتحذيرات بشأن المشكلات: لا يوجد مفتاح API، أو لا يوجد سعر، أو الدول المختارة خارج شبكة Packeta، أو وحدة وزن المتجر غير معروفة للإضافة. تُحدَّث التحذيرات بعد كل حفظ.

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

عام

Enable/Disable: يفعّل Packeta أو يوقفه أثناء الدفع. الافتراضي: إيقاف.

Name: اسم طريقة الشحن الذي يراه العميل. الافتراضي: Packeta pickup point. مطلوب، بحد أقصى 64 حرفًا.

API key: مفتاح API الخاص بـ Packeta من client.packeta.com > Client support. يمكنك أيضًا لصق كلمة مرور API المكونة من 32 حرفًا: لا يُحفظ منها إلا أول 16 حرفًا، وهي مفتاح API. مفتاح API عام: يُرسل إلى متصفح العميل لفتح الأداة. عند حفظ مفتاح جديد يُتحقق منه عبر قناة شركات الشحن لدى Packeta، وتعرض الصفحة Packeta API key verified أو تُعلن أن Packeta رفضته. وإذا تعذّر تنفيذ التحقق، يُحفظ المفتاح ويُتحقق منه مجددًا عند حفظك التالي.

Widget language: لغة أداة نقاط الاستلام. يتبع Store / visitor language (الافتراضي) لغة الصفحة. ويمكنك أيضًا تثبيتها على التشيكية أو السلوفاكية أو المجرية أو الرومانية أو الإنجليزية أو الألمانية أو البولندية أو الأوكرانية.

Pickup point types: نقاط Packeta التي تعرضها الأداة.

Tax status: الفئة الضريبية في OpenCart التي تُطبَّق على سعر الشحن، أو None (no tax on shipping) (الافتراضي).

Sort order: ترتيب Packeta بين طرق الشحن أثناء الدفع. رقم صحيح.

الأسعار

لا تملك Packeta واجهة برمجية عامة لأسعار الشحن. تأتي الأسعار من هذا الجدول وتُدخل بعملة متجرك الافتراضية، دون الضريبة. يرى العملاء الذين يدفعون بعملة أخرى السعر محوّلًا.

Calculation type: Per order (الافتراضي) يحصّل السعر مرة واحدة. أما Per item (price x quantity) فيضربه في كمية المنتجات التي تحتاج إلى شحن.

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

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

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

التوفر

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

Maximum weight (kg): يخفي الطريقة عندما يكون وزن السلة أكبر. الافتراضي: 15. تقبل نقاط استلام Packeta وZ-BOX عادةً طرودًا تصل إلى 15 كجم؛ راجع عقدك مع Packeta. الفارغ أو 0 يعني بلا حد. يُرفض حد أدنى للوزن أكبر من الحد الأقصى عند الحفظ، ويُحتفظ بالقيمتين السابقتين.

Minimum cart subtotal: يعرض الطريقة فقط عندما يبلغ المجموع الفرعي للسلة (بعد الكوبون، دون الضريبة) هذا المبلغ.

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

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

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

متقدم

Debug log: يسجّل حسابات الأسعار واختيارات نقاط الاستلام في storage/logs/vfd_pckt_debug.log.php. لا يمكن قراءة الملف من الويب. لا تُسجَّل البيانات الشخصية للعملاء ولا مفتاح API. تُسجَّل الأخطاء وفحوصات مفتاح API الفاشلة دائمًا. أوقف السجل عند الانتهاء. عندما يبلغ الملف 5 ميغابايت يُنقل إلى vfd_pckt_debug.old.log.php ويبدأ سجل جديد.

Log (last lines): يعرض حجم سجل التصحيح وأحدث إدخالاته. اضغط Clear log لمسحه.

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

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

Export: اضغط Download JSON لحفظ الإعدادات في ملف JSON، بما فيها مفتاح API، وهو مفتاح عام.

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

كيف تعمل أثناء الدفع

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

تحت خيار Packeta في خطوة طريقة الشحن يوجد الزر Choose pickup point. يفتح هذا الزر أداة Packeta الرسمية في متصفح العميل مع دولة الوجهة ووزن السلة وأنواع النقاط المختارة ولغة الأداة. بعد أن يختار العميل نقطة يظهر اسمها وعنوانها أسفل الطريقة، ويتحول الزر إلى Change pickup point. تُحفظ النقطة لجلسة الدفع وتبقى عند إعادة تحميل الصفحة. ولا تُستخدم نقطة اختيرت لدولة أخرى إذا تغير عنوان التسليم إلى دولة أخرى.

لا يطلب خادمك أي شيء من Packeta أثناء الدفع. يُحمَّل نص الأداة من widget.packeta.com في صفحة الدفع فقط. وإذا حُظر (بسبب مانع إعلانات أو خصوصية، أو سياسة أمان المحتوى، أو انقطاع في خدمة Packeta)، يرى العميل الرسالة: "The Packeta pickup point widget could not be loaded. Please reload the page or choose another shipping method."

لا تُطلب أسعار Packeta مباشرة وقت الدفع؛ بل تأتي من جدولك. لا تُنشئ الإضافة شحنات Packeta ولا تطبع ملصقات ولا تتتبع الطرود، ولا تقدم افتراضيًا التوصيل إلى المنزل أو نقاط استلام شركات الشحن الشريكة. أرسل معرّف نقطة الاستلام من الطلب إلى Packeta بالطريقة المعتادة لديك، مثلًا عبر الاستيراد في client.packeta.com. يعمل زر نقطة الاستلام مع الدفع القياسي لـ OpenCart في القالب الافتراضي.

على OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار Packeta في النافذة Shipping method options. يظهر الزر Choose pickup point والنقطة المختارة في تلك النافذة، تحت خيار Packeta، وتُفتح أداة Packeta فوقها. الأسعار هي نفسها في OpenCart 3.

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

نقطة الاستلام مطلوبة. إذا ضغط العميل Continue في خطوة طريقة الشحن دون اختيار نقطة، فلن تكتمل الخطوة، ويرى العميل الرسالة: "Please choose a Packeta pickup point." وإذا كانت النقطة المختارة في دولة غير دولة عنوان التسليم، يرى العميل: "The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again." لا تتحقق الإضافة من معرّف النقطة لدى Packeta؛ بل تتأكد فقط من أن نقطة قد اختيرت وأن دولتها متطابقة.

تُرفق النقطة بالطلب عند إنشائه:

طريقة شحن الطلب: يُضاف اسم النقطة وعنوانها إلى اسم الطريقة، مثل Packeta pickup point: <point> (حتى 128 حرفًا). يراه العميل في سجل الطلب وفي رسالة الطلب الإلكترونية، ويُطبع في الفاتورة. لا تعرض صفحة نجاح الطلب في OpenCart طريقة الشحن.

صفحة الطلب في الإدارة: افتح الطلب في Sales > Orders. تعرض لوحة Packeta pickup point الاسم والعنوان وPickup point ID والدولة. وإذا لم تكن لطلب Packeta نقطة، تقول اللوحة: "No pickup point was selected for this order."

على OpenCart 4 لا يتابع زر Continue في النافذة Shipping method options دون نقطة، بالرسائل نفسها. ويحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه في كل مرة يؤكد فيها العميل من جديد، وتُحدَّث نقطة الطلب معه. وتظهر لوحة Packeta pickup point في صفحة الطلب في الإدارة فوق قسم History.

تُخزَّن النقطة في جدول الإضافة الخاص vfd_pckt_point (جلسة الدفع، والطلب، ومعرّف النقطة، والاسم والعنوان، والدولة).

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

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

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

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

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

Packeta لا تظهر أثناء الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن API key مُدخل، وأن دولة التسليم هي CZ أو SK أو HU أو RO. تحقق من ضبط سعر للدولة (صف الدولة، أو صف * Default، أو Fallback cost)، وحدود الوزن والمجموع الفرعي، وGeo zone (أو Ignore shipping zones ودولها). تحقق من أن المنتجات تملك Requires Shipping على Yes. تسرد صفحة الإعدادات مشكلات الإعداد في الأعلى. فعّل Debug log لترى السبب في Log (last lines).

رفضت Packeta مفتاح API: انسخ مفتاح API مرة أخرى من client.packeta.com > Client support واحفظ. وحتى ذلك الحين لا يمكن أن تفتح الأداة أثناء الدفع.

لا تُفتح الأداة: نص Packeta محظور بسبب مانع إعلانات أو خصوصية، أو سياسة أمان المحتوى، أو انقطاع في خدمة Packeta. اسمح بـ widget.packeta.com في سياسة أمان المحتوى لديك.

الشحن مجاني عن طريق الخطأ: تحقق في Country prices من الصفوف التي يكون فيها Price مساويًا لـ 0، خاصةً صف * Default الذي أضفته بـ Add country وتركته فارغًا، وتحقق من Free shipping from.

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

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

للمطورين: يمكن للإضافات الأخرى إضافة دول، وتمرير خيارات مثل معرّفات شركات الشحن إلى الأداة، وتغيير عنوان URL لنص الأداة أو لغتها عبر أحداث OpenCart vfd_packeta/countries وvfd_packeta/widget_options وvfd_packeta/widget_url وvfd_packeta/widget_language (المشغّلات مسبوقة بالبادئة catalog/، مثل catalog/vfd_packeta/widget_options).

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

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

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

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