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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Shippo: أنشئ حساب Shippo، ثم اربط شركات الشحن (USPS وUPS وFedEx وDHL وغيرها) أو فعّلها، وانسخ رمز API من Shippo > Settings > Advanced > API. تفرض Shippo رسومًا على الملصقات المشتراة، لا على طلبات الأسعار. قد تحتاج الحسابات الجديدة في Shippo إلى تحقق من Shippo قبل أن تُعاد الأسعار المباشرة. ومن دون رمز، تُستخدم الأسعار الاحتياطية فقط.

المنتجات: يجب أن يكون للمنتجات وزن وأبعاد. المنتجات التي لا أبعاد لها تستخدم حجم الصندوق الافتراضي.

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

التثبيت

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

2. انقر Activate.

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

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

5. الصق رمز Shippo API واملأ عنوان Ship from. الرمز البريدي إلزامي.

6. اختر Shippo rate currency (USD إذا كنت تشحن من الولايات المتحدة)، وإذا كان متجرك يستخدم عملة أخرى فأدخل سعر الصرف.

7. اختياريًا، أدخل الأسعار الاحتياطية في الجدول حسب الدولة والوزن.

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

الإعدادات

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

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

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

عام

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

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

حساب Shippo

API token: رمز Shippo API الخاص بك. استخدم الرمز الفعلي (shippo_live_...) للحصول على أسعار حقيقية في المتجر الحي، أو رمز الاختبار (shippo_test_...) لأسعار Shippo التجريبية.

Allowed carriers / services: اختياري، ومفصول بفواصل. أدخل شركة شحن باسمها كما تسميها Shippo (USPS وUPS وFedEx وDHL Express)، أو رمز مستوى خدمة من Shippo (usps_priority وups_ground). يُعرض أرخص سعر مسموح به. اتركه فارغًا لعرض أرخص سعر من أي شركة شحن.

Ship from (العنوان الذي تُرسل منه الطرود؛ تُملأ الحقول الفارغة من عنوان المتجر في WooCommerce > Settings > General إذا كان في الدولة نفسها)

Sender name / company: اسم المرسل. ويُستخدم أيضًا للتوقيع على البيان الجمركي.

Street address: عنوان الشارع للمرسل.

City: مدينة المرسل.

State / province: رمز الولاية أو المحافظة المكون من حرفين، مثل CA أو NY. تحتاجه بعض شركات الشحن.

Postal / ZIP code: إلزامي للأسعار المباشرة.

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

الأسعار

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

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

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

Default box size: الطول x العرض x الارتفاع بوحدة القياس في متجرك، مثل 30 x 20 x 10. تحتاج Shippo إلى حجم الصندوق. ويُستخدم عندما لا تكون لأحد المنتجات في السلة أبعاد. اتركه فارغًا لاستخدام 30 x 20 x 10 سم.

Shippo rate currency: العملة التي تُسعِّر بها Shippo شركات الشحن، وهي عملة دولة الشحن: USD (الولايات المتحدة)، أو CAD (كندا)، أو GBP (المملكة المتحدة)، أو EUR (منطقة اليورو)، أو AUD (أستراليا). الافتراضي: USD. وتُستخدم الأسعار التي تعيدها Shippo بعملة المتجر كما هي دائمًا.

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

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

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

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

Other countries: السعر للدول غير الموجودة في الجدول أعلاه (عندما لا يوجد صف * Default). اتركه فارغًا لإخفاء الطريقة لها.

الشروط

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

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

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

Maximum weight (kg): تُخفى الطريقة إذا تجاوز وزن السلة هذا الحد. الافتراضي: 30. 0 يعني بلا حد.

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

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

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

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

متقدم

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

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

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

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

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

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

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

إذا لم يتوفر سعر مباشر، يُؤخذ السعر من الجدول الاحتياطي، ثم من Other countries. وإذا لم ينطبق أيٌّ منهما، تُخفى الطريقة. ولا يرى العميل أي خطأ أبدًا.

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

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

الطلبات

يحفظ سطر الشحن في الطلب Carrier / service المختارة، وفي حالة الطرد الواحد لكل طلب يحفظ Estimated delivery days. تراها في شاشة الطلب في لوحة الإدارة، ويمكنك شراء الملصق المطابق في Shippo.

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

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

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

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

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

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

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

لا تظهر الأسعار المباشرة: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs، ومصدرها vfd-shippo. الأسباب الشائعة: عدم وجود رمز API أو رمز بريدي للشحن، أو اختلاف عملة المتجر عن Shippo rate currency دون سعر صرف، أو أن العميل لم يُدخل رمزه البريدي بعد، أو أن شركات الشحن في حساب Shippo لا تخدم العنوان، أو أن حساب Shippo لم يُتحقق منه بعد.

أسعار الاختبار في المتجر الحي: يعيد رمز الاختبار (shippo_test_...) أسعار Shippo التجريبية. استخدم الرمز الفعلي (shippo_live_...).

شحن مجاني لدول غير متوقعة: تحقق من جدول الأسعار بحثًا عن صف فارغ، وخاصة صف * Default الفارغ. والصف الذي تكون جميع خلاياه فارغة يُحتسب بسعر 0.

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

للمطورين: تغيّر المرشحات vfd_shpo_shipment_request وvfd_shpo_customs_declaration وvfd_shpo_selected_rate وvfd_shpo_api_url محتوى الطلب والبيان الجمركي والسعر المختار وعنوان API.

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

الإزالة

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

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