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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث. لا يلزم امتداد SOAP في PHP.

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

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

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Purolator. وتنطبق على كل مناطق الشحن. وعند إضافة الطريقة إلى منطقة، تظهر في نافذة المنطقة خانة واحدة فقط:

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

في كل مرة تحفظ فيها الإعدادات تُمسح أسعار Purolator المخزنة مؤقتًا. وإذا تعذّر عمل الأسعار الفورية بالقيم المحفوظة (مفتاح أو كلمة مرور أو حساب مفقود، أو لا يوجد رمز بريدي كندي للشحن، أو لا يوجد سعر صرف CAD)، أو إذا لم تكن هناك بيانات اعتماد API ولا أسعار ثابتة، فسيظهر تحذير فوق الإعدادات.

عام

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

Method title: اسم طريقة الشحن الذي يظهر في سلة التسوق وفي صفحة الدفع. ويمكن لمنطقة أن تغيّره. الافتراضي: Purolator.

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. راجع أيضًا Canadian sales taxes أدناه.

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

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

API key: مفتاح E-Ship Web Services الخاص ببيئة الاختيار.

API password: كلمة المرور المرتبطة بالمفتاح.

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

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. فعّل Use Purolator prices without GST/HST/PST/QST عندما تكون Tax status على Taxable، حتى لا تُفرض الضريبة مرتين.

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

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

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

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

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

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

الشروط

Min cart weight (kg): يخفي الطريقة عندما يكون وزن السلة أقل من ذلك. 0 يعني بلا حد.

Max cart weight (kg): يخفي الطريقة عندما يكون وزن السلة أكثر من ذلك. الافتراضي: 30. 0 يعني بلا حد.

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

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

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

يحسب وزن السلة لهذه الشروط المنتجات بلا وزن على أنها 0. وتقبل الأسعار والأوزان الفاصلة أو النقطة كفاصل عشري.

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

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

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

متقدم

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

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

كيف يعمل في صفحة الدفع

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

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

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

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

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

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

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

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

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

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

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

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

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

الأسعار الفورية لا تظهر: افتح WooCommerce > Status > Logs، واختر المصدر "vfd-purolator". تظهر أخطاء API هناك دائمًا. فعّل Debug log للتفاصيل. ومع مفاتيح API يجب أن يحتوي العنوان على رمز بريدي صالح (كندا) أو رمز ZIP صالح (الولايات المتحدة).

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

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

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

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

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

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

Purolator علامة تجارية تعود إلى مالكها. هذه الإضافة غير تابعة لـ Purolator ولا معتمدة من قِبلها.