VibeFox Bob Go for PrestaShop — المساعدة

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

حساب Bob Go (للأسعار الفورية فقط): لا يستخدم Bob Go مفاتيح API. تحتاج إلى حساب Bob Go (bobgo.co.za)، ويجب أن يكون متجرك مثبّتًا في حسابك لدى Bob Go كقناة مبيعات WooCommerce (Sales channels)، مع تفعيل «Rates at checkout» لتلك القناة. تُعدّ الخدمات والأسعار والقواعد في Bob Go. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى حساب Bob Go.

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

التثبيت

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

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

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

4. في حسابك لدى Bob Go، ثبّت متجرك كقناة مبيعات. فعّل «Rates at checkout» لهذه القناة، واضبط الخدمات والأسعار.

5. في صفحة Configure، تحقّق من نطاق المتجر وعنوان الانطلاق (المكان الذي تشحن منه)، وإذا لم تكن عملة متجرك ZAR فتحقق من سعر التحويل إلى ZAR (انظر الإعدادات). إذا كانت العناوين الجنوب أفريقية في متجرك بلا مقاطعة، فانقر على Add South African provinces. ثم انقر على Save.

عند التثبيت، تنشئ الوحدة شركة الشحن Bob Go بنص مدة التسليم Courier delivery (South Africa). تكون شركة الشحن نشطة، ومرتبطة بجميع المناطق وجميع مجموعات العملاء، وتستخدم أسعار Bob Go الفورية افتراضيًا. يمكنك تغيير المناطق ومجموعات العملاء ومدة التسليم والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Bob Go > Configure. وهي تنطبق على جميع مناطق شركة الشحن. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. كما يمسح كل حفظ أسعار Bob Go المخزّنة مؤقتًا. تقبل الأرقام النقطة أو الفاصلة كفاصل عشري. إذا كانت قيمة خاطئة، تعرض الصفحة خطأً ولا يُحفظ شيء: قيمة ليست رقمًا ("…" must be a number.)، أو مبلغ أو وزن سالب ("…" must be a number of 0 or more.)، أو ZAR conversion rate يساوي 0 أو أقل، أو Minimum weight أكبر من Maximum weight، أو Method title يتجاوز 64 حرفًا.

فوق النموذج، تحذّر الصفحة عندما لا تعمل الأسعار الفورية: Live rates are not requested: your store currency is … — set the "ZAR conversion rate".، أو عندما تكون العناوين الجنوب أفريقية بلا مقاطعة (انظر المقاطعات الجنوب أفريقية أدناه)، أو عندما لا تُعرف وحدة الوزن أو الأبعاد في المتجر فتُعامَل كـ kg أو cm. اضبط الوحدات في International > Localization (Local units).

عام

Enable Bob Go: يُفعّل شركة الشحن أو يُعطّلها. وهو المفتاح نفسه الموجود في حالة شركة الشحن ضمن Shipping > Carriers.

Method title: اسم شركة الشحن الذي يراه العميل. تظهر خدمات Bob Go، مثل «The Courier Guy - Economy»، أسفله في صفحة الدفع بأسمائها من Bob Go. الافتراضي: Bob Go. حقل إلزامي، بحد أقصى 64 حرفًا.

Shipping cost: طريقة حساب السعر.

يُكتب سبب غياب الأسعار الفورية في السجل. ولا يُعرض للعميل أبدًا.

حساب Bob Go

يشرح هذا القسم ما تحتاجه في Bob Go، ويعرض آخر رد من Bob Go لنطاق متجرك: connected، أو the WooCommerce channel is not installed on Bob Go (HTTP 404)، أو "Rates at checkout" is not enabled for this channel (HTTP 401)، أو request failed مع رمز الخطأ، أو no connection.

Store domain: يتعرّف Bob Go على متجرك من خلال نطاقه. اتركه فارغًا لاستخدام نطاق متجرك، الذي يظهر كنص توضيحي في الحقل. أدخل نطاقًا آخر فقط إذا كانت قناتك في Bob Go مثبّتة على عنوان مختلف، مثل example.co.za/shop لمتجر في مجلد فرعي. تُحذف البادئة (scheme) والشرطة المائلة في النهاية.

ZAR conversion rate: يُسعّر Bob Go بالراند الجنوب أفريقي (ZAR). إذا لم تكن العملة الافتراضية لمتجرك ZAR، فأدخل قيمة 1 ZAR بعملتك، مثل 0.05. تُحوَّل الأسعار بهذا السعر، وتُرسل أسعار المنتجات إلى Bob Go بالراند. اتركه فارغًا إذا لا تريد استخدام أسعار Bob Go الفورية بعملتك (تبقى الأسعار الثابتة تعمل). يجب أن يكون السعر أكبر من 0. وإذا كانت عملة متجرك ZAR فاتركه فارغًا.

Delivery dates: يعرض نطاق تواريخ التسليم المقدّر من Bob Go بجانب كل خدمة في صفحة الدفع. ويُحفظ التقدير دائمًا مع الطلب، ويظهر في صفحة الطلب.

عنوان الانطلاق (عنوان المصدر)

يُرسَل عنوان الانطلاق إلى Bob Go مع كل طلب أسعار. وإذا كان عنوان المتجر في Shop Parameters > Contact > Stores في البلد نفسه، تُملأ الحقول الفارغة منه.

Origin country: البلد الذي تشحن منه. الافتراضي: جنوب أفريقيا. يشحن Bob Go داخل جنوب أفريقيا فقط.

Origin province: مقاطعة جنوب أفريقية، أو Store province (if in South Africa).

Origin city / suburb: المدينة أو الضاحية التي تشحن منها، مثل Johannesburg.

Origin postal code: الرمز البريدي الذي تشحن منه، مثل 2001.

Origin street address: عنوان الشارع الذي تشحن منه.

المقاطعات الجنوب أفريقية: لا يحتوي PrestaShop على مقاطعات لجنوب أفريقيا، لذلك لا تحتوي عناوين العملاء هناك على مقاطعة، بينما يتطلبها Bob Go. انقر على Add South African provinces لإضافة المقاطعات التسع (الرموز EC وFS وGP وKZN وLP وMP وNC وNW وWC) كولايات لجنوب أفريقيا، وإظهار حقل الولاية في العناوين الجنوب أفريقية. لا تُضاف مرة أخرى المقاطعات الموجودة بالفعل، سواء بالرمز أو بالاسم. ولا يتغير شيء حتى تنقر على الزر. وعندما تكون المقاطعات جاهزة، يعرض الحقل South African addresses have a province مع عددها.

الأسعار الثابتة (تُستخدم عندما يكون Shipping cost على Fixed prices (below)، وكخيار احتياطي عندما لا يعيد Bob Go أي سعر)

Price per country: سطر واحد لكل بلد: رمز بلد من حرفين، وعلامة يساوي، والسعر بالعملة الافتراضية لمتجرك دون الضريبة، مثل ZA=99.99. استخدم * لجميع البلدان الأخرى، مثل *=199.99 في السطر التالي. تُحذف الأسطر ذات التنسيق المختلف عند الحفظ، وتسردها الصفحة في تحذير.

Flat price: السعر للبلدان التي ليس لها سطر أعلاه. اتركه فارغًا لإخفاء شركة الشحن لتلك البلدان.

Fixed price applies: Per order يحصّل السعر مرة واحدة. أما Per item (price × quantity) فيضربه في عدد القطع في السلة. وأسعار Bob Go الفورية تنطبق دائمًا على الشحنة كلها.

الشروط

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

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

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

Free shipping: يُفعّل الشحن المجاني عند الوصول إلى مبلغ الطلب الموضح أدناه.

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

Tax: قاعدة الضريبة لشركة الشحن، أو No tax (الافتراضي). عادةً ما تتضمن أسعار Bob Go ضريبة القيمة المضافة مسبقًا. في هذه الحالة أبقِ No tax حتى لا تُفرض الضريبة مرتين.

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

Ignore shipping zones: عند التفعيل، ترتبط شركة الشحن بجميع المناطق، بما فيها المناطق المُنشأة لاحقًا، وتُعرض للبلدان المذكورة أدناه. وعند التعطيل، تُعرض فقط في مناطق شركة الشحن ضمن Shipping > Carriers، وتُعاد المناطق التي كانت لها من قبل.

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

متقدم

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

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

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

كيف يعمل الأمر في صفحة الدفع

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

في الأوضاع الفورية، ترسل الوحدة إلى Bob Go نطاق متجرك، وعنواني الانطلاق والتسليم (مع المقاطعة)، وعناصر السلة، مع أسعار المنتجات بالراند. ولا تُطلب الأسعار الفورية إلا بعد أن يُدخل العميل مدينة أو رمزًا بريديًا. وتُحوَّل الأسعار بالراند باستخدام ZAR conversion rate عندما لا تكون عملة متجرك ZAR. ويُحسب السعر بالعملة الافتراضية لمتجرك، ثم يُعرض بعملة سلة العميل.

تحت شركة الشحن Bob Go، يرى العميل Choose a delivery service: وخيارًا لكل خدمة من Bob Go، مع اسمها وسعرها، وتواريخ التسليم المقدّرة إذا كان Delivery dates مفعّلًا. تُحدَّد الخدمة الأولى افتراضيًا. وعندما يختار العميل خدمة أخرى، يُحفظ الاختيار فورًا، ويُحدَّث سعر شركة الشحن وإجمالي السلة. وتكلّف شركة الشحن بقدر تكلفة الخدمة المختارة. وإذا لم تعد الخدمة متاحة للعنوان، يرى العميل This service is not available for your address any more. Please choose another one. وإذا فشل الحفظ، تكون الرسالة The service could not be saved. Please try again. وتعمل قائمة الخدمات مع القالبين Classic وHummingbird.

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

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

تعرض الوحدة الأسعار فقط. فهي لا تنشئ شحنات أو بوالص شحن أو ملصقات، ولا تتتبع الطرود، ولا تزامن الطلبات مع Bob Go، ولا ترسل إشعارات. استخدم لوحة Bob Go لتنفيذ الطلبات. ولا توجد خاصية اختيار نقطة استلام أو خزانة. ويشحن Bob Go داخل جنوب أفريقيا فقط.

الطلبات

عند تقديم الطلب، تُحفظ خدمة Bob Go المختارة ورمزها وتقدير التسليم مع الطلب. ولا تغيّرها التعديلات اللاحقة على السلة أو على أسعار Bob Go.

في لوحة الإدارة، تعرض صفحة الطلب كتلة Bob Go تتضمن Bob Go service (الاسم والرمز) وEstimated delivery. ويرى العميل Bob Go service وEstimated delivery في صفحة تفاصيل الطلب ضمن حسابه. أما الطلبات ذات السعر الثابت أو الشحن المجاني فليس لها خدمة Bob Go.

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

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

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

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

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

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

لا تظهر أسعار Bob Go الفورية: افتح صفحة الوحدة. يعرض قسم حساب Bob Go آخر رد من Bob Go. ويعني "The WooCommerce channel is not installed on Bob Go" (HTTP 404) أن نطاق المتجر ليس قناة مبيعات في Bob Go: تحقّق من Store domain. ويعني "Rates at checkout is not enabled" (HTTP 401) أن الميزة معطّلة لهذه القناة. وتأكّد أيضًا من أن العميل أدخل مدينة أو رمزًا بريديًا، ومن أنه في المتاجر التي لا تستخدم ZAR، تم ضبط ZAR conversion rate. فعّل Debug log، وأعد تحميل صفحة الدفع، ثم انظر إلى حقل Log. ومع Bob Go live rates, fixed prices if Bob Go returns no rates، سيحصل العملاء على السعر الثابت بينما تُصلح المشكلة.

متجري لا يستخدم الراند: يُسعّر Bob Go بالراند ZAR. أدخل قيمة 1 ZAR بعملة متجرك. وبدون هذه القيمة، لا تطلب الوحدة الأسعار من Bob Go. وتبقى الأسعار الثابتة تعمل.

تحذّر الصفحة من أن العناوين الجنوب أفريقية بلا مقاطعة: انقر على Add South African provinces في قسم عنوان الانطلاق (عنوان المصدر). وتحصل عناوين العملاء الحالية على مقاطعة فقط عند تعديلها.

تُفرض الضريبة على الشحن مرتين: عادةً ما تتضمن أسعار Bob Go ضريبة القيمة المضافة. اضبط Tax على No tax.

تبدو الأسعار قديمة بعد تغيير: انقر على Save في صفحة الوحدة. هذا يمسح أسعار Bob Go المخزّنة مؤقتًا. وتُطبَّق التغييرات في حسابك لدى Bob Go بعد انتهاء التخزين المؤقت لمدة ساعة أو عند حفظ الإعدادات.

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

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

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

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