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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

تطبيق 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. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة، وانقر على Install Now. يمكنك أيضًا رفع مجلد vfd_ups إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

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

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

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

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

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

8. يمكنك اختياريًا إدخال أسعار ثابتة كبديل.

الإعداد

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

Title (zone): اسم هذا الخيار عند الدفع. اتركه فارغًا لاستخدام Name العام.

في كل مرة تحفظ فيها الإعدادات تُمسح الرموز المخزنة مؤقتًا من UPS والأسعار المخزنة. ويمكنك أيضًا النقر على Clear cached UPS token and rates في قسم UPS API. وتُظهر التحذيرات أعلى الإعدادات ما إذا كان Client ID أو Client Secret مُدخلًا وحده، أو لا توجد بيانات اعتماد ولا أسعار ثابتة، أو الرمز البريدي أو الولاية لنقطة الشحن مفقودة، أو اختيرت أسعار الحساب دون رقم حساب، أو سعر الصرف مفقود.

General

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

Name: اسم طريقة الشحن الذي يظهر عند الدفع. الافتراضي: UPS.

Tax status: Taxable يسمح لـ WooCommerce بإضافة ضريبة الشحن فوق السعر، وNone لا يضيفها. تُقدَّم أسعار UPS دون ضرائب، لذلك لا تُفرض الضريبة مرتين.

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

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

Client ID: معرّف العميل (Client ID) لتطبيقك في UPS Developer Portal.

Client Secret: السر (Client Secret) للتطبيق نفسه.

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

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

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

Residential delivery: يُحتسب عنوان العميل كعنوان سكني مع رسوم التوصيل السكني من UPS. أوقفه إذا كنت تشحن في الغالب إلى الشركات. الافتراضي: مُفعّل.

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 لإضافة صف، وعلى علامة الإغلاق لحذف صف. يُطبَّق الصف * Default على أي دولة أخرى. يحل عمود الوزن (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: المجموع الفرعي للسلة الذي تصبح عنده هذه الطريقة مجانية. يرى العميل اسم الطريقة مع "(Free)"، ولا يُرسل أي طلب إلى UPS. اتركه فارغًا لعدم تقديم شحن مجاني أبدًا.

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

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

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

Default product weight (kg): الوزن المستخدم للمنتجات التي لا وزن لها، في أسعار UPS وأعمدة الوزن وحدود الوزن. الافتراضي: 0.5.

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

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

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

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

متقدم

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

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

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

عندما يُدخل العميل عنوان التوصيل، يطلب WooCommerce من الإضافة سعرًا. تتحقق الإضافة أولًا من الشروط: وزن السلة، والحد الأدنى للمجموع الفرعي، وفئات الشحن المستثناة. فإذا انطبق الشحن المجاني، تُعرض الطريقة مجانية ولا يُرسل أي طلب إلى 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 أبدًا.

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

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

الطلبات

بالنسبة إلى السعر الفوري، يخزّن سطر الشحن في الطلب UPS service، مثل UPS Ground. ويراه مدير المتجر في شاشة الطلب في لوحة الإدارة.

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

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

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

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

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

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

لا تظهر UPS عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مُفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مُفعّل والدولة مسموح بها). وتحقق من حدود الوزن وMinimum subtotal وExcluded shipping classes. ومن دون بيانات اعتماد UPS صالحة تحتاج الطريقة إلى سعر ثابت (Country prices أو Fallback cost).

لا تظهر الأسعار الفورية: راجع التحذيرات أعلى صفحة الإعدادات. فعّل Debug log وافتح WooCommerce > Status > Logs، والمصدر vfd-ups. ستظهر فيه أخطاء 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 لدولة الشحن لديك.

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

للمطوّرين: ترشّح الفلاتر vfd_upsx_allowed_services وvfd_upsx_excluded_services خدمات UPS التي يمكن عرضها. ويغيّر vfd_upsx_rate_request طلب السعر، ويغيّر vfd_upsx_api_base_url عنوان API، ويربط vfd_upsx_currency_codes رموز العملات التي تُرجعها UPS.

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

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

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

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