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

المتطلبات

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

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

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

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

التثبيت

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

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

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

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

عند التثبيت، تُنشئ الوحدة شركة الشحن Delhivery مع نص مدة التوصيل Courier delivery (India) وصفحة تتبع Delhivery كرابط تتبع. تُعيَّن شركة الشحن إلى جميع المناطق وجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

توجد جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox Delhivery > Configure. وتُطبَّق على كل المناطق. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وكل حفظ يمسح أيضًا الأسعار المخزنة مؤقتًا من Delhivery. تقبل المبالغ القيمتين «9.99» و«9,99». إذا لم يحتوِ حقل رقمي على رقم غير سالب، يظهر خطأ ولا يُحفظ شيء.

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

عام

Enable Delhivery: يفعّل شركة الشحن أو يعطّلها. وهذا هو المفتاح نفسه الذي يعرض حالة شركة الشحن في Shipping > Carriers.

Method title: اسم شركة الشحن الذي يظهر في السلة وعند الدفع. الافتراضي: Delhivery. حقل مطلوب، بحد أقصى 64 حرفًا.

Tax: قاعدة الضريبة لشركة الشحن، أو No tax. مع وجود قاعدة، يضيف PrestaShop الضريبة فوق تكلفة الشحن.

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

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

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

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

Origin pincode: رمز PIN المكون من 6 أرقام لنقطة الاستلام أو المستودع، مثل 110001. إذا لم يكن مكوّنًا من 6 أرقام، يظهر تحذير ولا تُطلب الأسعار المباشرة حتى يُصحَّح.

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

يُطلب سعر مباشر للوجهات الهندية التي تحمل رمز PIN صالحًا مكونًا من 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 (shop currency) conversion rate: يعرض التسمية العملة الافتراضية لمتجرك. أسعار Delhivery بالروبية الهندية. إذا لم تكن عملتك الافتراضية INR، فأدخل عدد وحدات عملتك التي تساوي روبية واحدة، مثل 0.011. يجب أن يكون السعر أكبر من 0. إذا تركته فارغًا، لا تُستخدم الأسعار المباشرة وتُطبَّق الأسعار الثابتة. ولا حاجة إليه إذا كانت عملتك الافتراضية INR.

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

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

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: الحد الأدنى لوزن السلة بالكيلوغرام لعرض شركة الشحن. القيمة 0 تعني لا حد.

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

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

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

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

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

متقدم

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

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

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

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر Delhivery. تُحتسب المنتجات المادية فقط: فالمنتجات الافتراضية لا تضيف وزنًا ولا تُدرج في المجموع الفرعي. تتحقق الوحدة أولًا من الدول (عند تفعيل Ignore zones) ووزن السلة وShow from subtotal. إذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Delhivery.

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

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

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

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

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

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

أنشئ الشحنة في Delhivery One، ثم أدخل رقم AWB الخاص بها كرقم تتبع للطلب في كتلة Carriers في صفحة الطلب (Edit). تعرض كتلة Delhivery بعد ذلك رابط Track on delhivery.com. يرى العميل رابط التتبع في سجل الطلب، ويتلقى الرسالة الإلكترونية «في الطريق» من PrestaShop.

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

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

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

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

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

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

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

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

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

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

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

للمطورين: تشغّل الوحدة الخطافين actionVfdDlvApiUrl وactionVfdDlvApiTimeout، اللذين يمكنهما تغيير عنوان API ومهلة الانتظار.

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

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

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