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

المتطلبات

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

OpenCart 3

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

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

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

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

5. اختر Rate source (مصدر الأسعار). للأسعار الثابتة، أضف صفوفًا في Country prices. للأسعار اللحظية، أدخل مفتاح PAC API والرمز البريدي للشحن، وإذا لم تكن عملة متجرك الافتراضية AUD فأدخل سعر الصرف إلى AUD (راجع الإعداد). فعّل Enable Australia Post واضغط على Save.

OpenCart 4

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

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

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

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

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

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox Australia Post > Edit. تظهر الأقسام في الجانب الأيسر. يحفظ زر Save واحد الصفحة بأكملها دون إعادة تحميلها. وكل حفظ يمسح أيضًا أسعار Australia Post المخزنة مؤقتًا. ولا يستطيع حفظ الإعدادات إلا مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

بعض الأخطاء توقف الحفظ، وعندها لا يُحفظ شيء: Method title أطول من 64 حرفًا، أو Sort order ليس عددًا صحيحًا، أو فئة ضريبة أو منطقة جغرافية غير معروفة. وتظهر المشكلات الأخرى كتحذيرات فوق اللوحة، وتُحفظ بقية الإعدادات. ويحتفظ حقل رقمي تكون قيمته ليست رقمًا أو سالبة بقيمته السابقة، ويذكر التحذير اسم الحقل. وتقبل الحقول الرقمية النقطة أو الفاصلة كفاصل عشري.

إذا اخترت مصدر أسعار لحظية لكن مفتاح API أو الرمز البريدي المكوّن من 4 أرقام للشحن أو سعر صرف AUD مفقود، يظهر تحذير بعد الحفظ. ويوضح التحذير أيضًا ما يحدث حتى تصحح الأمر: تُخفى الطريقة أثناء الدفع، أو تُستخدم الأسعار الثابتة لكل دولة في وضع الاحتياط. وتحذر الصفحة أيضًا إذا لم يكن لدى متجرك فئة وزن بوحدة kg أو فئة طول بوحدة cm. عندها تُحوَّل أوزان المنتجات وأبعادها حسب وحدة فئتها (kg وg وlb وoz؛ وcm وmm وm وin)، وتُقرأ الوحدات الأخرى كـ kg وcm.

General

تنطبق الإعدادات على كل المناطق الجغرافية. يمكنك قصر الطريقة على منطقة جغرافية من خلال Conditions، أو على قائمة دول من خلال Availability without shipping zones.

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

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

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

تفاصيل الأخطاء تذهب إلى السجل، لا إلى العميل أبدًا.

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

واجهة Australia Post (الأسعار اللحظية) (غير مطلوبة للأسعار الثابتة)

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%. فعّله عندما يضيف OpenCart الضريبة على الشحن بنفسه (تم اختيار Tax class)، حتى لا تُحتسب GST مرتين. البريد الدولي معفى من GST ولا يُعدَّل أبدًا.

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

الطرد للأسعار اللحظية

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

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: قائمة بالدول والأسعار بعملة متجرك الافتراضية، دون الضريبة. انقر Add row لإضافة صف، وزر × لحذف صف. اختر * All other countries لسعر يُستخدم لكل دولة ليس لها صف خاص بها. الدولة التي لا سعر لها (ولا يوجد صف *) لا تحصل على سعر ثابت، لذلك تُخفى الطريقة عنها. تُحذف الصفوف بلا سعر عند الحفظ. يبقى الجدول فارغًا حتى تضيف أسعارًا.

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

Conditions

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 مفعّلًا.

Tax class: فئة الضريبة لتكلفة الشحن، أو No tax (الافتراضي). تتضمن أسعار Australia Post المحلية ضريبة GST: مع فئة ضريبة، فعّل Remove GST.

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

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

عادةً تُعرض الطريقة في المنطقة الجغرافية المختارة في Conditions (All zones تعني في كل مكان).

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

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

متقدم

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

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

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

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

Export: انقر Download JSON لحفظ الإعدادات في ملف JSON. لا يُصدَّر مفتاح API.

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

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

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر Australia Post. إذا كانت Geo zone مضبوطة (وIgnore shipping zones معطّل) والعنوان خارجها، فلن تُعرض Australia Post. مع Ignore shipping zones، تحدد قائمة Countries الأمر. لا تُحتسب إلا المنتجات التي تكون Requires Shipping فيها مضبوطة على Yes: المنتجات الأخرى لا تضيف وزنًا ولا تدخل في مبلغ الطلب. ثم تتحقق الإضافة من وزن السلة وMinimum order amount. ومبلغ الطلب هو سعر المنتجات التي تحتاج إلى شحن، بعد خصم القسيمة وقبل الضريبة. لا تُحتسب بطاقات الهدايا ونقاط المكافآت ورصيد المتجر. وإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Australia Post.

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

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

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

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

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

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

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

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

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

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

لا تظهر الأسعار اللحظية: فعّل 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 class محددة، فعّل Remove GST، أو اضبط Tax class على No tax.

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

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

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

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

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

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

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

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