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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل رمز API ورمز PIN لنقطة الإرسال، واختر Express أو Surface وPre-paid أو COD. إذا لم تكن عملة متجرك INR، فأدخل سعر التحويل. ويمكنك اختياريًا إدخال أسعار ثابتة (انظر الإعدادات).

6. أضف VibeFox Delhivery إلى منطقة شحن (مثلًا الهند) في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore zones واختر الدول.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Delhivery. وتُطبَّق على جميع مناطق الشحن. وعند إضافة الطريقة إلى منطقة، لا تحتوي نافذة المنطقة إلا على حقل واحد:

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

في كل مرة تحفظ فيها الإعدادات، تُمسح أسعار Delhivery المخزنة مؤقتًا. تقبل الأسعار والمبالغ الصيغتين "9.99" و"9,99".

عام

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

Method title: اسم طريقة الشحن الظاهر عند الدفع. الافتراضي: Delhivery. يمكن لأي منطقة أن تستبدله بالحقل Title الخاص بها.

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها.

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

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

API token: رمز Delhivery API الخاص بك. يُرسل فقط في ترويسة التفويض ولا يُكتب في السجلات أبدًا.

Origin pincode: رمز PIN المكون من 6 أرقام لنقطة الاستلام أو المستودع، مثل 110001.

الأسعار المباشرة

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

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

Payment type: نوع الدفع المُرسل إلى Delhivery: Pre-paid (الافتراضي) أو COD (الدفع عند الاستلام؛ تضيف Delhivery رسوم COD الخاصة بها). لا تغيّر الإضافة هذا الخيار بحسب طريقة الدفع التي يختارها العميل.

Rate amount: تُعيد Delhivery المبلغ مع GST وبدونه.

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

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

تُستخدم الأسعار الثابتة عند عدم وجود رمز أو رمز PIN بعد، أو عندما تكون الوجهة خارج الهند، أو عندما لا تكون خدمة الشحن متاحة لرمز PIN، أو عندما تُرجع الواجهة البرمجية خطأً. وهي بعملة متجرك.

Prices per country: سطر واحد لكل دولة بالصيغة COUNTRY_CODE:price، مثل 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 يعني بلا حد.

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

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

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

Ignore zones: تقديم Delhivery دون إضافتها إلى منطقة شحن، للدول المذكورة أدناه.

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

متقدم

Debug log: يسجّل حسابات الأسعار في WooCommerce > Status > Logs، بالمصدر vfd_delhivery. تُسجَّل أخطاء API دائمًا حتى عندما يكون هذا الخيار متوقفًا. لا تُسجَّل الرموز ولا رموز PIN الكاملة للعملاء أبدًا.

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

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

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

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

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وكتلتي Cart وCheckout. وهي متوافقة مع HPOS (تخزين الطلبات عالي الأداء) في WooCommerce.

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

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

في شاشة الطلب، أسفل عنوان الشحن، تعرض كتلة Delhivery نمط الشحن (Express أو Surface) ومصدر السعر: سعر Delhivery المباشر، أو السعر الثابت، أو حد الشحن المجاني.

أنشئ الشحنة في Delhivery One، ثم الصق رقم AWB في الحقل Delhivery AWB / tracking number واحفظ الطلب. يظهر رابط Track on delhivery.com في لوحة الإدارة. يرى العميل Delhivery tracking مع رابط في صفحة الطلب ضمن حسابي، وفي رسائل الطلب الإلكترونية (HTML ونص عادي). يُحفظ رقم AWB قبل حالة الطلب، لذلك تتضمنه رسالة "الطلب المكتمل" بالفعل إذا أكملت الطلب في الحفظ نفسه.

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

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

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

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

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

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

لا يظهر Delhivery عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore zones مفعّل والدولة مسموح بها). تحقق من حدود الوزن وShow from subtotal وExcluded shipping classes. بدون سعر مباشر، تحتاج إلى سعر لكل دولة أو إلى Fallback price.

لا تظهر الأسعار المباشرة: تحقق من رمز API، ومن Origin pincode صالح، وفي المتجر الذي لا تكون عملته INR، من سعر التحويل. يجب أن يُدخل العميل رمز PIN هنديًا صالحًا من 6 أرقام. فعّل Debug log وافتح WooCommerce > Status > Logs، بالمصدر vfd_delhivery، لرؤية أخطاء API، مثل رمز PIN غير مغطّى بالخدمة.

تُفرض ضريبة GST مرتين: المبلغ الإجمالي من Delhivery يتضمن GST بالفعل. اضبط Rate amount على Gross amount (excluding GST)، أو اضبط Tax status على None.

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

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

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

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

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

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