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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة دونه.

PHP: 8.0 أو أحدث.

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

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر Install Now. يمكنك أيضًا رفع مجلد vfd_packeta إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

3. افتح الإعدادات: WooCommerce > Settings > Shipping > VibeFox Packeta، أو انقر Settings أسفل اسم الإضافة في صفحة Plugins.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة، ثم انقر Activate.

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

6. أضف VibeFox Packeta إلى مناطق الشحن الخاصة بجمهورية التشيك وسلوفاكيا والمجر ورومانيا، في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Packeta. وهي تنطبق على كل مناطق الشحن. عندما تضيف الطريقة إلى منطقة، تحتوي نافذة المنطقة على حقل واحد فقط:

Title (zone): الاسم الذي يراه العملاء في هذه المنطقة. اتركه فارغًا لاستخدام Name العام.

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

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

عام

Enable/Disable: يفعّل الطريقة أو يعطّلها في جميع المناطق دفعة واحدة.

Name: اسم طريقة الشحن الذي يراه العميل. يمكن للمنطقة أن تستبدله بـ Title خاص بها. الافتراضي: Packeta pickup point.

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: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها.

الأسعار

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

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

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

التوفر

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

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

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

Excluded shipping classes: يُخفي الطريقة عندما تحتوي السلة على منتج من أي فئة شحن من فئات WooCommerce هذه.

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

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

متقدم

Debug log: يكتب حسابات الأسعار واختيارات نقاط الاستلام في WooCommerce > Status > Logs (المصدر "vfd-packeta"). لا يُسجَّل أي بيان شخصي للعميل ولا مفتاح API. تُسجَّل محاولات التحقق الفاشلة من مفتاح API دائمًا. أوقف السجل عندما تنتهي.

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

كيف تعمل في صفحة الدفع

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

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي Cart وCheckout. وهي متوافقة مع خاصية تخزين الطلبات عالي الأداء في WooCommerce (HPOS).

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

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

نقطة الاستلام إلزامية. إذا أتمّ العميل الطلب دون اختيار نقطة، تتوقف صفحة الدفع بالرسالة "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: مع الاسم والعنوان.

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

في قاعدة البيانات تُخزَّن النقطة في البيانات الوصفية للطلب _vfd_pckt_point_id و_vfd_pckt_point_name (الاسم والعنوان) و_vfd_pckt_point_country.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص موجودة أعلى WooCommerce > Settings > Shipping > VibeFox Packeta. الصق المفتاح في License key وانقر Activate. تعرض الكتلة الحالة، مثل التاريخ الذي يبقى فيه الترخيص فعالًا ونطاقك. استخدم Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك في vibefox.net.

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

بدون مفتاح فعّال لا تُعرض Packeta للعملاء في صفحة الدفع. أما مديرو المتجر المسجّلو الدخول فيرونها مع العلامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. يظهر تذكير في صفحة Plugins وفي صفحات WooCommerce. ولا تتأثر الطلبات الحالية.

عند انتهاء صلاحية الترخيص تستمر الإضافة في العمل، لكن التحديثات والدعم تتطلب التجديد. يُعاد التحقق من الحالة تلقائيًا في الخلفية.

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

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

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

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

الشحن مجاني بالخطأ: راجع صفوف Country prices التي تحمل Price يساوي 0، وخاصةً صف * Default المضاف بالزر + Add country والمتروك بلا تعبئة.

دول أو ناقلون آخرون: تعمل الطريقة افتراضيًا مع CZ وSK وHU وRO. يستطيع المطورون إضافة دول باستخدام الفلتر vfd_pckt_countries، وتمرير معرّفات الناقلين إلى الأداة باستخدام الفلتر vfd_pckt_widget_options.

تُظهر كتلة الترخيص خطأ: اتبع الرسالة الظاهرة في الكتلة. فمثلًا إذا كان المفتاح مستخدمًا بالفعل على نطاق آخر، فحرّر خانة في حسابك في vibefox.net ثم انقر Check now. وإذا تغير عنوان الموقع، فانقر Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذّر الوصول إلى خادم التراخيص، تستمر الإضافة بآخر حالة معروفة.

الإزالة

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

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