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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتداد cURL. بدونهما لا تُثبَّت الوحدة.

حساب FedEx ومفاتيح API (للأسعار الفورية فقط): في FedEx Developer Portal (developer.fedex.com) أنشئ مشروعًا مع Rate API، واربط حساب الشحن الخاص بك لدى FedEx، وانسخ API Key وSecret Key. كما تحتاج إلى رقم حساب FedEx المكوّن من 9 أرقام. تعمل مفاتيح الاختبار فقط عند تفعيل Sandbox، وتعمل مفاتيح الإنتاج فقط عند تعطيله. تستخدم الوحدة واجهة FedEx REST API مع OAuth 2.0، ولا تحتاج إلى meter number ولا كلمة مرور خدمات الويب. وإذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى مفاتيح FedEx.

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

التثبيت

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

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

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

4. أدخل API Key وSecret Key ورقم حساب FedEx المكوّن من 9 أرقام وعنوان Ship from (الرمز البريدي، وبالنسبة إلى الولايات المتحدة وكندا رمز الولاية المكوّن من حرفين). أوقف تفعيل Sandbox عند استخدام مفاتيح الإنتاج. يمكنك اختياريًا إدخال أسعار ثابتة كبديل. انقر على Save.

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

الإعدادات

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

تعرض الوحدة في أعلى الصفحة تحذيرات: بيانات اعتماد API الثلاث مكتملة جزئيًا فقط، أو لا توجد مفاتيح API ولا أسعار ثابتة (وعندها لا تظهر شركة الشحن أبدًا)، أو لا يوجد رمز بريدي للشحن من المصدر، أو لا توجد ولاية شحن من المصدر للولايات المتحدة أو كندا، أو عملة المتجر تختلف عن عملة حساب FedEx دون سعر صرف، أو وحدة وزن المتجر (أو وحدة الأبعاد عند تحديد حجم الصندوق) غير معروفة للوحدة، أو أن شركة الشحن قد حُذفت. وتقبل حقول الأرقام النقطة العشرية أو الفاصلة. ولا يُحفظ الرقم غير الصالح أو حجم الصندوق غير الصالح، ولا سعر الصرف 0، ولا عملة حساب ليست رمزًا من 3 أحرف، ولا اسم أطول من 64 حرفًا، ويُبلَّغ عنها؛ يحتفظ الحقل بقيمته السابقة وتُحفظ الحقول الأخرى. ويُبلَّغ أيضًا عندما يكون الحد الأدنى للوزن أكبر من الحد الأقصى، ويحتفظ الوزنان بقيمتيهما السابقتين.

عام

Enable/Disable: يفعّل شحن FedEx أو يعطّله. وهو المفتاح نفسه الموجود في حالة شركة الشحن في Shipping > Carriers.

Name: اسم طريقة الشحن الذي يراه العميل عند الدفع (اسم شركة الشحن). الافتراضي: FedEx. حقل مطلوب.

Tax status: قاعدة الضريبة لشركة الشحن، أو No tax. عند وجود قاعدة ضريبة (مع تفعيل الضرائب في المتجر) تضيف PrestaShop الضريبة إلى تكلفة الشحن، لذلك تُستخدم تكلفة FedEx دون الضرائب. مع No tax تُستخدم تكلفة FedEx الصافية كما هي.

واجهة FedEx API (الأسعار الفورية)

بدون المفاتيح تُستخدم الأسعار الثابتة الواردة أدناه. يحتوي هذا القسم على زر Clear cached FedEx token and rates.

Sandbox: يستخدم بيئة الاختبار الخاصة بـ FedEx (apis-sandbox.fedex.com) مع مفاتيح الاختبار. عطّله للحصول على الأسعار الفعلية (apis.fedex.com) مع مفاتيح الإنتاج. الافتراضي: مفعّل.

API Key: مفتاح API (client_id) لمشروعك في FedEx Developer Portal.

Secret Key: مفتاح Secret (client_secret) للمشروع نفسه. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ومسح API Key يحذف أيضًا Secret Key المحفوظ.

FedEx account number: رقم حساب الشحن لدى FedEx المكوّن من 9 أرقام والمرتبط بالمشروع. تُحسب أسعار الحساب (المتفق عليها) لهذا الحساب.

Rates: Account rates (your negotiated FedEx prices) (الافتراضي) أو List rates (FedEx published prices).

Residential delivery: تسعير عناوين العملاء كعناوين سكنية (FedEx Home Delivery، رسوم إضافية للتوصيل السكني). أوقفه إذا كنت تشحن في الغالب إلى الشركات. الافتراضي: مفعّل.

Box size: أبعاد صندوق اختيارية بوحدة الأبعاد في متجرك، مثلًا 30x20x15. عندها يطبّق FedEx الوزن الحجمي. اتركه فارغًا للتسعير بالوزن فقط.

FedEx account currency: عملة حسابك لدى FedEx، مثلًا USD لحسابات الولايات المتحدة أو CAD لكندا. الافتراضي: USD. ويُطلب من FedEx دائمًا التسعير بعملة المتجر الافتراضية أيضًا.

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

عنوان الشحن من

العنوان الذي يستلم منه FedEx الطرود أو الذي تسلّم عنده الطرود. يُستخدم للأسعار الفورية.

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

State / province code: رمز الولاية أو المقاطعة المكوّن من حرفين، ومطلوب للولايات المتحدة وكندا، مثلًا TN أو CA أو ON.

City: مدينة الشحن من المصدر.

ZIP / postal code: الرمز البريدي للشحن من المصدر. يحتاجه FedEx لتسعير الشحن.

الأسعار الثابتة

تُستخدم عندما لا يتم إدخال مفاتيح API، وكبديل عندما لا يعيد FedEx أي سعر (واجهة API غير متاحة، أو مفاتيح خاطئة، أو لا توجد خدمة). اترك الحقلين فارغين لإخفاء شركة الشحن في هذه الحالة.

Country prices: جدول يضم رموز الدول المقصودة المكوّنة من حرفين والأسعار بعملة متجرك الافتراضية، دون الضرائب. انقر على Add row لإضافة دولة، وعلى أيقونة سلة المهملات لحذفها. استخدم * كرمز للدولة لأي دولة أخرى. تُتجاهل الصفوف التي لا تحتوي على رمز دولة صالح (أو *) وسعر، ويُبلَّغ عنها عند الحفظ.

Fallback cost: سعر ثابت يُطبَّق عندما لا يتطابق أي سعر للدولة. اتركه فارغًا لإخفاء شركة الشحن.

Fixed price is: Per order يحتسب السعر مرة واحدة. أما Per item (price x number of items) فيضربه في عدد القطع في السلة. ويُطبَّق هذا على الأسعار الثابتة فقط. أما أسعار FedEx الفورية فتُحسب دائمًا لوزن السلة الكامل.

الشروط

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

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

Min weight: الحد الأدنى لوزن السلة بالكيلوغرام لكي تظهر شركة الشحن. القيمة 0 تعني بلا حد.

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

Default product weight: الوزن بالكيلوغرام للمنتجات التي لا وزن لها، ويُستخدم لأسعار FedEx ولحدود الوزن أعلاه. الافتراضي: 0.5. تُحوَّل أوزان المنتجات من وحدة الوزن في متجرك (كغ أو غ أو رطل أو أونصة)، وتُحدد في International > Localization (Local units).

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

الطلبات

في صفحة الطلب في لوحة الإدارة، تحتوي الطلبات التي تستخدم شركة الشحن FedEx على كتلة FedEx shipping. وتعرض هذه الكتلة FedEx service للسعر (للأسعار الفورية)، وPrice source (FedEx live rate أو Fixed price (no live rate) أو Free shipping threshold)، وCalculated price (excl. tax) بعملة متجرك الافتراضية. وتُثبَّت القيم عند تقديم الطلب: فالتغييرات اللاحقة في الإعدادات لا تغيّرها.

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

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

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

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

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

لا تظهر FedEx عند الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. وفي Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعة العميل (أو فعّل Ignore shipping zones وتحقق من Countries). وراجع التحذيرات أعلى صفحة الوحدة، وحدود الوزن، وMinimum subtotal. وبدون سعر فوري تحتاج شركة الشحن إلى سعر لدولة، أو صف *، أو Fallback cost. كما قد تكون المنتجات مقيدة بشركات شحن معينة في صفحة المنتج.

لا تظهر الأسعار الفورية: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم راجع حقل Log في صفحة الوحدة. تُسجَّل هناك المفاتيح الخاطئة، والبيئة الخاطئة (مفاتيح الاختبار مع إيقاف Sandbox، أو مفاتيح الإنتاج مع تفعيله)، والرمز البريدي للتوصيل المفقود، ورموز أخطاء FedEx.

متجري ليس بالدولار الأمريكي: يُطلب من FedEx السعر بعملة متجرك الافتراضية. إذا كان حسابك يعيد عملته الخاصة فقط، فاضبط FedEx account currency وExchange rate. وبدون سعر صرف تُتجاهل هذه الأسعار ويُستخدم السعر الثابت، فلا يُعرض مبلغ بالدولار أبدًا كأنه باليورو.

هل تضرب "Per item" سعر FedEx؟ لا. يُطبَّق Per item على الأسعار الثابتة فقط.

تبدو الأسعار قديمة بعد تغيير: حفظ صفحة الوحدة يمسح الذاكرة المؤقتة. ويمكنك أيضًا النقر على Clear cached FedEx token and rates.

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

يجب تقديم بعض الخدمات فقط: يمكن للمطوّرين تقييد الخدمات باستخدام الخطاف actionVfdFdxAllowedServices. أما الخطافان actionVfdFdxRateRequest وactionVfdFdxApiBaseUrl فيغيّران طلب السعر وعنوان API.

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

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

FedEx علامة تجارية تعود ملكيتها إلى مالكها. هذه الوحدة غير تابعة لـ FedEx ولا معتمدة من قِبلها.