VibeFox Australia Post for PrestaShop — المساعدة

المتطلبات

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

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

مفتاح Australia Post PAC API (للأسعار المباشرة فقط): تستخدم الأسعار المباشرة واجهة Postage Assessment Calculator (PAC) التابعة لـ Australia Post. المفتاح مجاني: سجّل للحصول على مفتاح PAC API من Australia Post Developer Centre (developers.auspost.com.au). تحتوي صفحة الوحدة على رابط لصفحة التسجيل. تحتاج أيضًا إلى الرمز البريدي الأسترالي المكوّن من 4 أرقام الذي ترسل منه. إذا كنت تستخدم أسعارًا ثابتة لكل دولة فقط، فلا تحتاج إلى مفتاح API.

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

التثبيت

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

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

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

4. اختر Rate source. للأسعار المباشرة، أدخل مفتاح PAC API والرمز البريدي للشحن، وإذا لم تكن العملة الافتراضية لمتجرك هي AUD فأدخل سعر التحويل إلى AUD (انظر الإعدادات). انقر على Save.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Australia Post > Configure. وتُطبَّق على كل منطقة. يعرض أعلى الصفحة اسم شركة الشحن ومعرّفها في Shipping > Carriers. لكل قسم زر Save خاص به، يحفظ الصفحة بأكملها. كما يؤدي كل حفظ إلى مسح أسعار Australia Post المخزّنة مؤقتًا.

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

تقبل حقول الأرقام النقطة أو الفاصلة كفاصل عشري. لا تُحفظ القيمة التي ليست رقمًا أو التي تكون سالبة: يسمّي التحذير الحقل، ويبقى الإدخال السابق كما هو. تحذّر الصفحة أيضًا إذا كانت وحدة الوزن أو الأبعاد في المتجر (International > Localization) غير معروفة للوحدة. عندئذٍ تُقرأ أوزان المنتجات بالكيلوغرام والأبعاد بالسنتيمتر.

عام

Enable Australia Post: يعطّل شركة الشحن في جميع المناطق دفعة واحدة. وهو المفتاح نفسه الذي يمثل حالة شركة الشحن في Shipping > Carriers.

Method title: اسم شركة الشحن الذي يراه العميل عند الدفع. وهو أيضًا اسم شركة الشحن في Shipping > Carriers، وإعادة تسمية الشركة هناك تحدّث هذا الحقل. الافتراضي: Australia Post. بحد أقصى 64 حرفًا: يُرفض العنوان الأطول ولا يُحفظ شيء. وإذا كان الحقل فارغًا أو يحتوي على أحرف لا يسمح بها PrestaShop في اسم شركة الشحن، يظهر تحذير وتُستخدم Australia Post.

Tax status: كيفية تطبيق الضريبة على تكلفة الشحن.

Rate source: كيفية حساب السعر.

تُرسل تفاصيل الأخطاء إلى السجل، ولا تُعرض للعميل أبدًا.

Australia Post API (live rates) (غير مطلوب للأسعار الثابتة)

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

Remove the saved API key: فعّل الخيار واحفظ لحذف المفتاح المحفوظ. بعد ذلك تتوقف الأسعار المباشرة.

Ship-from postcode: الرمز البريدي الأسترالي المكوّن من 4 أرقام الذي تُرسل منه الطرود، مثل 2000.

Domestic service: يُستخدم للتوصيل داخل أستراليا (حتى 22 كغ، و105 سم لكل جانب): Parcel Post (الافتراضي) أو Express Post.

International service: يُستخدم للتوصيل خارج أستراليا (حتى 20 كغ): International Standard (الافتراضي)، أو International Express، أو International Courier.

Remove GST: يقسم أسعار API المحلية على 1.1. تتضمن أسعار Australia Post المحلية ضريبة GST بنسبة 10%. فعّل هذا الخيار عندما يضيف PrestaShop الضريبة إلى الشحن بنفسه (Tax status = Taxable مع قاعدة ضريبة على شركة الشحن)، حتى لا تُحتسب GST مرتين. البريد الدولي معفى من GST ولا يُغيَّر أبدًا.

AUD → (your currency) rate: يعرض التسمية العملة الافتراضية لمتجرك. أسعار Australia Post بالدولار الأسترالي AUD. إذا لم تكن عملتك الافتراضية هي AUD، فأدخل عدد وحدات عملتك التي تعادل AUD واحدًا، مثل 0.61. يجب أن يكون السعر أكبر من 0. وبدونه لا تُستخدم الأسعار المباشرة. وإذا كانت عملتك الافتراضية هي AUD، تُبيّن الصفحة أنه لا حاجة إلى تحويل: اترك الحقل فارغًا. يُقبل كل من النقطة والفاصلة كفاصل عشري.

الطرد للأسعار المباشرة

تُرسل السلة كطرد واحد. تُحوَّل أوزان المنتجات وأبعادها من وحدات متجرك إلى كيلوغرامات وسنتيمترات. وتُستخدم القيم أدناه للمنتجات التي ليس لها وزن أو أبعاد.

Default product weight (kg): يُستخدم لكل منتج ليس له وزن، في طلب Australia Post وفي فحص Min cart weight (kg) / Max cart weight (kg). الافتراضي: 1.

Default parcel length (cm): يُستخدم عندما لا يكون لأي منتج في السلة أبعاد. الافتراضي: 22.

Default parcel width (cm): يُستخدم عندما لا يكون لأي منتج في السلة أبعاد. الافتراضي: 16.

Default parcel height (cm): يُستخدم عندما لا يكون لأي منتج في السلة أبعاد. الافتراضي: 8.

عندما تكون للمنتجات أبعاد، يأخذ الطرد أكبر طول وعرض بينها، ويزداد الارتفاع حتى يتسع الطرد لحجم جميع العناصر.

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

Country prices: جدول برموز الدول المكوّنة من حرفين (AU وNZ وUS وغيرها) وأسعار بالعملة الافتراضية لمتجرك، دون الضرائب. انقر على Add row لإضافة دولة، وعلى رابط × لحذف دولة. استخدم * لجميع الدول الأخرى. الدولة التي لا سعر لها (ولا يوجد صف * لها) ليس لها سعر ثابت، لذلك تُخفى شركة الشحن عنها. تُحذف الصفوف التي تحتوي على رمز دولة غير صالح أو بدون سعر عند الحفظ. يبقى الجدول فارغًا حتى تضيف أسعارًا.

Fixed price per: Order يحتسب السعر مرة واحدة. Item (price × quantity) يضربه في عدد العناصر في السلة. ينطبق هذا على الأسعار الثابتة فقط. تُحسب الأسعار المباشرة دائمًا للطرد كاملًا.

الشروط

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

Max cart weight (kg): إخفاء شركة الشحن إذا كان وزن السلة أعلى من هذه القيمة. الافتراضي: 22. القيمة 0 تعني بلا حد، والحقل الفارغ يعني 22 كغ. طرود Australia Post: 22 كغ داخل أستراليا، و20 كغ دوليًا. إذا كان Min cart weight (kg) أكبر من الحد الأقصى، فلن تظهر شركة الشحن أبدًا: يظهر تحذير، ويحتفظ الوزنان بقيمهما السابقة.

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

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

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

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

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

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

Countries: الدول المستهدفة لهذا الوضع. اتركه فارغًا للسماح بجميع الدول النشطة. اضغط مع الاستمرار على Ctrl (وCmd على Mac) وانقر لتحديد أكثر من دولة. يُستخدم فقط مع Ignore shipping zones.

متقدم

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

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

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

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

في خطوة الشحن يطلب PrestaShop من الوحدة سعر Australia Post. تُحتسب المنتجات المادية فقط: فالمنتجات الافتراضية لا تضيف وزنًا ولا تُدخل في مبلغ الطلب. تتحقق الوحدة أولًا من الشروط: قائمة Countries (مع Ignore shipping zones)، ووزن السلة، وMinimum order amount. إذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Australia Post.

في الوضع الثابت يُؤخذ السعر من الجدول. وفي أوضاع الأسعار المباشرة ترسل الوحدة إلى Australia Post وزن الطرد، وللتوصيل داخل أستراليا: الرمزين البريديين للشحن والتوصيل وحجم الطرد؛ وللتوصيل الدولي: الدولة المستهدفة. لا يُطلب سعر مباشر محلي إلا عندما يحتوي عنوان التوصيل على رمز بريدي من 4 أرقام. ولا يُرسل أي طلب عندما يتجاوز الطرد حدود Australia Post (22 كغ أو 105 سم داخل أستراليا، و20 كغ دوليًا). يُحوَّل سعر AUD بسعر صرفك، وتُزال GST من الأسعار المحلية إذا كان Remove GST مفعّلًا. يُحسب السعر بالعملة الافتراضية لمتجرك ثم يُعرض بعملة سلة العميل.

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

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

لا تقوم الوحدة إلا بحساب الأسعار. فهي لا تنشئ ملصقات شحن، ولا شحنات أو بيانات شحن جماعية من eParcel أو MyPost Business، ولا تتتبع الطرود، ولا تتيح للعملاء اختيار خزائن الطرود أو مكاتب البريد. وتُسعَّر السلة دائمًا كطرد واحد. ولا تشمل الرسائل والحقائب وأسعار العقود (eParcel).

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

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

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

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

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

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

لا تظهر الأسعار المباشرة: فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى حقل Log في صفحة الوحدة. يوضح الحقل السبب: لا يوجد مفتاح API أو رمز بريدي للشحن، أو لا يوجد بعد رمز بريدي للتوصيل مكوّن من 4 أرقام، أو الطرد يتجاوز الحدود، أو لا يوجد سعر تحويل AUD، أو رسالة الخطأ من Australia Post. مع Live rates, fixed price if the API gives no rate يظل العملاء يحصلون على السعر الثابت أثناء إصلاحك للمشكلة.

متجري لا يستخدم AUD: أدخل سعر التحويل (كم وحدة من عملتك الافتراضية تعادل AUD واحدًا) في الحقل AUD → (your currency) rate. تبقى الأسعار الثابتة دائمًا بعملتك الافتراضية.

تُحتسب GST على الشحن مرتين: تتضمن أسعار Australia Post المحلية ضريبة GST بنسبة 10%. إذا كان Tax status هو Taxable وكان لشركة الشحن قاعدة ضريبة، فعّل Remove GST أو اضبط Tax status على None.

لا تُضاف الضريبة إلى الشحن: عندما يكون Tax status = Taxable تأتي الضريبة من قاعدة الضريبة لشركة الشحن. اخترها في Shipping > Carriers. تعرض صفحة الوحدة تحذيرًا طالما لم تكن لشركة الشحن قاعدة ضريبة.

السعر مرتفع جدًا أو منخفض جدًا: تحقق من أوزان المنتجات وأبعادها والقيم الافتراضية في Parcel for live rates. مع Item (price × quantity) تُضرب الأسعار الثابتة في عدد العناصر.

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

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

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

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

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