VibeFox DPD Pickup for PrestaShop — المساعدة

المتطلبات

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

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

بيانات اعتماد DPD Baltic (ليتوانيا ولاتفيا وإستونيا): قائمة نقاط الاستلام تأتي من خدمة الويب الخاصة بـ DPD Baltic. تحتاج إلى اسم المستخدم وكلمة المرور الخاصين بواجهة API، واللذين تمنحهما DPD لعملائها من الشركات. اطلبهما من مدير حسابك لدى DPD أو من خدمة عملاء DPD في بلدك. يعرض حساب واحد نقاط الاستلام في ليتوانيا ولاتفيا وإستونيا.

DPD Slovakia: بحث parcelshop العام لدى DPD Slovakia لا يتطلب بيانات اعتماد.

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

التثبيت

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

2. عند انتهاء الرفع، اضغط Configure، أو اعثر لاحقًا على VibeFox DPD Pickup في قائمة الوحدات واضغط Configure.

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

4. اختر واجهة DPD API. بالنسبة إلى DPD ليتوانيا أو لاتفيا أو إستونيا، أدخل اسم المستخدم وكلمة مرور واجهة API. راجع الأسعار حسب الدولة ثم اضغط Save. بعد ذلك اضغط Refresh pickup points للتحقق من الاتصال (انظر الإعدادات).

عند التثبيت، تنشئ الوحدة شركة النقل DPD Pickup Point مع نص مدة التوصيل DPD Pickup point or locker. تُربط شركة النقل بمناطق سلوفاكيا وليتوانيا ولاتفيا وإستونيا وبجميع مجموعات العملاء، دون قاعدة ضريبية. يمكنك تغيير المناطق ومجموعات العملاء ونص مدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تضبط الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

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

تخبرك التحذيرات أعلى الصفحة متى يكون اسم مستخدم DPD Baltic أو كلمة المرور فارغين، ومتى لا تكون أي أسعار مضبوطة (في الحالتين لا تظهر شركة النقل عند الدفع)، ومتى حُذفت شركة النقل، ومتى لا تعرف الوحدة وحدة وزن المتجر (International > Localization، Local units)، فتُقرأ أوزان المنتجات بالكيلوغرام. لا تُحفَظ قيمة ليست رقمًا، أو رقم سالب، في حقل مبلغ أو وزن: يصبح الحقل فارغًا ويسمّيه تحذير. تُدرج أسطر Country prices التي ليست بصيغة CC:PRICE في تحذير وتُتجاهل.

عام

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

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

Tax status: قاعدة الضريبة لشركة النقل المطبّقة على سعر الشحن. تعني None عدم وجود ضريبة. تعرض الخيارات الأخرى Taxable مع اسم قاعدة ضريبية في متجرك.

قائمة نقاط استلام DPD

تُحمَّل نقاط الاستلام من DPD وتُخزَّن مؤقتًا لمدة 24 ساعة.

DPD API: شركة DPD التي لديك حساب معها. تستخدم حسابات دول البلطيق خدمة الويب في بلدها.

API username (Baltic): اسم مستخدم خدمة الويب الخاصة بـ DPD Baltic. غير مطلوب لـ DPD Slovakia. مسح هذا الحقل يمسح كلمة المرور المحفوظة أيضًا.

API password (Baltic): كلمة مرور خدمة الويب الخاصة بـ DPD Baltic. غير مطلوبة لـ DPD Slovakia. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Pickup points: يمسح زر Refresh pickup points الذاكرة المؤقتة ويحمّل نقاط الاستلام الآن من DPD: ليتوانيا ولاتفيا وإستونيا لواجهة Baltic API، وبحث تجريبي في براتيسلافا لـ DPD Slovakia. يعرض عدد نقاط الاستلام أو الخطأ لكل دولة. احفظ الإعدادات أولًا.

الأسعار

أسعار الشحن ثابتة لكل دولة، بعملة المتجر الافتراضية، دون ضريبة. لا تُطلب أسعار DPD من الواجهة.

Country prices: سطر واحد لكل دولة: CC:السعر، مثلًا EE:3.50. تُقبل الفاصلة العشرية. الافتراضي: SK:3.50, LT:4.00, LV:4.00, EE:4.00.

Fallback cost: السعر للدول غير الموجودة في Country prices. الافتراضي: 5.00. اتركه فارغًا لعرض شركة النقل في الدول المدرجة فقط.

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

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

التوفر

تُخفى شركة النقل أيضًا عندما لا تعيد DPD نقاط استلام لعنوان العميل، أو عندما يتعذر الوصول إلى واجهة DPD API، لأنه لا يمكن تسليم طلب دون نقطة استلام.

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

Max weight (kg): السلال الأثقل لا ترى شركة النقل. الافتراضي: 31.5. 0 يعني بلا حد. تحقق من حدود الطرود لنقاط الاستلام والخزائن الخاصة بـ DPD في بلدك. يُرفض Min weight (kg) إذا كان أكبر من Max weight (kg)، ولا يُحفظ شيء.

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

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

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

محدد نقطة الاستلام

City order: يعرض المدن الكبرى أولًا (تالين وريغا وفيلنيوس وبراتيسلافا وغيرها). مفعّل افتراضيًا.

City list width: العرض بوحدة CSS لقائمة المدن، مثلًا 100% أو 300px. الافتراضي: 100%.

Pickup point list width: العرض بوحدة CSS لقائمة نقاط الاستلام، مثلًا 100% أو 400px. الافتراضي: 100%.

متقدم

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

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

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

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

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

تُخزَّن قائمة نقاط الاستلام مؤقتًا لمدة 24 ساعة، والقائمة الفارغة لمدة ساعة. يُتذكَّر الطلب الفاشل لمدة 5 دقائق، فلا يبطئ انقطاع DPD الدفع أبدًا. مهلة API هي 15 ثانية.

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

لا تطلب الوحدة أسعار DPD، ولا تنشئ شحنات DPD، ولا تطبع ملصقات، ولا تنشئ بيانات تسليم جماعية، ولا تطلب استلام المندوب، ولا تتتبع الطرود، ولا تعرض خريطة. يُدعم فقط خدمة الويب الخاصة بـ DPD Baltic وبحث parcelshop الخاص بـ DPD Slovakia.

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

عندما يختار العميل DPD Pickup، تظهر قائمة مدن وقائمة نقاط استلام أسفل شركة النقل. تُختار مدينة عنوان العميل مسبقًا. يُحفظ الاختيار في السلة فور أن يختاره العميل. مع DPD Slovakia، يرى العميل Enter your city and postcode to see the DPD pickup points nearby. إلى أن يكتمل العنوان، ثم النقاط القريبة. إذا لم تكن لدى DPD نقاط لهذا العنوان، يرى العميل No DPD pickup points are available for this address right now. Please check the address or choose another shipping method.

نقطة الاستلام إلزامية. بدونها لا يستطيع العميل المتابعة ويرى Please select a DPD pickup point. يتحقق الخادم من أن النقطة تنتمي إلى قائمة DPD لعنوان العميل. يُرفض الاختيار المزوَّر أو القديم برسالة The selected DPD pickup point is not available for this address. Please choose another one.

تُحفظ النقطة المختارة في الطلب. تظهر في صفحة تأكيد الطلب وفي تفاصيل الطلب الخاصة بالعميل بعبارة DPD pickup point:. وفي رسالة تأكيد الطلب تُضاف بعد اسم شركة النقل. كما تعرض رسالة الطلب الجديدة إلى المتجر (ps_emailalerts) معرّف النقطة. يأتي الاسم المحفوظ في الطلب من DPD، لا من المتصفح.

في صفحة الطلب في لوحة الإدارة، يعرض كتلة DPD pickup point اسم النقطة ومعرّفها وبلدها. اضغط Edit، واختر مدينة ونقطة أخرى، ثم اضغط Save. تُتحقق النقطة من قائمة DPD لعنوان الطلب، وتعرض الصفحة Pickup point updated. أو Pickup point not found for the order address. يتطلب تغيير النقطة صلاحية تعديل الطلبات، لا الوصول إلى صفحات Modules. يُسجَّل كل تغيير في Advanced Parameters > Logs للطلب، مع النقطة القديمة والجديدة والموظف. ولتغيير النقطة مع DPD Slovakia، يجب أن يكون للطلب مدينة شحن ورمز بريدي.

إذا قُسمت سلة واحدة إلى عدة طلبات، تبقى نقطة الاستلام مع الطلب الأول. تعرض الطلبات الأخرى No pickup point was selected for this order.، ويحتوي سجل التصحيح على خطأ لكل منها، ويعرض Edit هناك The pickup point of this cart belongs to another order of the same cart. Nothing was changed. يجب تسليم نقطة طلب كهذا إلى DPD يدويًا.

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

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

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

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

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

لا يظهر DPD Pickup عند الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. في Shipping > Carriers تحقق من أن شركة النقل تغطي منطقة دولة العميل ومجموعته (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). راجع التحذيرات أعلى صفحة الوحدة واضغط Refresh pickup points. تحقق من حدود الوزن والمجموع الفرعي، ومن أن الدولة لها سعر (أو تكلفة احتياط). قد تكون المنتجات مقيّدة أيضًا بشركات نقل معينة في صفحة المنتج.

خطأ بعد Refresh pickup points: تعرض النتيجة خطأ DPD لكل دولة. مثلًا، تعني "Login failed" أن DPD رفض بيانات اعتماد Baltic، لذلك لا يمكن تحميل أي نقطة استلام. تحقق من اسم المستخدم وكلمة مرور API لدى DPD.

DPD Slovakia لا يعرض نقاطًا: تظهر النقاط بعد أن يُدخل العميل المدينة والرمز البريدي. لا يعرض DPD إلا النقاط في نطاق 50 كم من ذلك العنوان. يمكن للمطورين تغيير نطاق البحث عبر خطاف الوحدة actionVfdDpdSkSearchRadius.

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

تبدو نقاط الاستلام قديمة بعد تغيير: اضغط Save أو Refresh pickup points في صفحة الوحدة. كلاهما يمسح القوائم المخزنة مؤقتًا.

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

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

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

DPD علامة تجارية تعود ملكيتها إلى مالكها. هذه الوحدة غير تابعة لـ DPD ولا تحظى بتأييدها.