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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتداد cURL. ترفض الوحدة التثبيت على إصدارات PHP الأقدم أو دون cURL. وتحتاج DHL XML Services أيضًا إلى امتداد SimpleXML في PHP.

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

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

التثبيت

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

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

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

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

عند التثبيت، تنشئ الوحدة شركة الشحن DHL Express بنص مدة التوصيل DHL Express courier. وتُعيَّن شركة الشحن لجميع المناطق ولجميع مجموعات العملاء. ويمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. ولا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

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

تخبرك التحذيرات في أعلى الصفحة متى تكون الأسعار الفورية متوقفة، لأن API key أو API secret أو رقم الحساب مفقود (أو، مع XML Services، Site ID أو كلمة المرور)، ومتى يكون بلد الشحن أو مدينته مفقودًا، ومتى تكون XML Services مختارة (تقوم DHL بإيقافها)، ومتى تُضبط عملة عرض سعر دون سعر صرف، ومتى تكون وحدة الوزن أو الأبعاد للمتجر في International > Localization (Local units) غير معروفة للوحدة (فتُعامل عندئذ كـ kg أو cm). وإذا كانت قيمة غير صالحة عند الحفظ (اسم فارغ أو أطول من 64 حرفًا، أو رقم غير صالح أو سالب، أو سعر صرف 0، أو الحد الأدنى للوزن أعلى من الحد الأقصى، أو عملة العرض، أو بلد الشحن، أو قاعدة الضريبة)، فيوضح خطأ الحقل المعني، وتُحتفظ القيمة السابقة لذلك الحقل، وتُحفظ الإعدادات الأخرى.

عام

Enable DHL Express Africa: يُفعّل شركة الشحن أو يُعطّلها. وهو المفتاح نفسه الخاص بحالة شركة الشحن في Shipping > Carriers.

Name: اسم شركة الشحن الذي يراه العميل عند الدفع. الافتراضي: DHL Express. مطلوب، حتى 64 حرفًا.

Tax: قاعدة الضريبة لشركة الشحن، أو No tax. مع قاعدة ضريبة (وتفعيل الضرائب في المتجر) يُؤخذ سعر DHL دون الضريبة التي تعرضها DHL، ويضيف PrestaShop ضريبته الخاصة. ومع No tax يُحتسب سعر DHL كما عُرض، متضمنًا الضريبة.

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

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

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

API secret: كلمة مرور MyDHL API الخاصة بك (سر API). بعد الحفظ، تبقى حقول API key وAPI secret فارغة وتعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Remove the saved API key and API secret: يظهر فقط عندما يكون هناك مفتاح أو سر محفوظ. فعّله ثم انقر على Save لحذفهما معًا.

XML Site ID: Site ID الخاص بـ DHL XML Services (للواجهة القديمة فقط). مسحه يحذف أيضًا كلمة مرور XML المحفوظة.

XML password: كلمة مرور DHL XML Services (للواجهة القديمة فقط). وكما في API secret، لا تُعرض مرة أخرى بعد الحفظ.

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

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

Ship from

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

Origin country: البلد الذي تشحن منه.

Origin city: المدينة التي تشحن منها، مثلًا Johannesburg. تتطلبها MyDHL API.

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

الأسعار

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

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

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

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: يُخفي شركة الشحن إذا كان وزن السلة أقل من هذا الحد، بالكيلوغرام. 0 تعني دون حد. ولا يمكن أن يكون أكبر من Maximum weight.

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

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

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

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

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

متقدم

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

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

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

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر DHL Express. ولا تُحتسب إلا المنتجات المادية: فالمنتجات الافتراضية لا تضيف وزنًا ولا تدخل في المجموع الفرعي. تتحقق الوحدة أولًا من الشروط: دول Ignore shipping zones، ووزن السلة، والحد الأدنى للمجموع الفرعي. وإذا انطبق الشحن المجاني، فالسعر 0 ولا يُرسل أي طلب إلى DHL.

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

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

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

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

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

الطلبات

عند تقديم الطلب، تحتفظ الوحدة بالسعر المحسوب لسلته. ثم تعرض صفحة الطلب في لوحة الإدارة كتلة DHL Express Africa، لتعرف ما الذي تحجزه لدى DHL:

DHL product: منتج DHL Express من السعر الفوري، مثلًا "EXPRESS WORLDWIDE (P)". ويظهر فقط للأسعار الفورية.

Price source: Live DHL rate، أو Fallback price (no live rate)، أو Free shipping threshold.

Calculated price (excl. tax): السعر بعملة المتجر الافتراضية.

ولا تغيّر عمليات إعادة حساب السلة اللاحقة، مثلًا عند تعديل الطلب في لوحة الإدارة، هذه القيم. وتُحذف أسعار السلال التي لم تتحول إلى طلبات بعد 30 يومًا.

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

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

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

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

لا تظهر DHL Express عند الدفع: تحقق من أن الترخيص نشط وأن Enable DHL Express Africa مفعّل. وفي Shipping > Carriers، تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته (أو فعّل Ignore shipping zones وتحقق من Countries). وتحقق من حدود الوزن وMinimum subtotal. ودون سعر فوري لا تظهر شركة الشحن إلا إذا كان هناك سعر دولة أو تكلفة احتياطية مضبوطة. وقد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج أيضًا.

لا تظهر الأسعار الفورية: تحقق من التحذيرات أعلى صفحة الوحدة (بيانات اعتماد أو منشأ مفقود). فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى حقل Log في صفحة الوحدة. وتُسجَّل أخطاء DHL مثل خطأ HTTP من MyDHL API، أو عدم وجود منتجات للمسار، أو مشكلة في العملة، دائمًا. وتحقق من أن Test mode يطابق بيانات الاعتماد، وأن عنوان العميل يحتوي على مدينة.

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

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

تُفرض الضريبة على الشحن مرتين: اضبط قاعدة ضريبة في Tax ليُؤخذ سعر DHL دون ضريبة القيمة المضافة لدى DHL، أو اختر No tax لتحصيل مبلغ DHL كما عُرض.

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

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

للمطورين، توفر الوحدة الخطافات actionVfdDhlaApiUrl وactionVfdDhlaIsDutiable وactionVfdDhlaPackageBox وactionVfdDhlaRestRequest وactionVfdDhlaXmlRequest لتغيير عنوان API والتصريح الجمركي والصندوق وطلبات DHL.

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

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

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