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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

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

الإعدادات

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

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

في كل مرة تحفظ فيها الإعدادات، تُمسح أسعار Australia Post المخزّنة مؤقتًا. وإذا اخترت الأسعار المباشرة ولكن مفتاح API أو الرمز البريدي للشحن أو سعر AUD غير موجود، يظهر تحذير بعد الحفظ.

عام

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

Method title: اسم طريقة الشحن الذي يراه العميل عند الدفع. يمكن لأي منطقة استبداله بعنوانها الخاص. الافتراضي: Australia Post.

Tax status: تُضيف Taxable ضريبة WooCommerce إلى تكلفة الشحن، بينما لا تُضيفها None.

Rate source: طريقة احتساب السعر.

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

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

PAC API key: مفتاح Australia Post PAC API المجاني الخاص بك. يُرسل إلى Australia Post في ترويسة AUTH-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: يقسم أسعار الواجهة المحلية على 1.1. وتتضمن أسعار Australia Post المحلية ضريبة GST بنسبة 10%. فعّل هذا الخيار عندما تُضيف WooCommerce الضريبة إلى الشحن بنفسها (Tax status = Taxable)، حتى لا تُحتسب ضريبة GST مرتين. والبريد الدولي معفى من GST ولا يُعدَّل أبدًا.

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

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

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

Default product weight (kg): يُستخدم لكل منتج لا وزن له، في طلب Australia Post وفي فحص Min cart weight / Max cart weight. الافتراضي: 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 تعني بلا حد. طرود Australia Post: 22 كغ داخل أستراليا، و20 كغ دوليًا.

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

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

Free shipping: يفعّل الشحن المجاني من المبلغ المذكور أدناه.

Free shipping from: المجموع الفرعي للسلة الذي يصبح الشحن عنده مجانيًا. وفي هذه الحالة لا يُرسل أي طلب إلى الواجهة.

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

Ignore shipping zones: يعرض الطريقة للدول المذكورة أدناه، بغض النظر عن المنطقة المطابقة.

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

متقدم

Debug log: يسجّل حسابات الأسعار في WooCommerce > Status > Logs، بالمصدر "vfd-australia-post". وتُسجَّل أخطاء الواجهة دائمًا. ولا يُسجَّل مفتاح API ولا الرموز البريدية للعملاء.

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

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

عندما يُدخل العميل عنوان التوصيل، يطلب WooCommerce من الإضافة سعرًا. تتحقق الإضافة أولًا من وزن السلة وMinimum order amount وExcluded shipping classes. فإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Australia Post.

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

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي السلة والدفع. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

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

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

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

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

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

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

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

الأسعار المباشرة لا تظهر: فعّل Debug log، ثم أعد تحميل صفحة الدفع، وافتح WooCommerce > Status > Logs (المصدر "vfd-australia-post"). سيُظهر السجل السبب: لا يوجد مفتاح API أو رمز بريدي للشحن، أو لم يُدخَل بعد رمز بريدي للتوصيل مكوّن من 4 أرقام، أو الطرد يتجاوز الحدود، أو لا يوجد سعر تحويل AUD، أو رسالة الخطأ من Australia Post. ومع Live rates, fixed price if the API gives no rate، يحصل العملاء على السعر الثابت أثناء معالجتك للمشكلة.

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

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

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

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

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

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

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

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