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

المتطلبات

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

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

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. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP للوحدة.

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

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

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

عند التثبيت، تنشئ الوحدة شركة الشحن Canada Post بنص مدة النقل Canada Post parcel delivery. تُعيَّن شركة الشحن لجميع المناطق ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة النقل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

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

عند وجود قيمة خاطئة، تعرض الصفحة خطأً ولا يُحفظ شيء: حقل رقمي أو سعر في Country prices ليس رقمًا يساوي 0 أو أكبر (مثل -1 أو 12abc)، أو سعر صرف CAD يساوي 0، أو Min cart weight (kg) أكبر من Max cart weight (kg)، أو Method title أطول من 64 حرفًا. إذا كانت وحدة الوزن أو الأبعاد في متجرك غير معروفة للوحدة، تحذّرك الصفحة من أن الأوزان تُقرأ بالكيلوغرام (والأبعاد بالسنتيمتر). اضبط kg أو g أو lb أو oz (cm أو mm أو m أو in) في International > Localization، القسم Local units.

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

عام

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

Method title: اسم شركة الشحن الذي يراه العميل عند الدفع. القيمة الافتراضية: Canada Post، حتى إذا تُرك الحقل فارغًا. حتى 64 حرفًا، دون الأحرف التي لا يسمح بها PrestaShop في أسماء شركات الشحن.

Tax: قاعدة الضريبة التي يضيفها PrestaShop إلى تكلفة الشحن، أو No tax (غير خاضع للضريبة).

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

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

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

API password: الجزء من مفتاح API الذي يلي النقطتين. بعد الحفظ يبقى الحقل فارغًا ويعرض A password is saved. Leave empty to keep it; clear the username and save to remove both. اكتب قيمة جديدة فقط إذا أردت تغييرها. تُحفظ كلمة المرور كما كتبتها تمامًا، ولا تُكتب في السجل أبدًا.

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

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

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

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

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

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

International service: Cheapest available (الافتراضي)، أو International Parcel Surface (INT.IP.SURF)، أو International Parcel Air (INT.IP.AIR)، أو Tracked Packet International (INT.TP)، أو Small Packet International Surface (INT.SP.SURF)، أو Small Packet International Air (INT.SP.AIR)، أو Xpresspost International (INT.XP)، أو Priority Worldwide parcel International (INT.PW.PARCEL).

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

Use Canada Post prices without GST/HST/PST: بالنسبة للعناوين الكندية، يتضمن سعر Canada Post هذه الضرائب. فعّله عندما تضيف PrestaShop الضريبة على الشحن بنفسها (Tax أعلاه)، حتى لا تُحتسب الضريبة مرتين.

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

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

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

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

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

الشروط

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

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

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

Free shipping: يُفعّل التوصيل المجاني من المبلغ أدناه.

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

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

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

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

Countries: دول الوجهة لهذا الوضع. اضغط مع الاستمرار على Ctrl (Cmd) لتحديد أكثر من دولة. اتركه فارغًا للسماح بجميع الدول المفعّلة. يُستخدم هذا الحقل فقط عندما يكون Ignore shipping zones مفعّلًا.

متقدم

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

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

Log: تعرض اللوحة أسفل الإعدادات اسم الملف وآخر 50 مدخلًا. انقر على Clear log لحذفه.

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

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

مع بيانات اعتماد API، ترسل الوحدة إلى Canada Post الرمز البريدي للشحن، والوجهة، ووزن الطرد، وحجم الطرد التقديري عندما تكون أبعاد كل المنتجات متوفرة. بالنسبة لكندا، الوجهة هي الرمز البريدي؛ وبالنسبة للولايات المتحدة، رمز ZIP؛ ولجميع الدول الأخرى، الدولة وحدها. لا يُطلب سعر مباشر إلا عندما يحتوي عنوان كندي أو أمريكي على رمز بريدي أو ZIP صالح. تُرجع Canada Post جميع الخدمات للطرد. تختار الوحدة الخدمة المختارة لمجموعة الوجهة أو الأرخص، وتُزيل ضرائب المبيعات الكندية (GST/HST/PST) إذا كان خيار Use Canada Post prices without GST/HST/PST مفعّلًا، وتحوّل سعر CAD بسعر صرفك. يُحسب السعر بالعملة الافتراضية لمتجرك، ثم يُعرض بعملة سلة العميل.

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

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

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

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

الطلبات

عندما يُقدَّم طلب بشركة الشحن Canada Post، تحفظ الوحدة طريقة حساب سعره. في صفحة الطلب في لوحة الإدارة (Orders > Orders، افتح طلبًا) تعرض كتلة Canada Post:

Canada Post service: اسم الخدمة ورمزها للسعر المباشر، مثل Regular Parcel (DOM.RP).

Price source: Live rate (Canada Post Rating API)، أو Fixed price، أو Free shipping.

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

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

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

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

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

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

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

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

تُحتسب الضريبة على الشحن مرتين: فعّل Use Canada Post prices without GST/HST/PST، أو اضبط Tax على No tax.

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

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

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

ليست لديك صلاحية لإعداد هذه الوحدة: ملفك الوظيفي يمكنه فتح صفحة الوحدة ولكن لا يمكنه حفظها. اطلب من أحد المديرين منح ملفك صلاحية إعداد الوحدة.

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

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

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