VibeFox Delhivery for OpenCart — المساعدة

المتطلبات

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

PHP: 8.0 أو أحدث.

رمز API من Delhivery (للأسعار الفورية فقط): سجّل الدخول إلى Delhivery One وافتح Settings > API setup. تشرح مقالة المساعدة لدى Delhivery بعنوان "API token generation" الخطوات. يوجد الرابطان في صفحة الإضافة. تعمل رموز الاختبار مع بيئة الاختبار (staging). وتحتاج أيضًا إلى الرمز البريدي pincode المكوَّن من 6 أرقام لموقع الاستلام. وإذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى رمز.

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

التثبيت

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

OpenCart 3

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

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

3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات.

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

5. أدخل رمز API والرمز البريدي pincode لمكان الإرسال، واختر Express أو Surface، والدفع المسبق أو COD. إذا لم تكن العملة الافتراضية لمتجرك INR، فأدخل سعر الصرف. ويمكنك اختياريًا إدخال أسعار ثابتة (راجع الإعداد). فعّل Enable Delhivery وانقر على Save.

OpenCart 4

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

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

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

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

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

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox Delhivery > Edit. وتظهر الأقسام في الجهة اليسرى. يحفظ زر Save الواحد الصفحة بأكملها دون إعادة تحميلها. ويؤدي كل حفظ أيضًا إلى مسح أسعار Delhivery المخزنة مؤقتًا. وتقبل المبالغ القيمتين "9.99" و"9,99". وإذا كانت قيمة خاطئة، فلا يُحفظ أي شيء وتعرض الصفحة السبب، مثل Enter a valid method title (without < > ; = # { }).، أو رسالة تفيد بأن الحقل يجب أن يكون رقمًا غير سالب، أو Sort order must be a whole number. ولا يمكن حفظ الإعدادات إلا لمستخدمي الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

إذا كانت العملة الافتراضية لمتجرك ليست INR، وكان رمز API محفوظًا ولم يُحدَّد سعر صرف، فإن تحذيرًا في أعلى الصفحة يذكّرك بأن الأسعار الفورية لن تُستخدم حتى تُدخل السعر. وإذا لم يكن لدى المتجر فئة وزن بالكيلوغرام، وكانت وحدة الوزن فيه غير قياسية (kg أو g أو lb أو oz)، فسيُبلغ تحذير بأن أوزان المنتجات تُقرأ بالكيلوغرام. اضبط وحدة قياسية في System > Localisation > Weight Classes.

عام

تنطبق الإعدادات على كل منطقة جغرافية. ويمكنك تقييد طريقة الشحن في Availability.

Enable Delhivery: يعرض Delhivery عند الدفع. الافتراضي: معطّل.

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وعند الدفع. الافتراضي: Delhivery. حقل إلزامي، بحد أقصى 64 حرفًا، ودون الأحرف < > ; = # { }.

Tax class: فئة الضريبة الخاصة بتكلفة الشحن، أو No tax (الافتراضي). ومع اختيار فئة، يضيف OpenCart الضريبة فوق تكلفة الشحن.

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

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

Environment: Production (track.delhivery.com) (الافتراضي) أو Staging / test account (staging-express.delhivery.com). استخدم Staging فقط مع رمز اختبار من Delhivery.

API token: رمز API الخاص بـ Delhivery. يُرسل فقط في ترويسة التفويض ولا يُكتب في السجلات أبدًا. بعد الحفظ، يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها.

Remove saved token: فعّله واحفظ لحذف الرمز المحفوظ. وعندئذٍ لا تُستخدم سوى الأسعار الثابتة.

Origin pincode: الرمز البريدي pincode المكوَّن من 6 أرقام لموقع الاستلام أو المستودع، مثل 110001. إذا لم يكن مكوَّنًا من 6 أرقام، فستُحفظ الإعدادات مع التحذير The origin pincode must have 6 digits — live rates are not requested until it is fixed.

الأسعار الفورية

يُطلب السعر الفوري للوجهات الهندية التي لها رمز pincode صالح مكوَّن من 6 أرقام، لشحنة في الاتجاه المباشر (تُسلَّم).

Shipping mode: نمط الفوترة لدى Delhivery المستخدم لحساب السعر: Express (الافتراضي) أو Surface.

Payment type: نوع الدفع المرسل إلى Delhivery: Pre-paid (الافتراضي) أو COD (cash on delivery — Delhivery adds its COD charge). لا تبدّله الإضافة حسب طريقة الدفع التي يختارها العميل.

Rate amount: تُعيد Delhivery الرسوم مع ضريبة GST وبدونها.

INR to (store currency) conversion rate: يعرض التسمية العملة الافتراضية لمتجرك. أسعار Delhivery بالروبية الهندية. إذا لم تكن عملتك الافتراضية INR، فأدخل عدد وحدات عملتك التي تساوي روبية واحدة، مثل 0.011. يجب أن يكون السعر أكبر من 0. وإذا تركته فارغًا، فلن تُستخدم الأسعار الفورية وتُطبَّق الأسعار الثابتة. ولا حاجة إليه إذا كانت عملتك الافتراضية INR.

الأسعار الثابتة (تُستخدم عندما لا يتوفر سعر فوري)

تُستخدم الأسعار الثابتة عندما لا يوجد رمز أو رمز بريدي pincode بعد، أو تكون الوجهة خارج الهند، أو لا يُقدَّم الخدمة للرمز البريدي pincode، أو تُعيد API خطأ. وهي بعملة المتجر الافتراضية، دون الضريبة.

Prices per country: سعر واحد في كل سطر بالصيغة كود_الدولة:السعر، مثل IN:120. ويُتحقق منه قبل السعر الاحتياطي. ويُحذف عند الحفظ أي سطر بصيغة أخرى، ويُدرج التحذير هذه الأسطر.

Fallback price: يُستخدم عندما لا ينطبق لا السعر الفوري ولا سعر الدولة. اتركه فارغًا لإخفاء طريقة الشحن (الافتراضي). ويعني 0 الشحن المجاني.

Fixed price is charged: Per order (الافتراضي) يحتسب السعر مرة واحدة. أما Per item (price × quantity) فيضربه في عدد العناصر في السلة. ويكون السعر الفوري لدى Delhivery دائمًا لوزن الطرد كاملًا.

الشروط

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

Show from subtotal: اعرض طريقة الشحن فقط إذا بلغ هذا المجموع الفرعي هذا المبلغ على الأقل. اتركه فارغًا لعرضها دائمًا.

Min weight (kg): الحد الأدنى لوزن السلة لعرض طريقة الشحن. ويعني 0 عدم وجود حد (الافتراضي).

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

تُحوَّل أوزان المنتجات إلى كيلوغرامات من فئة الوزن الخاصة بها في OpenCart. ويستخدم السعر الوزن الفعلي للسلة (مجموع أوزان المنتجات)، دون الوزن الحجمي أو الصناديق.

التوفر

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

Ignore zones: عندما يكون مفعّلًا، لا تُفحص المنطقة الجغرافية وتُعرض طريقة الشحن للدول المذكورة أدناه (كل الدول إذا كانت القائمة فارغة).

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

متقدم

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

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

Remove data on uninstall: عند تفعيله، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات Delhivery والأسعار المخزنة مؤقتًا والسجل. وعند تعطيله (الافتراضي)، تُحفظ من أجل إعادة التثبيت. ولا تُحذف بيانات الطلبات (الوضع، ومصدر السعر، وأرقام AWB) أبدًا.

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

Export: انقر على Download JSON لحفظ الإعدادات في ملف JSON. لا يُصدَّر رمز API.

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

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

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر Delhivery. إذا كانت Geo zone محددة (وكان Ignore zones معطّلًا) وكان العنوان خارجها، فلن تُعرض Delhivery. ولا تُحتسب إلا المنتجات التي يكون فيها Requires Shipping على Yes: أما المنتجات الأخرى فلا تضيف وزنًا ولا تدخل في المجموع الفرعي. ثم تتحقق الإضافة من الدول (عندما يكون Ignore zones مفعّلًا)، ووزن السلة، وShow from subtotal. والمجموع الفرعي هو سعر المنتجات التي تحتاج إلى شحن، بعد خصم الكوبون وقبل الضريبة. ولا تُؤخذ في الاعتبار بطاقات الهدايا ونقاط المكافآت ورصيد المتجر. وإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Delhivery.

بالنسبة إلى عنوان هندي له رمز pincode صالح مكوَّن من 6 أرقام (الرمز البريدي للعنوان)، ترسل الإضافة إلى Delhivery الرمزين البريديين pincode لمكان الإرسال والوجهة، ووزن السلة بالغرامات، ووضع الشحن، ونوع الدفع. ويُحوَّل المبلغ المُعاد من INR إلى العملة الافتراضية للمتجر، ويُقرَّب إلى منازله العشرية، ويُعرض للعميل بعملته مع ضريبة Tax class المختارة. وتُخزَّن كل استجابة مؤقتًا لمدة ساعة. ويُخزَّن الطلب الفاشل مؤقتًا لمدة 10 دقائق، حتى لا تنتظر صفحة الدفع Delhivery عند كل تحديث. ومهلة API هي 10 ثوانٍ.

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

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

في OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار Delhivery في النافذة Shipping method options. تعمل الطريقة بالطريقة نفسها كما في OpenCart 3.

الطلبات والتتبع

عندما يُقدَّم طلب مع Delhivery، تحفظ الإضافة وضع الشحن ومصدر السعر مع الطلب. افتح الطلب في Sales > Orders: تعرض لوحة Delhivery فوق سجل الطلب القيم Mode: (Express أو Surface)، وPrice: (السعر الفوري من Delhivery، أو السعر الثابت، أو حد الشحن المجاني)، وDelhivery AWB / tracking number، أو Not entered yet. إذا لم يُدخل بعد.

في OpenCart 4 يحتفظ الدفع بطلب واحد ويحدّثه في كل مرة يؤكد فيها العميل. ويتم تحديث الوضع ومصدر السعر معه. وإذا انتقل العميل إلى طريقة شحن أخرى قبل إدخال رقم AWB، فلن تظهر لوحة Delhivery لذلك الطلب بعد الآن.

أنشئ الشحنة في Delhivery One، ثم أدخل رقم AWB الخاص بها في اللوحة وانقر على Save. لا تُعاد تحميل الصفحة. تُحفظ الحروف والأرقام والشرطات (حتى 64 حرفًا). واحفظ حقلًا فارغًا لإزالة رقم AWB. وعندما يكون رقم AWB موجودًا، تعرض اللوحة رابط Track on delhivery.com. ويتطلب حفظ رقم AWB صلاحية تعديل الطلبات. ومن دونها تكون اللوحة للقراءة فقط.

يرى العميل المسجل في صفحة الطلب بحسابه Delhivery tracking: مع رقم AWB كرابط إلى صفحة التتبع لدى Delhivery. وعندما تُضيف مدخلًا إلى سجل الطلب وتُبلغ العميل، تتضمن رسالة حالة الطلب البريدية السطر نفسه مع الرابط. ولا تتضمن رسالة الطلب الجديد رابط تتبع، لأن رقم AWB يُدخل لاحقًا. وتعمل اللوحة ورابط التتبع للطلبات القديمة أيضًا عندما تكون الإضافة معطّلة.

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

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

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

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

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

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

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

لا تظهر Delhivery في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable Delhivery مفعّل. تحقق من Geo zone، أو من Ignore zones وCountries، وحدود الوزن وShow from subtotal. وبدون سعر فوري، تحتاج إلى سعر لكل دولة أو إلى Fallback price. وتحقق من أن المنتجات لديها Requires Shipping على Yes.

لا تظهر الأسعار الفورية: تحقق من رمز API، ومن Origin pincode صالح، ومن سعر الصرف إذا لم تكن عملتك الافتراضية INR. ويجب على العميل إدخال رمز pincode هندي صالح مكوَّن من 6 أرقام كرمز بريدي. فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى الحقل Log في صفحة الإضافة. يعرض الحقل السبب، مثل رمز pincode غير مشمول بالخدمة أو خطأ HTTP من Delhivery.

تُحتسب ضريبة GST مرتين: يتضمن المبلغ الإجمالي لدى Delhivery ضريبة GST من قبل. اضبط Rate amount على Gross amount (excluding GST)، أو اضبط Tax class على No tax.

الاختبار: اضبط Environment على Staging واستخدم رمز اختبار من Delhivery.

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

لا يمكن حفظ رقم AWB: تعني الرسالة You do not have permission to modify orders. أن مجموعة مستخدمي الإدارة لديك تحتاج إلى صلاحية التعديل لـ sale/order في System > Users > User Groups.

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

للمطورين: تُطلق الإضافة أحداث OpenCart catalog/vfd_delhivery/api_url وcatalog/vfd_delhivery/api_timeout، والتي يمكن أن تغيّر عنوان API والمهلة.

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

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

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

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