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

المتطلبات

PrestaShop: 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

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

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

التثبيت

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Aramex > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. كما يمسح كل حفظ الأسعار المخزنة مؤقتًا من Aramex.

عام

Enable Aramex: يُفعِّل شركة الشحن أو يُوقفها. وهذا هو المفتاح نفسه الذي يحدد حالة شركة الشحن في Shipping > Carriers.

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

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

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

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

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

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

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 بعملة أخرى رغم ذلك، يُضرب السعر في هذا الرقم (وحدة واحدة من عملة Aramex = X وحدة من العملة الافتراضية لمتجرك). اترك الحقل فارغًا لرفض هذه العروض، حتى لا يُحمَّل العميل أبدًا بعملة خاطئة.

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

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

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

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

Origin postcode: اختياري.

إذا كانت دولة المنشأ هي دولة متجرك، تُملأ الحقول الفارغة من عنوان المتجر في Shop Parameters > Contact > Stores.

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

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

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

الشروط

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

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

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

Free shipping: يُفعِّل الشحن المجاني عبر Aramex ابتداءً من المبلغ الموضح أدناه.

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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