VibeFox PostNord for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل. لا يتفعّل الملحق بدونه.

PHP: 8.0 أو أحدث.

مفتاح API الخاص بـ PostNord (لمنتقي نقاط الخدمة): أنشئ حسابًا مجانيًا على developer.postnord.com، وأضف تطبيقًا، وانسخ مفتاح API الخاص به. من دون مفتاح تظل الطريقة تعمل، لكن العملاء لا يستطيعون اختيار نقطة خدمة.

اتفاقية PostNord: لإرسال الطرود تحتاج إلى اتفاقية العميل المعتادة مع PostNord، مثل MyPack Collect أو MyPack Home.

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

التثبيت

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

2. انقر Activate.

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

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

5. الصق API key الخاص بـ PostNord، واختر Agreement country، واملأ Country prices (انظر الإعدادات).

6. أضف VibeFox PostNord إلى مناطق الشحن الخاصة بالسويد أو الدنمارك أو النرويج أو فنلندا في WooCommerce > Settings > Shipping > Shipping zones. في إعدادات الطريقة، حدد Title وDelivery type. أو فعّل Ignore shipping zones.

الإعدادات

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

Title (zone): اسم هذا الخيار عند الدفع، مثلًا "PostNord MyPack Collect". اتركه فارغًا لاستخدام Name العام.

Delivery type (zone): Same as global setting (الافتراضي)، أو Service point / parcel locker، أو Home delivery. أضف طريقتين من PostNord إلى منطقة لعرض الخيارين معًا.

فوق الإعدادات، تعرض الصفحة تحذيرًا عندما لا يكون مفتاح API أو السعر مُدخلًا بعد. وفي كل مرة تحفظ فيها الإعدادات، تُمسح قوائم نقاط الخدمة المخزّنة مؤقتًا.

عام

Enable/Disable: عند إلغاء التحديد تُخفى الطريقة في كل مكان، بما في ذلك مناطق الشحن.

Name: اسم طريقة الشحن الظاهر عند الدفع. يمكن لطريقة المنطقة أن تستبدله بـ Title الخاص بها. الافتراضي: PostNord.

Delivery type: القيمة الافتراضية لكل طرق PostNord؛ ويمكن لكل طريقة في منطقة أن تختار نوعها.

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

واجهة PostNord API (منتقي نقاط الخدمة)

API key: مفتاح API الخاص بتطبيقك على developer.postnord.com. يُرسل إلى PostNord من خادمك فقط، ولا يُرسل إلى المتصفح أبدًا، ولا يُسجَّل في السجل مطلقًا.

Test mode: يستخدم بيئة اختبار PostNord (atapi2.postnord.com). ولا يُستخدم إلا مع المفاتيح الصادرة لبيئة الاختبار.

Agreement country: الدولة التي تتبعها اتفاقية العميل الخاصة بك مع PostNord: السويد أو الدنمارك أو النرويج أو فنلندا. وهي تحدد نقاط الخدمة المعروضة. ويستخدم Same as the delivery country (الافتراضي) دولة العميل.

الأسعار

الأسعار بعملة المتجر. لا تتوفر لدى PostNord واجهة برمجية عامة للأسعار، لذلك تحدد أسعارك الخاصة، وغالبًا ما تكون أسعار اتفاقيتك مع PostNord. والترتيب هو: أولًا جدول الدولة، ثم التكلفة الاحتياطية؛ ولا يُطبَّق الشحن المجاني إلا حيث يعطي أحدهما سعرًا.

Calculation type: Per order يحصّل السعر مرة واحدة. أما Per item (price × number of items) فيضربه في عدد العناصر في السلة.

Country prices: سعر حسب دولة الوجهة ووزن السلة. انقر + Add country لإضافة صف، والعلامة × لحذف صف. يحتوي كل صف على Price وأعمدة للوزن: XS حتى 1 كغ، وS حتى 2 كغ، وM حتى 3 كغ، وL حتى 5 كغ، وXL فوق 5 كغ. العمود الذي يحمل القيمة 0 يستخدم عمود Price. والدولة * All other countries تشمل كل الدول التي ليس لها صف خاص بها. الكسور بفاصلة أو نقطة (9,99 أو 9.99). يبدأ الصف الجديد باسم * All other countries وجميع الأسعار 0، أي شحن مجاني. اختر الدولة وأدخل الأسعار قبل الحفظ، أو احذف الصف. تُحفظ الخلية التي لا تحتوي على رقم بالقيمة 0 مع رسالة توضيحية.

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

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

التوفر

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

Max weight (kg): يُخفي الطريقة عندما يكون وزن السلة أكبر. الافتراضي: 30. والقيمة 0 تعني بلا حد. تحقق من حد الوزن لخدمة PostNord لديك: فخزائن الطرود تقبل وزنًا أقل من نقاط الخدمة.

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

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

Ignore shipping zones: عند التفعيل، تُعرض PostNord للدول المذكورة أدناه بالإعدادات العامة، حتى لو لم تُضف إلى منطقة شحن. وعند الإلغاء، تُعرض فقط في مناطق الشحن التي أضفتها إليها.

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

تقبل المبالغ والأوزان الفاصلة أو النقطة. ولا يُحفظ الرقم غير الصالح، مع رسالة توضيحية.

متقدم

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

Remove data on uninstall: عند التفعيل، يؤدي حذف الملحق إلى إزالة إعدادات PostNord وطرق المناطق. ولا يحذف إلغاء التفعيل الإعدادات أبدًا. وتبقى نقاط الخدمة المحفوظة في الطلبات دائمًا.

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

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

بالنسبة إلى طريقة نقطة الخدمة وعنوان توصيل في السويد أو الدنمارك أو النرويج أو فنلندا، يطلب خادمك من PostNord Business Location API نقاط الخدمة الأقرب إلى الرمز البريدي للتوصيل. ويرسل دولة التوصيل والرمز البريدي ودولة الاتفاقية. ومهلة استجابة API هي 10 ثوانٍ. وتُخزَّن القوائم مؤقتًا لمدة 6 ساعات لكل رمز بريدي، وإجابات "لا توجد نقاط" لمدة ساعة. وتُخزَّن أخطاء API مؤقتًا لمدة 5 دقائق، حتى لا يُبطئ تعطل PostNord كل تحديث للدفع.

بالنسبة إلى الوجهات الأخرى، يمكن عرض الطريقة بأسعارك دون منتقٍ.

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

لا يطلب الملحق أسعار PostNord الفورية، ولا ينشئ ملصقات الشحن، ولا يحجز الشحنات (EDI)، ولا يوفر أرقام التتبع، ولا يرسل رسائل التتبع الإلكترونية. ولا يوجد عرض خريطة. استخدم PostNord Portal أو Skicka Direkt Business أو ملحق ملصقات للشحنات؛ فمعرّف نقطة الخدمة المحفوظ هو ما تحتاجه هذه الأدوات.

نقاط الاستلام

عندما يختار العميل طريقة نقطة الخدمة، تظهر أسفلها قائمة PostNord service point بأقرب النقاط، مجمّعة حسب المدينة مع المسافة. قبل إدخال الرمز البريدي، يرى العميل الرسالة "Enter your postcode to choose a PostNord service point.". ويبقى الاختيار محفوظًا عند تحديثات الدفع.

عند تحميل القائمة، يجب اختيار نقطة. وإذا لم تُختر، يتوقف الدفع مع الرسالة "Please select a PostNord service point.". وتُتحقق النقطة المختارة على الخادم مقابل القائمة، في الدفع الكلاسيكي والدفع بالكتل على حد سواء.

لا يعطل المنتقي عملية البيع أبدًا. وإذا تعذر تحميل القائمة (لا يوجد مفتاح API بعد، أو واجهة PostNord متوقفة، أو لا توجد نقاط قرب الرمز البريدي)، يرى العميل ملاحظة ويمكنه إتمام الطلب. عندئذٍ تُسلّم PostNord الطرد إلى نقطة الخدمة الأقرب إلى العنوان.

شاشة الطلب في لوحة الإدارة: PostNord service point مع الاسم والعنوان وService point ID، أسفل عنوان الشحن. إذا لم تُختر نقطة، تظهر العبارة "not selected — PostNord delivers to the service point nearest to the shipping address".

صفحة الشكر وعرض الطلب في حسابي: PostNord service point: مع الاسم والعنوان.

رسائل الطلبات الإلكترونية: اسم النقطة وعنوانها ومعرّفها في الرسائل بتنسيق HTML والنص العادي.

في قاعدة البيانات تُحفظ النقطة في بيانات الطلب الوصفية _vfd_ptnd_servicepoint_id و_vfd_ptnd_servicepoint_name و_vfd_ptnd_servicepoint_address.

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

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

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

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

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

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

لا تظهر PostNord عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقق من تحديد سعر للدولة (صف الدولة، أو صف *، أو Fallback cost)، وحدود الوزن، وMinimum subtotal، وDisabled shipping classes.

يقول المنتقي إن نقاط الخدمة لا يمكن تحميلها: تحقق من API key وإعداد Test mode. فمفتاح الإنتاج لا يعمل مع بيئة الاختبار، والعكس صحيح. فعّل Debug log وراجع WooCommerce > Status > Logs، المصدر "vfd-postnord". يمكن إتمام الطلب مع ذلك؛ وعندئذٍ تُسلّم PostNord الطرد إلى أقرب نقطة خدمة.

نقاط خدمة غير متوقعة: تحقق من Agreement country. فهو يحدد نقاط الخدمة المعروضة.

الشحن مجاني بالخطأ: تحقق من Country prices بحثًا عن صفوف بقيمة Price تساوي 0، ولا سيما صف * الذي أضفته بـ + Add country وتركته دون ملء، وتحقق من Free shipping from.

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

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

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

PostNord علامة تجارية مملوكة لصاحبها. هذا الملحق غير تابع لـ PostNord ولا تعتمده PostNord.