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

المتطلبات

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

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

الوصول إلى واجهة NZ Post البرمجية (للأسعار الفورية فقط): تستخدم الأسعار الفورية واجهة NZ Post ShippingOptions API. اطلب الوصول إلى الواجهة البرمجية من Developer Resource Centre في موقع NZ Post. تمنحك NZ Post معرّف عميل (Client ID) وسرًا للعميل (Client Secret)، أولًا لبيئة الاختبار (UAT) ثم لبيئة الإنتاج بعد قائمة التحقق الخاصة بالإطلاق. للأسعار داخل نيوزيلندا تحتاج أيضًا إلى حساب تجاري لدى NZ Post: رقم الحساب ورمز المصادقة الخاص به (auth code) أو رمز الموقع (site code). إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى الوصول إلى الواجهة البرمجية.

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

التثبيت

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

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

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

4. للأسعار الفورية، املأ قسم NZ Post API (live rates). ويمكنك اختياريًا إدخال أسعار ثابتة، وتُستخدم بدون الأسعار الفورية وكبديل احتياطي (انظر الإعدادات). انقر على Save.

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

الإعدادات

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

تظهر تحذيرات فوق الإعدادات عندما لا تستطيع الأسعار الفورية العمل بالقيم المحفوظة: عند تعبئة أحد الحقلين Client ID أو Client Secret فقط، أو عدم وجود سعر صرف NZD، أو بيانات ناقصة للأسعار المحلية. يظهر تحذير أيضًا إذا كانت وحدة الوزن أو الأبعاد في المتجر غير معروفة للوحدة (عندها تُعامل الأوزان بالكيلوغرام والأبعاد بالسنتيمتر). اضبط الوحدات في International > Localization (Local units). يجب أن تحتوي حقول الأرقام على 0 أو رقم موجب؛ وإلا تعرض الصفحة خطأً ولا يُحفظ شيء.

General

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

Method title: اسم شركة الشحن الذي يظهر في عربة التسوق وفي الدفع. الافتراضي: NZ Post. حقل إلزامي، بحد أقصى 64 حرفًا.

Tax: قاعدة الضريبة لشركة الشحن، أو No tax (لا تخضع تكلفة الشحن للضريبة). إذا كان المتجر يضيف GST على الشحن، فاضبط API prices أدناه على Excluding GST حتى لا تُفرض GST مرتين.

NZ Post API (live rates) (اترك Client ID فارغًا لاستخدام الأسعار الثابتة فقط)

Environment: Production (api.nzpost.co.nz) (الافتراضي) أو Testing / UAT (api.uat.nzpost.co.nz). استخدم البيئة التي صدر لها معرّف العميل (Client ID).

Client ID: معرّف العميل OAuth2 لتطبيق NZ Post API الخاص بك. مسحه يمسح أيضًا Client Secret المحفوظ.

Client Secret: سر العميل OAuth2. يُستبدل برمز وصول يُخزَّن مؤقتًا حتى انتهاء صلاحيته. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Account number: رقم حسابك التجاري (حساب الفوترة) لدى NZ Post. مطلوب للأسعار داخل نيوزيلندا. وهو اختياري للأسعار الدولية؛ ومعه تعيد NZ Post أسعار التعاقد الخاصة بك. مسحه يمسح أيضًا auth code المحفوظ.

Auth code: رمز التفويض للحساب، ويُستخدم للأسعار المحلية. لا حاجة إليه إذا أدخلت site code. وكما في Client Secret، لا يُعرض مرة أخرى بعد الحفظ.

Site code: بديل عن auth code: رمز موقع الاستلام الخاص بك لدى NZ Post.

Ship-from suburb: الضاحية (suburb) في العنوان الذي تُرسل منه الطرود، مثل Petone. مطلوبة للأسعار المحلية.

Ship-from city: البلدة أو المدينة التي تُرسل منها الطرود، مثل Lower Hutt. مطلوبة للأسعار المحلية.

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

Services: رموز خدمات NZ Post اختيارية، مفصولة بفواصل، مثل CPOLP, ICOU. لا يُسعَّر إلا هذه الخدمات. اتركه فارغًا لاستخدام أرخص خدمة تعيدها NZ Post للطرد.

API prices: Including GST (الافتراضي) أو Excluding GST. تشمل أسعار NZ Post المحلية ضريبة GST بنسبة 15%؛ والبريد الدولي معفى من الضريبة (نسبة صفر). اختر Excluding GST عندما تكون لشركة الشحن قاعدة ضريبة (Tax أعلاه)، حتى لا تُفرض GST مرتين.

NZD → (shop currency) rate: أسعار NZ Post بالدولار النيوزيلندي (NZD). إذا لم تكن العملة الافتراضية لمتجرك NZD، فأدخل عدد وحدات عملتك التي تساوي دولارًا نيوزيلنديًا واحدًا، مثل 0.55. بدونه لا تُستخدم الأسعار الفورية. ويُستخدم السعر نفسه لتحويل مبلغ الطلب المُرسل في الطلبات الدولية. يجب أن يكون السعر أكبر من 0. إذا كانت عملة متجرك NZD، فاتركه فارغًا.

Parcel for live rates

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

Default product weight (kg): يُستخدم لكل منتج لا يملك وزنًا. الافتراضي: 0.5.

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

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

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

Fixed prices (تُستخدم عندما لا تكون الأسعار الفورية مُعدَّة أو عندما لا تعيد NZ Post أي سعر)

الأسعار بعملة المتجر الافتراضية، دون الضريبة.

Country prices: صف واحد لكل دولة وجهة. انقر على Add country لإضافة صف، وعلى أيقونة سلة المهملات لحذفه. اختر * Default لصف يغطي جميع الدول الأخرى. يحتوي كل صف على سعر Any weight وأعمدة وزن اختيارية: ≤ 1 kg، و1–2 kg، و2–3 kg، و3–5 kg، و> 5 kg (وزن السلة). العمود المعبأ بالوزن يتجاوز Any weight؛ أما العمود الفارغ أو الذي قيمته 0 فيستخدم Any weight. إذا كان سعر Any weight يساوي 0 فهذا يعني شحنًا مجانيًا إلى تلك الدولة. يُقبل كل من "9.99" و"9,99". تُحذف الصفوف التي لا تحمل أي سعر والأسعار السالبة عند الحفظ. يُحتفظ بصف واحد فقط لكل دولة.

Fallback cost: يُستخدم عندما لا تعطي الواجهة البرمجية ولا جدول الدول أي سعر. اتركه فارغًا لإخفاء شركة الشحن في هذه الحالة.

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

Conditions

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

Max cart weight (kg): يخفي شركة الشحن عندما تكون السلة أثقل من هذا الوزن. الافتراضي: 25 (طرود NZ Post السريعة تصل إلى 25 كجم)؛ والحقل الفارغ يعني 25 أيضًا. القيمة 0 تعني بلا حد. عندما يكون Ignore shipping zones مفعّلًا، يعني الحقل الفارغ عدم وجود حد خارج مناطق شركة الشحن نفسها. إذا كان Min cart weight أكبر من Max cart weight، تعرض الصفحة خطأً ولا يُحفظ شيء، لأن شركة الشحن لن تظهر أبدًا.

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

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

لأغراض هذه الشروط، يُحسب وزن السلة للمنتجات التي لا وزن لها على أنه 0.

Availability without shipping zones

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

Ignore shipping zones: يقدم NZ Post للدول المذكورة أدناه، أيًّا كانت المنطقة المطابقة. عند الحفظ تُضاف شركة الشحن إلى جميع المناطق (بما في ذلك المناطق التي تُنشأ لاحقًا). إيقاف الخيار يزيل المناطق المضافة مرة أخرى.

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

Advanced

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

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

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

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

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

عند إعداد الأسعار الفورية، تحصل الوحدة على رمز وصول باستخدام Client ID وClient Secret، وتطلب سعرًا من NZ Post. بالنسبة إلى عنوان في نيوزيلندا، ترسل بيانات حسابك وعنوان الإرسال وضاحية العميل ومدينته ورمزه البريدي، إضافة إلى وزن الطرد وحجمه. لا يوجد في PrestaShop حقل للضاحية: تستخدم الوحدة Address line 2 عندما يحتوي على اسم ضاحية (دون أرقام)، وإلا تستخدم المدينة. لا يُطلب السعر المحلي إلا بعد أن يُدخل العميل مدينة ورمزًا بريديًا مكوّنًا من 4 أرقام. أما للدول الأخرى، فترسل الدولة الوجهة ووزن الطرد وحجمه ومبلغ الطلب بالدولار النيوزيلندي.

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

إذا لم تُعد NZ Post أي سعر (الواجهة البرمجية غير مُعدَّة، أو خطأ، أو عنوان غير مكتمل، أو خدمة غير متاحة، أو لا يوجد سعر صرف NZD)، فلن يرى العميل أي خطأ. يُستخدم سعر جدول الدول، ثم التكلفة الاحتياطية. إذا لم يوجد سعر ثابت، تُخفى شركة الشحن. ويُكتب السبب في السجل.

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

تحسب الوحدة الأسعار فقط. لا تُنشئ ملصقات الشحن، ولا تحجز مواعيد الاستلام، ولا تُنشئ قوائم التسليم (manifests)، ولا تتتبع الطرود، ولا تتحقق من العناوين، ولا تسمح للعملاء باختيار نقطة استلام أو صندوق بريد (PO Box) أو خزانة طرود (parcel locker). تُسعَّر السلة كطرد واحد، ويرى العميل سعرًا واحدًا من NZ Post، لا قائمة بالخدمات.

الطلبات

عند تقديم طلب بشركة الشحن NZ Post، تحفظ الوحدة الأساس الذي استندت إليه تكلفة الشحن. تعرض صفحة الطلب في لوحة الإدارة كتلة NZ Post تحتوي على NZ Post service (خدمة NZ Post المُسعَّرة في السعر الفوري) وPrice source: Live rate (NZ Post ShippingOptions API) أو Fixed price أو Free shipping. تعرض الكتلة القيم في لحظة الطلب، حتى لو تغيرت الأسعار أو الإعدادات لاحقًا.

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

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

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

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

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

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

لا تظهر الأسعار الفورية: راجع التحذيرات أعلى صفحة الوحدة. ثم فعّل Debug log، وأعد تحميل الدفع، وانظر إلى حقل Log. تظهر أخطاء الواجهة البرمجية هناك دائمًا. يوضح السجل السبب: غياب Client ID أو Client Secret، أو رفض الرمز، أو غياب بيانات الحساب أو عنوان الإرسال، أو عدم وجود مدينة أو رمز بريدي للعميل بعد، أو عدم وجود سعر صرف NZD، أو عدم وجود خدمة مُسعَّرة. تُستخدم الأسعار الثابتة أثناء إصلاح المشكلة.

يفشل طلب الرمز: تحقق من Client ID وClient Secret وEnvironment. بيانات اعتماد UAT لا تعمل في بيئة الإنتاج، والعكس صحيح.

الأسعار المحلية مفقودة والأسعار الدولية تعمل: تحتاج الأسعار داخل نيوزيلندا إلى Account number أو Auth code أو Site code، وعنوان الإرسال الكامل مع رمز بريدي من 4 أرقام. يجب أن يُدخل العميل مدينة ورمزًا بريديًا من 4 أرقام. يمكن للمطوّرين تغيير الضاحية المُرسلة لعنوان التوصيل باستخدام الخطاف actionVfdNzptDeliverySuburb.

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

تُفرض GST مرتين على الشحن: تشمل أسعار NZ Post المحلية ضريبة GST بنسبة 15%. إذا كانت لشركة الشحن قاعدة ضريبة في Tax، فاضبط API prices على Excluding GST.

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

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

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

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

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