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

المتطلبات

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

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

حساب 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. في الواجهة الخلفية، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

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

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

6. يمكنك اختياريًا ملء أسعار الاحتياط.

عند التثبيت، تُنشئ الوحدة شركة النقل ShipStation Shipping مع نص مدة التسليم ShipStation carriers (USPS, UPS, FedEx, ...). وتُسنَد شركة النقل إلى جميع المناطق وجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التسليم والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

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

تخبرك التحذيرات في أعلى الصفحة متى لا يمكن للأسعار الفورية أن تعمل: لا توجد مفاتيح، أو لا يوجد رمز لشركة النقل، أو لا يوجد رمز بريدي للشحن من، أو لا يوجد سعر صرف، أو فشل فحص الاتصال، أو رموز شركات النقل غير مرتبطة بحسابك. يظهر تحذير أيضًا عندما تكون وحدة وزن المتجر أو وحدة أبعاده وحدة لا تستطيع الوحدة تحويلها. اضبط kg أو g أو lb أو oz، وcm أو mm أو m أو in، في International > Localization (Local units). يُعد حقل الأرقام الذي يحتوي على قيمة سالبة أو نصًا ليس رقمًا، أو Minimum weight أعلى من Maximum weight، خطأ، ولا يُحفظ أي شيء.

عام

Enable ShipStation shipping: يُشغّل شركة النقل أو يوقفها. وهو مفتاح التبديل نفسه الموجود في حالة شركة النقل ضمن Shipping > Carriers.

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

Tax: قاعدة الضريبة لشركة النقل، أو No tax. لا تتضمن أسعار ShipStation ضريبة المبيعات. يعرضها No tax كما هي مُسعَّرة؛ أما قاعدة الضريبة فتضيف ضريبة على الشحن وفق قواعد الضرائب لديك.

حساب ShipStation

API Key: مفتاح API من ShipStation > Settings > Account > API Settings. يُرسل إلى ShipStation فقط ولا يُسجَّل أبدًا. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره.

API Secret: سر API من الصفحة نفسها. يُحفظ بالطريقة نفسها التي يُحفظ بها المفتاح.

Remove the saved API key and secret: يظهر بعد حفظ المفاتيح. ضع علامة عليه واحفظ لإزالة الاثنين معًا.

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

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

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

الشحن من

Ship-from postal code: مطلوب للأسعار الفورية. تحسب ShipStation السعر من الرمز البريدي وحده، ويجب أن يكون هذا الرمز في بلد حساب ShipStation لديك. اتركه فارغًا لاستخدام الرمز البريدي للمتجر من Shop Parameters > Contact > Stores.

الأسعار

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. يلزم فقط عندما تختلف العملة الافتراضية عن عملة الحساب. وبدونه لا تُستخدم الأسعار الفورية، وتُطبَّق أسعار الاحتياط. لا تُحدَّث أسعار الصرف تلقائيًا.

أسعار الاحتياط (تُستخدم عندما لا يوجد سعر فوري: لا توجد مفاتيح 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 تعني بلا حد.

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

عادةً تُعرض شركة النقل في مناطقها ضمن Shipping > Carriers. وبدلًا من ذلك يمكن عرضها حسب البلد.

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

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

متقدم

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

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

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

طريقة العمل عند الدفع

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

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

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

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

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

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

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

الطلبات

عندما يُقدَّم طلب بسعر فوري من ShipStation، تُحفظ الخدمة المختارة مع الطلب. وتعرضها صفحة الطلب في الواجهة الخلفية في كتلة ShipStation باسم Service، مثل "USPS Ground Advantage - Package"، حتى تتمكن من إنشاء الملصق المطابق في ShipStation. ولا تغيّرها عمليات إعادة حساب السلة اللاحقة. ولا تحتوي الطلبات التي قُدّمت بسعر احتياط أو بشحن مجاني على كتلة الخدمة.

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

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

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

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

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

لا تظهر ShipStation عند الدفع: تحقق من أن الترخيص نشط وأن Enable ShipStation shipping مفعّل. وفي Shipping > Carriers تحقق من أن شركة النقل تغطي منطقة بلد العميل ومجموعته، أو فعّل Ignore shipping zones وتحقق من Countries. تحقق من حدود الوزن ومن Minimum subtotal. وبدون سعر فوري، تحقق من أن البلد أو * Default أو Other countries له سعر. كما قد تكون المنتجات مقيّدة بشركات نقل معينة في صفحة المنتج.

يعرض الدفع سعر الاحتياط بدلًا من سعر ShipStation: تحقق من التحذيرات أعلى صفحة الوحدة (المفاتيح، ورمز شركة النقل، والرمز البريدي للشحن من، وسعر الصرف). فعّل Debug log، وأعد تحميل صفحة الدفع، ثم انظر إلى حقل Log. الرمز البريدي للعميل مطلوب. لا يُرسل أي طلب قبل إدخاله.

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

فشل فحص الاتصال بـ ShipStation: تعرض الرسالة السبب. تحقق من API Key وAPI Secret، ثم احفظ مرة أخرى لإعادة الفحص.

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

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

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

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

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