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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

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

الإعداد

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

Title: اسم هذا السعر عند الدفع في هذه المنطقة. اتركه فارغاً لاستخدام Method name العام.

تخبرك التحذيرات أعلى الإعدادات متى أُدخلت بيانات اعتماد API واحدة فقط، ومتى لا توجد بيانات اعتماد، ومتى لا توجد أسعار للدول ولا تكلفة احتياطية، ومتى فشل آخر طلب إلى Budbee API (مع التاريخ والوقت والسبب). في كل مرة تحفظ فيها الإعدادات، تُمسح قوائم الصناديق المخزنة مؤقتاً وآخر خطأ في API.

عام

Enable/Disable: يفعّل الطريقة أو يعطّلها في كل مكان، بما في ذلك مناطق الشحن. الافتراضي: مفعّل.

Method name: اسم طريقة الشحن الذي يظهر في سلة التسوق وعند الدفع. يمكن لمنطقة أن تستبدله بـ Title خاص بها. الافتراضي: Instabee parcel box.

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها.

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

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

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

API secret: سر Budbee API الخاص بك (كلمة مرور HTTP Basic).

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

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

جميع الأسعار بعملة المتجر. يُقبل الفاصل العشري والنقطة العشرية (49,90 = 49.90). لا يُحفظ أي قيمة ليست رقماً، وتذكر رسالة الخطأ اسم الحقل.

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

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

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

الشروط

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

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

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

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

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

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

عادةً تضيف VibeFox Instabee إلى منطقة شحن. وبدلاً من ذلك يمكنك تفعيلها هنا لقائمة من الدول.

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

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

متقدم

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

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

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

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

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

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

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

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

يعمل المحدد في الدفع الكلاسيكي وفي كتلتي السلة والدفع. الإضافة متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

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

يُحفظ صندوق الطرود المختار في الطلب ويظهر في هذه الأماكن:

شاشة الطلب في الإدارة: أسفل عنوان الشحن، باسم Instabee parcel box مع اسم الصندوق وعنوانه وBox ID. إذا تعذّر التحقق من الصندوق عند الدفع، يُعلَّم بأنه not verified (Budbee API was unavailable at checkout). إذا لم يُختر أي صندوق لأن API كان غير متاح، تُوضح الشاشة ذلك وتذكّرك باختيار الصندوق عند حجز الشحنة.

صفحة شكراً لك وصفحة الطلب في حسابي: اسم الصندوق وعنوانه.

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

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

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

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

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

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

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

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

لا يرى العملاء قائمة صناديق الطرود: تظهر القائمة فقط عندما تُملأ API key وAPI secret، وتكون الدولة من السويد أو فنلندا أو الدنمارك أو هولندا أو بلجيكا، ويُدخل الرمز البريدي. يظهر آخر خطأ في API أعلى الإعدادات. التفاصيل في WooCommerce > Status > Logs (المصدر vfd-instabee). فعّل Debug log لمزيد من التفاصيل.

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

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

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

دول أخرى للبحث عن الصناديق: يمكن للمطورين تغيير قائمة الدول باستخدام المرشح vfd_ibee_box_countries.

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

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

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

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