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

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعده (تم الاختبار على 4.1.0.3).

PHP: 8.0 أو أحدث.

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم لكلا إصداري OpenCart. فك ضغطه على جهاز الكمبيوتر. ويحتوي على README.txt، وحزمة OpenCart 3 vfd_cargoson-oc3-(الإصدار).ocmod.zip، وحزمة OpenCart 4 vfd_cargoson.ocmod.zip. ثبّت فقط الحزمة الخاصة بإصدار OpenCart لديك. مفتاح الترخيص هو نفسه للإصدارين.

OpenCart 3

1. في الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، واختر الملف vfd_cargoson-oc3-(الإصدار).ocmod.zip. لا يضيف الملحق أي تعديلات OCMOD، لذلك لا تحتاج إلى تحديث Extensions > Modifications. وبدلًا من Installer يمكنك نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذري لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر نوع الملحقات Shipping. ابحث عن VibeFox Cargoson وانقر على Install (زر + الأخضر).

3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات.

4. أدخل مفتاح ترخيص VibeFox في حقل License key ضمن كتلة الترخيص في أعلى صفحة Edit، وانقر على Activate (انظر مفتاح الترخيص).

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

OpenCart 4

1. في الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، واختر الملف vfd_cargoson.ocmod.zip. لا تغيّر اسم الملف: يأخذ OpenCart 4 رمز الملحق من اسم الملف، ولا تعمل الحزمة إذا أُعيدت تسميتها.

2. تظهر الحزمة في قائمة الملحقات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions، واختر نوع الملحقات Shipping. ابحث عن VibeFox Cargoson، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوتين 4 و5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

بعد التثبيت تبقى الطريقة معطلة حتى تفعّل Enable Cargoson وتحفظ. وإذا أعدت تثبيت الملحق بعد إلغاء تثبيته، فستُستخدم إعدادات Cargoson التي احتفظت بها مرة أخرى.

الإعدادات

توجد جميع الإعدادات في صفحة الملحق: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. الأقسام مدرجة على اليسار. يحفظ زر Save الواحد في أسفل الصفحة الصفحة كاملة دون إعادة تحميلها. وبعد الحفظ ترى Settings saved. Cached Cargoson prices were cleared. ويمكن إدخال الأرقام العشرية بنقطة أو بفاصلة. ولا يُحفظ شيء وتعرض الصفحة الأخطاء إذا كان Method title فارغًا أو أطول من 64 حرفًا، أو كان حقل رقمي يحتوي على نص أو رقم سالب، أو كان Currency conversion rate يساوي 0، أو كان Minimum weight (kg) أكبر من Maximum weight (kg)، أو كان Price currency ليس رمزًا من 3 أحرف، أو كان صف في جدول الأسعار يحتوي على بلد أو سعر غير صالحين، أو كان Sort order ليس عددًا صحيحًا. وإذا لم يتعرف الملحق على وحدة وزن المتجر، فإن تحذيرًا بعد الحفظ يوضح أن أوزان المنتجات تُعامَل بالكيلوغرام؛ أضف فئة وزن وحدتها kg في System > Localisation > Weight Classes. ولا يمكن حفظ الإعدادات إلا للمستخدمين المديرين الذين لديهم صلاحية التعديل لهذا الملحق.

عام

يرى العميل سعر Cargoson واحدًا. يمكنك قصر الطريقة على منطقة جغرافية أو على بلدان في Availability.

Enable Cargoson: يُظهر Cargoson أو يخفيه عند الدفع. الافتراضي: معطل.

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وعند الدفع، بحد أقصى 64 حرفًا. الافتراضي: Cargoson. حقل إلزامي.

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

يُسجَّل سبب غياب السعر الفوري في سجل التصحيح، ولا يُعرض للعميل أبدًا.

Sort order: ترتيب Cargoson بين طرق الشحن عند الدفع. عدد صحيح.

واجهة 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. تعيد الواجهة مبالغ بلا رمز عملة.

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

عنوان الاستلام (عنوان الجمع) (للأسعار الفورية)

Collection country: البلد الذي تشحن منه. الخيار الأول Store country يستخدم بلد متجرك.

Collection postcode: الرمز البريدي الذي تشحن منه. يطلبه Cargoson للأسعار الفورية. وعنوان المتجر في OpenCart نص حر، فلا يُؤخذ الرمز البريدي منه أبدًا: أدخله هنا.

تاريخ الاستلام المرسل إلى 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. السعر الفارغ أو الصفري لأي حجم يستخدم عمود Price؛ وPrice الفارغ يعني عدم وجود سعر ثابت لذلك الحجم. انقر على Add country لإضافة صف. اختر * All other countries للأسعار التي تنطبق على كل بلد ليس له صف خاص. البلدان التي لا صف لها (عند عدم وجود صف *) لا سعر ثابت لها، لذلك تُخفى الطريقة عنها. يجب أن تكون الأسعار أرقامًا أكبر من أو تساوي 0. يُتجاهل الصف الفارغ.

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

الشروط

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

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

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

Free shipping: فعّل الشحن المجاني من Cargoson ابتداءً من المبلغ أدناه.

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

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

التوفر

Geo zone: تقدم Cargoson فقط للعناوين في هذه المنطقة الجغرافية. All zones (الافتراضي) يعني بلا حد. وتُدار المناطق الجغرافية في System > Localisation > Geo Zones.

Ignore shipping zones: لا يتحقق من المنطقة الجغرافية؛ وقائمة البلدان أدناه هي التي تقرر.

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

متقدم

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

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

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

استيراد / تصدير

Export: انقر على Download JSON لحفظ الإعدادات في ملف JSON. لا تُصدَّر مفتاح API.

Import: ألصق ملف JSON صُدِّر سابقًا وانقر على Import لاستعادة الإعدادات، مثلًا في متجر آخر. تُفحص القيم كما في الحفظ العادي. يُحتفظ بمفتاح API المحفوظ.

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

عندما يعرض OpenCart طرق الشحن، يطلب من الملحق سعر Cargoson. إذا كانت Geo zone محددة (وIgnore shipping zones معطل) وكان العنوان خارجها، فلا يُعرض Cargoson. ولا تُحتسب إلا المنتجات التي يكون فيها Requires Shipping على Yes: أما المنتجات الأخرى فلا تضيف وزنًا ولا تدخل في مبلغ الطلب. تُحوَّل أوزان المنتجات من فئة الوزن الخاصة بها إلى كيلوغرامات. ثم يتحقق الملحق من الشروط: البلدان المسموح بها، ووزن السلة، والحد الأدنى لمبلغ الطلب. ومبلغ الطلب هو سعر المنتجات التي تحتاج إلى شحن، بعد خصم القسيمة وقبل الضريبة. ولا تُحتسب بطاقات الهدايا ونقاط المكافآت ورصيد المتجر. وإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Cargoson.

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

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

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

في OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار Cargoson في نافذة Shipping method options. وتعمل الطريقة بالطريقة نفسها في OpenCart 3.

الطلبات

عندما يطلب العميل بواسطة Cargoson، يُحفظ السعر المحسوب عند الدفع مع الطلب. وفي صفحة الطلب في Sales > Orders تظهر لوحة Cargoson shipping:

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

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

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

تظهر اللوحة أيضًا عندما تكون الطريقة معطلة. وفي OpenCart 4 يُنشأ الطلب مرة واحدة في خطوة التأكيد ويُحدَّث في كل مرة يعود فيها العميل إليها، لذلك فإن العرض المحفوظ هو آخر عرض حُسب عند الدفع؛ وإذا انتقل العميل إلى طريقة شحن أخرى، يُحذف عرض Cargoson الخاص بالطلب. ولا يغيّر تعديل الطلب في الإدارة العرض، ولا يتغير العرض لاحقًا. احجز الشحنة في Cargoson أو عبر تكاملاته الخاصة.

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

يعمل الملحق بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Cargoson هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox Cargoson > Edit، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-shipping-cargoson والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. ولا يستطيع تغيير المفتاح إلا المستخدمون المديرون الذين لديهم صلاحية Modify لهذا الملحق. وتتبع نصوص الكتلة لغة الإدارة (الإنجليزية والروسية مضمنتان).

إذا لم يُقبل المفتاح، توضح الكتلة السبب، مثل Key not found، أو This key belongs to another product، أو Domain limit reached، أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير فتحة نطاق في حسابك، انقر على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، يواصل الملحق العمل بآخر حالة معروفة.

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

بدون مفتاح فعّال، لا يُعرض Cargoson للعملاء عند الدفع ولا يُحسب أي سعر. ويظل المستخدم المدير الذي سجّل الدخول إلى الإدارة في المتصفح نفسه يرى الطريقة في المتجر، معلَّمة بـ (unlicensed — visible to admins only)، حتى تتمكن من إعداد الملحق واختباره قبل شراء مفتاح. وفي OpenCart 4 هذه المعاينة غير متاحة: فالمتجر لا يرى تسجيل دخول المدير، لذلك وبدون مفتاح فعّال تُخفى الطريقة عن الجميع. وبعد فتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الإدارة. أغلقه بـ × لإخفائه لمدة 7 أيام. ولا تتأثر الطلبات الحالية.

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

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

لا يظهر Cargoson عند الدفع: تحقق من أن الترخيص فعّال وأن Enable Cargoson مفعل. تحقق من Geo zone (أو من Ignore shipping zones وCountries)، وحدود الوزن، وMinimum order amount. وفي الوضع الثابت، تحقق من أن البلد أو * All other countries له سعر لحجم السلة. تحقق من أن المنتجات لديها Requires Shipping على Yes.

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

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

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

تُفرض الضريبة على الشحن مرتين: أسعار Cargoson لديك تتضمن ضريبة القيمة المضافة بالفعل. اضبط Tax class على No tax.

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

تقول الصفحة "Warning: You do not have permission to modify VibeFox Cargoson!": ربما لا تملك مجموعة المستخدمين الإدارية لديك إلا صلاحية عرض الإعدادات. امنح المجموعة صلاحية التعديل لـ extension/shipping/vfd_cargoson (OpenCart 3) أو extension/vfd_cargoson/shipping/vfd_cargoson (OpenCart 4) في System > Users > User Groups.

للمطورين: يمكن استبدال عنوان Cargoson API بالإعداد vfd_cgs_api_url (للاختبارات)؛ وليس له حقل في صفحة الإعدادات.

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

انتقل إلى Extensions > Extensions، واختر النوع Shipping، وانقر على Uninstall (الزر الأحمر −) بجوار VibeFox Cargoson. تُحذف دائمًا مفتاح الترخيص وحالة الترخيص لهذا الملحق. يعيد OpenCart دائمًا ضبط Enable Cargoson وSort order وTax class وGeo zone. وتُحذف الأسعار المخزنة مؤقتًا دائمًا. فإذا كان Remove data on uninstall مفعلًا، تُحذف إعدادات Cargoson والسجل أيضًا. وإذا كان معطلًا، تبقى الإعدادات الأخرى وتُستخدم مرة أخرى عند إعادة تثبيت الملحق. وتبقى عروض أسعار Cargoson للطلبات المنفذة محفوظة أبدًا، وتحتفظ الطلبات الحالية بطريقة شحنها وتكلفتها.

وفي OpenCart 4، لحذف ملفات الملحق أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر في قائمة الملحقات المثبتة على Uninstall (الزر البرتقالي −) بجوار VibeFox Cargoson، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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