VibeFox bpost Cubee for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب bpost Shipping Platform (لأداة اختيار نقطة الاستلام فقط): يبحث الملحق عن نقاط الاستلام عبر واجهة bpost Shipping Platform API. سجّل الدخول إلى حسابك في bpost Shipping Platform على plugins.bpost.be وأنشئ المفاتيح في Settings > Key management. تحتاج إلى ثلاث قيم: Account ID (المفتاح العام)، وPassphrase (المفتاح الخاص)، وApp ID (X-APPID). يصدر bpost معرّف App ID لتكاملك؛ اطلبه من دعم التجارة الإلكترونية في bpost (eol@bpost.be). كما تحتاج إلى معرّف الناقل في عقدك (68 = bpost). بدون مفاتيح كاملة تستمر الطريقة في العمل كطريقة شحن بسعر ثابت، لكن لا يُطلب من العميل اختيار نقطة استلام.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل أسعارك، ولأداة اختيار نقطة الاستلام، أدخل مفاتيح bpost API (راجع «الإعدادات»).

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

الإعدادات

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

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

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

عام

Enable/Disable: يفعّل أو يعطّل شحن خزائن الطرود التابعة لـ bpost في جميع المناطق دفعة واحدة.

Name: اسم طريقة الشحن الذي يراه العميل في صفحة الدفع. الافتراضي: bpost parcel locker.

Tax status: Taxable يضيف ضريبة WooCommerce إلى أسعارك، وNone يعني أن الأسعار نهائية.

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

Account ID (public key): المفتاح العام لحساب bpost Shipping Platform الخاص بك، من Key management على plugins.bpost.be.

Passphrase (private key): المفتاح الخاص الذي يُوقّع كل طلب (HMAC-SHA256). لا يُرسل إلى bpost أبدًا، ولا يُكتب في السجل.

App ID (X-APPID): معرّف التطبيق الذي أصدره bpost لتكاملك. يُرسل في الترويسة X-APPID.

Carrier ID: الناقل في عقد bpost Shipping Platform الخاص بك، والذي تُدرج نقاط الاستلام وخزائن الطرود الخاصة به. الافتراضي: 68 (bpost). للنواقل الأخرى المفعّلة في عقدك معرّفات خاصة بها.

أداة اختيار نقطة الاستلام

Pickup points: يعرض أداة اختيار نقاط الاستلام وخزائن الطرود في صفحة الدفع. مفعّل افتراضيًا. تظهر الأداة فقط عندما تكون مفاتيح API الثلاثة مملوءة.

Search field width: عرض حقل الرمز البريدي / المدينة بصيغة CSS، مثل 100% أو 300px. الافتراضي: 100%.

Pickup point list width: عرض قائمة نقاط الاستلام بصيغة CSS، مثل 100% أو 400px. الافتراضي: 100%.

الأسعار (بعملة متجرك؛ لا يُرجع bpost أسعار الشحن عبر هذه الواجهة)

Price by: كيفية اختيار السعر.

Country prices: سطر واحد لكل دولة بصيغة CC=PRICE، مثل BE=4.95. يحدد السطر *=PRICE السعر لجميع الدول الأخرى، مثل *=9.95. تُقبل النقطة والفاصلة كفاصل عشري. تُتجاهل الأسطر غير الصالحة وتُدرج في رسالة خطأ عند الحفظ. لا تُعرض الطريقة على الدول التي لا سعر لها (عند غياب سطر *).

Size prices: يُستخدم عندما تكون Price by حسب حجم الطرد، بصيغة S=3.50, M=4.50, L=6.00, XL=8.00. يُحدَّد الحجم وفق وزن السلة: S حتى 2 كجم، M حتى 5 كجم، L حتى 10 كجم، XL أكثر من 10 كجم.

Calculation: Per order يحصّل السعر مرة واحدة. Per item (price x number of items) يضربه في عدد العناصر في السلة.

الشروط

Min weight (kg): الحد الأدنى لوزن السلة لظهور الطريقة. 0 يعني بلا حد.

Max weight (kg): تُخفى الطريقة عند وزن سلة أعلى من هذا الحد. الافتراضي: 30، لأن خزائن الطرود التابعة لـ bpost تقبل طرودًا حتى 30 كجم. 0 يعني بلا حد.

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

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

تُحوَّل أوزان المنتجات من وحدة الوزن في متجرك إلى كيلوغرامات.

الشحن المجاني

Free shipping: يفعّل التوصيل المجاني من المبلغ أدناه.

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

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

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

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

متقدم

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

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

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

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

عندما يختار العميل سعر bpost، تظهر أسفله خانة بحث، وزر Search، وقائمة بنقاط الاستلام. إذا كانت خانة البحث فارغة، يُبحث تلقائيًا عن الرمز البريدي لعنوان الدفع. يمكن للعميل إدخال رمز بريدي آخر أو اسم مدينة. يُعرض كل نقطة باسمها وعنوانها. تُدرج حتى 50 نقطة. تُطلب قائمة نقاط الاستلام باللغة الهولندية في المواقع الهولندية، وبالفرنسية في غيرها.

يجب على العميل اختيار نقطة استلام. دون اختيار، تعرض صفحة الدفع الكلاسيكية الرسالة Please select a bpost pickup point.، ويرفض الدفع بالكتل تقديم الطلب بالرسالة نفسها. يُحفظ الاختيار طوال جلسة الدفع، لذلك لا يُفقد عند تحديث الصفحة.

لعرض نقاط الاستلام، يرسل الملحق إلى bpost الرمز البريدي أو المدينة التي بُحث عنها، والدولة، ومعرّف الناقل فقط، موقّعةً بمفاتيحك. لا يُرسل اسم العميل ولا بريده الإلكتروني ولا سطور عنوانه. يُطلب رمز API ويُجدَّد تلقائيًا. إذا رفض bpost رمزًا، يُطلب رمز جديد مرة واحدة ويُعاد البحث. تُخزَّن نتائج البحث مؤقتًا لمدة 6 ساعات. إذا لم يستجب bpost، يرى العميل الرسالة Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.، ويعيد الملحق المحاولة بعد 5 دقائق. مهلة API هي 15 ثانية.

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

لا يستخدم الملحق إلا الأسعار الثابتة. لا يحصل على أسعار فورية من bpost، ولا ينشئ شحنات، ولا يطبع ملصقات، ولا يتتبع الطرود. تُعرض نقاط الاستلام في قائمة، لا على خريطة. أنشئ الشحنات في حساب bpost Shipping Platform أو Shipping Manager الخاص بك؛ ومعرّف نقطة الاستلام موجود في الطلب.

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

تُحفظ نقطة الاستلام المختارة (الاسم والعنوان) ومعرّفها في الطلب. تظهر في شاشة الطلب في لوحة الإدارة أسفل عنوان الشحن باسم bpost pickup point. انقر Change، وابحث عن رمز بريدي أو مدينة، واختر نقطة أخرى من القائمة. يُحدَّث الطلب فورًا وتُضاف ملاحظة الطلب bpost pickup point changed to: …. رابط Change متاح فقط عندما تكون مفاتيح API مملوءة.

يرى العملاء نقطة الاستلام في صفحة الشكر وفي My account > Orders. وتُضاف أيضًا إلى رسائل البريد الإلكتروني للطلبات، بصيغتي HTML والنص العادي.

لتقديم خزانة الطرود والتوصيل إلى المنزل معًا، أضف طريقة شحن أخرى، مثل Flat rate، إلى المنطقة نفسها. تظهر أداة اختيار نقطة الاستلام أسفل سعر bpost فقط.

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

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

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

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

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

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

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

لا توجد أداة اختيار نقطة استلام في صفحة الدفع: تحقق من أن Pickup points مفعّل، وأن Account ID (public key) وPassphrase (private key) وApp ID (X-APPID) مملوءة جميعها. تعرض صفحة الإعدادات تحذيرًا عندما تكون المفاتيح غير مكتملة.

يرى العملاء الرسالة "Pickup points cannot be loaded right now": لم يستجب bpost أو رفض المفاتيح. السبب موجود في WooCommerce > Status > Logs (المصدر vfd-bpost-cubee) وفي صفحة الإعدادات. يعيد الملحق المحاولة تلقائيًا بعد 5 دقائق. حفظ الإعدادات يعيد المحاولة فورًا.

لم يُعثر على نقاط استلام لهذا الرمز البريدي أو المدينة: لم يُرجع bpost أي نقاط لهذا البحث. اطلب من العميل تجربة رمز بريدي قريب أو اسم مدينة، وتحقق من Carrier ID.

لا تُستخدم الأسعار التي تحتوي على فاصلة: تُقبل 5,50 و5.50 كليهما. تُتجاهل الأسطر في Country prices التي لا تتبع الصيغة CC=PRICE؛ ورسالة الخطأ بعد الحفظ تدرجها.

هل تشمل الأسعار الضريبة؟ عند ضبط Tax status على Taxable، يضيف WooCommerce الضريبة إلى أسعارك. عند ضبطه على None، تكون الأسعار نهائية.

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

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

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

bpost علامة تجارية تخص مالكها. هذا الملحق غير تابع لـ bpost ولا تعتمده bpost.