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

المتطلبات

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

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

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

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

التثبيت

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

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

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

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

عند التثبيت، تنشئ الوحدة شركة الشحن Cargoson مع نص مدة التسليم Delivery by the cheapest Cargoson carrier. تُعيَّن شركة الشحن إلى جميع المناطق وجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التسليم والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: يأتي السعر دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Cargoson > Configure. تنطبق على كل مناطق شركة الشحن. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. بعد الحفظ تظهر لك الرسالة Settings saved. Cached Cargoson prices were cleared. يمكن كتابة الأرقام العشرية بنقطة أو فاصلة. لا يُحفظ أي شيء وتعرض الصفحة خطأً إذا احتوى حقل رقمي على نص أو رقم سالب، أو كان Currency conversion rate يساوي 0، أو كان Minimum weight أكبر من Maximum weight، أو تجاوز Method title 64 حرفًا، أو لم يكن Price currency رمز عملة مكونًا من 3 أحرف، أو كان في أحد صفوف جدول الأسعار رمز دولة أو سعر غير صالح. إذا لم تتعرف الوحدة على وحدة وزن المتجر، فستظهر بعد الحفظ رسالة تحذير تفيد بأن أوزان المنتجات تُعامل بالكيلوغرام؛ اضبط الوحدة في International > Localization (Local units).

General

Enable Cargoson: يشغّل شركة الشحن أو يوقفها. وهو المفتاح نفسه الخاص بحالة شركة الشحن في Shipping > Carriers.

Method title: اسم شركة الشحن الذي يظهر في السلة وعند الدفع. الافتراضي: Cargoson. حقل إلزامي. وهو أيضًا اسم شركة الشحن في Shipping > Carriers.

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

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

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

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

Remove the saved API key: يظهر عند وجود مفتاح محفوظ. فعّله واحفظ لحذف المفتاح.

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

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

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

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

الشحن من (عنوان الاستلام) (يُستخدم للأسعار الفورية)

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

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

تاريخ الاستلام المرسل إلى Cargoson هو تاريخ اليوم بتوقيت المتجر، أو يوم الاثنين التالي في عطلة نهاية الأسبوع.

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

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

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

الشروط

Minimum weight: إخفاء شركة الشحن إذا كان وزن السلة أقل من هذه القيمة، بالكيلوغرام. 0 يعني دون حد.

Maximum weight: إخفاء شركة الشحن إذا كان وزن السلة أعلى من هذه القيمة، بالكيلوغرام. الافتراضي: 25. 0 يعني دون حد.

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

Free shipping: تفعيل الشحن المجاني عند بلوغ مبلغ الطلب المحدد أدناه.

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

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

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

عادةً تُعرض شركة الشحن في المناطق المعيّنة لها في Shipping > Carriers.

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

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

متقدم

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

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

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

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر Cargoson. تُحتسب المنتجات المادية فقط: فالمنتجات الافتراضية لا تضيف وزنًا ولا تدخل في مبلغ الطلب. تُحوَّل أوزان المنتجات من وحدة متجرك إلى الكيلوغرام. تتحقق الوحدة أولًا من الشروط: دولة التسليم، ووزن السلة، والحد الأدنى لقيمة الطلب. إذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Cargoson.

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

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

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

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

الطلبات

تعرض صفحة طلب Cargoson كتلة Cargoson shipping تحتوي على السعر المحسوب عند الدفع:

Carrier وService وCargoson service ID: شركة الشحن وخدمة Cargoson المعروضتان، وتظهران عندما استُخدم سعر فوري.

Price source: Cargoson live price أو Fixed price أو Free shipping threshold.

Calculated price (excl. tax): السعر بعملة المتجر الافتراضية.

يُحفظ عرض السعر عند تقديم الطلب ولا يتغير بعد ذلك. احجز الشحنة في Cargoson أو عبر تكاملاته الخاصة.

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

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

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

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

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

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

الأسعار الفورية لا تظهر: انظر إلى حقل Log في صفحة الوحدة. تُسجَّل أخطاء 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 تتضمن ضريبة القيمة المضافة بالفعل. اضبط Tax على No tax.

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

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

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

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

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