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

المتطلبات

OpenCart: 3.0.x (تم اختباره على 3.0.5.0) أو 4.0.2 وما بعدها (تم اختباره على 4.1.0.3).

PHP: 8.0 أو أحدث.

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

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

فئة الوزن: تُحوَّل أوزان المنتجات إلى كيلوغرام. يحتاج متجرك إلى فئة وزن بوحدة kg في System > Localisation > Weight Classes (يتضمن OpenCart واحدة افتراضيًا).

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

التثبيت

يأتي التنزيل في ملف zip واحد يحتوي على الحزم الخاصة بالإصدارين من OpenCart. فكّه على حاسوبك. يحتوي على README.txt، وحزمة OpenCart 3 vfd_dpd_pickup-oc3-(version).ocmod.zip، وحزمة OpenCart 4 vfd_dpd_pickup.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص هو نفسه للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف vfd_dpd_pickup-oc3-(version).ocmod.zip. لا تضيف الإضافة أي تعديلات OCMOD، لذلك لا تحتاج إلى تحديث Extensions > Modifications. بدلًا من أداة Installer، يمكنك نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذري لمتجرك.

2. انتقل إلى Extensions > Extensions واختر نوع الإضافة Shipping. ابحث عن VibeFox DPD Pickup واضغط Install (زر + الأخضر).

3. اضغط Edit (زر القلم) لفتح صفحة الإعدادات.

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

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

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف vfd_dpd_pickup.ocmod.zip. لا تغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة بعد تغيير اسمها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. اضغط Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر نوع الإضافة Shipping. ابحث عن VibeFox DPD Pickup، واضغط Install (زر + الأخضر)، ثم Edit (زر القلم).

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوتين 4 و5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

بعد التثبيت، تبقى الطريقة معطلة حتى تفعّل Enable/Disable وتحفظ. وإذا أعدت تثبيت الإضافة بعد إلغاء تثبيتها، فستُستخدم الإعدادات التي احتفظت بها من جديد.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit. تظهر الأقسام في القائمة على اليسار. يحفظ زر Save واحد الصفحة كاملة دون إعادة تحميلها. كما يمسح كل حفظ قوائم نقاط الاستلام المخزنة مؤقتًا. يستطيع حفظ الإعدادات أو تحديث نقاط الاستلام أو مسح السجل فقط المستخدمون المسؤولون الذين لديهم صلاحية التعديل لهذه الإضافة.

تخبرك التحذيرات في أعلى الصفحة بأن اسم مستخدم DPD Baltic أو كلمة مروره فارغان، أو بأنه لم يُحدَّد أي سعر (وفي الحالتين لا تُعرض الطريقة في صفحة الدفع)، وبأن المتجر لا يملك فئة وزن بوحدة kg (تُقرأ أوزان المنتجات حينها من اسم وحدتها، وتُعامل الوحدات غير المعروفة على أنها كجم). بعض القيم تمنع الحفظ، وعندها لا يُحفظ شيء: Name فارغ أو أطول من 64 حرفًا، وSort order ليس عددًا صحيحًا، وMin weight (kg) أكبر من Max weight (kg). لا تُحفظ القيمة في حقل المبلغ أو الوزن إذا لم تكن رقمًا، أو إذا كانت سالبة: يصبح الحقل فارغًا وينبّه تحذير إلى اسمه، بينما تُحفظ بقية الإعدادات. تُدرج أسطر Country prices التي لا تطابق صيغة CC:PRICE في تحذير، وتُتجاهل.

عام

تُعرض الطريقة في المنطقة الجغرافية المحددة في Availability (جميع المناطق إن لم تُحدَّد أي منطقة)، أو مع Ignore shipping zones في الدول المختارة هناك.

Enable/Disable: يعرض DPD Pickup في صفحة الدفع أو يخفيه. الافتراضي: معطّل.

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

Tax class: فئة الضريبة المطبقة على سعر الشحن، أو None (الافتراضي) لعدم فرض ضريبة.

Sort order: موضع الطريقة في قائمة طرق الشحن. عدد صحيح.

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

تُحمَّل نقاط الاستلام من DPD وتُخزَّن مؤقتًا (راجع كيف تعمل عند الدفع).

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

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، وبحث تجريبي في براتيسلافا لـ 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 البرمجية، لأن الطلب لا يمكن تسليمه بدون نقطة استلام.

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

Max weight (kg): السلال الأثقل لا ترى الطريقة. الافتراضي: 31.5. الفارغ أو 0 يعني بلا حد. تحقق من حدود وزن الطرود لنقاط الاستلام والخزائن التابعة لـ DPD Pickup في بلدك.

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

Geo zone: اعرض الطريقة فقط للعناوين في هذه المنطقة الجغرافية. All zones (الافتراضي) تعني بلا حد. تُدار المناطق الجغرافية في System > Localisation > Geo Zones. لا تُستخدم مع Ignore shipping zones.

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

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

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

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

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

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

متقدم

Debug log: يكتب طلبات الواجهة البرمجية وخطوات الدفع في storage/logs/vfd_dpd_debug.log.php (في OpenCart 4 system/storage/logs/vfd_dpd_debug.log.php). لا يمكن قراءة الملف من الويب. تُسجَّل أخطاء الواجهة البرمجية دائمًا، حتى عندما يكون هذا الخيار معطّلًا. لا تُسجَّل بيانات الاعتماد أبدًا. عندما يصل الملف إلى 5 ميغابايت يُنقل إلى vfd_dpd_debug.old.log.php ويبدأ سجل جديد.

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

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

الاستيراد / التصدير

Export: اضغط Download JSON لحفظ الإعدادات كملف JSON. لا يُصدَّر مفتاح كلمة المرور الخاص بالواجهة البرمجية.

Import: ألصق ملف JSON مُصدَّرًا سابقًا، ثم اضغط Import لاستعادة الإعدادات، مثلًا في متجر آخر. تُفحص القيم كما في الحفظ العادي. يبقى كلمة المرور المحفوظ للواجهة البرمجية كما هو.

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

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر DPD Pickup. إذا كانت Geo zone مُحدَّدة (وIgnore shipping zones معطّل) وكان العنوان خارجها، فلا تُعرض الطريقة. تُحتسب فقط المنتجات التي يكون فيها Requires Shipping على Yes: لا تضيف المنتجات الأخرى وزنًا ولا تدخل في المجموع الفرعي. تفحص الإضافة الدول (مع Ignore shipping zones) ووزن السلة والحد الأدنى للمجموع الفرعي، وتأخذ سعر الدولة (أو تكلفة الاحتياط)، وتطبق الشحن المجاني إذا كان المجموع الفرعي مرتفعًا بما يكفي. المجموع الفرعي هو سعر المنتجات التي تحتاج إلى شحن، بعد خصم الكوبون وقبل الضريبة.

ثم تحمّل نقاط استلام DPD للعنوان. إذا لم تُعد DPD أي نقطة، أو تعذّر الوصول إليها، أو كانت بيانات اعتماد Baltic مفقودة، فتُخفى الطريقة. مع DPD Slovakia تُعرض الطريقة ما دامت المدينة أو الرمز البريدي ناقصين، وتظهر النقاط عندما يكتمل العنوان. يُحسب السعر بعملة المتجر الافتراضية، ويُعرض للعميل بعملته مع ضريبة Tax class المختارة.

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

لا تطلب الإضافة أسعار 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. عندما يضغط العميل Continue، يتحقق الخادم من أن النقطة تنتمي إلى قائمة DPD لعنوان العميل. يُرفض الاختيار المزوَّر أو القديم برسالة The selected DPD pickup point is not available for this address. Please choose another one. إذا تعذر تحميل قائمة DPD في تلك اللحظة، تُقبل النقطة التي اختارها العميل بالفعل، ويعرض الطلب معرّفها بدلًا من الاسم.

في OpenCart 4 ينقر العميل Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار DPD Pickup في نافذة Shipping method options. تظهر قائمة المدن وقائمة نقاط الاستلام داخل تلك النافذة أسفل الطريقة وتعملان كما وُصف أعلاه. زر Continue في النافذة لا يتابع من دون نقطة استلام، وتظهر الرسائل نفسها.

تُضاف النقطة المختارة إلى طريقة شحن الطلب، مثل DPD Pickup Point: name, street, postcode city بالعنوان الافتراضي، أو My title - DPD pickup point: name, street, postcode city بعنوانك الخاص (بحد أقصى 128 حرفًا). وبهذا تظهر في الطلب في لوحة الإدارة، وفي سجل طلبات العميل، وفي رسائل البريد الإلكتروني للطلب، وفي الفاتورة. يأتي الاسم المحفوظ في الطلب من DPD، وليس من المتصفح.

في OpenCart 4 يمكن أن يصل نص طريقة الشحن إلى 255 حرفًا. يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه في كل مرة يؤكد فيها العميل، وتُحدَّث معه نقطة استلام الطلب.

في صفحة الطلب في الإدارة (Sales > Orders)، تعرض لوحة DPD pickup point فوق السجل اسم النقطة ومعرّفها وبلدها. اضغط Edit، واختر مدينة ونقطة أخرى، ثم اضغط Save. تُفحص النقطة مقابل قائمة DPD لعنوان الطلب، وتعرض اللوحة Pickup point updated. أو Pickup point not found for the order address. يُحدَّث نص طريقة الشحن في الطلب، وتُضاف ملاحظة إلى سجل الطلب (لا تُرسل إلى العميل) تتضمن النقطة القديمة والنقطة الجديدة ومستخدم الإدارة. يحتاج تغيير النقطة إلى صلاحية تعديل الطلبات، وليس الوصول إلى إعدادات الإضافة. مع DPD Slovakia يحتاج الطلب إلى مدينة شحن ورمز بريدي، وإلا تعرض اللوحة Add the shipping city and postcode to change the pickup point. يعرض الطلب الذي وُضع بدون نقطة الرسالة No pickup point was selected for this order.، ويتضمن سجل التصحيح خطأ لأجله. تعمل اللوحة وEdit حتى بعد تعطيل الإضافة.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox DPD Pickup هي أول كتلة في صفحة Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit، فوق الإعدادات. الصق المفتاح في حقل License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثلًا تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. تحتها السطر Product: opencart-shipping-dpd-pickup والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. يستطيع تغيير المفتاح فقط المستخدمون المسؤولون الذين لديهم صلاحية Modify للإضافة. تتبع نصوص الكتلة لغة الإدارة (الإنجليزية والروسية متوفرتان).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، اضغط Check now. إذا تعذر الوصول إلى خادم الترخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

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

من دون مفتاح نشط، لا تُعرض طريقة شحن DPD Pickup للعملاء في صفحة الدفع، ولا تُحسب أي تسعيرة. يرى مستخدم الإدارة المسجَّل دخوله إلى الإدارة في المتصفح نفسه الطريقة في المتجر، ومعها الوسم (unlicensed — visible to admins only)، لتتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. في OpenCart 4 هذه المعاينة غير متاحة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تُخفى الطريقة عن الجميع من دون مفتاح نشط. بعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الإدارة. أغلقه بالزر × ليختفي لمدة 7 أيام. لا تتأثر الطلبات الحالية.

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

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

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

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

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

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

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

تقول الصفحة "Warning: You do not have permission to modify VibeFox DPD Pickup!": قد تملك مجموعة المستخدمين المسؤولين صلاحية عرض الإعدادات فقط. امنح المجموعة صلاحية التعديل لـ extension/shipping/vfd_dpd_pickup (OpenCart 3) أو extension/vfd_dpd_pickup/shipping/vfd_dpd_pickup (OpenCart 4) في System > Users > User Groups.

للمطورين: يمكن لإضافة أخرى تغيير نطاق بحث DPD Slovakia عبر حدث OpenCart vfd_dpd_pickup/sk_search_radius.

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

انتقل إلى Extensions > Extensions، واختر النوع Shipping، ثم اضغط Uninstall (زر − الأحمر) بجانب VibeFox DPD Pickup. يُحذف دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. يعيد OpenCart دائمًا ضبط Enable/Disable وSort order وTax class وGeo zone. تحذف الإضافة دائمًا أحداثها وقوائم نقاط الاستلام المخزنة مؤقتًا. إذا كان Remove data on uninstall مفعّلًا، تُحذف الإعدادات الأخرى وسجل التصحيح واختيارات عمليات الدفع غير المكتملة أيضًا. إذا كان معطّلًا، تُحفظ الإعدادات وتُستخدم مجددًا عند إعادة تثبيت الإضافة. لا تُحذف نقطة الاستلام المحفوظة في الطلبات أبدًا، وتحتفظ الطلبات الحالية بطريقة شحنها وتكلفتها.

في OpenCart 4، ولحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، واضغط Uninstall (زر − البرتقالي) بجانب VibeFox DPD Pickup في قائمة الإضافات المثبتة، ثم Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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