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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب ShipStation: اربط شركات الشحن في ShipStation (Settings > Shipping > Carriers)، ثم انسخ API Key وAPI Secret من ShipStation > Settings > Account > API Settings. يعتمد الوصول إلى API على خطة ShipStation لديك. إذا لم تكن الصفحة متاحة، فخطتك لا تتضمن الوصول إلى API. تستخدم الإضافة ShipStation API V1 (API Key وAPI Secret). ولا تُدعم حسابات ShipStation API V2 التي تملك مفتاح API واحدًا. ومن دون المفاتيح تُستخدم أسعار الاحتياط فقط.

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

التثبيت

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

2. انقر Activate.

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

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

5. الصق API Key وAPI Secret، وأدخل الرمز البريدي لمكان الشحن، ثم احفظ. ستعرض الصفحة الآن رموز شركات الشحن في حسابك. أدخل الرمز أو الرموز التي تريدها في Carrier codes، ثم احفظ مرة أخرى.

6. إذا كانت عملة متجرك تختلف عن عملة حساب ShipStation، فاضبط Exchange rate.

7. اختياريًا، املأ أسعار الاحتياط.

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

الإعدادات

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

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

في كل مرة تحفظ فيها الإعدادات، تُمسح أسعار ShipStation المخزنة مؤقتًا، ويُفحص API Key وAPI Secret. ثم تعرض الصفحة شركات الشحن المرتبطة بحسابك مع رموزها، مثل: "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". وتخبرك التحذيرات فوق الإعدادات بالحالات التي لا تعمل فيها أسعار الشحن الفورية: غياب المفاتيح، أو غياب رمز شركة الشحن، أو غياب الرمز البريدي لمكان الشحن، أو غياب سعر الصرف، أو فشل فحص الاتصال، أو عدم ارتباط رموز شركات الشحن بحسابك.

عام

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

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

حساب ShipStation

API Key: الـ API Key من ShipStation > Settings > Account > API Settings.

API Secret: الـ API Secret من الصفحة نفسها.

Carrier codes: رمز واحد أو أكثر لشركات شحن ShipStation، مفصولة بفواصل، مثل stamps_com, ups_walleted. يُستخدم ما يصل إلى 5 رموز، مع طلب API واحد لكل شركة شحن. ويُعرض أرخص سعر من هذه الشركات. خذ الرموز من القائمة التي تظهر بعد الحفظ.

Allowed services: اختياري، رموز خدمات ShipStation مفصولة بفواصل، مثل usps_priority_mail, ups_ground. اتركه فارغًا لعرض أرخص خدمة من شركات الشحن المذكورة أعلاه.

Package code: "package" (الافتراضي) يحسب السعر لصندوقك الخاص، ويستثني أظرف شركة الشحن وصناديق السعر الثابت. اتركه فارغًا لحساب الأسعار لكل أنواع الحزم التي تقدمها شركة الشحن.

مكان الشحن

Ship-from postal code: مطلوب للأسعار الفورية. تحسب ShipStation الأسعار استنادًا إلى الرمز البريدي وحده، ويجب أن يقع في بلد حساب ShipStation لديك. اتركه فارغًا لاستخدام الرمز البريدي للمتجر المعرّف في WooCommerce > Settings > General.

الأسعار

Parcels: كيفية إرسال السلة إلى ShipStation.

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

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

ShipStation account currency: العملة التي تعيد بها ShipStation الأسعار: USD أو CAD أو GBP أو AUD أو NZD أو EUR. الافتراضي: USD (حسابات الولايات المتحدة).

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

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

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

Prices by country: جدول يضم سعرًا أساسيًا لكل بلد وأعمدة حجم حسب وزن الطرد: XS ≤1 kg وS ≤2 kg وM ≤3 kg وL ≤5 kg وXL >5 kg. انقر + Add country لإضافة صف، وأيقونة الإغلاق لحذف صف. الحجم الفارغ يستخدم السعر الأساسي. والسعر الأساسي 0 يعني شحنًا مجانيًا. ينطبق الصف * Default (all other countries) على البلدان التي ليس لها صف خاص بها.

Other countries: السعر عندما لا يحتوي الجدول على سعر للبلد. اتركه فارغًا لإخفاء الطريقة في هذه الحالة.

الشروط

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

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

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

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

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

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

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

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

متقدم

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

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

كيف تعمل في صفحة الدفع

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

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

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

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

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

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي السلة والدفع. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce (HPOS).

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

الطلبات

يحفظ سطر الشحن في الطلب Service المختارة، مثل "USPS Ground Advantage - Package". تراها في شاشة الطلب في لوحة الإدارة، ويمكنك إنشاء الملصق المطابق في ShipStation.

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

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

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

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

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

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

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

تعرض صفحة الدفع سعر الاحتياط بدلًا من سعر ShipStation: راجع التحذيرات أعلى صفحة الإعدادات (المفاتيح، ورمز شركة الشحن، والرمز البريدي لمكان الشحن، وسعر الصرف). فعّل Debug log وافتح WooCommerce > Status > Logs، بالمصدر vfd-shipstation. الرمز البريدي للعميل مطلوب، ولا يُرسل أي طلب قبل إدخاله.

رمز شركة الشحن الذي يجب إدخاله: احفظ الإعدادات بالمفتاح والسر. تعرض الصفحة رموز شركات الشحن في حسابك. استخدم واحدًا منها أو أكثر.

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

للمطورين: تغيّر الفلاتر vfd_shst_rate_request وvfd_shst_selected_rate وvfd_shst_api_url طلب السعر لكل شركة شحن، والسعر المختار، وعنوان URL الأساسي لواجهة API.

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

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

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

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