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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

تطبيق 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، لذلك لم يعد Web Tools User ID يعمل. دون مفاتيح تُستخدم الأسعار الثابتة فقط.

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

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

التثبيت

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

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

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

4. أدخل Consumer Key وConsumer Secret، ورمز Ship from ZIP code المكوّن من 5 أرقام، ثم اختر الخدمات. إذا لم تكن العملة الافتراضية للمتجر الدولار الأمريكي، فأدخل USD exchange rate. ويمكنك اختياريًا إدخال أسعار ثابتة كبديل. انقر على Save.

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

الإعدادات

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

لا تُحفظ القيمة غير الصالحة: تبقى القيمة السابقة، ويشير خطأ إلى الحقل المعني، بينما تُحفظ الحقول الأخرى. تخبرك التحذيرات أعلى الصفحة بما يلي: عند تعبئة أحد المفتاحين فقط، أو عدم وجود أي مفتاح ولا سعر ثابت (وعندها لا تظهر شركة الشحن أبدًا)، أو عند غياب رمز ZIP لمكان الإرسال، أو عدم اختيار أي خدمة، أو عند غياب سعر صرف الدولار، أو عند تفعيل بيئة الاختبار، أو عند عدم معرفة وحدة الوزن أو الأبعاد في المتجر (اضبطها في International > Localization، ضمن Local units)، أو عند حذف شركة الشحن USPS.

عام

Enable USPS shipping: يفعّل شركة الشحن أو يعطّلها. وهو المفتاح نفسه الذي يعرض حالة شركة الشحن في Shipping > Carriers.

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

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

واجهة USPS البرمجية (الأسعار الفورية)

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

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

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

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. دونه لا تُستخدم الأسعار الفورية وتُطبَّق الأسعار الثابتة. لا حاجة إليه إذا كانت العملة الافتراضية هي الدولار الأمريكي. يجب أن تكون القيمة أكبر من 0.

Cache: يمسح الزر Clear cached USPS token and rates الذاكرة المؤقتة فورًا. تُخزَّن الأسعار مؤقتًا لمدة ساعة، والسعر الفاشل لمدة 10 دقائق. بعد انتهاء المهلة أو خطأ الخادم أو تجاوز حد الطلبات أو رفض المفاتيح، لا يُستدعى USPS لمدة 5 دقائق.

الشحن والطرد (تعتمد أسعار USPS على رمز ZIP لمكان الإرسال والوزن وحجم الطرد؛ يُسعَّر السلة كطرد واحد، وتستخدم الطرود التي يزيد وزنها على 70 رطلًا الأسعار الثابتة)

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

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

Default product weight: الوزن بالكيلوغرام للمنتجات التي لا وزن لها، وذلك في أسعار USPS وحدود الوزن وشرائح الوزن. الافتراضي: 0.5.

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

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

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: الحد الأدنى لوزن السلة بالكيلوغرام لكي تظهر شركة الشحن هذه. 0 يعني بلا حد.

Max weight: تُخفى شركة الشحن عندما يتجاوز وزن السلة هذا الحد بالكيلوغرام. الافتراضي: 30. تقبل USPS حتى 70 رطلًا (31.7 كغ). 0 يعني بلا حد. إذا كان Min weight أكبر من Max weight، يظهر خطأ وتبقى الحدود السابقة.

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

الطلبات

عند إتمام طلب بشركة الشحن USPS، تحفظ الوحدة الطريقة التي حُسب بها سعر الشحن. تعرض صفحة الطلب في لوحة الإدارة كتلة USPS تتضمن USPS service (للسعر الفوري، مثلًا USPS Ground Advantage) وPrice source: USPS live rate أو Fixed price أو Free shipping.

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

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

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

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

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

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

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

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

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

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

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

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

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

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