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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 5.0 أو أحدث، مثبت ومفعّل. ترفض الإضافة التفعيل بدونه.

PHP: 8.0 أو أحدث.

حساب DHL Express (للأسعار الفورية فقط): تستخدم الأسعار الفورية واجهة MyDHL API. تحتاج إلى رقم حساب DHL Express وبيانات اعتماد MyDHL API: مفتاح API وسر API. اطلبها من بوابة مطوري DHL (MyDHL API، "Get access") أو من مدير حسابك لدى DHL Express. يمكن للحسابات التي ما زالت لديها بيانات اعتماد DHL XML Services (Site ID وكلمة المرور) استخدامها بدلًا من ذلك. وإذا كنت تستخدم الأسعار الاحتياطية فقط فلا تحتاج إلى بيانات اعتماد DHL.

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

التثبيت

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

2. انقر Activate.

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

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

5. اختر DHL API، وأدخل مفتاح API والسر ورقم حسابك لدى DHL. أبقِ Test mode مفعّلًا أثناء استخدام بيانات اعتماد الاختبار. أدخل عنوان Ship from. إذا لم يكن حساب DHL لديك مفوترًا بعملة متجرك، فاضبط DHL quote currency وExchange rate. واختياريًا اضبط أسعار الدول والتكلفة الاحتياطية (راجع قسم الإعدادات).

6. أضف DHL Express Africa إلى مناطق الشحن في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

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

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

تخبرك التحذيرات فوق الإعدادات متى تكون الأسعار الفورية متوقفة بسبب نقص بيانات الاعتماد أو المنشأ، ومتى تُحدَّد عملة عرض دون سعر صرف. في كل مرة تحفظ فيها الإعدادات تُمسح عروض DHL المخزنة مؤقتًا. وتقبل الأسعار والأوزان الفاصلة العشرية كنقطة أو كفاصلة.

عام

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

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

Tax status: Taxable (مع تفعيل ضرائب WooCommerce) يأخذ سعر DHL دون الضريبة التي تعرضها DHL، ويضيف WooCommerce ضريبته الخاصة. None يحتسب سعر DHL كما هو معروض، شاملًا الضريبة.

حساب DHL Express (مطلوب للأسعار الفورية فقط)

DHL API: واجهة DHL المستخدمة. تظهر فقط حقول الواجهة المختارة.

API key: اسم المستخدم في MyDHL API (مفتاح API).

API secret: كلمة المرور في MyDHL API (سر API).

XML Site ID: معرّف الموقع في DHL XML Services (للواجهة القديمة فقط).

XML password: كلمة مرور DHL XML Services (للواجهة القديمة فقط).

DHL account number: رقم حسابك لدى DHL Express (9 أرقام). تتطلبه MyDHL API. ومع XML Services يعيد أسعار حسابك بدلًا من الأسعار المنشورة.

Test mode: استخدام بيئة الاختبار لدى DHL. مفعّل افتراضيًا. تعمل بيانات اعتماد الاختبار في بيئة الاختبار فقط، وبيانات اعتماد الإنتاج في الإنتاج فقط. أوقفه عند الانتقال إلى الإنتاج.

الشحن من

العنوان الذي تستلم منه DHL الطرود. ويعتمد السعر عليه.

Origin country: الدولة التي تشحن منها.

Origin city: المدينة التي تشحن منها، مثل جوهانسبرغ. تتطلبها MyDHL API.

Origin postcode: اتركه فارغًا للدول التي لا تستخدم الرمز البريدي (مثل كينيا ونيجيريا وغانا).

الأسعار

كل الأسعار بعملة متجرك. السعر الفوري هو أرخص منتج DHL Express للطرد. إذا لم تكن DHL مُعدّة، أو فشلت، أو لم تتوفر لها خدمة للمسار، يُستخدم سعر الدولة ثم التكلفة الاحتياطية. وإن لم يتوفر أي منهما تُخفى الطريقة.

DHL quote currency: تُسعّر DHL بعملة دولة حسابك لدى DHL (مثل ZAR أو NGN أو KES). إذا لم تُرجع DHL مبلغًا بعملة متجرك، يُحوَّل السعر الفوري من هذه العملة بسعر الصرف أدناه. وإلا فلا يُستخدم.

Exchange rate: قيمة وحدة واحدة من عملة عرض DHL بعملة متجرك، مثل 1 ZAR = 0.05. اتركه فارغًا لعدم التحويل. هذا السعر يُدخل يدويًا.

Fallback cost: تكلفة ثابتة عند غياب السعر الفوري وسعر الدولة. اتركه فارغًا لإخفاء الطريقة.

Country prices: سعر احتياطي لكل دولة وجهة، سطر لكل دولة بالصيغة CC:Price، مثل ZA:25.00. يُستخدم عند غياب السعر الفوري.

Fallback price basis: Per order يحتسب السعر مرة واحدة. Per item (multiplied by the cart quantity) يضربه في عدد القطع. ينطبق على سعر الدولة والتكلفة الاحتياطية فقط. أما السعر الفوري من DHL فيكون دائمًا للطرد كاملًا.

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

الشروط

Minimum weight (kg): إخفاء الطريقة إذا كان وزن السلة أقل من هذا الحد. 0 يعني بلا حد.

Maximum weight (kg): إخفاء الطريقة إذا كان وزن السلة أعلى من هذا الحد. الافتراضي: 70. 0 يعني بلا حد.

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

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

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

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

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

متقدم

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

Remove data on uninstall: عند التفعيل، يحذف إلغاء تثبيت الإضافة إعداداتها وطرق مناطق الشحن. أما إلغاء تفعيل الإضافة فلا يحذف أي بيانات أبدًا.

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

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

وإلا فإن الإضافة ترسل إلى DHL المنشأ والوجهة (الدولة والمدينة والرمز البريدي)، ووزن السلة محوَّلًا إلى كيلوغرامات (0.5 كجم على الأقل)، وصندوقًا واحدًا مبنيًا من أبعاد المنتجات بالسنتيمتر: أطول طول، وأعرض عرض، والارتفاعات مكدسة فوق بعضها. المنتجات التي لا أبعاد لها لا تضيف شيئًا. وإذا لم تكن لأي منتج أبعاد، يُستخدم صندوق بمقاس 10 × 10 × 10 سم. يُصرَّح عن الشحنات الدولية كبضائع، بالمجموع الفرعي للسلة كقيمة معلنة، حتى تسعّر DHL منتجات الطرد. ولا يُصرَّح عن الشحنات المحلية. ولا يُطلب السعر الفوري إلا بعد أن يدخل العميل المدينة (مع XML Services، مدينة أو رمز بريدي).

يُعرض أرخص منتج DHL Express كسعر واحد بالاسم الذي حددته. ولا يرى العميل منتج DHL ولا مدة التوصيل. يُحفظ اسم المنتج (مثل "EXPRESS WORLDWIDE (P)") باسم DHL product في بند الشحن الخاص بالطلب، لتعرف ما الذي ستحجزه.

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

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

تحسب الإضافة الأسعار فقط. فهي لا تنشئ شحنات DHL، ولا تطبع ملصقات أو فواتير تجارية، ولا تحجز مواعيد استلام، ولا تتتبع الطرود، ولا تعرض نقاط خدمة DHL، ولا تتيح للعميل الاختيار بين منتجات DHL، ولا تجمع عدة صناديق، ولا تضيف تأمينًا، ولا تحسب الرسوم الجمركية والضرائب. عرض السعر للشحن فقط. ويدفع المستلم الرسوم الجمركية وضرائب الاستيراد.

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

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

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

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

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

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

DHL Express لا يظهر عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة شحن دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموحة). تحقق من حدود الوزن وMinimum subtotal وExcluded shipping classes. بدون سعر فوري تظهر الطريقة فقط إذا كان سعر دولة أو تكلفة احتياطية مضبوطًا.

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

تعيد DHL السعر بـ ZAR أو NGN أو KES لكن متجري يستخدم عملة أخرى: اضبط DHL quote currency على تلك العملة وأدخل Exchange rate. بدونه لا يُستخدم السعر الفوري وتُطبَّق الأسعار الاحتياطية.

لدي بيانات اعتماد DHL XML Services قديمة: اختر XML Services (legacy) في DHL API. وانتقل إلى MyDHL API عند استلام بيانات اعتماد MyDHL.

الضريبة تُحتسب مرتين على الشحن: اضبط Tax status على Taxable ليُؤخذ سعر DHL دون ضريبة DHL، أو على None لاحتساب مبلغ DHL كما هو معروض.

الأسعار تبدو قديمة بعد تغيير: احفظ صفحة الإعدادات. وهذا يمسح عروض DHL المخزنة مؤقتًا.

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

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

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

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