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

المتطلبات

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

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

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

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

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

4. أدخل أسعارك، ولأداة اختيار نقطة الاستلام، مفاتيح API الخاصة بـ bpost (انظر الإعدادات). انقر على Save.

عند التثبيت تُنشئ الوحدة شركة الشحن bpost parcel locker مع نص مدة التوصيل Pickup point or parcel locker. تُربط شركة الشحن بمنطقة بلجيكا وبجميع مجموعات العملاء، دون قاعدة ضريبة. يمكنك تغيير المناطق ومجموعات العملاء ونص مدة التوصيل والشعار في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox bpost Cubee > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. كل عملية حفظ تمسح أيضًا رمز API المخزن وقوائم نقاط الاستلام المخزنة مؤقتًا.

تعرض الصفحة تحذيرات عندما يُخفي شيء ما شركة الشحن أو الأداة دون إعلان: أداة اختيار نقطة الاستلام مفعّلة لكن مفاتيح API غير مكتملة، أو لا يوجد سعر لبلجيكا (BE) ولا سعر افتراضي، أو فشل آخر اتصال بواجهة bpost، أو أن وحدة الوزن في المتجر غير معروفة للوحدة (اضبطها في International > Localization، ضمن Local units)، أو لم يُعثر على شركة شحن bpost. عند الحفظ، تُدرج في تحذير أسطر Country prices التي تعذّرت قراءتها، وكذلك قيمة في Size prices لم يُتعرّف فيها على أي حجم. لا يُحفظ الوزن أو المبلغ الذي ليس رقمًا أو يكون سالبًا: يذكر التحذير الحقل، وتبقى القيمة السابقة كما هي. وإذا كان Min weight (kg) أكبر من Max weight (kg)، فلا تُحفظ الأوزان أيضًا.

عام

Enable/Disable: يفعّل شحن bpost parcel locker أو يعطّله. وهو المفتاح نفسه الخاص بحالة شركة الشحن في Shipping > Carriers.

Name: اسم طريقة الشحن الذي يراه العميل عند الدفع (اسم شركة الشحن). الافتراضي: bpost parcel locker. إذا تركته فارغًا، يُستخدم الافتراضي. بحد أقصى 64 حرفًا؛ الاسم الأطول يُرفض ولا يُحفظ شيء.

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

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

Account ID (public key): المفتاح العام لحساب bpost Shipping Platform الخاص بك، من Key management على plugins.bpost.be. مسح هذا الحقل يزيل أيضًا Passphrase المحفوظة.

Passphrase (private key): المفتاح الخاص المستخدم لتوقيع كل طلب (HMAC-SHA256). لا يُرسل أبدًا إلى bpost ولا يُكتب في السجل. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

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 أكثر من ذلك.

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

تُقرَّب الأسعار إلى الخانات العشرية لعملتك الافتراضية، ثم تُعرض بعملة سلة العميل.

الشروط

Min weight (kg): الحد الأدنى لوزن السلة لكي تظهر شركة الشحن. تُحوَّل أوزان المنتجات من وحدة الوزن في متجرك. يعني 0 عدم وجود حد.

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

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

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

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

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

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

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

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

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

متقدم

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

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

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

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

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

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

يجب على العميل اختيار نقطة استلام. فإذا لم يختر، يعرض Continue في خطوة التوصيل الرسالة Please select a bpost pickup point.، ويُحجز زر Place order في الصفحة مع الرسالة نفسها. لا تُقبل إلا نقطة من قائمة bpost الخاصة بالبحث. وإلا يرى العميل الرسالة The selected bpost pickup point is not in the list of your search. Please choose another one. تُحفظ عملية البحث والاختيار مع السلة، فلا يؤدي تحديث الصفحة إلى فقدانهما. يؤدي البحث الجديد إلى مسح الاختيار السابق.

لعرض نقاط الاستلام، ترسل الوحدة إلى 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 ثانية.

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

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

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

عند تقديم الطلب، تُحفظ نقطة الاستلام المختارة (الاسم والعنوان) ومعرّفها مع الطلب. في صفحة الطلب في لوحة الإدارة، تعرض كتلة bpost pickup point النقطة ومعرّفها، أو تعرض No pickup point was selected for this order. انقر على Change، وابحث عن رمز بريدي أو مدينة، واختر نقطة أخرى من القائمة، ثم انقر على Save. يُحدَّث الطلب فورًا وتعرض الصفحة Pickup point updated. يُكتب التغيير في سجل التصحيح عندما يكون Debug log مفعّلًا. لا يكون رابط Change متاحًا إلا عندما تكون مفاتيح API معبأة. يتطلب حفظ نقطة جديدة صلاحية تعديل الطلبات؛ وإلا تعرض الصفحة Permission denied. لا حاجة إلى الوصول إلى صفحات الوحدات (Modules).

إذا قسمت PrestaShop السلة الواحدة إلى عدة طلبات، تبقى نقطة الاستلام مع الطلب الأول. الطلبات الأخرى لا تملك نقطة استلام، ويعرض سجل التصحيح خطأ يذكر اسم الطلب الأول؛ عيّن النقطة لتلك الطرود يدويًا في bpost.

يرى العملاء نقطة الاستلام بالصيغة bpost pickup point: في صفحة تأكيد الطلب وفي تفاصيل الطلب في حساباتهم. وتُضاف أيضًا إلى اسم شركة الشحن في بريد تأكيد الطلب. كما يحتوي بريد الطلب الجديد الموجَّه إلى المتجر (إذا كنت تستخدم وحدة تنبيهات البريد الإلكتروني) على معرّف النقطة.

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

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

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

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

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

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

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

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

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

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

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

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

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

للمطورين: تغيّر الخطافات actionVfdBpstApiUrl وactionVfdBpstApiLanguage عنوان واجهة bpost ولغة قائمة نقاط الاستلام.

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

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

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