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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم. لا يلزم امتداد SOAP في PHP.

Purolator E-Ship Web Services (للأسعار الفورية فقط): سجّل في E-Ship Web Services عبر Purolator E-Ship Resource Centre على موقع Purolator. تمنح Purolator مفاتيح وكلمات مرور منفصلة لبيئتي التطوير والإنتاج. كما تحتاج إلى رقم حساب الفوترة لدى Purolator والرمز البريدي الكندي الذي تشحن منه. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى مفاتيح API.

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

التثبيت

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

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

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

4. للأسعار الفورية، املأ قسم Purolator API (live rates). للاختبار، فعّل Development environment مع مفتاح التطوير. إذا أردت أسعارًا ثابتة أو سعرًا بديلًا، فاملأ Country prices أو Fallback price (انظر الإعدادات). اضغط Save.

عند التثبيت تُنشئ الوحدة شركة الشحن Purolator بنص مدة التوصيل Purolator courier. تُسنَد شركة الشحن إلى جميع المناطق وجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الأحجام في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

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

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

لا يُحفظ حقل رقمي لا يحتوي على رقم 0 أو أكبر. يذكر التحذير الحقل والقيمة. يبقى الحقل فارغًا، أو يأخذ قيمته الافتراضية في حقول الوزن. تُحفظ القيمة الخاطئة في Country prices بالقيمة 0، ويذكر التحذير الدولة والعمود. إذا كان Min cart weight أكبر من Max cart weight، فلا يُحفظ شيء وتظهر رسالة خطأ.

عام

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

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

Tax: قاعدة الضريبة لشركة الشحن، أو No tax. تحدد هذه القاعدة هل يضيف المتجر ضريبة على تكلفة الشحن. بالنسبة للعناوين الكندية يتضمن إجمالي Purolator بالفعل GST/HST/PST/QST. انظر Canadian sales taxes أدناه.

Purolator API (الأسعار الفورية)

عند ملء مفتاح API وكلمة المرور وحساب الفوترة، يأتي السعر من خدمة الويب Purolator E-Ship Estimating. إذا لم تعد Purolator أي سعر، يُستخدم السعر الثابت، أو تُخفى شركة الشحن إذا لم يوجد سعر ثابت. يحتوي هذا القسم على رابط إلى Purolator E-Ship Resource Centre حيث تسجل وتحصل على المفاتيح.

API key: مفتاح E-Ship Web Services الخاص بك للبيئة المختارة. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره.

API password: كلمة المرور المرتبطة بالمفتاح. مثل المفتاح، لا تُعرض مرة أخرى بعد الحفظ.

Billing account number: رقم حساب Purolator الخاص بك. تستخدم التقديرات أسعار هذا الحساب. تقبل بيئة التطوير حساب الاختبار الوارد في وثائق Purolator. مسح هذا الحقل يحذف أيضًا مفتاح API وكلمة المرور المحفوظين.

Development environment: يستخدم بيئة التطوير لدى Purolator (devwebservices.purolator.com) مع مفتاح التطوير. الأسعار بيانات اختبار. أوقفه في متجر فعلي.

Ship-from postal code: الرمز البريدي الكندي الذي تُرسل منه الطرود، مثل L4W 5M8.

Service in Canada: Cheapest available (الافتراضي)، Purolator Ground، Purolator Ground 9AM، Purolator Ground 10:30AM، Purolator Ground Evening، Purolator Express، Purolator Express 9AM، Purolator Express 10:30AM، Purolator Express 12PM، أو Purolator Express Evening.

Service to the USA: Cheapest available (الافتراضي)، Purolator Ground U.S.، Purolator Express U.S.، Purolator Express U.S. 9AM، Purolator Express U.S. 10:30AM، أو Purolator Express U.S. 12:00.

International service: Cheapest available (الافتراضي)، Purolator Express International، Purolator Express International 9AM، Purolator Express International 10:30AM، أو Purolator Express International 12:00.

إذا لم تكن الخدمة المختارة متاحة للعنوان، تُستخدم أرخص خدمة متاحة.

Canadian sales taxes: استخدام أسعار Purolator بدون GST/HST/PST/QST. بالنسبة للعناوين الكندية يتضمن إجمالي Purolator هذه الضرائب. فعّله عندما تكون لدى شركة الشحن قاعدة ضريبة في Tax، حتى لا تُحصَّل الضريبة مرتين.

CAD → (shop currency) rate: أسعار Purolator بالدولار الكندي (CAD). إذا لم تكن العملة الافتراضية لمتجرك هي CAD، فأدخل عدد وحدات عملتك التي تعادل دولارًا كنديًا واحدًا، مثل 0.68. بدون هذه القيمة لا تُستخدم الأسعار الفورية. إذا كانت عملتك الافتراضية هي CAD، فاترك الحقل فارغًا.

Default product weight: بالكيلوغرام، ويُستخدم لكل منتج بلا وزن. الافتراضي: 0.5. تُحوَّل الأوزان من وحدة وزن المتجر وتُرسل إلى Purolator كوزن إجمالي بالأرطال الكاملة، مع التقريب إلى الأعلى.

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

Country prices: سعر حسب الدولة ووزن السلة، بعملة المتجر الافتراضية، دون الضريبة. اضغط Add country لإضافة سطر، وأيقونة سلة المهملات لحذف سطر. اختر * Default (all other countries) لسطر يغطي كل الدول التي ليس لها سطر خاص. لكل سطر سعر Base وأعمدة أحجام: XS حتى 1 كغ، وS من 1 إلى 2 كغ، وM من 2 إلى 3 كغ، وL من 3 إلى 5 كغ، وXL أكثر من 5 كغ. السعر الفارغ أو الصفري للحجم يستخدم Base. إذا كان Base يساوي 0، أو كان Base فارغًا، فالشحن مجاني للأوزان التي ليس لها سعر حجم خاص بها. يُقبل كل من 9.99 و9,99. لا تُحفظ الأسطر التي لا تحتوي على أي سعر، ويُحتفظ بسطر واحد فقط لكل دولة.

Fallback price: السعر لدولة ليس لها سطر في Country prices ولا سطر *. اتركه فارغًا لإخفاء شركة الشحن في تلك الدول.

Fixed price per: Order يحصّل السعر مرة واحدة. Item (price × quantity) يضربه في عدد المنتجات في السلة. ينطبق هذا على الأسعار الثابتة فقط. تُحسب الأسعار الفورية دائمًا للشحنة كاملة.

الشروط

Min cart weight: بالكيلوغرام، يُخفي شركة الشحن عندما تكون السلة أخف من ذلك. 0 يعني بلا حد.

Max cart weight: بالكيلوغرام، يُخفي شركة الشحن عندما تكون السلة أثقل من ذلك. الافتراضي: 30. 0 يعني بلا حد.

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

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

لأغراض هذه الشروط، تُحسب المنتجات التي بلا وزن بوزن 0 ضمن وزن السلة.

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

عادةً تُعرض شركة الشحن في المناطق المسندة إليها في Shipping > Carriers.

Ignore shipping zones: اعرض Purolator للدول المذكورة أدناه، بغض النظر عن المنطقة المطابقة. عند الحفظ تُضاف شركة الشحن إلى جميع المناطق، وتُضاف أيضًا المناطق التي تُنشأ لاحقًا. إيقاف الخيار يزيل تلك المناطق مرة أخرى.

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

متقدم

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

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

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

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

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

مع بيانات اعتماد API ترسل الوحدة إلى Purolator طلب Quick Estimate: حساب الفوترة لديك، والرمز البريدي للشحن، ومدينة العميل وإقليمه أو ولايته، والدولة والرمز البريدي، والوزن الإجمالي للسلة بالأرطال الكاملة. بالنسبة لكندا يلزم رمز بريدي صالح، ولأمريكا رمز ZIP صالح؛ وتُرسل الدول الأخرى بالرمز البريدي كما أُدخل. لا تُرسل الأبعاد (الوزن الحجمي). تجيب Purolator بالفرنسية أو الإنجليزية حسب لغة العميل. تعيد Purolator أسعار جميع الخدمات؛ تأخذ الوحدة الخدمة التي اخترتها أو الأرخص، وتزيل ضرائب المبيعات الكندية إن كانت مضبوطة، وتحوّل السعر من CAD. يُحسب السعر بعملة المتجر الافتراضية ثم يُعرض بعملة سلة العميل.

تُخزَّن كل استجابة مؤقتًا لمدة ساعة. يُخزَّن الطلب الفاشل مؤقتًا لمدة 10 دقائق، حتى لا يُبطئ انقطاع Purolator كل تحديث لصفحة الدفع. مهلة API هي 10 ثوانٍ.

إذا لم تعد Purolator أي سعر (API متوقف، أو بيانات اعتماد أو رمز بريدي خاطئ، أو الخدمة غير متاحة، أو لا يوجد سعر صرف CAD)، لا يرى العميل أي خطأ. يُستخدم السعر الثابت، أو تُخفى شركة الشحن إذا لم يوجد سعر ثابت. يُكتب السبب في السجل.

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

الوحدة تحسب الأسعار فقط. لا تنشئ شحنات Purolator، ولا تطبع ملصقات، ولا تحجز مواعيد استلام، ولا تعالج المرتجعات، ولا تتتبع الطرود. لا تستخدم Full Estimate (الأبعاد، والقطع المتعددة، والخيارات مثل التوقيع أو البضائع الخطرة)، ولا تعرض مواعيد التسليم، ولا تعرض عدة خدمات كشركات شحن منفصلة، ولا تجلب أسعار الصرف تلقائيًا.

الطلبات

عند تنفيذ طلب بسعر Purolator فوري، تُحفظ الخدمة مع الطلب. إعادة حساب السلة لاحقًا لا تغيّرها. في صفحة الطلب في لوحة الإدارة (Orders > Orders، افتح الطلب)، تعرض كتلة Purolator الخدمة Purolator service (الاسم والرمز) وLive rate (excl. tax). الطلبات المسعّرة بأسعار ثابتة أو بشحن مجاني ليس لها هذه الكتلة.

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

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

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

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

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

Purolator لا يظهر عند الدفع: تحقق من أن الترخيص نشط وأن Enable Purolator مفعّل. في Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقق من حدود الوزن وMinimum order amount. إذا لم تعد Purolator أي سعر، تُعرض شركة الشحن فقط مع سعر لكل دولة أو سطر * أو Fallback price. ويمكن أيضًا قصر المنتجات على شركات شحن معينة من صفحة المنتج.

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

HTTP 401 في السجل: مفتاح API أو كلمة المرور لا يطابق البيئة المختارة. تعمل مفاتيح التطوير فقط مع تفعيل Development environment، وتعمل مفاتيح الإنتاج فقط مع إيقافه.

السعر يختلف عن موقع Purolator: يستخدم Quick Estimate أسعار حساب الفوترة لديك والوزن الإجمالي مقرَّبًا إلى الأعلى بالأرطال الكاملة، دون الوزن الحجمي. بالنسبة للعناوين الكندية يتضمن الإجمالي ضرائب المبيعات؛ استخدم Canadian sales taxes إذا كانت لشركة الشحن قاعدة ضريبة. تُحوَّل الأسعار بسعر CAD → (shop currency) rate لديك.

اختفت قيمة بعد الحفظ: اقرأ التحذير الذي يظهر بعد Save. لم تكن القيمة رقمًا 0 أو أكبر، لذلك لم تُحفظ. أعد إدخالها كرقم عادي.

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

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

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

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

Purolator علامة تجارية تعود لمالكها. هذه الوحدة غير مرتبطة بـ Purolator ولا معتمدة منها.