VibeFox Canada Post for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

Canada Post Developer Program (للأسعار المباشرة فقط): تستخدم الأسعار المباشرة Canada Post Rating API. انضم إلى Canada Post Developer Program على موقع Canada Post، وانسخ مفتاح API ورقم العميل. يأخذ مفتاح API الشكل username:password، وتصدر Canada Post مفاتيح منفصلة لبيئة التطوير (sandbox) وبيئة الإنتاج. تحتاج أيضًا إلى الرمز البريدي الكندي الذي تشحن منه. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى مفاتيح API.

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

التثبيت

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

2. انقر Activate.

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

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

5. للأسعار المباشرة، أدخل اسم المستخدم وكلمة المرور لواجهة API، ورقم العميل، والرمز البريدي للشحن. إذا لم تكن عملة متجرك الدولار الكندي (CAD)، فأدخل سعر الصرف إلى CAD. واملأ Country prices إذا أردت أسعارًا ثابتة أو بديلًا احتياطيًا (انظر الإعدادات).

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

الإعدادات

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

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

في كل مرة تحفظ فيها الإعدادات، تُمسح أسعار Canada Post المخزنة مؤقتًا. وتعرض الصفحة أيضًا خطأً عندما لا تستطيع الإعدادات العمل: إذا كان اسم مستخدم API أو كلمة مروره مملوءًا وحده، أو كان الرمز البريدي للشحن غير كندي، أو كان سعر الصرف إلى CAD مفقودًا لمتجر بعملة أخرى، أو لم يكن هناك مفاتيح API ولا أسعار ثابتة.

عام

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

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

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

واجهة Canada Post API (الأسعار المباشرة)

عند ملء اسم المستخدم وكلمة المرور، يأتي السعر من Canada Post Rating API. وإذا لم تُرجع الواجهة سعرًا (الواجهة غير متاحة، أو رمز بريدي خاطئ، أو الخدمة غير متاحة)، يُستخدم السعر الثابت من Country prices، أو تُخفى الطريقة إذا لم يكن هناك سعر ثابت.

API username: الجزء من مفتاح API الذي يسبق النقطتين. استخدم مفتاح التطوير مع Sandbox، ومفتاح الإنتاج في متجر حقيقي.

API password: الجزء من مفتاح API الذي يلي النقطتين. لا يُكتب في السجل أبدًا.

Customer number: مع رقم العميل، تُرجع Canada Post الأسعار التجارية (المخفّضة) لحسابك. اتركه فارغًا للحصول على أسعار المكتب (التجزئة).

Contract number: اختياري، للعملاء المتعاقدين. يُستخدم فقط مع رقم العميل.

Sandbox: يستخدم بيئة التطوير من Canada Post، للاختبار بمفتاح API الخاص بالتطوير. الأسعار بيانات اختبار. أوقفه في متجر حقيقي.

Ship-from postal code: الرمز البريدي الكندي الذي تُرسل منه الطرود، مثل K1A 0B1. الأسعار المباشرة تحتاجه.

Service in Canada: الخدمة للعناوين الكندية: Cheapest available، أو Regular Parcel (الافتراضي)، أو Expedited Parcel، أو Xpresspost، أو Priority.

Service to the USA: Cheapest available (الافتراضي)، أو Expedited Parcel USA، أو Tracked Packet USA، أو Small Packet USA Air، أو Xpresspost USA، أو Priority Worldwide parcel USA.

International service: Cheapest available (الافتراضي)، أو International Parcel Surface، أو International Parcel Air، أو Tracked Packet International، أو Small Packet International Surface، أو Small Packet International Air، أو Xpresspost International، أو Priority Worldwide parcel International.

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

Canadian sales taxes: يستخدم أسعار Canada Post بدون GST/HST/PST. وبالنسبة للعناوين الكندية يتضمن سعر Canada Post هذه الضرائب. فعّله عندما يضيف WooCommerce الضريبة على الشحن بنفسه (Tax status = Taxable)، حتى لا تُحتسب الضريبة مرتين.

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

Default product weight (kg): يُرسل إلى Canada Post لكل منتج بلا وزن. الافتراضي: 0.5. تُحوَّل أوزان المنتجات وأبعادها من وحدات متجرك، وتُحسب السلة كطرد واحد.

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

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

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

الشروط

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

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

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

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

Free shipping: يفعّل الشحن المجاني من المبلغ المذكور أدناه.

Free shipping from: المجموع الفرعي للسلة الذي يصبح عنده الشحن مجانيًا. وفي هذه الحالة لا يُرسل أي طلب إلى الواجهة.

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

Ignore shipping zones: يعرض الطريقة للدول المذكورة أدناه، بغض النظر عن المنطقة المطابقة.

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

متقدم

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

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

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

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

مع مفاتيح API، ترسل الإضافة إلى Canada Post الرمز البريدي للشحن، والوجهة، ووزن الطرد، وعند توفر أبعاد لكل المنتجات، حجم الطرد التقديري. وبالنسبة لكندا تكون الوجهة الرمز البريدي، ولبلدان الولايات المتحدة رمز ZIP، ولباقي الدول الدولة وحدها. ولا يُطلب سعر مباشر إلا عندما يحتوي عنوان كندي أو أمريكي على رمز بريدي أو ZIP صالح. تُرجع Canada Post جميع الخدمات للطرد؛ وتختار الإضافة الخدمة المختارة لمجموعة الوجهة أو الأرخص، وتزيل ضرائب المبيعات الكندية إذا كان Canadian sales taxes مفعّلًا، وتحوّل السعر بالدولار الكندي بسعر صرفك. يُحفظ اسم الخدمة مع الطلب ويظهر في شاشة طلب المسؤول باسم Canada Post service.

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

إذا لم تُرجع الواجهة سعرًا، يُستخدم السعر الثابت، أو تُخفى الطريقة إذا لم يوجد سعر ثابت. ولا يرى العميل تفاصيل أخطاء API أبدًا؛ إذ تُسجَّل في سجل WooCommerce.

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي Cart وCheckout. وهي متوافقة مع High-Performance Order Storage (HPOS) في WooCommerce.

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

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

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

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

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

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

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

لا تظهر Canada Post عند الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقّق من حدود الوزن وMinimum order amount وExcluded shipping classes. ويجب أن يوجد سعر: مع مفاتيح API يجب أن يحتوي العنوان على رمز بريدي صالح (كندا) أو رمز ZIP (الولايات المتحدة)، وإلا يجب أن يوجد سعر ثابت للدولة أو لـ *.

لا تظهر الأسعار المباشرة: فعّل Debug log، ثم أعد تحميل صفحة الدفع وافتح WooCommerce > Status > Logs، بالمصدر vfd-canada-post. ستجد السبب: اسم مستخدم أو كلمة مرور API مفقودة، أو رمز بريدي للشحن أو الوجهة غير صالح، أو سعر CAD مفقود، أو طرد يتجاوز 30 كجم، أو رسالة الخطأ من Canada Post. وفي الأثناء يحصل العملاء على السعر الثابت إن وُجد.

السعر يختلف عن موقع Canada Post: مع رقم العميل تحصل على الأسعار التجارية (المخفّضة) لحسابك؛ وبدونه تحصل على أسعار المكتب (التجزئة). وبالنسبة للعناوين الكندية يتضمن سعر Canada Post الضريبة GST/HST/PST. وتُحوَّل الأسعار بسعر صرف CAD الخاص بك.

تُحتسب الضريبة مرتين على الشحن: فعّل Canadian sales taxes، أو اضبط Tax status على None.

اختبار الأسعار في متجر حقيقي: أوقف Sandbox واستخدم مفتاح API الخاص بالإنتاج.

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

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

الإلغاء

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

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