VibeFox Blue Express for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Blue Express (للتعرفات المباشرة فقط): تحتاج التعرفات المباشرة إلى حساب تجارة إلكترونية لدى Blue Express ومفتاح واجهته البرمجية (x-api-key). اطلبه من Blue Express: developers.bluex.cl أو gpo.integraciones@bx.cl. يجب أن تكون الخدمة التي تستخدمها (EX أو PY أو MD) مفعّلة في عقدك مع Blue Express. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى مفتاح واجهة برمجية.

نقاط الاستلام: تُحمَّل خريطة Blue Express في متصفح العميل من widget-pudo.blue.cl.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل مفتاح الواجهة البرمجية، والخدمة، ورمز منطقة الانطلاق (مثل SCL)، وسعر صرف CLP إذا لم تكن عملة متجرك CLP، والأسعار الثابتة (مثل CL=4500). راجع قسم الإعدادات.

6. انتقل إلى WooCommerce > Settings > Shipping > Shipping zones، وأضف VibeFox Blue Express إلى منطقة تشيلي. في إعدادات الطريقة اختر العنوان ونوع التوصيل (إلى المنزل أو استلام من نقطة Blue Express). أضفها مرتين لعرض الخيارين.

الإعدادات

توجد الإعدادات الرئيسية في WooCommerce > Settings > Shipping > VibeFox Blue Express. وتسري على جميع مناطق الشحن. تظهر أعلى الصفحة تحذيرات بشأن الإعدادات التي قد تُخفي الطريقة أو التعرفة المباشرة (غياب مفتاح الواجهة البرمجية، أو سعر صرف CLP، أو جدول الأسعار الثابتة الفارغ). وحفظ الإعدادات يمسح الذاكرة المؤقتة.

نافذة المنطقة (عند إضافة الطريقة إلى منطقة شحن)

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

Delivery type: As in the global settings (الافتراضي)، أو Home delivery، أو Pickup at a Blue Express point (PUDO). أضف الطريقة مرتين إلى منطقة لعرض التوصيل إلى المنزل والاستلام معًا.

عام

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

Name: اسم طريقة الشحن الذي يظهر في صفحة الدفع. يمكن لأي منطقة تعيين عنوانها الخاص. الافتراضي: Blue Express.

Tax status: تشمل أسعار Blue Express ضريبة IVA. اختر None إذا لا ينبغي لـ WooCommerce إضافة ضريبة فوقها، أو Taxable إذا ينبغي ذلك.

واجهة Blue Express البرمجية (مطلوبة للتعرفات المباشرة)

API key: مفتاح واجهة Blue Express البرمجية (ترويسة x-api-key). وبدونه لا تُستخدم إلا الأسعار الثابتة.

Service: خدمة Blue Express المستخدمة للتعرفة: Express (EX) (الافتراضي)، أو Prioritario (PY)، أو SameDay (MD). يجب أن تكون مفعّلة في عقدك مع Blue Express.

Origin district code: رمز منطقة Blue Express للمكان الذي تشحن منه، مثل SCL لسانتياغو (الافتراضي). إذا لم تكن متأكدًا فاسأل Blue Express.

CLP per 1 (your currency): أسعار Blue Express بالبيزو التشيلي (CLP). إذا كان متجرك يستخدم عملة أخرى، فأدخل كم يساوي وحدة واحدة منها بالـ CLP، مثل 1050. وبدونه لا تُستخدم التعرفات المباشرة. يُتجاهل هذا الحقل إذا كانت عملة متجرك CLP.

السعر

Rate source: طريقة حساب السعر.

Fixed prices: سطر واحد لكل دولة بالصيغة COUNTRY_CODE=PRICE، وبعملة متجرك، مثل CL=4500 لمتجر بالبيزو التشيلي أو CL=4.50 لمتجر باليورو. تُقبل الفاصلة أو النقطة فاصلًا عشريًا. تُعرض الأسطر غير الصالحة عند الحفظ. يمكن استخدام الأسعار الثابتة لأي دولة.

Fixed price per: Order يحتسب السعر مرة واحدة. Item (price x quantity) يضربه في عدد العناصر في السلة. ينطبق هذا على السعر الثابت فقط. تعرفة الواجهة البرمجية تكون دائمًا للشحنة كاملة.

الشروط

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

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

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

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

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

Free shipping: يُفعّل الشحن المجاني ابتداءً من مجموع فرعي للسلة.

Free from subtotal: المجموع الفرعي للسلة (بعملة المتجر) الذي يصبح عنده الشحن مجانيًا.

الاستلام من نقاط Blue Express (PUDO)

Pickup point by default: عند التفعيل، تُسلَّم طرق Blue Express إلى نقطة Blue Express يختارها العميل. وهذا هو الافتراضي لطرق المناطق التي يكون فيها Delivery type = As in the global settings. يجب على العميل اختيار نقطة لإتمام الطلب.

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

Ignore shipping zones: يعرض الطريقة حتى عند عدم إضافتها إلى منطقة الشحن المناسبة. وعندئذ تستخدم الإعدادات العامة (دون عنوان منطقة أو نوع توصيل).

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

متقدم

Debug log: يسجل الطلبات والقرارات في WooCommerce > Status > Logs، بالمصدر "vfd-blue-express". تُسجَّل أخطاء الواجهة البرمجية دائمًا. ولا تُسجَّل أبدًا مفاتيح الواجهة البرمجية أو عناوين العملاء.

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

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

عندما يُدخل العميل عنوان التوصيل، تتحقق الإضافة من وزن السلة وMinimum order subtotal وExcluded shipping classes. إذا كان الشحن المجاني ينطبق، تكون التعرفة 0 ولا يُرسل أي طلب إلى Blue Express.

للحصول على تعرفة مباشرة، يجب أن يكون العنوان في تشيلي مع منطقة ومدينة (بلدية). تطلب الإضافة أولًا من Blue Express التعرّف على البلدية، ثم تطلب السعر للخدمة ومنطقة الانطلاق والوجهة والطرود. يُرسل كل منتج بوزنه وأبعاده محوَّلين إلى كيلوغرام وسنتيمتر. تُرسل المنتجات التي لا وزن لها أو أبعاد لها كـ 0.01 kg، 10 x 10 x 10 cm. تُرسل القيمة المُعلنة بالـ CLP. ويُحوَّل سعر CLP إلى عملة متجرك.

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي Cart وCheckout. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

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

مع نوع التوصيل Pickup at a Blue Express point (PUDO)، يرى العميل Choose pickup point أسفل خيار Blue Express، في صفحة الدفع الكلاسيكية وفي صفحة الدفع القائمة على الكتل. يفتح الزر خريطة Blue Express الرسمية، حيث يختار العميل نقطة. تُعرض النقطة المختارة باسمها وعنوانها، ويتحول الزر إلى Change pickup point. ثم تُعاد حساب التعرفة باستخدام سعر الاستلام (PUDO) الخاص بـ Blue Express.

لا يمكن إتمام الطلب دون نقطة: يرى العميل Please choose a Blue Express pickup point. ويجري هذا التحقق على الخادم.

تُحفظ النقطة المختارة في الطلب مع رمز وكالة Blue Express واسمها وعنوانها. وفي شاشة الطلب في لوحة الإدارة تظهر أسفل عنوان الشحن باسم Blue Express pickup point. انقر Edit لاختيار نقطة أخرى على خريطة Blue Express أو لإدخال رمز الوكالة والاسم والعنوان يدويًا، ثم انقر Save pickup point. يُسجَّل التغيير في ملاحظة الطلب. يرى العميل النقطة في صفحة الطلب وفي رسائل البريد الإلكتروني للطلبات (HTML ونص عادي). كما تُظهر الرسائل المرسلة إلى المتجر رمز الوكالة. تحتفظ الطلبات الموجودة ببيانات نقطة الاستلام الخاصة بها.

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

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

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

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

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

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

لا تظهر Blue Express في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة عنوان العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). اقرأ التحذيرات أعلى صفحة الإعدادات. تحقّق من حدود الوزن وMinimum order subtotal وExcluded shipping classes، وأن Fixed prices يحتوي على سطر للدولة إذا كنت تستخدم الأسعار الثابتة أو البديل.

لا تظهر التعرفات المباشرة: مع Blue Express API only تُخفى الطريقة عند عدم وجود تعرفة. فعّل Debug log، وأعد تحميل صفحة الدفع، وافتح WooCommerce > Status > Logs (المصدر "vfd-blue-express"). من الأسباب الشائعة: غياب مفتاح الواجهة البرمجية، أو أن عملة المتجر ليست CLP دون سعر صرف، أو نقص المنطقة أو البلدية في العنوان، أو عدم تعرف Blue Express على البلدية، أو خطأ في الواجهة البرمجية (مثل HTTP 401 أو 403 عند رفض مفتاح الواجهة). مع Blue Express API, fixed price if the API gives no rate يحصل العملاء على السعر الثابت أثناء إصلاحك للمشكلة.

تُضاف الضريبة فوق سعر Blue Express: تشمل أسعار Blue Express ضريبة IVA. اضبط Tax status على None إذا كان ينبغي لـ WooCommerce ألا يضيف ضريبة فوقها.

لا تفتح الخريطة: تُحمَّل الخريطة من widget-pudo.blue.cl في متصفح العميل، لذا يجب أن يكون هذا العنوان متاحًا وغير محجوب في موقعك.

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

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

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

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

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