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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 5.0 أو أحدث، مثبّت ومفعّل. لا يُفعَّل الملحق بدونه.

PHP: 8.0 أو أحدث.

حساب Cargoson (للأسعار الفورية فقط): تستخدم الأسعار الفورية واجهة أسعار الشحن الخاصة بـ Cargoson. تتطلب استعلامات أسعار الشحن اشتراكًا في Cargoson مع إمكانية الوصول إلى API (خطة Advanced أو أعلى وقت كتابة هذا النص). يُصدر مفتاح API في حسابك في Cargoson؛ وإذا لم تظهر إعدادات API في خطتك، فاطلب المساعدة من دعم Cargoson. تأتي الأسعار من شركات الشحن وقوائم الأسعار المتصلة بهذا الحساب. وإذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى حساب Cargoson.

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

التثبيت

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

2. انقر على Activate.

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

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

5. اختر طريقة احتساب تكلفة الشحن واملأ الأقسام المناسبة: الأسعار الثابتة، وبالنسبة إلى الأسعار الفورية، مفتاح API والرمز البريدي للاستلام (راجع الإعدادات).

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

الإعدادات

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

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

في كل مرة تحفظ فيها الإعدادات، تُمسح أسعار Cargoson المخزنة مؤقتًا. ويمكن كتابة الأرقام العشرية بنقطة أو بفاصلة.

General

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

Method title: اسم طريقة الشحن الذي يظهر في السلة وعند الدفع. الافتراضي: Cargoson. يمكن لمنطقة أن تستبدله.

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

Fixed prices (table below): يأتي السعر من جدول Price per country and size. لا يلزم حساب Cargoson.

Cargoson live prices (API): يُطلب السعر من Cargoson لكل سلة. إذا لم يُعِد Cargoson أي سعر، تُخفى الطريقة لتلك السلة.

Cargoson live prices, fixed prices if the API fails: يُطلب السعر من Cargoson. إذا لم يستجب Cargoson، أو رفض مفتاح API، أو لم تكن هناك شركة شحن لهذا المسار، يُستخدم السعر الثابت.

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

Cargoson API (مطلوبة للأسعار الفورية فقط)

API key: مفتاح API من حسابك في Cargoson. يُرسل إلى cargoson.com فقط، ولا يُعرض للعملاء ولا يُكتب في السجل أبدًا.

Carrier: الأسعار المستخدمة. يرى العميل سعرًا واحدًا.

Any carrier (cheapest price): أقل سعر يعيده Cargoson. وهذا هو الخيار الافتراضي.

DPD, Omniva, Smartpost / Posti, Venipak, UPS, FedEx, DHL, GLS: أقل سعر لشركة الشحن هذه وحدها، ويُطابَق حسب اسم شركة الشحن الذي يعيده Cargoson (وكذلك الأسماء القانونية، مثل AS Eesti Post بالنسبة إلى Omniva).

Package type code: نوع الطرد في Cargoson الذي يُرسل مع استعلام السعر. الافتراضي: CLL. تستخدم أمثلة API الخاصة بـ Cargoson الرموز EUR (منصة EUR) وFIN (منصة FIN). بالنسبة إلى الطرود، استخدم رمز الطرد الخاص بحسابك في Cargoson. يُرسل الطلب كطرد واحد بالوزن الإجمالي للسلة.

Price currency: عملة الأسعار في حسابك في Cargoson، بصيغة رمز من 3 أحرف. الافتراضي: EUR. يُعيد API المبالغ دون رمز عملة.

Currency conversion rate: مطلوب فقط إذا اختلفت عملة الأسعار عن عملة متجرك: وحدة واحدة من عملة Cargoson = X وحدة من عملة متجرك. اتركه فارغًا لرفض هذه الأسعار، حتى لا يُحمَّل العميل بعملة خاطئة أبدًا.

Ship from (collection address) (تُستخدم للأسعار الفورية)

Collection country: الدولة التي تشحن منها. الافتراضي هو دولة متجرك.

Collection postcode: الرمز البريدي الذي تشحن منه. يشترطه Cargoson. إذا كان فارغًا وكانت دولة الاستلام هي دولة متجرك، يُستخدم الرمز البريدي للمتجر من WooCommerce > Settings > General.

تاريخ الاستلام الذي يُرسل إلى Cargoson هو اليوم، أو يوم الاثنين التالي إذا كان نهاية أسبوع.

Fixed prices (تُستخدم عندما تكون Shipping cost على Fixed prices، وكبديل للأسعار الفورية)

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

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

Conditions

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

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

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

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

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

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

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

Availability without shipping zones

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

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

Advanced

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

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

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

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

في وضع الأسعار الثابتة، يُؤخذ السعر من الجدول. وفي الأوضاع الفورية، يرسل الملحق إلى Cargoson تاريخ الاستلام، ودولة الاستلام والرمز البريدي، ودولة التوصيل والرمز البريدي، وطردًا واحدًا برمز نوع الطرد والوزن الإجمالي للسلة (لا يقل عن 0.1 kg). تُحوَّل أوزان المنتجات من وحدة متجرك إلى كيلوغرامات. لا يُطلب السعر الفوري إلا بعد أن يُدخل العميل رمزًا بريديًا. يعيد Cargoson أسعار شركات الشحن لديك، ويختار الملحق الأرخص (من الشركة المحددة، إن وُجدت)، ويحوّله إلى عملة متجرك عند الحاجة.

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

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

يحسب الملحق الأسعار فقط. لا ينشئ شحنات أو حجوزات في Cargoson، ولا يطبع ملصقات، ولا يتتبع الطرود، ولا يستطيع العملاء اختيار آلة استلام طرود أو نقطة استلام. تُقدَّر السلة كطرد واحد بالوزن الإجمالي؛ ولا تُرسل أبعاد الطرد. وتُعرض أرخص سعر واحد فقط، وليس قائمة بشركات الشحن.

الطلبات

عند استخدام سعر فوري، يحفظ بند الشحن في الطلب Carrier وService وCargoson service ID المعروضة. وتظهر هذه القيم في شاشة تعديل الطلب، حتى تعرف ما الذي يجب حجزه في Cargoson. احجز الشحنة في Cargoson أو عبر تكاملاته الخاصة.

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

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

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

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

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

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

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

الأسعار الفورية لا تظهر: افتح WooCommerce > Status > Logs، بالمصدر vfd_cargoson. تُسجَّل أخطاء API دائمًا؛ فعّل Debug log لرؤية كل حساب. الأسباب الشائعة: لم يُدخَل الرمز البريدي للتوصيل بعد، أو لا يوجد رمز بريدي للاستلام، أو رُفض مفتاح API (مفتاح خاطئ أو منتهٍ، أو لا توجد إمكانية وصول إلى API في خطتك في Cargoson)، أو لا توجد شركة شحن لهذا المسار أو الوزن، أو السعر بعملة أخرى. وعند استخدام Cargoson live prices, fixed prices if the API fails، يحصل العملاء على السعر الثابت أثناء معالجتك للمشكلة.

Cargoson يرفض نوع الطرد: استخدم رمز الطرد الذي يستخدمه حسابك في Cargoson في Package type code. يظهر السبب في السجل.

يُرفض سعر بعملة أخرى: اضبط Price currency على عملة أسعار Cargoson، وأدخل Currency conversion rate.

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

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

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

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

Cargoson علامة تجارية مملوكة لصاحبها. هذا الملحق غير تابع لـ Cargoson ولا تعتمده Cargoson.