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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

مفتاح API الخاص بـ PostNL (لنقاط الاستلام فقط): تُحمَّل نقاط الاستلام من PostNL Checkout API. يجد عملاء PostNL من الشركات مفتاح API في Mijn PostNL ضمن My account > API beheren. تحتاج بيئة sandbox التابعة لـ PostNL إلى مفتاح sandbox منفصل. ولا تحتاج طرق التوصيل إلى العنوان إلى أي مفتاح.

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

التثبيت

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

2. انقر Activate.

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

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

5. املأ الأسعار. وبالنسبة إلى نقاط الاستلام، أدخل أيضًا API key الخاص بـ PostNL وShip from (postcode) (انظر الإعدادات).

6. أضف VibeFox PostNL إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones، مثل هولندا وبلجيكا. وفي المنطقة، حدد Title وDelivery to. أضف الطريقة مرة ثانية لنوع التوصيل الآخر.

الإعدادات

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

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

Delivery to (zone): As in the global settings (الافتراضي)، أو PostNL pickup point (customer chooses a point)، أو Home address. أضف الطريقة مرتين إلى منطقة لعرض الخيارين معًا.

تعرض الصفحة فوق الإعدادات تحذيرات: مفتاح API أو الرمز البريدي للشحن غير موجود لنقاط الاستلام، أو تفعيل sandbox، أو عدم تحديد أي سعر، وآخر طلب فاشل إلى PostNL مع تاريخه وخطئه.

عام

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

Name: اسم طريقة الشحن الذي يظهر عند الدفع. ويحل محله Title المحدد في المنطقة. الافتراضي: PostNL.

Delivery to: نوع التوصيل الافتراضي لطرق المناطق التي تستخدم As in the global settings، ولوضع Ignore zones.

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

واجهة PostNL API (نقاط الاستلام) (غير مطلوبة للتوصيل إلى العنوان)

API key: مفتاح API الخاص بـ PostNL من Mijn PostNL (My account > API beheren). يُرسل إلى PostNL في ترويسة "apikey"، ويُخزَّن في قاعدة بيانات WordPress، ولا يظهر للعملاء ولا يُكتب في السجل أبدًا.

Sandbox: يستخدم بيئة sandbox الخاصة بـ PostNL (api-sandbox.postnl.nl) مع مفتاح API للـ sandbox. وعندها يرى العملاء نقاط استلام تجريبية. أبقه معطّلًا في المتجر الحي.

Ship from (country): الدولة التي تسلّم منها طرودك إلى PostNL: هولندا أو بلجيكا. وهي افتراضيًا دولة متجرك. تستخدم PostNL عنوان المُرسِل لتحديد تاريخ الاستلام.

Ship from (postcode): الرمز البريدي للمُرسِل، مثل 1234AB في هولندا أو 1000 في بلجيكا. اتركه فارغًا لاستخدام الرمز البريدي للمتجر من WooCommerce > Settings > General عندما يكون المتجر في الدولة نفسها. يُرفض الرمز البريدي غير الصالح مع رسالة. وعند تغيير مفتاح API أو إعداد sandbox أو عنوان الشحن، تُمسح قوائم نقاط الاستلام المخزنة مؤقتًا.

الأسعار (بعملة المتجر)

لا تتوفر لدى PostNL واجهة برمجة عامة لأسعار الشحن، ولذلك لا تطلب الإضافة الأسعار الفورية ولا تحوّل الأسعار أبدًا.

Price per country: صف واحد لكل دولة وجهة. انقر + Add country لإضافة صف، والعلامة × لحذف صف. اختر * All other countries لصف يغطي كل دولة ليس لها صف خاص. ولكل صف Price وفئات وزن اختيارية حسب وزن السلة: XS حتى 1 كغ، وS حتى 2 كغ، وM حتى 3 كغ، وL حتى 5 كغ، وXL أكثر من 5 كغ. ويتجاوز سعر فئة الوزن الحقل Price؛ اتركه فارغًا لاستخدام Price. والسعر Price بقيمة 0 يعني شحنًا مجانيًا. ويُقبل كل من "6.95" و"6,95". تُحذف الصفوف الفارغة ورموز الدول غير الصالحة عند الحفظ. وإذا ظهرت دولة مرتين، يُحتفظ بالصف الأول. وتُتجاهل الأسعار غير الصالحة مع رسالة.

Calculation: Per order يحصّل السعر مرة واحدة. أما Per item (price x quantity) فيضربه في عدد العناصر القابلة للشحن في السلة.

Price for other countries: يُستخدم عندما لا يحتوي الجدول على الدولة ولا على صف *. اتركه فارغًا لإخفاء الطريقة هناك.

الشروط

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

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

Minimum weight (kg): أخفِ الطريقة عندما يكون وزن السلة أقل من ذلك. تُحوَّل أوزان المنتجات من وحدة متجرك. اتركه فارغًا لعدم وجود حد.

Maximum weight (kg): أخفِ الطريقة للسلات الأثقل. الافتراضي: 30 (تصل طرود PostNL إلى 30 كغ في Benelux). اتركه فارغًا لعدم وجود حد.

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

تقبل جميع المبالغ والأوزان الفاصل العشري بالفاصلة، وكذلك مع فاصل الآلاف (1.234,50 أو 1,234.50). يُتجاهل الرقم غير الصالح مع رسالة.

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

Ignore zones: اعرض PostNL أيضًا للدول المذكورة أدناه عندما لا تضيفه أي منطقة. وتستمر المناطق التي تحتوي الطريقة في العمل كالمعتاد. يستخدم هذا الوضع Name وDelivery to العامَّين.

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

متقدم

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

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

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

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

تُعرض طريقة نقطة الاستلام فقط لعناوين هولندا وبلجيكا، وفقط عند وجود مفتاح API. فور أن يُدخل العميل رمزًا بريديًا صالحًا، تطلب الإضافة من PostNL Checkout API أقرب نقاط الاستلام. وترسل الرمز البريدي للعميل وشارعه ورقم منزله ومدينته ودولته، إضافةً إلى عنوان الشحن الخاص بمتجرك. ولا يُرسل شيء لطرق التوصيل إلى العنوان. وإذا تعذر الوصول إلى PostNL أو لم تُرجع نقاط لذلك العنوان، فتُخفى طريقة نقطة الاستلام وتبقى طرقك الأخرى متاحة. ومهلة API هي 12 ثانية.

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

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

لا تطلب الإضافة أسعار PostNL الفورية، ولا تنشئ ملصقات شحن أو باركودًا أو track and trace أو مرتجعات أو إشعارات مسبقة. ولا تتضمن خيارات ليوم التسليم أو التسليم المسائي أو الصباحي. أنشئ الشحنة في Mijn PostNL أو أي أداة أخرى من PostNL باستخدام نقطة الاستلام المحفوظة.

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

عندما يختار العميل طريقة نقطة الاستلام، تظهر أسفلها قائمة PostNL pickup point بأقرب ثلاث نقاط: اسم الشركة والعنوان والمسافة. قبل إدخال الرمز البريدي، يرى العميل الرسالة "أدخل رمزك البريدي (مثال 1234 AB) لعرض نقاط استلام PostNL." (4 أرقام لبلجيكا). ويُحفظ الاختيار عند تحديث صفحة الدفع.

النقطة إلزامية. وبدونها تتوقف صفحة الدفع مع الرسالة "يرجى اختيار نقطة استلام PostNL." ويُقارن الخادم النقطة بقائمة PostNL لعنوان الشحن. فإن لم تكن في القائمة، تتوقف صفحة الدفع مع الرسالة "نقطة استلام PostNL المختارة غير متاحة لهذا العنوان. يرجى اختيارها مرة أخرى." ويأتي الاسم والعنوان المحفوظان مع الطلب من PostNL، لا من المتصفح.

شاشة الطلب في لوحة الإدارة: PostNL pickup point مع الاسم والعنوان وLocation code، أسفل عنوان الشحن.

صفحة شكر الطلب وعرض الطلب في «حسابي»: PostNL pickup point مع الاسم والعنوان.

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

في قاعدة البيانات تُحفظ النقطة في بيانات الطلب الوصفية _vfd_ptnl_servicepoint_id (رمز موقع PostNL)، و_vfd_ptnl_servicepoint_name (الاسم والعنوان)، و_vfd_ptnl_servicepoint (معرّف الشريك، والشركة، والشارع، ورقم المنزل، والرمز البريدي، والمدينة، والدولة).

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

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

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

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

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

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

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

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

"لا يمكن تحميل نقاط استلام PostNL الآن": تعذر الوصول إلى PostNL، أو رفض مفتاح API، أو الرمز البريدي للشحن مفقود. تعرض شاشة الإعدادات آخر خطأ. ويعمل مفتاح sandbox فقط مع تفعيل Sandbox، ويعمل المفتاح الحي فقط مع تعطيله.

يرى العملاء نقاط استلام تجريبية: عطّل Sandbox.

مرشحات للمطورين: vfd_ptnl_number_of_locations (الافتراضي 3)، وvfd_ptnl_checkout_request (نص الطلب)، وvfd_ptnl_api_url.

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

الإزالة

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

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