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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

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

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

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

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

الإعدادات

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

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

في كل مرة تحفظ فيها الإعدادات، تُمسح الأسعار المخزنة مؤقتًا من Aramex.

عام

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

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

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

Fixed prices per country (table below): يأتي السعر من جدول Price per country. لا حاجة إلى حساب Aramex.

Aramex live rates (API): يُطلب السعر من Aramex لكل سلة. إذا لم تُرجع Aramex سعرًا، تُخفى الطريقة لتلك السلة.

Aramex live rates, fixed prices if the API fails: يُطلب السعر من Aramex. إذا لم ترد Aramex (بيانات اعتماد خاطئة، أو انتهاء المهلة، أو خطأ في الخدمة)، يُستخدم السعر الثابت للدولة.

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

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

Username: اسم مستخدم واجهة Aramex البرمجية، وعادةً عنوان بريد إلكتروني.

Password: كلمة مرور واجهة Aramex البرمجية.

Account number: رقم حسابك لدى Aramex.

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، أو 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 (يدفع المرسل)، أو Collect (يدفع المستلم)، أو Third party (طرف ثالث). عادةً Prepaid.

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

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

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

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

Origin city: المدينة التي تشحن منها. تشترطها Aramex.

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

Origin postcode: اختياري.

إذا كانت دولة المنشأ هي دولة متجرك، تُؤخذ الحقول الفارغة من عنوان المتجر في WooCommerce > Settings > General.

الأسعار الثابتة (تُستخدم في الوضع الثابت وكبديل للأسعار الفورية)

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

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

الشروط

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

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

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

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

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

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

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

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الضريبة تُحتسب مرتين على الشحن: قد تتضمن إجماليات Aramex ضريبة القيمة المضافة (VAT) مسبقًا. اضبط Tax status على None.

الأسعار تبدو قديمة بعد تغيير: احفظ صفحة الإعدادات. هذا يمسح الأسعار المخزنة من Aramex.

بيئة Aramex التجريبية (sandbox): تستخدم الإضافة Aramex Rate Calculator الإنتاجي. يمكن للمطوّرين تغيير نقطة الوصول عبر الفلتر vfd_armx_api_url. وتعدّل الفلاتر vfd_armx_rate_request وvfd_armx_number_of_pieces وvfd_armx_volumetric_divisor الطلب وعدد القطع وقاسم الوزن الحجمي.

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

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

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

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