VibeFox DHL Packstation for PrestaShop — المساعدة

المتطلبات

PrestaShop: من 8.0 إلى 9.x. يدعم الوحدة قالبا Classic وHummingbird.

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

DHL API key: تأتي قائمة المواقع من واجهة DHL Location Finder API المجانية. سجّل في بوابة مطوّري DHL (developer.dhl.com)، وأنشئ تطبيقًا، وأضف واجهة «Location Finder - Unified»، وانسخ مفتاح API الخاص بالتطبيق. لا تتطلب هذه الواجهة عقدًا تجاريًا مع DHL. بدون المفتاح تُخفى شركة الشحن في الدفع. انتبه إلى حد الطلبات في تطبيق DHL الخاص بك: كل بحث جديد برمز بريدي أو مدينة يُحتسب طلب API واحدًا.

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

التثبيت

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

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

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

4. الصق مفتاح API الخاص بـ DHL، وانقر Save، ثم انقر Test API key. اختر أنواع المواقع وأدخل أسعار الدول (انظر الإعدادات).

عند التثبيت، تنشئ الوحدة شركة الشحن DHL Packstation مع نص مدة التوصيل Delivery to a DHL Packstation or post office. تكون شركة الشحن مفعّلة، ومعيَّنة لجميع مجموعات العملاء ولمناطق ألمانيا والنمسا (دول قائمة الأسعار الافتراضية). يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تُعيّن الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox DHL Packstation > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. إذا كان في أحد الحقول خطأ (رقم غير صالح أو سالب، أو Min weight (kg) أكبر من Max weight (kg)، أو اسم أطول من 64 حرفًا)، فلا يُحفظ شيء ويظهر الخطأ في الأعلى. كل حفظ يمسح ذاكرة التخزين المؤقت للمواقع.

تخبرك التحذيرات فوق الإعدادات بما يلي: عدم العثور على شركة الشحن؛ عدم معرفة الوحدة لوحدة وزن المتجر (International > Localization، Local units)، فتُقرأ الأوزان حينها كيلوغرامات (استخدم kg أو g أو lb أو oz)؛ فراغ مفتاح API الخاص بـ DHL؛ عدم تفعيل أي نوع من المواقع؛ وأن إدخالات أسعار الدول ليست بالصيغة CC:PRICE (وتُتجاهل هذه الإدخالات).

عام

تُحدَّد مجموعات العملاء والمناطق وحدود الحجم لشركة الشحن في Shipping > Carriers. تنطبق الإعدادات أدناه على جميع المناطق.

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

Name: اسم شركة الشحن الذي يراه العميل. الافتراضي: DHL Packstation. إلزامي، بحد أقصى 64 حرفًا.

Tax: قاعدة الضريبة الخاصة بشركة الشحن، أو No tax. تضيف PrestaShop هذه الضريبة إلى الأسعار أدناه. مع No tax تكون الأسعار نهائية.

DHL Location Finder API

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

Remove the saved API key: حدد هذا المربع واحفظ لحذف المفتاح المحفوظ.

Connection test: يبحث زر Test API key عن المواقع القريبة من 53113 Bonn باستخدام المفتاح المحفوظ، ويمسح ذاكرة التخزين المؤقت للمواقع. احفظ الإعدادات أولًا. يعرض عدد المواقع التي وُجدت، أو رفض DHL للمفتاح (401/403)، أو عدم الرد الصحيح من API (التفاصيل في سجل تصحيح الأخطاء).

مواقع الاستلام

في الدفع يرى العميل المواقع القريبة من الرمز البريدي للتوصيل، ويمكنه البحث عن رمز بريدي أو مدينة أخرى.

Location types: مواقع DHL التي يمكن للعميل اختيارها: Packstation (parcel locker) وPost Office (Postfiliale) وDHL Parcel Shop (Paketshop). الثلاثة مفعّلة افتراضيًا. إذا لم يُحدَّد أي منها، تُخفى شركة الشحن. بالنسبة إلى Packstation يجب على العميل إدخال DHL Postnummer الخاص به.

Search radius (meters): نصف القطر حول الرمز البريدي أو المدينة المبحوث عنهما. الافتراضي: 5000. عدد صحيح؛ القيم الأقل من 100 أو الأكبر من 25000 م (الحد الأقصى لـ DHL) تُعدَّل إلى هذا الحد.

Max results: الحد الأقصى لعدد المواقع المعروضة في كل بحث. الافتراضي: 20. عدد صحيح؛ تسمح DHL بما يصل إلى 50، والقيم الأكبر تُخفَّض إلى 50.

Shipping address: يستخدم الموقع المختار عنوان توصيل الطلب. مفعّل افتراضيًا. يصبح السطر 1 من العنوان مثلًا «Packstation 105» (أو «Postfiliale 502» لمكتب بريد أو Parcel Shop)، ويصبح السطر 2 «Postnummer» مع الرقم، مع الرمز البريدي والمدينة والدولة الخاصة بالموقع، حتى تصل الملصقات المطبوعة من الطلب إلى المكان الصحيح. يأتي الاسم والشركة والهاتف من عنوان العميل. يُستخدم العنوان الجديد في الطلب فقط ولا يظهر في دفتر عناوين العميل.

الأسعار (يعرض عنوان القسم العملة الافتراضية لمتجرك)

Country prices: السعر لكل دولة وجهة بعملة المتجر الافتراضية، دون الضريبة، بصيغة CC:PRICE، مفصولة بفواصل أو أسطر جديدة. الافتراضي: DE:4.99، AT:5.99. تعمل الفاصلة العشرية أيضًا (DE:4,99).

Other countries: السعر لدولة وجهة غير موجودة في Country prices. الافتراضي: 5.99. اتركه فارغًا لإخفاء شركة الشحن لتلك الدول.

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

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

التوفر

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

Max weight (kg): تُخفى شركة الشحن فوق وزن السلة هذا. الافتراضي: 31.5، لأن Packstation يستقبل طرودًا حتى 31.5 كجم. القيمة 0 تعني لا حد.

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

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

Countries (ignore zones): الدول الوجهة لهذا الوضع. انقر مع Ctrl/Cmd لاختيار عدة دول. يُستخدم فقط مع Ignore shipping zones.

متقدم

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

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

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

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

في خطوة التوصيل تطلب PrestaShop من الوحدة سعر DHL Packstation. تُحتسب المنتجات المادية فقط: المنتجات الافتراضية لا تضيف وزنًا ولا تُدرج في المجموع الفرعي. تتحقق الوحدة من أن مفتاح API ونوع موقع واحد على الأقل مضبوطان، والدول المسموح بها (مع Ignore shipping zones)، ووزن السلة، والحد الأدنى للمجموع الفرعي. ثم تأخذ سعر الدولة الوجهة (أو سعر الدول الأخرى)، وتطبّق الشحن المجاني إذا كان المجموع الفرعي مرتفعًا بما يكفي. يُحسب السعر بعملة المتجر الافتراضية ويُعرض بعملة سلة العميل.

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

لا تنشئ الوحدة شحنات DHL، ولا تطبع الملصقات، ولا تتتبع الطرود. استخدم بوابة عملاء DHL التجارية أو أداة ملصقات: مع تفعيل Shipping address يحتوي الطلب بالفعل على عنوان Packstation وPostnummer. لا تحسب الوحدة أسعار DHL الفورية ولا تعرض خريطة. لا يوجد إدخال يدوي لرقم Packstation.

مواقع الاستلام

عندما يختار العميل DHL Packstation يظهر منتقٍ أسفل شركة الشحن. تُحمَّل مواقع DHL القريبة من الرمز البريدي والمدينة الخاصين بالتوصيل. يُسأل DHL عن شركة الشحن المختارة فقط. يمكن للعميل كتابة رمز بريدي أو مدينة أخرى والنقر على Search. تُجمَّع المواقع حسب النوع (Packstation وPost Office وParcel Shop) وتُرتَّب حسب المسافة. إذا لم يُعثر على شيء، يرى العميل No DHL locations found near "…". Try another postcode or city.

بالنسبة إلى Packstation يجب على العميل إدخال DHL Postnummer، وهو رقم العميل لدى DHL المكوّن من 6-12 رقمًا، من تطبيق DHL أو من حساب DHL. أما بالنسبة إلى المواقع الأخرى فهو اختياري. يُحفظ الاختيار في السلة فور إجرائه. عند النقر على Continue يتحقق الخادم منه مرة أخرى: يجب أن يكون الموقع أحد نتائج بحث DHL في دولة التوصيل. بدون موقع يرى العميل Please choose a DHL Packstation or post office for delivery. ولا يستطيع المتابعة. يُبلَّغ عن Postnummer المفقود أو غير الصالح بالطريقة نفسها.

تُخزَّن نتائج البحث مؤقتًا لمدة 12 ساعة. يُخزَّن البحث الفارغ أو الفاشل مؤقتًا لمدة 10 دقائق، حتى لا ينتظر الدفع DHL عند كل تحديث. مهلة API هي 12 ثانية. إذا تعذّر الوصول إلى واجهة DHL، يرى العميل DHL locations cannot be loaded right now. Please try again later or choose another shipping method. ويظل الموقع الذي اختاره العميل من قبل مقبولًا.

عند تنفيذ الطلب يُحفظ الموقع (المعرّف والنوع والرقم والاسم والعنوان) وPostnummer مع الطلب. إذا كان Shipping address مفعّلًا، يُستبدل عنوان التوصيل في الطلب بعنوان الموقع. يظهر الموقع في صفحة تأكيد الطلب، وفي Order history and details في حساب العميل، وفي بريد تأكيد الطلب وبريد الطلب الجديد الخاص بوحدة Mail alerts، مع إضافة التسميتين DHL pickup location وDHL Postnummer إلى اسم شركة الشحن.

في صفحة الطلب في الواجهة الخلفية يعرض مربع DHL pickup location الموقع ونوعه ومعرّفه، وكذلك Postnummer. انقر Change، وابحث بالرمز البريدي أو المدينة، واختر موقعًا آخر، وغيّر Postnummer، ثم انقر Save location. يمكنك أيضًا تغيير Postnummer وحده. يضيف كل تغيير رسالة خاصة إلى الطلب: DHL pickup location changed to: …. إذا كان Shipping address مفعّلًا، يُحدَّث عنوان توصيل الطلب أيضًا. يتطلب تغيير الموقع صلاحية تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات الوحدات. إذا أُنشئت عدة طلبات من السلة نفسها، فالموقع يخص الطلب الأول فقط؛ والنقر على Change في طلب آخر من السلة نفسها يعرض The DHL location of this cart belongs to another order of the same cart - nothing was changed.

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

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

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

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

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

لا تظهر DHL Packstation في الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. في Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته (أو فعّل Ignore shipping zones وتحقق من Countries (ignore zones)). تحقق من أن DHL API key مملوء، وأن نوع موقع واحد على الأقل مختار، وأن للدولة الوجهة سعرًا (أو أن Other countries مضبوط)، وأن قواعد الوزن والمجموع الفرعي لا تُخفيها. قد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج أيضًا.

لا تظهر أي مواقع: انقر Test API key. إذا رفض DHL المفتاح (401/403)، فتحقق من المفتاح ومن وجود واجهة «Location Finder - Unified» في تطبيقك. فعّل Debug log، وأعد تحميل الدفع، وانظر إلى حقل Log في صفحة الوحدة. تحقق من أنك لم تصل إلى حد الطلبات في تطبيق DHL الخاص بك.

لا توجد مواقع قرب عنوان: زِد Search radius (meters) أو Max results، أو دع العميل يبحث عن رمز بريدي أو مدينة أخرى. لا يُدرج Packstation بلا رقم في بيانات DHL.

يرى العميل «Enter your postcode or city to see DHL locations near you.»: عنوان التوصيل لا يحتوي على رمز بريدي ولا على مدينة. يمكن للعميل كتابة أحدهما في حقل البحث.

يقول Change في صفحة الطلب «Please choose a DHL location of the search - nothing was changed.»: ابحث بالرمز البريدي أو المدينة، واختر موقعًا من النتائج. إذا لم يكن للطلب موقع بعد، فيجب اختيار موقع قبل أن يمكن حفظ Postnummer.

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

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

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

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