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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

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

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

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

6. أضف DHL Packstation إلى منطقة شحن (مثل ألمانيا) في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Shipping > DHL Packstation. وهي تنطبق على كل مناطق الشحن. عند إضافة الطريقة إلى منطقة، تحتوي نافذة المنطقة على حقل واحد فقط:

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

تُظهر التحذيرات فوق الإعدادات متى يكون مفتاح DHL API فارغًا، ومتى تكون إدخالات الأسعار حسب الدولة بصيغة غير صحيحة. وكلما حفظت الإعدادات تُمسح ذاكرة مواقع الاستلام المؤقتة.

عام

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

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

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

DHL Location Finder API

DHL API key: مفتاح API لتطبيقك على developer.dhl.com. بدونه تُخفى الطريقة في صفحة الدفع.

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

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

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

Search radius (meters): نطاق البحث حول الرمز البريدي أو المدينة المطلوبة. الافتراضي: 5000. تسمح DHL بما يصل إلى 25000 م.

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

Shipping address: يستخدم الموقع المختار كعنوان شحن للطلب. مفعّل افتراضيًا. يصبح سطر العنوان 1 مثلًا «Packstation 105»، ويصبح السطر 2 «Postnummer» مع الرقم، إضافة إلى الرمز البريدي والمدينة للموقع، حتى تصل الملصقات المطبوعة من الطلب إلى المكان الصحيح. ويُحفظ Postnummer أيضًا باسم _shipping_dhl_postnum، وهو الحقل الذي تقرؤه الإضافة الرسمية «DHL Shipping Germany for WooCommerce».

الأسعار

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: اعرض الطريقة فقط إذا كان المجموع الفرعي للسلة يساوي هذه القيمة على الأقل. اتركه فارغًا لعرضها دائمًا.

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

Ignore shipping zones: اعرض الطريقة للدول المذكورة أدناه حتى لو لم تكن منطقة الشحن المطابقة تتضمنها.

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

متقدم

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

Remove data on uninstall: عند التفعيل، يؤدي حذف الإضافة إلى إزالة إعداداتها وطرق مناطق الشحن الخاصة بها. ولا يحذف إلغاء التفعيل أي شيء. وتبقى مواقع الاستلام المختارة في الطلبات.

كيف تعمل في صفحة الدفع

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

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

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

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

عندما يختار العميل DHL Packstation، يظهر منتقٍ أسفل خيار الشحن. تُحمَّل مواقع DHL القريبة من الرمز البريدي أو المدينة الخاصة بالشحن. ويمكن للعميل البحث عن رمز بريدي أو مدينة أخرى. تُجمَّع المواقع حسب النوع (Packstation وPost Office وParcel Shop) وتُرتَّب حسب المسافة.

بالنسبة إلى Packstation، يجب على العميل إدخال DHL Postnummer، وهو رقم عميل DHL المكوّن من 6 إلى 12 رقمًا والموجود في تطبيق DHL أو حساب DHL. أما بالنسبة إلى المواقع الأخرى فهو اختياري. لا يمكن إتمام الطلب بدون موقع استلام، أو برقم Postnummer غير صالح. ويُتحقق من ذلك على الخادم، بما في ذلك صفحة الدفع القائمة على الكتل.

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

يُحفظ الموقع (المعرّف، النوع، الرقم، الاسم، العنوان) ورقم Postnummer في الطلب. ويظهران في شاشة الطلب أسفل عنوان الشحن، وفي صفحة الشكر، وفي My account > Orders، وفي رسائل الطلب الإلكترونية (HTML ونص عادي) باسم DHL pickup location وDHL Postnummer.

في شاشة الطلب، انقر Edit بجوار الموقع، وابحث بالرمز البريدي أو المدينة، واختر موقعًا آخر، وغيّر Postnummer، ثم انقر Save location. كل تغيير يضيف ملاحظة إلى الطلب. وإذا كان Shipping address مفعّلًا، يُحدَّث عنوان الشحن أيضًا. أعد تحميل الصفحة لرؤيته.

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

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

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

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

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

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

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

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

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

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

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

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

DHL وPackstation علامتان تجاريتان مسجّلتان لمالكيهما. هذه الإضافة غير تابعة لـ DHL ولا تحظى بتأييدها.