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

المتطلبات

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

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

بيانات اعتماد Budbee API (لاختيار صندوق الطرود فقط): مفتاح API وسر API. تمنحها Instabee للتجار الذين لديهم اتفاقية توصيل. اسأل جهة الاتصال لديك في Instabee أو استخدم بوابة التاجر في Instabee. توثيق الواجهة البرمجية موجود على developer.budbee.com. من دون بيانات الاعتماد تعمل شركة الشحن بالأسعار الثابتة، لكن العملاء لا يستطيعون اختيار صندوق طرود.

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

التثبيت

1. في لوحة الإدارة انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

4. املأ قسم Prices وأدخل، لمحدد صندوق الطرود، API key وAPI secret الخاصين بـ Budbee (راجع الإعدادات). انقر على Save.

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

الإعدادات

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

تخبرك التحذيرات أعلى الإعدادات عندما يُدخَل أحد بيانات اعتماد API فقط، أو عندما لا توجد بيانات اعتماد، أو عندما لا توجد أسعار للدول ولا تكلفة احتياطية، أو عندما فشل آخر طلب إلى Budbee API (مع التاريخ والوقت والسبب)، أو عندما لا تُعثر على شركة الشحن Instabee، أو عندما لا تُعرف وحدة الوزن في المتجر (اضبط kg أو g أو lb أو oz في International > Localization، ضمن Local units). في كل مرة تحفظ فيها الإعدادات تُمسح قوائم الصناديق المخزنة مؤقتاً وآخر خطأ في API. إذا كان اسم الطريقة أو حالة الضريبة غير صالح، أو كان Min weight (kg) أكبر من Max weight (kg)، فلا يُحفظ شيء ويظهر خطأ.

General

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

Method name: اسم شركة الشحن الذي يراه العميل عند الدفع. الافتراضي: Instabee parcel box. حقل إلزامي، بحد أقصى 64 حرفاً.

Tax status: None يعني أن الأسعار أدناه نهائية. Taxable مع قاعدة ضريبية يعني أن PrestaShop يضيف ضريبة الشحن لتلك القاعدة فوق الأسعار أدناه.

محدد صندوق الطرود (Budbee API)

مع بيانات اعتماد API يختار العميل صندوق طرود قريباً من رمزه البريدي عند الدفع، ويُحفظ الصندوق مع الطلب. الحقلان مطلوبان. يبقى المحدد مغلقاً حتى يُملأ الحقلان معاً.

API key: مفتاح Budbee API الخاص بك (اسم المستخدم في HTTP Basic).

API secret: سر Budbee API الخاص بك (كلمة المرور في HTTP Basic). لا يُكتب في السجل أبداً.

بعد الحفظ يبقى الحقلان فارغين ويعرضان Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. لحذف بيانات الاعتماد المحفوظة، ضع علامة على Remove the saved API key and secret ثم احفظ. إذا لم يكن هناك شيء محفوظ تعرض الصفحة No credentials saved.

Test environment: يستخدم واجهة staging البرمجية الخاصة بـ Budbee (api.staging.budbee.com). فعّله فقط مع بيانات اعتماد staging من Instabee. تتركه المتاجر الفعلية متوقفاً (api.budbee.com). الافتراضي: متوقف.

الأسعار (يعرض عنوان القسم عملة المتجر الافتراضية)

جميع الأسعار بعملة المتجر الافتراضية، دون الضريبة. يُقبل كلٌّ من الفاصلة العشرية والنقطة العشرية (49,90 = 49.90). يُعرض السعر للعميل بعملة السلة.

Calculation type: طريقة تطبيق السعر.

Country prices: جدول بالأعمدة Country وPrice وXS ≤1 kg وS ≤2 kg وM ≤3 kg وL ≤5 kg وXL >5 kg. انقر على Add country لإضافة صف، وعلى أيقونة سلة المهملات لحذف صف. اختر * Any other country لصف يُطبَّق على جميع الدول التي ليس لها صف خاص. الشريحة الفارغة أو 0 تستخدم عمود Price. السعر Price الذي يساوي 0 يعني توصيلاً مجانياً. إذا لم يكن لصف الدولة سعر لوزن السلة، يُستخدم صف *، ثم Fallback cost. السعر الذي ليس رقماً يُمسح، ويذكره تحذير. تُحوَّل الأوزان من وحدة وزن المتجر إلى كغ.

Fallback cost: يُستخدم عندما لا يعطي صف الدولة المقصودة ولا صف * سعراً. اتركه فارغاً لإخفاء شركة الشحن في تلك الدول.

الشروط

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

Max weight (kg): يخفي شركة الشحن عند وزن سلة أعلى من هذا الحد. تتسع صناديق الطرود لنحو 20 كغ. الافتراضي: 20. 0 تعني بلا حد. لا يمكن أن يكون أقل من Min weight (kg).

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

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

إذا لم تكن قيمة في هذه الحقول أو في Fallback cost رقماً، فلا تُحفظ، وتبقى القيمة السابقة، ويذكر التحذير اسم الحقل.

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

عادةً تُعرض شركة الشحن في مناطق الشحن المرتبطة بها في Shipping > Carriers. وبديلاً عن ذلك يمكنك تفعيلها هنا لقائمة من الدول.

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

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

متقدم

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

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

Remove data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات وشركة الشحن. عند الإيقاف، لا يؤدي إلا إلى إيقاف شركة الشحن. تُحفظ الصناديق المختارة في الطلبات دائماً.

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

في خطوة الشحن تطلب PrestaShop من الوحدة سعر Instabee. تُحتسب المنتجات المادية فقط: المنتجات الافتراضية لا تضيف وزناً ولا تدخل في مبلغ الطلب. تتحقق الوحدة من الشروط: وزن السلة والحد الأدنى لمبلغ الطلب، ومع Ignore shipping zones الدول المسموح بها. إذا بلغ المجموع الفرعي للسلة Free shipping from فالسعر 0. وإلا يُؤخذ السعر من صف Country prices الخاص بالدولة المقصودة، أو من صف *، أو من Fallback cost. إذا لم يوجد سعر تُخفى شركة الشحن.

عندما يختار العميل شركة شحن Instabee وتكون بيانات اعتماد API مُدخلة، يظهر كتلة Parcel box أسفل شركة الشحن للسويد وفنلندا والدنمارك وهولندا وبلجيكا. تعرض الكتلة الصناديق القريبة من الرمز البريدي لعنوان التوصيل، مرتبة حسب المسافة، مع الاسم والعنوان والمسافة. يمكن للعميل كتابة رمز بريدي آخر والنقر على Search (أو الضغط على Enter). إلى أن يُدخل رمز بريدي تطلبه الكتلة. إذا لم يُعثر على أي صندوق، يُطلب من العميل تجربة رمز بريدي آخر أو اختيار طريقة شحن أخرى. أما للدول الأخرى فتُعرض شركة الشحن دون صندوق.

صندوق الطرود إلزامي. لا يُحفظ الصندوق المختار في السلة إلا إذا كان موجوداً في قائمة Budbee لذلك الرمز البريدي. عندما ينقر العميل على Continue في خطوة التوصيل، تتحقق الوحدة من الصندوق مرة أخرى على الخادم. وإلا يرى العميل Please choose an Instabee parcel box. يُؤخذ اسم الصندوق من قائمة Budbee، لا من المتصفح. إذا غيّر العميل دولة التوصيل أو الرمز البريدي للعنوان، يُلغى الاختيار السابق.

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

إذا تعذّر الوصول إلى Budbee API، يرى العميل Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. ويُوضع على الطلب علامة، وتختار أنت الصندوق عند حجز الشحنة. يُحتفظ بالصندوق المختار سابقاً الذي لا يمكن التحقق منه في تلك اللحظة، ويُعلَّم بأنه غير متحقق منه.

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

لا تحسب الوحدة الأسعار الحية، ولا تحجز الشحنات، ولا تطبع الملصقات، ولا توفر أرقام التتبع أو رسائل التتبع البريدية، ولا تعرض فترات توصيل Budbee Home، ولا تعرض خريطة. احجز الطرد للصندوق المختار في أدوات التاجر الخاصة بك في Instabee / Budbee.

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

عند إنشاء الطلب يُتحقق من الصندوق مرة أخرى ويُحفظ مع الطلب. ومن تلك اللحظة لا تستطيع واجهة المتجر تغييره. يظهر الصندوق في هذه الأماكن:

صفحة الطلب في لوحة الإدارة: كتلة Instabee parcel box تتضمن اسم الصندوق وعنوانه وBox ID. إذا تعذّر التحقق من الصندوق عند الدفع، يُعلَّم بأنه not verified (Budbee API was unavailable at checkout). إذا لم يُختر صندوق لأن API لم يكن متاحاً، تقول الكتلة Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment.

صفحة تأكيد الطلب وتفاصيل الطلب في حساب العميل: Instabee parcel box: مع اسم الصندوق وعنوانه.

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

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

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

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

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

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

لا تظهر Instabee عند الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. في Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته، أو أن Ignore shipping zones مفعّل والدولة مسموح بها. تحقق من أن للدولة سعراً، أو أن هناك صف * أو Fallback cost. تحقق من حدود الوزن وMinimum order amount. يخبرك تحذير أعلى الإعدادات متى لا يكون هناك سعر مُعدّ. وقد تكون المنتجات مقيدة بشركات شحن معينة في صفحة المنتج. فعّل Debug log لرؤية السبب في حقل Log.

لا يرى العملاء قائمة صناديق الطرود: تظهر القائمة فقط عندما يُملأ كل من API key وAPI secret، وللدول السويد وفنلندا والدنمارك وهولندا وبلجيكا، وبعد إدخال رمز بريدي. يظهر آخر خطأ في API أعلى الإعدادات. التفاصيل موجودة في حقل Log في صفحة الوحدة. فعّل Debug log لمزيد من التفاصيل.

HTTP 401 أو 403 في السجل: رفضت Budbee مفتاح API أو السر. تحقق منهما، وتأكد من أن Test environment يطابق بيانات الاعتماد لديك (بيانات staging فقط عندما يكون وضع الاختبار مفعّلاً).

لا توجد صناديق لرمز بريدي: لا تخدم Budbee هذا الرمز البريدي. يمكن للعميل البحث عن رمز بريدي آخر أو اختيار طريقة شحن أخرى.

لا يستطيع العميل المتابعة من خطوة التوصيل: يجب اختيار صندوق طرود من القائمة، إلا إذا تعذّر الوصول إلى Budbee API. لا يُحفظ الصندوق الذي لا يوجد في قائمة الرمز البريدي المبحوث عنه، ويرى العميل This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

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

تقول الصفحة إن شركة الشحن Instabee لم تُعثر عليها: حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإنشائها من جديد. وينطبق الأمر نفسه على الرسالة The settings were saved, but the carrier could not be updated. تحافظ إعادة الضبط على حالة شركة الشحن: شركة الشحن التي أوقفتها تبقى متوقفة.

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

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

Instabee وBudbee علامتان تجاريتان لمالكيهما. لا تنتمي هذه الوحدة إلى Instabee أو Budbee ولا تحظى بتأييدهما.