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

المتطلبات

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

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

حساب Balikobot (للأسعار الفورية ونقاط الاستلام): تحتاج إلى حساب Balikobot بصلاحية الوصول إلى API. يوجد اسم مستخدم 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. في الواجهة الخلفية، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند اكتمال الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Balikobot في قائمة الوحدات وانقر على Configure.

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

4. أدخل اسم مستخدم API ومفتاح API، واختر الناقل ونوع الخدمة ومصدر السعر والأسعار لكل دولة (انظر الإعدادات). للخدمات التي تتضمن الاستلام، فعّل Pickup point selection. انقر على Save.

عند التثبيت، تنشئ الوحدة الناقل Balikobot مع نص مدة التوصيل Delivery by Balikobot. يُعيَّن الناقل إلى مناطق التشيك وسلوفاكيا والمجر وإلى جميع مجموعات العملاء. ويمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Balikobot > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة بأكملها. بعد الحفظ ترى Settings saved. Cached rates and pickup points were cleared. وتظهر في أعلى الصفحة تحذيرات بشأن الإعدادات التي قد تخفي الناقل أو الأسعار الفورية أو نقاط الاستلام: أسعار فورية أو نقاط استلام من دون اسم مستخدم API أو مفتاح API، وعملة متجر غير CZK من دون Exchange rate، وحقل Country prices فارغ مع الأسعار الثابتة أو مع وضع الاحتياط، ووحدة وزن للمتجر لا تتعرف عليها الوحدة (عندها تُقرأ الأوزان بالكيلوغرام؛ استخدم kg أو g أو lb أو oz)، وناقل محذوف. ولا تُحفظ القيمة التي ليست رقمًا، وترى تحذيرًا يذكر اسم الحقل.

General

Enable/Disable: يفعّل شحن Balikobot أو يعطّله. وهو المفتاح نفسه الذي يمثل حالة الناقل في Shipping > Carriers.

Name: اسم طريقة الشحن الذي يراه العميل (اسم الناقل). القيمة الافتراضية: Balikobot. حقل إلزامي، بحد أقصى 64 حرفًا.

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

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

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

API key: مفتاح Balikobot API من منطقة العملاء. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. Clear the API user to remove the saved key. أدخل قيمة جديدة فقط إذا أردت تغييره.

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) والأسعار. انقر على Add row لإضافة دولة، وعلى أيقونة سلة المهملات لحذفها. استخدم * رمزًا للدولة لجميع الدول الأخرى. تُكتب الكسور بنقطة أو فاصلة. تُستخدم في الوضع الثابت وكاحتياط للواجهة. الدولة التي لا سعر لها (ولا يوجد صف *) لا تحصل على سعر ثابت. تُحذف الصفوف غير الصالحة عند الحفظ، ويعرض تحذير قائمة بها.

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

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

الشروط

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

Max weight (kg): يخفي الناقل عندما تكون السلة أثقل من ذلك. القيمة الافتراضية: 100. 0 تعني بلا حد. الحقل الفارغ يعني 100 kg. إذا كان Min weight (kg) أكبر من الحد الأقصى، ترى تحذيرًا وتُحفظ الأوزان السابقة.

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

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

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

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

عادةً يُعرض الناقل في مناطقه في Shipping > Carriers.

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

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

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

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

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

متقدم

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

Log: يعرض حجم السجل وآخر مدخلاته. انقر على Clear log لتفريغه.

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

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر Balikobot. تُحتسب المنتجات المادية فقط: فالمنتجات الافتراضية لا تضيف وزنًا ولا تدخل في مبلغ الطلب. تتحقق الوحدة أولًا من الدول (مع Ignore shipping zones) ووزن السلة وMinimum order amount. إذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Balikobot.

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

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

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

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

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

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

يُحفظ الاختيار في السلة فور أن يختار العميل نقطة. والاختيار إلزامي: زرا Continue في خطوة الشحن وPlace order محجوبان مع الرسالة Please select a pickup point. ويتحقق الخادم أيضًا من أن النقطة المختارة تنتمي إلى عنوان التوصيل. وإلا يرى العميل The selected pickup point is not available for your shipping address. Please choose a pickup point again. وإذا لم تُوجد أي نقطة، يُطلب من العميل التحقق من المدينة والرمز البريدي أو اختيار طريقة شحن أخرى. وإذا تعذر تحميل النقاط، يُطلب منه المحاولة لاحقًا أو اختيار طريقة شحن أخرى.

تُحفظ نقطة الاستلام المختارة في الطلب. وفي صفحة الطلب بالواجهة الخلفية تظهر في كتلة Balikobot pickup point مع معرّف فرع Balikobot والناقل، وهما ما تحتاجه عند إنشاء الشحنة في Balikobot. انقر على Change لاختيار نقطة أخرى قرب عنوان الطلب، ثم انقر على Save. ولتغيير النقطة يكفي حق تعديل الطلبات، ولا يلزم الوصول إلى صفحات الوحدات. وإذا لم تكن للطلب نقطة، تعرض الكتلة No pickup point was selected for this order.

يرى العميل النقطة بصيغة Pickup point: في صفحة تأكيد الطلب وفي تفاصيل الطلب. وفي بريد تأكيد الطلب وفي بريد الطلب الجديد للمتجر (وحدة Mail alerts) تُضاف بعد اسم الناقل. وتحتفظ الطلبات الحالية ببيانات نقطة الاستلام الخاصة بها.

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

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

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

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

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

لا يظهر Balikobot عند الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. اقرأ التحذيرات أعلى صفحة الوحدة. وفي Shipping > Carriers تحقق من أن الناقل يغطي منطقة دولة العميل ومجموعته، أو فعّل Ignore shipping zones وتحقق من Countries. تحقق من حدود الوزن وMinimum order amount. وفي الوضع الثابت، تحقق من أن الدولة أو * لها سعر. وقد تكون المنتجات مقيّدة بناقلين معينين في صفحة المنتج أيضًا.

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

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

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

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

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

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

للمطورين: للوحدة خطافات خاصة لتغيير عنوان API (actionVfdBlkbApiUrl) وحزمة "transportcosts" (actionVfdBlkbTransportcostsPackage) وعدد نقاط الاستلام (actionVfdBlkbPickupMaxResults، والافتراضي 30).

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

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

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