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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتداد cURL. يرفض الوحدة التثبيت دونهما.

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

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

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

التثبيت

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

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

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

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

5. إذا لم تكن عملتك الافتراضية هي USD، فأدخل USD exchange rate. ويمكنك اختياريًا إدخال الأسعار الاحتياطية (انظر الإعدادات). انقر على Save.

عند التثبيت، تنشئ الوحدة شركة الشحن EasyPost Shipping بنص مدة التسليم Live carrier rate (EasyPost). تُخصَّص شركة الشحن لجميع المناطق ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التسليم والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: يأتي السعر دائمًا من الوحدة.

الإعدادات

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

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

عند الحفظ، لا تُحفظ القيمة التي ليست رقمًا (أو التي تكون سالبة): يذكر التحذير الحقل، وتبقى القيمة السابقة. ويحدث الأمر نفسه عندما يكون USD exchange rate صفرًا، أو عندما يكون Minimum weight أكبر من Maximum weight.

عام

Enable EasyPost shipping: يفعّل شركة الشحن أو يعطّلها. وهو المفتاح نفسه الموجود في حالة شركة الشحن في Shipping > Carriers. الافتراضي: on.

Name: اسم شركة الشحن الذي يراه العميل عند الدفع، بحد أقصى 64 حرفًا (يُرفض الاسم الأطول ولا يُحفظ شيء). الافتراضي: EasyPost Shipping. إذا كان الاسم فارغًا أو يحتوي على أحرف لا يسمح بها PrestaShop في اسم شركة الشحن، فيُستخدم الاسم الافتراضي.

حساب EasyPost

API key: مفتاح API الخاص بـ EasyPost من EasyPost Dashboard > Account Settings > API Keys. يعيد مفتاح الإنتاج (الذي يبدأ بـ EZAK) أسعارًا حقيقية. ويعيد مفتاح الاختبار (الذي يبدأ بـ EZTK) أسعار اختبار من EasyPost؛ استخدمه للاختبار فقط. بعد الحفظ يبقى الحقل فارغًا ويعرض المفتاح المحفوظ مُقنَّعًا، مثل EZAK******abcd. اترك الحقل فارغًا للاحتفاظ بالمفتاح. أدخل قيمة جديدة فقط عندما تريد تغييره.

Remove the saved API key: ضع علامة في هذا المربع وانقر على Save لحذف المفتاح المحفوظ.

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

الشحن من

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

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: قاعدة الضريبة لشركة الشحن، أو No tax. لا تتضمن أسعار EasyPost ضريبة المبيعات. اختر قواعد الضريبة التي تنطبق على الشحن.

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

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

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

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

الشروط

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

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

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

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

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

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

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

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

متقدم

Debug log: يكتب طلبات EasyPost في modules/vfd_easypost/logs/vfd_ep.log.php. لا يمكن فتح الملف من الويب، ويُدوَّر عند بلوغ 5 MB. تُسجَّل أخطاء API دائمًا، حتى عندما يكون هذا الخيار متوقفًا. ولا تُسجَّل أبدًا مفاتيح API أو عناوين العملاء.

Remove data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها وجداولها وسجلها. ولا يحذف تعطيل الوحدة الإعدادات أبدًا.

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

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

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

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

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

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

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

الطلبات

عند تقديم طلب بشركة شحن EasyPost، يُحفظ السعر المعروض عند الدفع مع الطلب. تعرض صفحة الطلب في لوحة الإدارة بند EasyPost shipping:

Carrier / service: شركة شحن EasyPost والخدمة الخاصة بالسعر، مثل USPS Priority. وفي وضع طرد واحد لكل قطعة تُدرج جميع الخدمات المستخدمة.

Estimated delivery days: أيام التسليم التي تعيدها EasyPost (في وضع طرد واحد لكل طلب فقط، عندما تعيدها EasyPost).

Price source: Live EasyPost rate أو Fallback price (no live rate) أو Free shipping threshold.

Calculated price (excl. tax): السعر بعملتك الافتراضية.

التغييرات اللاحقة على السلة في لوحة الإدارة لا تغيّر هذه القيم. استخدمها لشراء الملصق من حسابك في EasyPost. وتُحذف أسعار السلال المتروكة بعد 30 يومًا.

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

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

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

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

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

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

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

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

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

هل الضريبة مشمولة؟ لا تتضمن أسعار EasyPost ضريبة المبيعات. اختر قاعدة الضريبة في Tax لإضافة الضريبة على الشحن.

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

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

خطافات المطورين: تعدّل الخطافات actionVfdEpShipmentRequest (نص الطلب)، وactionVfdEpSelectedRate (السعر المختار)، وactionVfdEpApiUrl (عنوان API الأساسي) سلوك الوحدة.

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

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

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