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

المتطلبات

PrestaShop: من 8.0 إلى 9.x، وسمة Classic أو Hummingbird (أو سمة مبنية عليهما).

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

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

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

التثبيت

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

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

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

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

عند التثبيت، تنشئ الوحدة شركتي شحن: PostNL pickup point بنص مدة التوصيل Delivery to a PostNL pickup point، وPostNL مع PostNL delivery to the home address. وترتبط الشركتان بمناطق هولندا وبلجيكا وبجميع مجموعات العملاء. ويمكنك إضافة مناطق وتغيير مجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

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

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

عام

PostNL pickup point: يفعّل شركة شحن نقطة الاستلام أو يعطّلها. يجب على العميل اختيار نقطة PostNL عند الدفع. ولا تُعرض إلا لعناوين هولندا وبلجيكا وفقط عند وجود مفتاح API. وهذا هو المفتاح نفسه لحالة شركة الشحن في Shipping > Carriers.

Pickup point carrier name: الاسم الذي يراه العميل عند الدفع. الافتراضي: PostNL pickup point. حقل مطلوب.

PostNL home address: يفعّل شركة شحن التوصيل إلى العنوان أو يعطّلها. لا تُختار أي نقطة. وتعمل لكل دولة لها سعر. وهو المفتاح نفسه لحالة شركة الشحن.

Home delivery carrier name: الاسم الذي يراه العميل عند الدفع. الافتراضي: PostNL. حقل مطلوب.

Tax status: قاعدة الضريبة لكلتا شركتي الشحن. تضيف القاعدة Taxable ضريبة الشحن الخاصة بها فوق الأسعار. أما None فتعني أن الأسعار نهائية.

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

API key: مفتاح API الخاص بـ PostNL من Mijn PostNL (My account > API beheren). يُرسل إلى PostNL في ترويسة "apikey"، ولا يُعرض للعملاء أبدًا ولا يُكتب في السجل. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط عند الرغبة في تغييرها.

Remove the saved API key: ضع علامة في المربع ثم انقر على Save لحذف المفتاح المحفوظ. بعد ذلك لن تُعرض شركة شحن نقطة الاستلام.

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

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

Ship from (postcode): الرمز البريدي للمرسل، مثل 1234AB في هولندا أو 1000 في بلجيكا. اتركه فارغًا لاستخدام الرمز البريدي للمتجر من Shop Parameters > Contact > Stores عندما يكون المتجر في الدولة نفسها. يُحفظ الرمز البريدي غير الصالح فارغًا مع تحذير. وعند تغيير مفتاح API أو إعداد sandbox أو عنوان الشحن، تُمسح قوائم نقاط الاستلام المخزنة مؤقتًا وآخر خطأ في API.

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

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

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"، والمبالغ التي تحتوي على فاصل آلاف مثل "1.234,50" أو "1,234.50". تُحذف الصفوف الفارغة ورموز الدول غير الصالحة عند الحفظ. إذا ظهرت دولة مرتين، يُحتفظ بالصف الأول. وتُتجاهل الأسعار غير الصالحة مع تحذير.

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). و0 يعني بلا حد. وإذا تركته فارغًا، يُطبَّق 30 كغ في مناطق شركات الشحن، ولا يُطبَّق "بلا حد" إلا على الدول التي تُبلغ عنها Ignore zones. ويُرفض الحد الأدنى للوزن إذا تجاوز الحد الأقصى، بخطأ، لأن شركات الشحن لن تظهر أبدًا.

تقبل جميع المبالغ والأوزان الفاصلة العشرية، حتى مع فاصل الآلاف. وتُتجاهل القيمة غير الصالحة أو السالبة مع تحذير، ويُحفظ الحقل فارغًا.

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

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

Ignore zones: اعرض PostNL أيضًا في الدول الواردة أدناه، التي لا تتضمنها مناطقه. عندها ترتبط شركات الشحن بكل منطقة نشطة، بما في ذلك المناطق التي تنشئها لاحقًا. وعند تعطيله مرة أخرى، تستعيد شركات الشحن المناطق التي كانت لها من قبل.

Countries: الدول الوجهة لهذا الوضع. اتركه فارغًا للسماح بجميع الدول. يُستخدم هذا الحقل فقط عند تفعيل Ignore zones. وفي هذه الدول يمكن عرض شركتي الشحن معًا؛ أما شركة نقطة الاستلام فتبقى مقتصرة على هولندا وبلجيكا.

متقدم

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

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

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

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

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

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

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

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

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

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

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

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

صفحة الطلب في لوحة الإدارة: كتلة PostNL pickup point تضم الاسم والعنوان وLocation code وPartner ID.

صفحتا تأكيد الطلب وتفاصيله: PostNL pickup point مع الاسم والعنوان.

رسائل البريد الإلكتروني للطلبات: يُضاف اسم النقطة وعنوانها إلى اسم شركة الشحن في رسالة تأكيد الطلب. كما تعرض رسالة الطلب الجديد للمتجر (وحدة Mail alerts) رمز الموقع.

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

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

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

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

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

لا يظهر PostNL عند الدفع: تحقق من أن الترخيص نشط وأن مفتاح شركة الشحن مفعّل. وفي Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعة العميل (أو أن Ignore zones مفعّل والدولة مسموح بها). وتحقق من تحديد سعر للدولة، وحدود الوزن، وMinimum subtotal. وقد تكون المنتجات مقصورة على شركات شحن معينة في صفحة المنتج.

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

"PostNL pickup points cannot be loaded right now": تعذر الوصول إلى PostNL، أو رفضت مفتاح API، أو الرمز البريدي للشحن مفقود. تعرض صفحة الوحدة آخر خطأ. ويعمل مفتاح sandbox فقط مع تفعيل Sandbox، ويعمل المفتاح الفعلي فقط مع تعطيله.

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

تبدو أوزان المنتجات غير صحيحة: إذا حذّرت صفحة الوحدة من أن وحدة وزن المتجر غير معروفة، فاضبط وحدة قياسية (kg أو g أو lb أو oz) في International > Localization ضمن Local units. وحتى ذلك الحين تُقرأ أوزان المنتجات بالكيلوغرام.

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

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

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

PostNL علامة تجارية مسجلة لمالكها. وهذه الوحدة غير تابعة لـ PostNL ولا معتمدة منها.