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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. املأ جدول الأسعار. للأسعار الفورية، أدخل مفتاحي الاشتراك ورمز origin county الخاص بمنطقة الشحن، وإذا كانت عملة المتجر غير CLP فأدخل سعر صرف CLP، ثم اختر مصدر الأسعار (انظر الإعدادات).

6. أضف VibeFox Chilexpress إلى منطقة شحن لتشيلي في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Chilexpress. وهي تنطبق على كل مناطق الشحن. عند إضافة الطريقة إلى منطقة، تحتوي نافذة المنطقة على حقل واحد فقط:

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

تعرض صفحة الإعدادات المشكلات أعلاها: أسعار API مفعّلة لكن المفتاح أو رمز origin county أو سعر صرف CLP مفقود، أو أن جدول الأسعار لا يحتوي على صف لتشيلي أو للافتراضي (* Default). في كل مرة تحفظ الإعدادات تُمسح الأسعار المخزنة مؤقتًا وقوائم comuna. يمكن كتابة الأرقام بنقطة أو فاصلة؛ والرقم غير الصالح لا يُحفظ ويظهر خطأ.

عام

Enable/Disable: يفعّل شحن Chilexpress أو يعطّله في جميع المناطق دفعة واحدة.

Name: اسم طريقة الشحن الذي يراه العميل في صفحة الدفع. Default: Chilexpress.

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

الأسعار

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

Fixed prices (Country prices below): يأتي السعر من جدول Country prices. لا تحتاج مفاتيح API.

Chilexpress API (method hidden when the API has no rate): يُطلب السعر من Chilexpress. إذا لم تُعِد Chilexpress سعرًا لعنوان في تشيلي، تُخفى الطريقة لتلك السلة.

Chilexpress API, fixed price if the API fails: يُطلب السعر من Chilexpress. إذا لم يوجد سعر، يُستخدم السعر الثابت.

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

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

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

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

Test environment: يستخدم بيئة اختبار Chilexpress (qaservices.wschilexpress.com). استخدمه مع مفاتيح الاختبار وعطّله في متجر إنتاجي.

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

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

Origin county code: رمز county الخاص بـ Chilexpress (comuna) الذي تشحن منه، من 2 إلى 5 أحرف، مثل STGO (Santiago Centro) وPROV (Providencia) وLCON (Las Condes) وVALP (Valparaíso) وCONC (Concepción). القيمة التي ليست رمز county تُرفض مع خطأ.

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

Cheapest available: أرخص خدمة تقدمها Chilexpress.

Prioritario (next business day, before 11:00)

Express (next business day): الخيار الافتراضي.

Extendido (1-2 business days)

Extremos (2-3 business days, remote areas)

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

التوفر

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

Max weight (kg): تُخفى الطريقة إذا تجاوز وزن السلة هذه القيمة. Default: 25. 0 يعني بلا حد.

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

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

Ignore shipping zones: تعرض الطريقة للدول المذكورة أدناه حتى إذا لم تُضَف إلى منطقة شحن.

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

شحن مجاني

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

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

متقدم

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

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

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

عندما يُدخل العميل عنوان التوصيل، يطلب WooCommerce من الإضافة سعرًا. تتحقق الإضافة أولًا من الشروط: وزن السلة، والحد الأدنى للمجموع الفرعي، وفئات الشحن المستبعدة. إذا انطبق الشحن المجاني، يحصل العميل على سعر مجاني ولا يُرسل أي طلب إلى Chilexpress.

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

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي السلة والدفع. وهي متوافقة مع High-Performance Order Storage (HPOS) في WooCommerce.

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

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

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

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

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

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

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

لا يظهر Chilexpress في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مُضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقق من حدود الوزن وMinimum subtotal وExcluded shipping classes. مع الأسعار الثابتة، تحقق من أن الدولة أو * Default لها صف.

لا يظهر السعر الفوري، ويُستخدم السعر الثابت بدلًا منه: تحقق أولًا من التحذيرات أعلى صفحة الإعدادات. وإلا فعّل Debug log، وأعد تحميل صفحة الدفع، وافتح WooCommerce > Status > Logs، بالمصدر vfd-chilexpress. الأسباب الشائعة: comuna لا تتعرف عليها Chilexpress (تحقق من حقل City والمنطقة)، أو مفتاح لمنتج أو بيئة خاطئة، أو وجهة لا تغطيها Chilexpress.

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

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

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

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

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

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

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

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