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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

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

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

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

التثبيت

1. في لوحة الإدارة، اذهب إلى Modules > Module Manager واضغط Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، اضغط Configure، أو ابحث لاحقًا عن VibeFox Packeta في قائمة الوحدات واضغط Configure.

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

4. أدخل API key الخاص بـ Packeta وأسعارك: صف واحد على الأقل في Country prices (مثلًا * Default)، أو Fallback cost. اضغط Save. تعرض الصفحة ما إذا قبلت Packeta المفتاح.

عند التثبيت، تنشئ الوحدة شركة الشحن Packeta pickup point بنص مدة التوصيل Packeta pickup point or Z-BOX. وترتبط بمناطق جمهورية التشيك وسلوفاكيا والمجر ورومانيا، وبجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار في Shipping > Carriers. لا تحدد الأسعار هناك: يأتي السعر دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Packeta > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة.

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

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

عام

Enable/Disable: يفعّل Packeta أو يعطّلها في الدفع.

Name: اسم شركة الشحن الذي يراه العميل. وهو أيضًا اسم شركة الشحن في Shipping > Carriers. الافتراضي: 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: قواعد الضريبة المطبقة على سعر الشحن. None (no tax on shipping) أو Taxable مع إحدى مجموعات قواعد الضريبة الخاصة بك. يُحفظ الاختيار في شركة الشحن.

الأسعار

لا تتيح 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) في صفين، فعند الحفظ يُحتفظ بالأول فقط. إذا لم تكن قيمة في الجدول رقمًا صالحًا، فلن يُحفظ الجدول، وتعرض الصفحة القيم الخاطئة.

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

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

التوفر

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

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

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

Ignore shipping zones: عند التفعيل، تُربط شركة الشحن بجميع المناطق وتُعرض للدول المختارة أدناه. تُربط المناطق التي تُنشأ لاحقًا فورًا. عند إيقافه، تستعيد شركة الشحن المناطق التي كانت لها سابقًا. عند الإيقاف، تُعرض شركة الشحن فقط في المناطق المحددة لها في Shipping > Carriers.

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

متقدم

Debug log: يكتب حسابات الأسعار واختيارات نقاط الاستلام في modules/vfd_packeta/logs/. لا يمكن فتح الملف من الويب. لا تُسجَّل بيانات العملاء الشخصية ولا مفتاح API. تُسجَّل الأخطاء وفحوصات مفتاح API الفاشلة دائمًا. أوقف السجل عند الانتهاء.

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

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

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

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

عندما يختار العميل شركة الشحن 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."

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

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

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

نقطة الاستلام مطلوبة. إذا ضغط العميل 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 تعرض الاسم والعنوان وPickup point ID والدولة. إذا لم يكن لطلب Packeta نقطة، تقول الكتلة: "No pickup point was selected for this order."

صفحتا تأكيد الطلب وتفاصيله: Packeta pickup point: مع الاسم والعنوان.

رسائل البريد الإلكتروني للطلب: يُضاف اسم النقطة وعنوانها إلى شركة الشحن في رسالة تأكيد الطلب. وتتضمن رسالة الطلب الجديد الموجهة إلى التاجر أيضًا Pickup point ID.

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

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

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

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

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

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

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

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

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

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

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

دول أو شركات شحن أخرى: افتراضيًا، تعمل شركة الشحن مع CZ وSK وHU وRO. يمكن للمطورين إضافة دول عبر الخطاف actionVfdPcktCountries، وتمرير معرّفات شركات الشحن إلى الأداة عبر الخطاف actionVfdPcktWidgetOptions.

تقول الصفحة إن شركة الشحن Packeta مفقودة: حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإنشائها من جديد.

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

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

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