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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

4. الصق رمز Shippo API واملأ عنوان Ship from. الرمز البريدي مطلوب للأسعار المباشرة.

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

6. يمكنك اختياريًا إدخال أسعار احتياطية في جدول الدول والوزن، ثم انقر على Save.

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

الإعدادات

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

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

عام

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

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

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

حساب Shippo

API token: رمز Shippo API الخاص بك. استخدم الرمز الفعلي (shippo_live_...) للحصول على أسعار حقيقية في المتجر الفعلي، أو رمز تجريبي (shippo_test_...) لأسعار Shippo التجريبية. يُرسل الرمز إلى Shippo فقط ولا يُسجَّل في أي سجل. وبعد الحفظ يبقى الحقل فارغًا ويظهر Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها، أو حدد Remove the saved API token لحذفه.

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

عنوان الإرسال (العنوان الذي تُرسل منه طرودك؛ تُملأ الحقول الفارغة من عنوان المتجر في Shop Parameters > Contact > Stores عندما يكون في الدولة نفسها)

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

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

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

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

Postal / ZIP code: مطلوب للأسعار المباشرة.

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

الأسعار

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

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

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

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

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

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

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

الشروط

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

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

Minimum weight (kg): الحد الأدنى لوزن السلة لعرض شركة الشحن. وتعني 0 عدم وجود حد.

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

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

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

الطلبات

عند إتمام طلب بسعر Shippo مباشر، تحفظ الوحدة Carrier / service المختارة، وفي حالة طرد واحد لكل طلب تحفظ Estimated delivery days. وتظهر هذه البيانات في كتلة Shippo في صفحة الطلب بلوحة الإدارة، حتى تتمكن من شراء الملصق المطابق في Shippo. وتُجمَّد البيانات مع الطلب: فتغييرات السلة اللاحقة لا تغيّرها. ولا تحتوي الطلبات ذات السعر الاحتياطي أو الشحن المجاني على كتلة Shippo.

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

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

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

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

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

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

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

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

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

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

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

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

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

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