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

المتطلبات

PrestaShop: 8.0 إلى 9.x.

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

تطبيق UPS Developer Portal (للأسعار الفورية فقط): سجّل الدخول إلى UPS Developer Portal (developer.ups.com)، وأنشئ تطبيقًا يتضمن منتج "Rating"، واربط حساب UPS الخاص بك، وانسخ Client ID وClient Secret. تستخدم الوحدة OAuth 2.0. لا حاجة إلى Access Key أو اسم مستخدم أو كلمة مرور. وللأسعار المتفق عليها تحتاج أيضًا إلى رقم حساب UPS المكوّن من 6 أحرف. ومن دون بيانات الاعتماد تُستخدم الأسعار الثابتة فقط.

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

التثبيت

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

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

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

4. أدخل Client ID وClient Secret، ورقم حساب UPS الخاص بك (للأسعار المتفق عليها)، وعنوان Ship from: الرمز البريدي، وللولايات المتحدة وكندا، رمز الولاية المكوّن من حرفين.

5. إذا كانت عملة حساب UPS الخاص بك تختلف عن العملة الافتراضية لمتجرك، فأدخل UPS account currency وExchange rate.

6. اختياريًا، أدخل الأسعار الثابتة كبديل احتياطي، ثم انقر على Save.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox UPS > Configure. وتُطبَّق على كل مناطق شركة الشحن. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. يمسح كل حفظ الرمز المميز والأسعار المخزنة مؤقتًا من UPS. ويمكنك أيضًا النقر على Clear cached UPS token and rates في قسم UPS API.

تخبرك التحذيرات فوق الإعدادات عندما يكون أحد الحقلين Client ID أو Client Secret فقط مُعبّأً، أو لا توجد بيانات اعتماد ولا أسعار ثابتة (وعندها لا تظهر شركة الشحن أبدًا)، أو يكون الرمز البريدي أو الولاية لعنوان الشحن مفقودًا، أو تُختار أسعار الحساب دون رقم حساب، أو يكون سعر الصرف مفقودًا، أو تكون وحدة الوزن أو الأبعاد في المتجر غير معروفة للوحدة. تُبلَّغ الأرقام غير الصالحة وحجم الصندوق الخاطئ وMin weight الأكبر من Max weight عند الحفظ، ويُحتفظ بالقيمة السابقة.

عام

Enable UPS shipping: يُشغّل شركة الشحن أو يوقفها. وهو المفتاح نفسه الموجود في حالة شركة الشحن في Shipping > Carriers.

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

Tax status: قاعدة الضريبة لشركة الشحن، أو None. تُعرض أسعار UPS دون ضرائب. ومع وجود قاعدة ضريبة، يضيف المتجر ضريبة الشحن الخاصة به فوقها.

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

Test mode: يستخدم بيئة الاختبار الخاصة بـ UPS. أسعار الاختبار ليست أسعارًا حقيقية. أوقفه للحصول على أسعار فورية. القيمة الافتراضية: off.

Client ID: Client ID لتطبيقك في UPS Developer Portal. مسح هذا الحقل يحذف أيضًا Client Secret المحفوظ.

Client Secret: Client Secret للتطبيق نفسه. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

UPS account number: رقم الشاحن الخاص بك في UPS المكوّن من 6 أحرف، مثل A1B2C3. مطلوب لأسعار الحساب (المتفق عليها)، واختياري للأسعار المعلنة.

Rates: أي أسعار UPS تُستخدم.

Measurement units: الوحدات المرسلة إلى UPS. تُحوَّل أوزان المتجر وأحجامه.

Residential delivery: يحسب عناوين العملاء كعناوين سكنية، مع رسوم UPS السكنية الإضافية. أوقفه إذا كنت تشحن غالبًا إلى الشركات. القيمة الافتراضية: on.

Box size: أبعاد الصندوق الاختيارية بوحدة الأبعاد في متجرك، مثل 30x20x15. عندها تطبّق UPS الوزن الحجمي. اتركه فارغًا للتسعير بالوزن فقط.

UPS account currency: تُسعّر UPS بعملة دولة حساب الشاحن، مثل USD للولايات المتحدة، وCAD لكندا، وEUR لمنطقة اليورو. القيمة الافتراضية: USD.

Exchange rate: مطلوب فقط عندما تختلف عملة حساب UPS عن العملة الافتراضية لمتجرك. أدخل سعر وحدة واحدة من عملة الحساب بعملتك الافتراضية، مثل 0.92. ومن دونه لا تُستخدم هذه الأسعار وتُطبَّق الأسعار الثابتة. لا تُحدَّث أسعار الصرف تلقائيًا.

عنوان الشحن (العنوان الذي تستلم منه UPS الطرود أو الذي تُسلّم فيه الطرود؛ يُستخدم للأسعار الفورية)

Country: البلد الذي تشحن منه. افتراضيًا، هو بلد متجرك.

State / province code: الرمز المكوّن من حرفين، ومطلوب للولايات المتحدة وكندا، مثل NY أو CA أو ON.

City: المدينة التي تشحن منها.

ZIP / postal code: الرمز البريدي الذي تشحن منه. تحتاجه UPS لحساب الأسعار.

الأسعار الثابتة (تُستخدم عند عدم إدخال بيانات اعتماد API، وكبديل احتياطي عندما لا تُرجِع UPS أي سعر؛ اترك الحقلين فارغين لإخفاء شركة الشحن في هذه الحالة)

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

Fallback cost: سعر ثابت بالعملة الافتراضية لمتجرك، عندما لا يتطابق أي سعر حسب البلد. اتركه فارغًا لإخفاء شركة الشحن في هذه الحالة.

Fixed price is: Per order يحتسب السعر مرة واحدة، لوزن السلة كاملة. Per item (each item priced by its own weight x quantity) يسعّر كل منتج بوزنه الخاص (الوزن الافتراضي إذا لم يكن له وزن) ويضربه في كميته. إذا لم يكن لأحد المنتجات سعر ثابت، تُخفى شركة الشحن. تُحسب أسعار UPS الفورية دائمًا لوزن السلة الكامل.

الشروط

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

Minimum subtotal: اعرض شركة الشحن فقط عندما يبلغ المجموع الفرعي للسلة هذا المبلغ على الأقل. اتركه فارغًا لعرضها دائمًا.

Min weight: الحد الأدنى لوزن السلة بالكغ حتى تظهر شركة الشحن هذه. القيمة 0 تعني بلا حد.

Max weight: تُخفى شركة الشحن عندما يتجاوز وزن السلة هذا الحد بالكغ. القيمة الافتراضية: 70، وهي حد UPS لكل طرد (70 كغ / 150 lbs). القيمة 0 تعني بلا حد، والفراغ يعني 70. لا يمكن أن يكون Min weight أكبر من Max weight.

Default product weight: الوزن بالكغ الذي يُستخدم للمنتجات التي لا وزن لها، في أسعار UPS وأعمدة الوزن وحدود الوزن. القيمة الافتراضية: 0.5.

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

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

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

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

متقدم

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

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

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

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

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

تحصل الوحدة على رمز OAuth من UPS وتحتفظ به حتى انتهاء صلاحيته. ويُجدَّد الرمز الذي ترفضه UPS تلقائيًا. ثم تطلب من UPS Rating API جميع الخدمات من عنوان الشحن الخاص بك إلى عنوان العميل، للسلة كطرد واحد. بالنسبة للبلدان التي تستخدم الرموز البريدية، ينتظر الطلب حتى يُدخل العميل رمزه البريدي. أما الشحنات من الولايات المتحدة إلى كندا أو بورتوريكو، فتُرسل قيمة البضائع كما تشترط UPS.

يرى العميل خيارًا واحدًا مع أرخص خدمة UPS. يُحتسب السعر بالعملة الافتراضية لمتجرك، ثم يُعرض بعملة سلة العميل. لا تُسعَّر خدمة UPS Access Point Economy، لأن الوحدة لا تجمع عنوان Access Point.

يُخزَّن كل عرض سعر مؤقتًا لمدة ساعة. يُتذكّر الطلب الفاشل لمدة 10 دقائق، وطلب الرمز الفاشل لمدة 5 دقائق، حتى لا يُبطئ أي عطل كل تحديث للدفع. مهلة HTTP هي 15 ثانية.

إذا لم تُرجِع UPS أي سعر (واجهة API متوقفة، أو بيانات اعتماد خاطئة، أو لا توجد خدمة، أو عملة أخرى بلا سعر صرف)، يأتي السعر من Country prices، ثم من Fallback cost. وإذا لم ينطبق أي منهما، تُخفى شركة الشحن. ولا يرى العميل نصوص أخطاء UPS أبدًا.

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

تحسب الوحدة الأسعار فقط. فهي لا تعرض اختيار UPS Access Point، ولا تنشئ ملصقات شحن أو شحنات UPS، ولا تحجز مواعيد الاستلام، ولا تتتبع الطرود. تعرض خيارًا واحدًا لا عدة خدمات من UPS. لا يوجد تعبئة في صناديق: تُسعَّر السلة كطرد واحد. أسعار الصرف ليست تلقائية.

الطلبات

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

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

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

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

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

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

لا تظهر UPS عند الدفع: تحقّق من أن الترخيص نشط وأن Enable UPS shipping مفعّل. في Shipping > Carriers، تحقّق من أن شركة الشحن تغطي منطقة بلد العميل ومجموعته، أو فعّل Ignore shipping zones وتحقّق من Countries. تحقّق من حدود الوزن وMinimum subtotal. ومن دون بيانات اعتماد UPS تعمل، تحتاج شركة الشحن إلى سعر ثابت (Country prices أو Fallback cost). ويمكن أيضًا قصر المنتجات على شركات شحن معيّنة من صفحة المنتج.

لا تظهر الأسعار الفورية: راجع التحذيرات أعلى صفحة Configure. فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى الحقل Log في صفحة الوحدة. يعرض أخطاء OAuth (تحقّق من Client ID وClient Secret وTest mode)، ورسائل أخطاء UPS، ومشكلات العملة.

السعر بالدولار الأمريكي والمتجر ليس كذلك: تُرجِع UPS الأسعار بعملة حساب الشاحن. اضبط UPS account currency وExchange rate. ومن دون سعر صرف تُتجاهل هذه الأسعار ويُستخدم السعر الثابت.

"This measurement system is not valid for the selected country": اترك Measurement units على Automatic، أو اختر الوحدات التي تتوقعها UPS لبلد الشحن الخاص بك.

تحذّر الصفحة من أن وحدة وزن المتجر أو أبعاده غير معروفة: عندها تُقرأ الأوزان بالكغ وحجم الصندوق بالسنتيمتر. اضبط وحدة قياسية (kg أو g أو lb أو oz؛ أو cm أو mm أو m أو in) في International > Localization، القسم Local units.

تبدو الأسعار قديمة بعد تغيير: انقر على Save في صفحة الوحدة، أو على Clear cached UPS token and rates.

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

للمطورين: تحدّ الخطافات actionVfdUpsxAllowedServices وactionVfdUpsxExcludedServices خدمات UPS التي يمكن عرضها. تغيّر actionVfdUpsxRateRequest طلب السعر، وتغيّر actionVfdUpsxApiBaseUrl عنوان API، وactionVfdUpsxCurrencyCodes تربط رموز العملات التي تُرجعها UPS.

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

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

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