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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب 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. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر Install Now. ويمكنك أيضًا رفع مجلد vfd_fedex إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

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

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

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

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

7. اختياريًا، أدخل أسعارًا ثابتة كبديل.

الإعدادات

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

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

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

General

Enable/Disable: يُفعِّل شحن FedEx أو يُوقفه في جميع المناطق دفعة واحدة. الافتراضي: مفعّل.

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

Tax status: يتيح Taxable لـ WooCommerce إضافة الضريبة إلى تكلفة الشحن، فيُستخدم مبلغ FedEx بدون ضرائب. ويستخدم None صافي مبلغ FedEx كما هو. الافتراضي: Taxable.

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

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

Sandbox: يستخدم بيئة الاختبار الخاصة بـ FedEx مع مفاتيح الاختبار. أوقفه للحصول على أسعار حقيقية بمفاتيح الإنتاج. الافتراضي: مفعّل.

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

Secret Key: الـ Secret Key (client_secret) للمشروع نفسه.

FedEx account number: حساب الشحن المكوَّن من 9 أرقام لدى FedEx المرتبط بالمشروع.

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: السعر بعملة متجرك لكل دولة وجهة، سطر لكل دولة بالصيغة CC=PRICE، مثل US=12.99 أو CA=19,99. استخدم * لأي دولة أخرى، مثل *=29.99. تُتجاهل الأسطر بصيغة أخرى ويُبلَّغ عنها عند الحفظ.

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

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

الشروط

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

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

Min weight (kg): الحد الأدنى لوزن السلة كي تظهر الطريقة. 0 تعني بلا حد.

Max weight (kg): الحد الأقصى لوزن السلة. تُخفى الطريقة إذا تجاوز الوزن هذا الحد. 0 تعني بلا حد.

Default product weight (kg): الوزن المستخدم للمنتجات التي لا وزن لها، لأسعار FedEx ولحدود الوزن أعلاه. الافتراضي: 0.5.

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

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

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

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

متقدم

Debug log: يسجّل طلبات API وحساب الأسعار في WooCommerce > Status > Logs، بالمصدر vfd-fedex. وتُسجَّل أخطاء API دائمًا. ولا تُسجَّل المفاتيح ولا الرموز ولا عناوين العملاء أبدًا.

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

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

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

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

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

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

تعمل الطريقة على الدفع الكلاسيكي وعلى الدفع بالكتل. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

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

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

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

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

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

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

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

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

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

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

يجب تقديم خدمات معينة فقط: يستطيع المطورون تقييد الخدمات باستخدام الفلتر vfd_fdx_allowed_services.

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

الإزالة

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

FedEx علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ FedEx ولا تحظى بتأييدها.