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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب EasyPost (للأسعار المباشرة فقط): أنشئ حسابًا على موقع EasyPost، واربط حسابات شركات الشحن لديك (USPS وUPS وFedEx وغيرها) في لوحة EasyPost، وانسخ مفتاح API من EasyPost Dashboard > Account Settings > API Keys. تفرض EasyPost رسومًا على الملصقات المشتراة، لا على طلبات الأسعار. وإذا كنت تستخدم الأسعار الاحتياطية فقط، فلا تحتاج إلى حساب EasyPost.

المنتجات: يجب أن تحتوي المنتجات على وزن، والأفضل أن تحتوي أيضًا على أبعاد.

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

التثبيت

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

2. انقر Activate.

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

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

5. الصق مفتاح API الخاص بـ EasyPost واملأ عنوان Ship from. الرمز البريدي مطلوب للأسعار المباشرة.

6. إذا لم تكن عملة متجرك USD، فأدخل USD exchange rate. ويمكنك اختياريًا إدخال الأسعار الاحتياطية (راجع الإعدادات).

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

الإعدادات

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

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

في أعلى الصفحة، تعرض الإضافة تحذيرات عندما لا يمكن استخدام الأسعار المباشرة: لا يوجد مفتاح API، أو لا يوجد رمز ZIP أو دولة للشحن من مكانه، أو عملة المتجر ليست USD دون سعر صرف. وتظهر ملاحظة أيضًا عند تعيين مفتاح API تجريبي. وفي كل مرة تحفظ فيها الإعدادات، تُمسح أسعار EasyPost المخزنة مؤقتًا.

عام

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

Name: اسم طريقة الشحن المعروض في السلة وعند الدفع. يمكن لأي منطقة أن تستبدله بـ Title خاص بها. الافتراضي: EasyPost Shipping.

حساب EasyPost

API key: مفتاح API الخاص بـ EasyPost من EasyPost Dashboard > Account Settings > API Keys. يعيد مفتاح الإنتاج (ويبدأ بـ EZAK) أسعارًا حقيقية. ويعيد مفتاح الاختبار (ويبدأ بـ EZTK) أسعار اختبار من EasyPost؛ استخدمه للاختبار فقط.

Allowed carriers / services: اختياري، مفصول بفواصل. أدخل شركة شحن (USPS) أو شركة شحن وخدمة (USPS:Priority وUPS:Ground) كما تسميها EasyPost. يُعرض أرخص سعر مسموح به. اتركه فارغًا لعرض أرخص سعر من أي شركة شحن.

مصدر الشحن

العنوان الذي تُرسل منه طرودك. إذا كانت Country هي دولة متجرك، تُملأ الحقول الفارغة من عنوان المتجر في WooCommerce > Settings > General (ويُؤخذ اسم المرسل من عنوان الموقع).

Sender name / company: اسم المرسل أو الشركة.

Street address: الشارع في عنوان الشحن.

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

State: رمز الولاية المكون من حرفين، مثل CA أو NY.

ZIP code: الرمز البريدي للشحن. مطلوب للأسعار المباشرة.

Country: الدولة التي تشحن منها. الافتراضي: United States.

الأسعار

Parcels: طريقة إرسال السلة إلى EasyPost.

One parcel per order (the cart is packed into one box): تُعبأ جميع الوحدات في صندوق واحد وتُحتسب مرة واحدة. وهذا هو الافتراضي.

One parcel per item (every unit ships in its own box): يُحتسب كل منتج كطرد مستقل، ويُحتسب السعر عن كل وحدة. وتُحتسب الأسعار الاحتياطية عن كل وحدة أيضًا.

تُحوَّل الأوزان من وحدة الوزن في متجرك إلى أونصات (بحد أدنى 1 oz)، وتُحوَّل الأبعاد إلى بوصات. إذا لم تكن لأي منتج أبعاد، يُحتسب الطرد حسب الوزن فقط.

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

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

الأسعار الاحتياطية

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

Country prices: سطر واحد لكل دولة: رمز الدولة المكون من حرفين، ثم نقطتان رأسيتان، ثم السعر، مثل US:9.99. تُتجاهل الأسطر بصيغة أخرى، وتُدرج في رسالة خطأ عند الحفظ.

Other countries: السعر للدول غير المدرجة في القائمة أعلاه. اتركه فارغًا لإخفاء الطريقة لتلك الدول.

الشروط

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

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

Minimum weight: أخفِ الطريقة عندما يكون وزن السلة أقل من ذلك، بوحدة الوزن في متجرك. يعني 0 عدم وجود حد.

Maximum weight: أخفِ الطريقة عندما يكون وزن السلة أكبر من ذلك، بوحدة الوزن في متجرك. يعني 0 عدم وجود حد.

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

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

Ignore shipping zones: اعرض الطريقة للدول المذكورة أدناه، سواء أُضيفت إلى منطقة أم لا.

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

متقدم

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

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

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

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

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

تُخزَّن كل استجابة مؤقتًا لمدة ساعة لنفس العنوان ونفس الطرد. ويُتذكَّر العنوان الذي لا تتوفر له أسعار صالحة لمدة 10 دقائق. وبعد انتهاء المهلة، أو رفض المفتاح، أو تجاوز حد الطلبات (rate limit)، أو حدوث خطأ في خادم EasyPost، لا تُرسل أي طلبات لمدة 5 دقائق. مهلة API هي 10 ثوانٍ. وفي كل هذه الحالات لا يرى العميل أي خطأ: يُستخدم السعر الاحتياطي، أو تُخفى الطريقة إذا لم يوجد سعر احتياطي.

تُخزَّن شركة الشحن والخدمة المختارتان، وفي وضع الطرد الواحد أيام التسليم المقدَّرة، مع بند الشحن في الطلب. وتراها في شاشة الطلب في لوحة الإدارة.

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

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

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

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

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

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

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

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

لا تظهر EasyPost عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). وتحقق من حدود الوزن، وMinimum subtotal، وDisabled shipping classes. وبدون سعر مباشر تحتاج الطريقة إلى سعر احتياطي لتلك الدولة أو لـ Other countries.

لا تظهر الأسعار المباشرة: اقرأ التحذيرات أعلى صفحة الإعدادات، ثم فعّل Debug log، وأعد تحميل صفحة الدفع، وافتح WooCommerce > Status > Logs بالمصدر vfd-easypost. الأسباب الشائعة: لا يوجد مفتاح API أو رمز ZIP للشحن، أو متجر ليست عملته USD دون USD exchange rate، أو لم يُدخل العميل رمزه البريدي بعد، أو لا تخدم أي شركة شحن في حساب EasyPost لديك هذا العنوان، أو أن Allowed carriers / services يستبعد جميع الأسعار.

تبدو الأسعار كأسعار تجريبية: مفتاح الاختبار (EZTK...) مُعيَّن. استخدم مفتاح إنتاج (EZAK...) في المتجر الفعلي.

توقفت الأسعار لبضع دقائق: بعد انتهاء المهلة، أو رفض المفتاح، أو خطأ في خادم EasyPost، توقف الإضافة الطلبات لمدة 5 دقائق وتستخدم الأسعار الاحتياطية. تحقق من مفتاح API والسجل.

هل الضريبة مشمولة؟ لا تتضمن أسعار EasyPost ضريبة المبيعات. ومع Tax status على Taxable، يضيف WooCommerce الضريبة على الشحن وفق إعدادات الضرائب لديك.

تبدو الأسعار قديمة بعد تغيير: احفظ صفحة الإعدادات. سيؤدي ذلك إلى مسح أسعار EasyPost المخزنة مؤقتًا.

خطافات المطورين: تُخصِّص المرشحات vfd_ep_shipment_request (جسم الطلب)، وvfd_ep_selected_rate (السعر المختار)، وvfd_ep_api_url (عنوان URL الأساسي لـ API)، وwoocommerce_shipping_vfd_easypost_is_available الإضافة.

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

الإلغاء

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

EasyPost علامة تجارية تعود ملكيتها إلى مالكها. ولا ترتبط هذه الإضافة بـ EasyPost ولا تحظى بتأييدها.