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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

4. الصق API key من PostNord، واختر Agreement country، واملأ Country prices (راجع الإعدادات)، ثم انقر على Save.

عند التثبيت ينشئ الملحق شركتي شحن. PostNord يسلّم إلى نقطة خدمة، مع نص مدة التوصيل Delivery to a PostNord service point. وهي مفعّلة. أما PostNord Home delivery فيسلّم إلى العنوان، مع النص PostNord home delivery. وتبقى معطّلة حتى تفعّل Home delivery. وكلتا الشركتين مرتبطتان بمناطق السويد والدنمارك والنرويج وفنلندا وبجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ونص مدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الملحق.

الإعدادات

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

فوق الإعدادات تنبّه الصفحة إذا لم يكن هناك مفتاح API بعد، أو لم يُحدَّد سعر بعد، أو إذا حُذفت شركة شحن من PostNord، أو إذا كانت وحدة وزن المتجر غير معروفة للملحق. في هذه الحالة تُحسب أوزان المنتجات بالكيلوغرام. استخدم kg أو g أو lb أو oz في International > Localization (Local units).

عام

Enable/Disable: يفعّل شركة شحن نقطة الخدمة أو يعطّلها. وهو المفتاح نفسه الموجود في حالة شركة الشحن في Shipping > Carriers.

Name: اسم شركة شحن نقطة الخدمة عند الدفع، على سبيل المثال "PostNord MyPack Collect". القيمة الافتراضية: PostNord. حقل إلزامي.

Home delivery: يعرض أيضًا خدمة التوصيل إلى المنزل من PostNord. وهي شركة الشحن الثانية، من دون نقطة خدمة. وهي معطّلة افتراضيًا.

Home delivery name: اسم شركة شحن التوصيل إلى المنزل عند الدفع، على سبيل المثال "PostNord MyPack Home". القيمة الافتراضية: PostNord Home delivery. حقل إلزامي.

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

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

API key: مفتاح API لتطبيقك على developer.postnord.com. يُرسل إلى PostNord من خادمك فقط، ولا يُرسل إلى المتصفح أبدًا، ولا يُكتب في السجل. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره.

Remove the saved API key: حدّد المربع ثم انقر على Save لحذف المفتاح المحفوظ.

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

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

الأسعار

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

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

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

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

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

التوفر

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

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

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

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

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

تقبل المبالغ والأوزان الفاصلة أو النقطة. والقيمة التي ليست رقمًا يساوي 0 أو أكبر لا تُحفظ، وتظهر رسالة.

متقدم

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

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

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

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

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

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

لجهات الوصول الأخرى يمكن أن تُعرض شركات الشحن بأسعارك دون منتقٍ. ولا تعرض شركة التوصيل إلى المنزل المنتقي أبدًا.

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

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

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

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

عند تحميل القائمة يكون اختيار نقطة إلزاميًا. ومن دون اختيار يتوقف Continue مع الرسالة "يرجى اختيار نقطة خدمة PostNord." ويُتحقق من النقطة المختارة على الخادم مقابل قائمة PostNord لعنوان التوصيل. ولا تُستخدم نقطة اختيرت لرمز بريدي آخر.

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

صفحة الطلب في لوحة الإدارة: كتلة PostNord service point تضم الاسم والعنوان وService point ID. وإذا لم تُختر نقطة، تظهر العبارة "لم تُحدَّد - يسلّم PostNord الطرد إلى نقطة الخدمة الأقرب إلى عنوان الشحن".

تأكيد الطلب وتفاصيله لدى العميل: PostNord service point: مع الاسم والعنوان.

رسائل الطلبات الإلكترونية: رسالة تأكيد الطلب التي تُرسل إلى العميل، وتنبيه الطلب الجديد الذي يُرسل إلى المتجر، تعرضان اسم النقطة وعنوانها ومعرّفها بجانب اسم شركة الشحن. ويعرض تنبيه المتجر أيضًا "not selected" عندما لا توجد نقطة.

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

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

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

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

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

لا تظهر PostNord عند الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable (أو Home delivery) مفعّل. وفي Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته، أو فعّل Ignore shipping zones. تحقق من وجود سعر للدولة (صف الدولة أو صف * أو Fallback cost) وحدود الوزن وMinimum subtotal. وقد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج.

يقول المنتقي إنه لا يمكن تحميل نقاط الخدمة: تحقق من API key ومن إعداد Test mode. فمفتاح الإنتاج لا يعمل مع بيئة الاختبار، والعكس صحيح. فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى الحقل Log في صفحة الملحق. يمكن إتمام الطلب مع ذلك؛ فعندئذ يسلّم PostNord إلى أقرب نقطة خدمة.

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

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

تبدو نقاط الخدمة قديمة بعد تغيير: انقر على Save في صفحة الملحق. فهذا يمسح القوائم المخزنة مؤقتًا.

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

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

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

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