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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

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

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

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

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

الإعداد

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

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

في كل مرة تحفظ فيها الإعدادات، تُمسح أسعار NZ Post المخزّنة مؤقتًا ورموز الوصول. إذا لم تستطع الأسعار الفورية العمل بالقيم المحفوظة (إدخال واحد فقط من Client ID وClient Secret، أو عدم وجود سعر صرف NZD، أو بيانات ناقصة للأسعار المحلية)، يظهر تحذير أعلى الإعدادات.

General

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

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. انظر أيضًا API prices أدناه.

NZ Post API (الأسعار الفورية) (اترك 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: سرّ العميل OAuth2. يُستبدل برمز وصول يُخزَّن مؤقتًا إلى أن ينتهي.

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

Auth code: auth code الحساب للأسعار المحلية. لا يلزم إذا أدخلت site code.

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

Ship-from 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 status هي Taxable، حتى لا تُفرض GST مرتين.

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

الطرد للأسعار الفورية

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

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

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

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

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

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

الشروط

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

Max cart weight (kg): يُخفي الطريقة عندما يكون وزن السلة أكثر من ذلك. الافتراضي: 25 (طرود NZ Post السريعة تصل إلى 25 كجم). 0 يعني بلا حد.

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

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

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

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

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

Ignore shipping zones: يعرض NZ Post للدول المدرجة أدناه، حتى إذا لم تُضَف الطريقة إلى أي منطقة شحن.

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

متقدم

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

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

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

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

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

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

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

تعمل الطريقة على الدفع الكلاسيكي وعلى كتلتي Cart وCheckout. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

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

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

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

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

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

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

لا تظهر الأسعار الفورية: افتح WooCommerce > Status > Logs مع المصدر "vfd-nz-post". أخطاء الواجهة البرمجية موجودة هناك دائمًا. فعّل Debug log للتفاصيل. يوضح السجل السبب: Client ID أو Client Secret مفقود، أو رمز مرفوض، أو بيانات الحساب أو عنوان الإرسال ناقصة، أو لم تُعرف مدينة العميل أو رمزه البريدي بعد، أو لا يوجد سعر صرف NZD، أو لا توجد خدمة مُسعَّرة. تُستخدم الأسعار الثابتة أثناء حل المشكلة.

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

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

متجري لا يستخدم NZD: أدخل NZD → (store currency) rate. الأسعار الثابتة دائمًا بعملة المتجر.

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

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

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

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

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

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