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

المتطلبات

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

PHP: 8.0 أو أحدث.

حساب Aramex (للأسعار اللحظية فقط): تستخدم الأسعار اللحظية واجهة Aramex Rate Calculator API. تمنح Aramex إمكانية الوصول إلى الواجهة لأصحاب الحسابات. اسأل مدير حسابك في Aramex، أو راجع Aramex Developers Solution Center على موقع Aramex. تحتاج إلى ستة قيم: اسم المستخدم للواجهة (عادةً بريد إلكتروني)، وكلمة المرور، ورقم الحساب، ورقم PIN للحساب، وكيان الحساب (مثل DXB)، ورمز دولة الحساب (مثل AE). إذا كنت تستخدم الأسعار الثابتة لكل دولة فقط، فلا تحتاج إلى حساب Aramex.

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

التثبيت

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

OpenCart 3

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

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

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

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

5. اختر طريقة حساب تكلفة الشحن، واملأ الأقسام المناسبة (راجع الإعداد)، وفعّل Enable Aramex، ثم اضغط على Save.

OpenCart 4

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

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

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

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

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

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox Aramex > Edit. تظهر الأقسام في الجانب الأيسر. يحفظ زر Save واحد في الأسفل الصفحة بأكملها دون إعادة تحميلها. وكل حفظ يمسح أيضًا أسعار Aramex المخزنة مؤقتًا. إذا كانت قيمة خاطئة، فلا يُحفظ شيء وتعرض الصفحة السبب، مثل Enter a method title (1 to 64 characters).، أو رسالة تفيد بأن الحقل يجب أن يكون رقمًا، أو The account country code must have 2 letters, e.g. AE. ولا يستطيع حفظ الإعدادات إلا مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

General

تنطبق الإعدادات على كل المناطق الجغرافية. يمكنك قصر الطريقة على منطقة جغرافية وعلى دول محددة من خلال Conditions.

Enable Aramex: يعرض Aramex أو يخفيه أثناء الدفع. الافتراضي: معطّل.

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

Shipping cost: كيفية حساب السعر.

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

Sort order: ترتيب Aramex بين طرق الشحن أثناء الدفع. رقم صحيح.

حساب واجهة Aramex (مطلوب للأسعار اللحظية فقط؛ جميع الحقول الستة إلزامية)

Username: اسم المستخدم لواجهة Aramex، وعادةً يكون بريدًا إلكترونيًا. مسح هذا الحقل يمسح كلمة المرور المحفوظة أيضًا.

Password: كلمة مرور واجهة Aramex. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Account number: رقم عميل حسابك في Aramex. مسح هذا الحقل يمسح رقم PIN المحفوظ أيضًا.

Account PIN: رقم PIN لحسابك في Aramex. مثل كلمة المرور، لا يُعرض مجددًا بعد الحفظ.

Account entity: رمز كيان (مكتب) Aramex لحسابك، مثل DXB أو AMM أو RUH.

Account country code: رمز الدولة المكوّن من حرفين لحسابك في Aramex، مثل AE.

خدمة Aramex (تُستخدم للأسعار اللحظية)

إذا كان عنوان التسليم في بلد الشحن، فإن الشحنة تُسعَّر بوصفها Domestic. وجميع الشحنات الأخرى تُسعَّر بوصفها International express.

International service: منتج Aramex للشحنات إلى الخارج: PPX Priority Parcel Express (الافتراضي)، وPDX Priority Document Express، وPLX Priority Letter Express (للمستندات التي يقل وزنها عن 0.5 كغ)، وDPX Value Express Parcels، وEPX Economy Parcel Express، وEDX Economy Document Express، وGPX Ground Parcel Express، أو GDX Ground Document Express.

Domestic service: منتج Aramex للشحنات داخل بلد الشحن: ONP Overnight (Parcel) (الافتراضي)، وOND Overnight (Document)، وSMP Same Day (Parcel)، وSMD Same Day (Document)، وSDD Same Day Delivery، وEMD Early Morning Delivery، وPEC Economy Delivery، وPEX Road Express، أو HVY Heavy (20 كغ فأكثر).

Payment type: من يدفع لـ Aramex ثمن الشحنة: Prepaid (shipper pays) (الافتراضي)، أو Collect (receiver pays)، أو Third party. عادةً يكون Prepaid.

API weight unit: الوحدة المرسلة إلى Aramex: Kilograms (KG) (الافتراضي) أو Pounds (LB). تُحوَّل أوزان المنتجات من فئة الوزن الخاصة بها، وأبعادها من فئة الطول الخاصة بها. الوزن الخاضع للرسوم هو الأكبر بين الوزن الفعلي والوزن الحجمي (الطول × العرض × الارتفاع بالسنتيمتر / 5000). الحد الأدنى 0.5 كغ، وينطبق ذلك أيضًا على المنتجات التي لا وزن لها.

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

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

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

Origin city: المدينة التي تشحن منها. يشترط Aramex ذلك. عنوان المتجر في OpenCart نص حر، لذلك لا تُؤخذ المدينة منه: أدخلها هنا.

Origin state / emirate: اختياري.

Origin postcode: اختياري.

إذا كان بلد الشحن هو بلد متجرك، فإن الولاية الفارغة تُؤخذ من منطقة متجرك في System > Settings > Store > Local.

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

Price per country: قائمة بالدول والأسعار بعملة متجرك الافتراضية، دون الضريبة. انقر Add country لإضافة صف، وزر × لحذف صف. اختر * All other countries لسعر يُستخدم لكل دولة ليس لها صف خاص بها. الدول التي لا تملك سعرًا (عند عدم وجود صف *) لا تحصل على سعر ثابت، لذلك تُخفى الطريقة عنها.

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

Conditions

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

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

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

Free shipping: تفعيل التوصيل المجاني عبر Aramex ابتداءً من المبلغ أدناه.

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

Tax class: فئة الضريبة لتكلفة الشحن، أو No tax (الافتراضي). قد تتضمن الأسعار اللحظية من Aramex ضريبة القيمة المضافة بالفعل. في هذه الحالة اختر No tax حتى لا تُفرض الضريبة على الشحن مرتين.

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

Countries: اعرض Aramex فقط لدول الوجهة هذه. اتركه فارغًا للسماح بكل الدول. ينطبق هذا الحد مع Geo zone.

متقدم

Debug log: يكتب حسابات الأسعار وأخطاء الواجهة في storage/logs/vfd_armx_debug.log.php. لا يمكن قراءة الملف من الويب. لا تُسجَّل كلمات المرور ولا رقم PIN ولا عناوين العملاء أبدًا. أوقف السجل عندما تنتهي. وعندما يصل الملف إلى 5 ميغابايت يُنقل إلى vfd_armx_debug.old.log.php ويبدأ سجل جديد.

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

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

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

تصدير: انقر Download JSON لحفظ الإعدادات في ملف JSON. لا يُصدَّر كلمة المرور ولا رقم PIN.

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

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

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

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

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

إذا أعاد Aramex خطأً، أو مبلغًا صفريًا، أو عرضًا بعملة أخرى دون سعر صرف، فإن العميل لا يرى أي خطأ. تُخفى الطريقة، أو يُستخدم السعر الثابت في وضع الاحتياط. ويُكتب السبب في سجل التصحيح.

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

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

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

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

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

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

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

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

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

لا يظهر Aramex أثناء الدفع: تحقق من أن الترخيص نشط وأن Enable Aramex مفعّل. راجع Geo zone وCountries وحدود الوزن وMinimum order amount. في وضع الأسعار الثابتة، تأكد من أن للدولة أو لـ * All other countries سعرًا. وتأكد من أن للمنتجات Requires Shipping مضبوطًا على Yes.

لا تظهر الأسعار اللحظية: فعّل Debug log، ثم أعد تحميل الدفع وانظر إلى الحقل Log في صفحة الإضافة. سيعرض السبب: بيانات اعتماد الواجهة مفقودة، أو رمز خطأ من Aramex، أو غياب مدينة الشحن، أو غياب مدينة التسليم أو رمزه البريدي، أو حد للوزن أو للمبلغ، أو عرض بعملة أخرى. ومع Aramex live rates, fixed prices if the API fails، يحصل العملاء على السعر الثابت أثناء إصلاحك للمشكلة.

الخطأ ERR75 في السجل: رفض Aramex تسجيل الدخول. تحقق من اسم المستخدم وكلمة المرور ورقم الحساب ورقم PIN والكيان ورمز الدولة مع مدير حسابك في Aramex.

يُرفض عرض بعملة أخرى: ردّ Aramex بعملة مختلفة عن عملة متجرك الافتراضية. أدخل Currency conversion rate، أو اطلب من Aramex أن يقدم السعر بعملتك.

تُفرض الضريبة على الشحن مرتين: قد تتضمن إجماليات Aramex ضريبة القيمة المضافة بالفعل. اضبط Tax class على No tax.

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

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

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

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

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

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

Aramex علامة تجارية مسجلة لمالكها. هذه الإضافة غير تابعة لـ Aramex ولا معتمدة من قبلها.