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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Balikobot (للأسعار الفورية ونقاط الاستلام): تحتاج إلى حساب Balikobot بصلاحية الوصول إلى API. يوجد مستخدم API والمفتاح في منطقة العملاء في Balikobot (client.balikobot.cz). يفعّل دعم Balikobot (podpora@balikobot.cz) واجهة API لحسابك وشركات النقل لديك. تتطلب الأسعار الفورية شركة نقل وخدمة يدعم Balikobot لهما "transportcosts". وتتطلب نقاط الاستلام شركة نقل تدعم "branchlocator" (مثل Česká pošta وZásilkovna وPPL وDPD وGLS). وإذا لم تكن متأكدًا، فاسأل دعم Balikobot. وتعمل الأسعار الثابتة من دون حساب.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل مستخدم API ومفتاح API، واختر شركة النقل ونوع الخدمة ومصدر السعر والأسعار حسب الدولة (راجع «الإعداد»). بالنسبة إلى خدمات الاستلام، فعّل Pickup point selection.

6. أضف VibeFox Balikobot إلى منطقة شحن (مثلًا التشيك) في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول.

الإعداد

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Balikobot. وتُطبَّق على جميع مناطق الشحن. تظهر في أعلى الصفحة تحذيرات بشأن الإعدادات التي قد تخفي الطريقة أو الأسعار الفورية أو نقاط الاستلام. وفي كل مرة تحفظ فيها الإعدادات، تُمسح الأسعار ونقاط الاستلام المخزنة مؤقتًا. وعند إضافة الطريقة إلى منطقة، تحتوي نافذة المنطقة على حقل واحد فقط:

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

عام

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

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

Tax status: تعني Taxable أن WooCommerce يضيف ضريبة الشحن فوق السعر، وتعني None أنه لا يضيفها. وعادةً ما تكون أسعار Balikobot غير شاملة لضريبة القيمة المضافة.

حساب API الخاص بـ Balikobot (مطلوب للأسعار الفورية ونقاط الاستلام)

API user: مستخدم API الخاص بـ Balikobot من منطقة العملاء.

API key: مفتاح API الخاص بـ Balikobot من منطقة العملاء.

Carrier: شركة النقل من Balikobot المستخدمة للأسعار ونقاط الاستلام: Česká pošta (الافتراضية)، وZásilkovna (Packeta)، وPPL، وDPD، وGLS، وDHL Express، وUPS، وTNT، وFedEx، وGeis، وInTime، وUloženka، وToptrans، وPošta bez hranic، وSlovenská pošta، وSPS (Slovak Parcel Service)، أو Magyar Posta. ويجب تفعيلها في حسابك لدى Balikobot.

Service type: رمز الخدمة في Balikobot لشركة النقل. الافتراضي: NP. بالنسبة إلى Česká pošta: NP = طرد إلى مكتب بريد، وNB = طرد إلى Balíkovna، وDR = توصيل إلى المنزل. ترد رموز شركات النقل الأخرى في منطقة عملاء Balikobot وفي وثائق API.

السعر (جميع الأسعار بعملة متجرك)

Price source: طريقة حساب السعر.

Country prices: سعر ثابت لكل دولة مقصودة (رمز من حرفين، مثل CZ وSK). استخدم * لجميع الدول الأخرى. الأرقام العشرية بنقطة أو فاصلة. ويُستخدم في الوضع الثابت وكبديل عند فشل الواجهة. والدولة التي لا سعر لها (ولا يوجد صف * لها) لا تحصل على سعر ثابت.

Fixed price per: Order يحتسب السعر مرة واحدة. Item (price × quantity) يضربه في عدد العناصر في السلة. ويسري هذا على الأسعار الثابتة فقط. أما السعر الفوري من Balikobot فيكون دائمًا للطرد كاملًا.

Exchange rate: قيمة وحدة واحدة من عملة سعر Balikobot (عادةً CZK) بعملة متجرك، مثل 0.04. ويُستخدم فقط عندما يعيد Balikobot سعرًا بعملة مختلفة. اتركه فارغًا لرفض هذه الأسعار، حتى لا يُحمَّل العميل سعرًا خاطئًا أبدًا.

الشروط

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

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

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

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

Free shipping: فعّل الشحن المجاني من المبلغ المذكور أدناه.

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

التوفر من دون مناطق الشحن

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

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

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

Pickup point selection: يجب على العميل اختيار نقطة استلام. استخدمه لخدمات الاستلام، مثل Česká pošta NP أو NB، أو Zásilkovna. ويتطلب مستخدم API والمفتاح.

Selector width: عرض قائمة نقاط الاستلام بوحدة CSS، مثل 100% أو 400px. الافتراضي: 100%.

متقدم

Debug log: يسجّل طلبات API وحسابات الأسعار في WooCommerce > Status > Logs، بالمصدر "vfd-balikobot". وتُسجَّل أخطاء API دائمًا. ولا تُسجَّل بيانات الاعتماد وعناوين العملاء أبدًا.

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

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

عندما يدخل العميل عنوان التوصيل، تتحقق الإضافة من وزن السلة وMinimum order amount وExcluded shipping classes. فإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Balikobot.

في الوضع الثابت يُؤخذ السعر من Country prices. وفي الأوضاع الفورية ترسل الإضافة إلى Balikobot شركة النقل ونوع الخدمة والدولة المقصودة والرمز البريدي، إضافة إلى وزن السلة بالكيلوغرام. ولا يُطلب السعر الفوري إلا بعد أن يُدخل العميل رمزًا بريديًا. ويُحوَّل السعر بعملة أخرى باستخدام Exchange rate، أو يُرفض إذا لم يكن سعر الصرف محددًا.

تُخزَّن الأسعار الفورية مؤقتًا لمدة ساعة، حتى لا تُنشئ السلة نفسها طلبًا جديدًا. ويُخزَّن الطلب الفاشل مؤقتًا لمدة 5 دقائق، ومهلة API 12 ثانية، حتى لا تنتظر صفحة الدفع Balikobot في كل تحديث. ولا تُعرض أخطاء API على العميل أبدًا: تُخفى الطريقة، أو يُستخدم السعر الثابت في وضع البديل. وتُكتب التفاصيل في السجل.

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي السلة والدفع. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

عند تفعيل Pickup point selection، تظهر قائمة بنقاط الاستلام أسفل خيار Balikobot في صفحة الدفع، سواء في الصفحة الكلاسيكية أو في صفحة الدفع القائمة على الكتل. وتُحمَّل القائمة من "branchlocator" في Balikobot حسب دولة العميل ومدينته ورمزه البريدي. وإلى أن يُدخل العميل المدينة والرمز البريدي، يرى الرسالة Enter your city and postcode to see the pickup points. وتُخزَّن القائمة مؤقتًا لمدة 12 ساعة.

الاختيار إلزامي: يرى العميل الرسالة Please select a pickup point. ويتحقق الخادم أيضًا من أن النقطة المختارة تنتمي إلى عنوان الشحن. وبعد تغيير العنوان، يُطلب من العميل اختيار نقطة استلام مرة أخرى. وإذا تعذر تحميل النقاط، يُطلب من العميل المحاولة لاحقًا أو اختيار طريقة شحن أخرى.

تُحفظ نقطة الاستلام المختارة في الطلب. وفي شاشة الطلب بلوحة الإدارة تظهر أسفل عنوان الشحن باسم Balikobot pickup point، مع معرّف فرع Balikobot وشركة النقل، وهما ما تحتاجه عند إنشاء الشحنة في Balikobot. انقر Change لاختيار نقطة أخرى قريبة من عنوان الطلب. ويرى العميل النقطة باسم Pickup point في صفحة الطلب وفي رسائل البريد الإلكتروني للطلب (HTML ونص عادي). وتحتفظ الطلبات الحالية ببيانات نقطة الاستلام الخاصة بها.

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

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

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

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

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

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

لا يظهر Balikobot عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). اقرأ التحذيرات أعلى صفحة الإعدادات. وتحقق من حدود الوزن وMinimum order amount وExcluded shipping classes. وفي الوضع الثابت، تحقق من أن الدولة أو * لديها سعر.

لا تظهر الأسعار الفورية: فعّل Debug log، ثم أعد تحميل صفحة الدفع وافتح WooCommerce > Status > Logs (المصدر "vfd-balikobot"). يعرض السجل السبب: بيانات اعتماد API مفقودة، أو رمز بريدي لم يُدخل بعد، أو خطأ من Balikobot لشركة النقل والخدمة، أو سعر بعملة أخرى من دون Exchange rate. ومع Live Balikobot rate, fixed price if the API fails، يظل العملاء يحصلون على السعر الثابت أثناء إصلاح المشكلة.

الأسعار بعملة خاطئة: الأسعار الثابتة بعملة متجرك. ويعيد Balikobot الأسعار الفورية بعملة عقدك مع Balikobot (عادةً CZK). وإذا اختلفت عن عملة متجرك، فاضبط Exchange rate.

هل تشمل الضريبة؟ أسعار Balikobot عادةً غير شاملة لضريبة القيمة المضافة. ومع ضبط Tax status على Taxable، يضيف WooCommerce ضريبة الشحن.

لا توجد نقاط استلام في القائمة: تحقق من ضبط مستخدم API والمفتاح، ومن أن شركة النقل تدعم "branchlocator"، ومن أن العميل أدخل المدينة والرمز البريدي. وراجع السجل لمعرفة خطأ Balikobot.

تبدو الأسعار أو نقاط الاستلام قديمة بعد تغيير: احفظ صفحة الإعدادات. فهذا يمسح الأسعار ونقاط الاستلام المخزنة مؤقتًا.

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

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

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

Balikobot علامة تجارية تعود إلى مالكها. هذه الإضافة غير تابعة لـ Balikobot ولا معتمدة من قِبلها.