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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

تطبيق في USPS Developer Portal (للأسعار الفورية فقط): سجّل الدخول إلى USPS Developer Portal (developers.usps.com) بحساب أعمال مجاني لدى USPS، وأنشئ تطبيقًا وانسخ Consumer Key وConsumer Secret الخاصين به. تستخدم الإضافة واجهات USPS البرمجية الحالية مع OAuth 2.0. أوقفت USPS واجهة Web Tools القديمة (User ID وXML) في 25 يناير 2026، لذلك لم يعد User ID الخاص بـ Web Tools يعمل. وبدون مفاتيح تُستخدم الأسعار الثابتة فقط.

Ship-from ZIP code: تحتاج الأسعار الفورية إلى رمز ZIP أمريكي من 5 أرقام للمكان الذي تُرسل منه الطرود.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل Consumer Key وConsumer Secret، ورمز Ship from ZIP code المكون من 5 أرقام، واختر الخدمات. إذا لم تكن عملة متجرك الدولار الأمريكي، فأدخل USD exchange rate.

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

7. اختياري: أدخل أسعارًا ثابتة كبديل.

الإعدادات

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

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

في كل مرة تحفظ فيها الإعدادات، يُمسح رمز USPS المخزن مؤقتًا والأسعار. ويمكنك أيضًا النقر على Clear cached USPS token and rates في قسم USPS API. وتُظهر التحذيرات فوق الإعدادات ما إذا كان مفتاح واحد فقط مُدخلًا، أو لا توجد مفاتيح ولا أسعار ثابتة، أو كان رمز Ship from ZIP code مفقودًا، أو لم تُختر أي خدمة، أو كان USD exchange rate مفقودًا، أو كانت بيئة الاختبار مفعّلة.

عام

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

Name: اسم طريقة الشحن المعروض عند الدفع. الافتراضي: USPS.

Tax status: أسعار USPS لا تشمل الضرائب. يتيح Taxable لـ WooCommerce إضافة ضريبة الشحن إلى التكلفة، أما None فلا يضيفها.

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

Consumer Key: مفتاح Consumer Key (client_id) لتطبيق المطور الخاص بك لدى USPS.

Consumer Secret: مفتاح Consumer Secret (client_secret) للتطبيق نفسه.

Test environment: يستخدم USPS Testing Environment for Mailers. خاص بالتطبيقات التي لديها صلاحية الوصول إليه فقط. اتركه معطّلًا للحصول على أسعار حقيقية. الافتراضي: معطّل.

Prices: أي أسعار USPS تُستخدم.

Services: خدمات USPS التي يمكن عرضها. تُعرض أرخص الخدمات المختارة التي تقدمها USPS للطرد. أسعار Flat Rate وCubic وHold for Pickup وSunday لا تُستخدم أبدًا. الافتراضي: USPS Ground Advantage وPriority Mail وFirst-Class Package International Service.

USD exchange rate: أسعار USPS بالدولار الأمريكي. إذا لم تكن عملة متجرك الدولار الأمريكي، فأدخل سعر 1 دولار أمريكي بعملة متجرك، مثلًا 0.92. وبدونه لا تُستخدم الأسعار الفورية وتُطبَّق الأسعار الثابتة. لا حاجة إليه عندما تكون عملة المتجر الدولار الأمريكي.

الشحن من وطرد (أسعار USPS تعتمد على رمز ZIP لنقطة الإرسال والوزن وحجم الطرد)

Ship from ZIP code: رمز ZIP أمريكي من 5 أرقام للمكان الذي تُرسل منه الطرود. يُقتطع رمز ZIP+4 إلى 5 أرقام. القيم الأخرى تُرفض مع رسالة.

Box size: أبعاد صندوق اختيارية بوحدة قياس متجرك، مثل 30x20x15. اتركه فارغًا لحساب الحجم من أبعاد المنتجات: أطول طول، وأعرض عرض، والارتفاعات مكدسة. إذا لم تكن للمنتج أبعاد، يُستخدم صندوق بحجم 10 x 8 x 4 بوصة.

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

الأسعار الثابتة (الأسعار بعملة متجرك؛ تُستخدم عندما لا يُدخل أي مفتاح API، وكبديل عندما لا تُرجع USPS سعرًا: خدمة API متوقفة، أو مفاتيح خاطئة، أو لا توجد خدمة، أو وجهة بلا رمز ZIP أمريكي؛ اترك الحقلين فارغين لإخفاء الطريقة في هذه الحالة)

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

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

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

الشروط

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

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

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

Max weight (kg): تُخفى الطريقة فوق وزن السلة هذا. الافتراضي: 30. تقبل USPS حتى 70 رطلًا (31٫7 كجم). 0 يعني بلا حد.

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

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

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

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

متقدم

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

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

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

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

تحصل الإضافة على رمز OAuth من USPS وتحتفظ به حتى انتهاء صلاحيته. يُجدَّد الرمز الذي ترفضه USPS وتُكرَّر طلب السعر. بالنسبة للوجهات في الولايات المتحدة وأقاليمها (ومنها بويرتو ريكو وجزر فيرجن الأمريكية وغوام) تستعلم الإضافة عن Domestic Prices API، وتحتاج إلى رمز ZIP المكون من 5 أرقام للعميل. أما للدول الأخرى فتستعلم عن International Prices API بالدولة والرمز البريدي.

يتضمن الطلب رمز ZIP الخاص بنقطة الإرسال، ووزن السلة بالأرطال، وحجم الطرد بالبوصات، ونوع السعر. تحصل الطرود التي يزيد وزنها على 70 رطلًا على الأسعار الثابتة. يرى العميل خيارًا واحدًا بأرخص الخدمات المختارة، محوَّلًا إلى عملة متجرك.

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

إذا لم تُرجع USPS سعرًا، يُؤخذ السعر من Country prices، ثم من Fallback cost. إذا لم ينطبق أيٌّ منهما، تُخفى الطريقة. لا يرى العميل نصوص أخطاء USPS أبدًا.

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

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

الطلبات

بالنسبة إلى السعر الفوري، يحفظ سطر الشحن في الطلب USPS service، مثل USPS Ground Advantage. يرى مدير المتجر ذلك في شاشة الطلب في لوحة الإدارة.

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

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

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

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

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

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

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

لا تظهر الأسعار الفورية: راجع التحذيرات أعلى صفحة الإعدادات. فعّل Debug log وافتح WooCommerce > Status > Logs، بالمصدر vfd-usps. تُسجَّل هناك المفاتيح الخاطئة وبيئة الاختبار الخاطئة ورسائل خطأ USPS. الأسعار المحلية تحتاج إلى رمز ZIP المكون من 5 أرقام للعميل.

متجري ليس بالدولار الأمريكي: تُسعِّر USPS بالدولار الأمريكي فقط. أدخل USD exchange rate. وبدونه لا يُستخدم السعر الفوري، ويظهر السعر الثابت بدلًا منه.

لا يعمل User ID الخاص بـ Web Tools: أُوقفت واجهة Web Tools القديمة. أنشئ تطبيقًا في USPS Developer Portal واستخدم Consumer Key وConsumer Secret الخاصين به.

تبدو الأسعار قديمة بعد تغيير: يُمسح التخزين المؤقت عند حفظ الإعدادات. ويمكنك أيضًا النقر على Clear cached USPS token and rates.

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

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

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

USPS علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ USPS ولا معتمدة من قبلها.