VibeFox Chilexpress for PrestaShop — المساعدة

المتطلبات

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

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

مفاتيح Chilexpress API (للأسعار الفورية فقط): أنشئ حسابًا في بوابة مطوّري Chilexpress (developers.wschilexpress.com) واشترك في منتجين: Rating (Cotizador) وCoverage (Coberturas / Georreferencia). لكل منتج مفتاح اشتراك خاص به. تعمل مفاتيح الاختبار في بيئة الاختبار فقط؛ وتُصدر مفاتيح الإنتاج لعملاء Chilexpress من الشركات الذين لديهم عقد عميل. تحتاج أيضًا إلى رمز county الخاص بـ Chilexpress للـ comuna التي تشحن منها، مثل STGO. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى مفاتيح API.

مناطق تشيلي (للأسعار الفورية فقط): تحتاج الأسعار الفورية إلى منطقة عنوان التسليم. لا تتضمن PrestaShop مناطق تشيلي افتراضيًا؛ ويمكن للوحدة إضافتها لك (راجع Chilean regions أدناه). يجب أن تكون الدولة Chile موجودة في المتجر.

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

التثبيت

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

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

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

4. املأ جدول Country prices. للأسعار الفورية، أدخل مفتاحي الاشتراك ورمز county الخاص بمكان الشحن، وإذا لم تكن عملة المتجر CLP فأدخل سعر الصرف إلى CLP؛ وانقر على Add Chilean regions إذا طلبت الصفحة ذلك؛ ثم اختر مصدر الأسعار (راجع الإعدادات) وانقر على Save.

عند التثبيت، تنشئ الوحدة شركة الشحن Chilexpress مع نص مدة التوصيل Chilexpress courier. تُربط شركة الشحن بمنطقة Chile وبجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم من Shipping > Carriers. لا تحدد الأسعار هناك: يأتي السعر دائمًا من الوحدة. لعرض Chilexpress في مناطق أخرى، أضفها إلى شركة الشحن في تلك الصفحة، أو فعّل Ignore shipping zones.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Chilexpress > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. كما يمسح كل حفظ الأسعار المخزنة مؤقتًا لـ Chilexpress وقوائم comuna. تحتاج التغييرات إلى إذن "configure" للوحدة؛ ومن دونه تعرض الصفحة الرسالة You do not have permission to configure this module.

تعرض الصفحة المشكلات في أعلاها: خيارات أسعار API مفعّلة لكن المفتاح أو رمز county لمكان الشحن أو سعر صرف CLP مفقود؛ جدول الأسعار لا يحتوي على صف لتشيلي أو للقيمة الافتراضية؛ المتجر لا يحتوي على مناطق تشيلية أو نموذج العنوان التشيلي لا يحتوي على حقل المنطقة؛ وحدة الوزن أو الأبعاد في المتجر غير معروفة للوحدة (فتُقرأ حينئذ كـ kg أو cm؛ اضبطها في International > Localization، ضمن Local units)؛ شركة الشحن حُذفت. يمكن كتابة الأرقام بنقطة أو فاصلة حسب لغة لوحة الإدارة لديك. يُعد الرقم غير الصالح أو السالب، وCLP exchange rate بقيمة 0، وMin weight (kg) الأكبر من Max weight (kg)، أو Name الأطول من 64 حرفًا، أخطاءً، ولا يُحفظ شيء حتى تصححها.

عام

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

Name: اسم طريقة الشحن التي يراها العميل أثناء الدفع. وهو اسم شركة الشحن. الافتراضي: Chilexpress. حقل إلزامي، حتى 64 حرفًا.

Tax: قاعدة الضريبة لشركة الشحن، أو No tax (الافتراضي لشركة شحن جديدة). تُستخدم أسعار Chilexpress API كما عُرضت تمامًا. اختر No tax إذا كان العرض يتضمن IVA بالفعل وكان المتجر سيضيف ضريبة فوقه.

الأسعار

Rate source: مصدر السعر.

الأسعار الفورية متاحة للوجهات داخل تشيلي فقط. تستخدم الدول الأخرى الأسعار الثابتة دائمًا.

Country prices: جدول لدول الوجهة يحتوي على عمود Price وأسعار اختيارية حسب حجم الطرد، بعملة المتجر الافتراضية، دون الضريبة. يُحدَّد الحجم من وزن السلة: XS حتى 1 كغ، وS حتى 2 كغ، وM حتى 3 كغ، وL حتى 5 كغ، وXL فوق 5 كغ. إذا تُرك الحجم عند 0 فإنه يستخدم Price. انقر على Add country لإضافة صف، وعلى أيقونة سلة المهملات لحذفه. يُطبَّق الصف * Default على الدول التي ليس لها صف خاص بها. الدولة التي لا يوجد لها صف (ولا * Default) لا يكون لها سعر ثابت، لذلك تُخفى شركة الشحن هناك. الصف الذي يكون سعره وأسعار أحجامه كلها 0 يعني شحنًا مجانيًا. يُعرض الجدول الفارغ بصف واحد لتشيلي بقيمة 0؛ ولا يمكن حذف الصف الأخير، بل إعادة تعيينه إلى 0 فقط؛ لذلك أدخل أسعارًا حقيقية قبل حفظ الصفحة. تُصحَّح الدولة المكررة أو السعر غير الصالح (يُتجاهل المكرر ويُضبط السعر على 0)، ويعرض تحذير قائمة بالتصحيحات.

Calculation type: Per order يفرض السعر الثابت مرة واحدة. Per item (fixed price x number of items) يضربه في عدد العناصر في السلة. يُسعَّر خيار Chilexpress API دائمًا للطرد كاملًا.

Chilexpress API (الأسعار الفورية)

يبدأ هذا القسم بروابط إلى بوابة المطورين وإلى صفحات اشتراك Rating وCoverage.

Test environment: يستخدم بيئة الاختبار الخاصة بـ Chilexpress (qaservices.wschilexpress.com). استخدمه مع مفاتيح الاختبار، وأوقفه في متجر حقيقي.

Rating API key: مفتاح الاشتراك لمنتج Rating (Cotizador).

Coverage API key: مفتاح الاشتراك لمنتج Coverage (Coberturas / Georreferencia). يُستخدم لإيجاد رمز county الخاص بـ Chilexpress للـ comuna الخاصة بالعميل (حقل City في العنوان، مع منطقته).

بعد الحفظ، يبقى حقل المفتاح فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. يُحفظ المفتاح كما أدخلته؛ ولا تُزال إلا المسافات الزائدة في طرفيه.

Remove the saved Rating API key وRemove the saved Coverage API key: تظهر فقط عند وجود مفتاح محفوظ. فعّل الخيار وانقر على Save لحذف المفتاح.

Origin county code: رمز county الخاص بـ Chilexpress (comuna) لمكان الشحن، من حرفين إلى 5 أحرف، مثل STGO (Santiago Centro) أو PROV (Providencia) أو VALP (Valparaíso). يكون فارغًا بعد التثبيت. القيمة التي ليست رمز county تُرفض بخطأ.

Service: خدمة Chilexpress المستخدمة لحساب السعر. إذا لم تكن متاحة للوجهة، تُستخدم أرخص خدمة متاحة.

CLP exchange rate: تُسعِّر Chilexpress بالبيزو التشيلي. يلزم فقط إذا لم تكن عملة المتجر الافتراضية هي CLP: سعر 1 CLP بتلك العملة، مثل 0.001. ومن دونه لا تُستخدم أسعار API. إذا كانت عملة المتجر هي CLP فاتركه فارغًا. يجب أن تكون القيمة أكبر من 0.

Chilean regions: تُبحث comuna في تشيلي حسب المنطقة، لذلك تحتاج الأسعار الفورية إلى منطقة العنوان. إذا لم تكن في المتجر مناطق تشيلية، يعرض الحقل الزر Add Chilean regions. يضيف الزر المناطق الـ 16 كولايات لتشيلي (رموز ISO مثل RM وVS…)، ويفعّل "Contains states" لتشيلي، ويضيف حقل المنطقة إلى نموذج العنوان التشيلي. لا تُضاف المناطق الموجودة مسبقًا (بالرمز أو بالاسم) مرة أخرى. عندما يكون كل شيء جاهزًا، يعرض الحقل Chilean addresses have a region مع عدد المناطق.

التوفر

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

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

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

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

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

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

Free shipping: يفعّل حد الشحن المجاني.

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

متقدم

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

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

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

كيف يعمل أثناء الدفع

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

بالنسبة لعنوان في تشيلي ومصدر أسعار API، تأخذ الوحدة منطقة العنوان وcomuna من حقل City، وتبحث عن رمز county الخاص بـ Chilexpress في قائمة comuna لتلك المنطقة (Coverage API). تُتجاهل الحروف المنقوطة والمسافات وصيغ الكتابة المختلفة، فيتطابق Ñuñoa مع Nunoa، ويتطابق Santiago مع Santiago Centro. كما يُقبل رمز county المكتوب مباشرة في حقل City. ثم ترسل الوحدة إلى Rating API رمزي county لمكان الشحن والوجهة، ووزن السلة (لا يقل عن 0.1 كغ)، وأبعاد الطرد (طول وعرض أكبر منتج، والارتفاعات مكدسة)، والمجموع الفرعي للسلة بـ CLP كقيمة معلنة. تعيد Chilexpress خدماتها؛ وتستخدم الوحدة الخدمة المختارة أو الأرخص، وتحوّل مبلغ البيزو إلى عملة المتجر الافتراضية. يُقرَّب السعر إلى الخانات العشرية لتلك العملة، ثم يُعرض بعملة سلة العميل.

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

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

تحسب الوحدة الأسعار فقط. لا تُنشئ شحنات أو أوامر نقل (OT)، ولا تطبع ملصقات، ولا تحجز مواعيد استلام، ولا تتتبع الطرود؛ احجز الشحنة في حسابك لدى Chilexpress. لا يستطيع العملاء اختيار مكتب Chilexpress، ولا يوجد محدد لـ comuna: يكتب العميل اسم comuna في حقل City القياسي. تستخدم الشحنات الدولية الأسعار الثابتة.

الطلبات

عندما يُقدَّم طلب بشركة الشحن Chilexpress، تحفظ الوحدة طريقة حساب سعره. تعرض صفحة الطلب في لوحة الإدارة كتلة Chilexpress تتضمن Chilexpress service (للسعر الفوري، الخدمة التي قدّرتها Chilexpress، مثل Express) وPrice source: Live rate (Chilexpress Rating API) أو Fixed price أو Free shipping.

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

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

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

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

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

لا تظهر Chilexpress في الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. في Shipping > Carriers، تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته (أو أن Ignore shipping zones مفعّل والدولة موجودة في Countries). تحقق من حدود الوزن وMinimum subtotal. مع الأسعار الثابتة، تحقق من أن الدولة أو * Default لها صف. قد تكون المنتجات مقيّدة أيضًا بشركات شحن معينة في صفحة المنتج.

الشحن إلى تشيلي مجاني رغم أنه يجب ألا يكون كذلك: الصف الخاص بتشيلي (أو * Default) في Country prices يحتوي على 0 في Price وفي أعمدة الأحجام. أدخل الأسعار وانقر على Save.

لا يظهر السعر الفوري، ويُستخدم السعر الثابت بدلًا منه: تحقق أولًا من التحذيرات أعلى صفحة الوحدة. إذا لم توجد تحذيرات، فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى حقل Log في صفحة الوحدة. من الأسباب الشائعة: العنوان ليس له منطقة أو حقل المنطقة مفقود (استخدم Add Chilean regions)، أو comuna لا تتعرف عليها Chilexpress (تحقق من حقل City والمنطقة)، أو مفتاح يخص منتجًا أو بيئة أخرى، أو وجهة لا تغطيها Chilexpress.

HTTP 401 أو 403 في السجل: مفتاح الاشتراك غير صحيح أو غير نشط أو يخص منتجًا أو بيئة أخرى. تعمل مفاتيح الاختبار فقط عند تفعيل Test environment.

لا تُستخدم أسعار API في متجر بعملة أخرى: أدخل CLP exchange rate.

هل أسعار API تشمل IVA أم لا؟ تُستخدم كما تعرضها Chilexpress تمامًا. إذا كان متجرك يضيف ضريبة على الشحن، وكان العرض يتضمن IVA بالفعل، فاضبط Tax على No tax.

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

تقول الصفحة "The Chilexpress carrier was not found": حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإنشائها من جديد.

تقول الصفحة "The country Chile does not exist in this shop": أضف تشيلي أو فعّلها في International > Locations > Countries، ثم استخدم Add Chilean regions.

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

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

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