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

المتطلبات

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

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

حساب 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. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

4. أدخل مفتاح الواجهة البرمجية، والخدمة، ورمز منطقة المنشأ (مثل SCL)، وسعر الصرف إلى CLP إذا لم تكن عملة متجرك CLP، والأسعار الثابتة (مثل CL=4500). فعِّل Pickup point carrier إذا أردت تقديم الاستلام من نقاط Blue Express. انقر على Save. راجع الإعدادات.

عند التثبيت، تُنشئ الوحدة شركتي شحن: Blue Express (التوصيل إلى المنزل، ونص مدة التوصيل Home delivery، مفعّلة) وBlue Express pickup point (نص مدة التوصيل Pickup at a Blue Express point، معطّلة حتى تفعّلها). تُسند الشركتان إلى منطقة تشيلي وإلى جميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود المقاس في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Blue Express > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. كل حفظ يمسح أيضًا التعرفات المخزنة مؤقتًا لـ Blue Express وبيانات البلديات. تظهر في أعلى الصفحة تحذيرات بشأن الإعدادات التي قد تخفي شركات الشحن أو التعرفة المباشرة: لا يوجد مفتاح واجهة برمجية، أو عملة المتجر ليست CLP دون سعر صرف، أو جدول الأسعار الثابتة فارغ، أو لا توجد مناطق لتشيلي، أو وحدة وزن أو أبعاد للمتجر لا تتعرف عليها الوحدة (فتُقرأ الأوزان عندها بالكيلوغرام والأبعاد بالسنتيمتر)، أو شركة شحن محذوفة. تُرفض القيم غير الصالحة برسالة خطأ ولا يُحفظ شيء: اسم شركة شحن فارغ أو غير صالح، أو اسم يزيد عن 64 حرفًا، أو رقم سالب أو غير صالح، أو أن تكون Min weight (kg) أكبر من Max weight (kg). تنطبق الشروط والأسعار الواردة أدناه على شركتي الشحن معًا.

عام

Enable/Disable: يفعّل أو يعطّل شركة شحن التوصيل إلى المنزل. وهو المفتاح نفسه الذي يمثل حالة شركة الشحن في Shipping > Carriers.

Name: اسم شركة الشحن الذي يظهر في الدفع لخدمة التوصيل إلى المنزل. الافتراضي: Blue Express. حقل إلزامي، بحد أقصى 64 حرفًا.

Tax status: None (no tax on shipping)، أو Taxable مع إحدى قواعد الضريبة لديك. تتضمن أسعار Blue Express ضريبة IVA. اختر None إذا كان PrestaShop لا ينبغي أن يضيف ضريبة فوق السعر. ينطبق على شركتي الشحن معًا.

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

Pickup point carrier: يعرض التوصيل إلى نقطة Blue Express يختارها العميل، كشركة شحن ثانية إلى جانب التوصيل إلى المنزل. معطّل افتراضيًا. وهو المفتاح نفسه الذي يمثل حالة شركة الشحن Blue Express pickup point في Shipping > Carriers.

Pickup point name: اسم شركة الشحن الذي يظهر في الدفع للاستلام من نقطة Blue Express. الافتراضي: Blue Express pickup point. حقل إلزامي، بحد أقصى 64 حرفًا.

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

API key: مفتاح واجهة Blue Express البرمجية (ترويسة x-api-key). بدونه تُستخدم الأسعار الثابتة فقط. بعد الحفظ يبقى الحقل فارغًا ويعرض A key is saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره. ضع علامة على Remove the saved API key ثم احفظ لحذفه.

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

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

CLP per 1 unit of store currency: عندما تكون العملة الافتراضية لمتجرك غير CLP، يعرض التسمية ذلك، مثل CLP per 1 EUR. أسعار Blue Express بالبيزو التشيلي (CLP). أدخل كم وحدة CLP تساوي وحدة واحدة من العملة الافتراضية لمتجرك، مثل 1050. بدون هذه القيمة لا تُستخدم التعرفات المباشرة. يُتجاهل الحقل عندما تكون عملة المتجر CLP.

السعر

Rate source: طريقة حساب السعر. تحتاج التعرفة المباشرة إلى عنوان تشيلي يتضمن المنطقة والبلدية (المدينة). تُكتب الأخطاء في السجل ولا تُعرض للعميل أبدًا.

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

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

الشروط

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

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

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

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

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

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

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

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

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

خيارات متقدمة

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

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

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

المناطق التشيلية (تظهر فقط عندما لا تحتوي شركتك على مناطق تشيلية صالحة للاستخدام)

تحتاج Blue Express إلى منطقة العنوان التشيلي (RM وVS وغيرهما) للتعرفة المباشرة. لا يتضمن PrestaShop المناطق التشيلية افتراضيًا. انقر على Add Chilean regions لإضافة المناطق التشيلية الست عشرة بوصفها ولايات لتشيلي، بالرموز التي تستخدمها Blue Express، ولإظهار حقل المنطقة في نموذج العنوان التشيلي. لا تُضاف المناطق الموجودة لديك مرتين، سواء بالرمز أو بالاسم. لا يتغير شيء حتى تنقر على الزر. يمكنك أيضًا إضافتها بنفسك في International > Locations > States بالرموز RM وVS وغيرها.

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر كل شركة شحن من Blue Express. تُحتسب المنتجات المادية فقط: المنتجات الافتراضية لا تضيف وزنًا ولا تدخل في المجموع الفرعي. تتحقق الوحدة من Countries (مع Ignore shipping zones) ووزن السلة وMinimum order subtotal. إذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Blue Express.

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

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

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

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

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

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

لا يستطيع العميل المتابعة دون نقطة: Please choose a Blue Express pickup point. يتحقق المتجر من ذلك عندما ينقر العميل على Continue في خطوة التوصيل. يُرفض رمز النقطة غير الصالح بالرسالة The selected Blue Express pickup point is not valid. Please choose it again on the map.، ويبقى الاختيار السابق كما هو.

عند تقديم الطلب، تُحفظ النقطة في الطلب مع رمز الوكالة لدى Blue Express واسمها وعنوانها. تظهر في صفحة الطلب في لوحة الإدارة ضمن كتلة Blue Express pickup point. انقر على Edit لاختيار نقطة أخرى باستخدام Choose on the Blue Express map، أو لإدخال Agency code وName وAddress يدويًا، ثم انقر على Save pickup point. يُسجَّل التغيير بوصفه رسالة خاصة بالطلب. يتطلب تغيير النقطة صلاحيات تحرير الطلبات فقط، لا الوصول إلى صفحات Modules. يرى العميل النقطة في صفحة تأكيد الطلب وفي صفحة تفاصيل الطلب وفي بريد تأكيد الطلب، بجوار اسم شركة الشحن. يعرض بريد الطلب الجديد إلى المتجر (من وحدة Mail alerts) رمز الوكالة أيضًا. تحتفظ الطلبات الحالية ببيانات نقطة الاستلام الخاصة بها.

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

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

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

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

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

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

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

عناوين تشيلي بلا منطقة: تعرض الصفحة تحذيرًا عن المناطق المفقودة. انقر على Add Chilean regions في صفحة الوحدة. يحتاج العملاء الذين حُفظت عناوينهم دون منطقة إلى تعديل العنوان واختيار المنطقة.

تُضاف ضريبة فوق تعرفة Blue Express: تتضمن أسعار Blue Express ضريبة IVA. اضبط Tax status على None (no tax on shipping).

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

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

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

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

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

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