VibeFox The Courier Guy for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

مفتاح API من ShipLogic (للأسعار الفورية والخزائن): تعمل The Courier Guy على منصة ShipLogic. أنشئ مفتاح API في بوابة الشحن الخاصة بـ The Courier Guy، ضمن Settings > API Keys (حساب أعمال). من دون المفتاح، يُستخدم جدول الأسعار فقط، ولا يمكن تقديم توصيل بخزانة الاستلام.

الشحن إلى جنوب أفريقيا: الأسعار الفورية والخزائن مخصصة لعناوين جنوب أفريقيا فقط. يجب أن يكون متجرك مُعدًّا للشحن إلى جنوب أفريقيا (WooCommerce > Settings > General > Shipping location(s)).

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع مجلد vfd_the_courier_guy إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

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

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

5. أدخل API key الخاص بـ ShipLogic. للأسعار الفورية، املأ عنوان المُرسِل (الشارع والمدينة والمحافظة والرمز البريدي)، وإذا لم تكن عملة متجرك ZAR فأدخل ZAR conversion rate أيضًا.

6. املأ جدول الأسعار و/أو التكلفة الاحتياطية.

7. أضف VibeFox The Courier Guy إلى منطقة شحن لجنوب أفريقيا في WooCommerce > Settings > Shipping > Shipping zones، واختر Delivery type (courier أو TCG locker)، واكتب عنوانًا إن رغبت. أضفها مرة ثانية لنوع التوصيل الآخر.

الإعدادات

الإعدادات الرئيسية موجودة في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox The Courier Guy. وهي تنطبق على كل مناطق الشحن. عندما تضيف الطريقة إلى منطقة، تحتوي نافذة المنطقة على حقلين:

Title (zone): اسم هذا السعر عند الدفع في هذه المنطقة. اتركه فارغًا لاستخدام Method name العام.

Delivery type (zone): Courier to the door (الافتراضي) أو TCG locker (customer chooses a locker). أضف الطريقة مرتين لتقديم الخيارين. تحتاج الخزائن إلى مفتاح API من ShipLogic، وهي متاحة في جنوب أفريقيا فقط.

في كل مرة تحفظ فيها الإعدادات، تُمسح الأسعار والخزائن المخزنة مؤقتًا. تخبرك التحذيرات فوق الإعدادات عندما لا يشحن المتجر إلى جنوب أفريقيا، أو يكون مفتاح API مفقودًا، أو يكون سعر تحويل ZAR أو عنوان المُرسِل مفقودًا، أو لا يوجد جدول أسعار ولا تكلفة احتياطية، أو يكون آخر طلب إلى ShipLogic قد فشل (مع تاريخه وخطئه).

عام

Enable/Disable: يوقف الطريقة في كل مكان، بما في ذلك مناطق الشحن.

Method name: الاسم الذي يظهر عند الدفع. في حالة التوصيل بالخزانة تُضاف كلمة "locker"، مثل "The Courier Guy locker". يمكن للمنطقة أن تستبدله بعنوانها الخاص. الافتراضي: The Courier Guy.

Tax status: Taxable: تُؤخذ الأسعار الفورية دون ضريبة القيمة المضافة، ويضيف WooCommerce ضريبته الخاصة. None: تُؤخذ الأسعار الفورية شاملة ضريبة القيمة المضافة.

واجهة ShipLogic (الأسعار الفورية والخزائن)

API key: مفتاح API الخاص بـ ShipLogic من بوابة The Courier Guy.

Account ID: اختياري. معرّف الحساب الرقمي في ShipLogic، ويلزم فقط إذا كان مفتاحك يتيح الوصول إلى عدة حسابات.

الأسعار الفورية(لعناوين جنوب أفريقيا؛ إذا لم يتوفر سعر فوري يُستخدم جدول الأسعار)

Price source: مصدر السعر.

ZAR conversion rate: تُسعّر ShipLogic بالراند الجنوب أفريقي (ZAR). إذا لم تكن عملة متجرك ZAR، فأدخل قيمة 1 ZAR بعملة متجرك، مثلًا 0.05. من دون هذه القيمة لا تُستخدم الأسعار الفورية، ويُطبَّق جدول الأسعار. إذا كانت عملة متجرك ZAR، فاتركه فارغًا. لا يُحدَّث هذا السعر تلقائيًا.

عنوان المُرسِل (للأسعار الفورية)(المكان الذي تستلم منه The Courier Guy الطرود في جنوب أفريقيا؛ الأسعار الفورية تحتاج إلى الشارع والمدينة والمحافظة والرمز البريدي)

Sender company: اسم شركتك.

Sender street address: مثل 12 My Road.

Sender suburb: الحي الذي يقع فيه عنوان المُرسِل.

Sender city: المدينة التي يقع فيها عنوان المُرسِل.

Sender province: اختر المحافظة الجنوب أفريقية من القائمة.

Sender postal code: الرمز البريدي لعنوان المُرسِل.

جدول الأسعار(أسعارك الخاصة بعملة المتجر: تُستخدم مع Price table only، وخارج جنوب أفريقيا، وكلما لم يتوفر سعر فوري؛ ويُقبل الفاصل العشري سواء كان فاصلة أو نقطة)

Calculation type: ينطبق على جدول الأسعار فقط. يكون السعر الفوري دائمًا للطلب كله.

Prices by weight: جدول دول يحتوي على عمود Price وفئات الوزن XS (حتى 1 كغ)، وS (حتى 2 كغ)، وM (حتى 3 كغ)، وL (حتى 5 كغ)، وXL (أكثر من 5 كغ). انقر على + Add row لإضافة صف (يبدأ الصف الجديد بجنوب أفريقيا)، وعلى علامة الإغلاق لحذفه. تستخدم الفئة الفارغة أو الصفر عمود Price. السعر 0 يعني شحنًا مجانيًا. ينطبق الصف * Any country على الدول التي ليس لها صف خاص، وعلى صف دولة لا يحتوي على أي سعر.

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

الشروط

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

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

Minimum order amount: يُظهر الطريقة فقط من مجموع السلة الفرعي المحدد. اتركه فارغًا لإظهارها دائمًا.

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

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

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

Ignore shipping zones: يعرض الطريقة للدول المذكورة أدناه، حتى حيث لا تحتويها أي منطقة.

Delivery type without zones: courier أو TCG locker لهذا الوضع. يُستخدم فقط مع Ignore shipping zones.

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

متقدم

Debug log: يكتب رسائل التصحيح في WooCommerce > Status > Logs، والمصدر vfd-the-courier-guy. تُسجَّل أخطاء API دائمًا، حتى عند إيقاف هذا الخيار. لا يُسجَّل مفتاح API ولا بيانات العملاء أبدًا.

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

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

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

Courier to the door: تطلب الإضافة من ShipLogic أرخص خدمة من عنوان المُرسِل إلى عنوان العميل. يجب أولًا إكمال الشارع والمدينة والمحافظة والرمز البريدي للعميل. وحتى ذلك الحين يُعرض السعر من جدول الأسعار.

TCG locker: السعر الفوري هو أرخص خدمة من الباب إلى الخزانة، حتى الخزانة الأقرب إلى مدينة العميل. ولا يُعاد حسابه للخزانة التي يختارها العميل.

يُسعَّر الطلب كله كطرد واحد: الوزن الإجمالي، وأطول طول وعرض، والارتفاعات مكدّسة. تُحسب المنتجات التي لا أبعاد لها كمكعبات بطول 10 سم. يُحوَّل مبلغ الراند إلى عملة متجرك. ويُحفظ مستوى الخدمة، مثل ECO، في سطر الشحن.

تنتهي مهلة طلبات ShipLogic بعد 12 ثانية. تُخزَّن الأسعار مؤقتًا لمدة ساعة، والخزائن لمدة 6 ساعات، والإخفاقات لمدة 10 دقائق، حتى لا تُبطئ واجهة API البطيئة كل تحديث للدفع. إذا لم يتوفر سعر فوري، يُؤخذ السعر من الجدول، ثم من Fallback cost. وإذا لم ينطبق أيٌّ منهما، تُخفى الطريقة.

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

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

نقاط الاستلام

عندما يختار العميل سعر TCG locker في الدفع الكلاسيكي أو دفع الكتل، يظهر أسفله منتقي للخزائن. يعرض المنتقي الخزائن التي تعيدها ShipLogic لمدينة عنوان الشحن، بدءًا من الأقرب. يمكن للعميل كتابة مدينة أو حيّ أو رمز بريدي آخر، ثم النقر على Search. يجب اختيار خزانة قبل أن يتمكن العميل من إتمام الطلب.

يُتحقق من الخزانة مرة أخرى على الخادم مقابل قائمة ShipLogic. يُؤخذ اسمها ومزوّدها من ShipLogic، وليس من المتصفح. يبقى الاختيار محفوظًا عبر تحديثات الدفع، ويُعاد تعيينه عند تغيير العنوان.

إذا تعذّر الوصول إلى ShipLogic، يُظهر المنتقي أن الخزائن لا يمكن تحميلها، ويمكن إتمام الطلب من دون خزانة. عندها يُعلَّم الطلب: "Not chosen — ShipLogic was unavailable at checkout. Agree the locker with the customer." (لم تُختر: ShipLogic غير متاح عند الدفع. اتفق على الخزانة مع العميل.)

الطلبات

تُحفظ الخزانة المختارة (الاسم والمعرّف والمزوّد) في الطلب. وتظهر في شاشة الطلب في لوحة الإدارة، وفي صفحتي "شكرًا لك" و"حسابي" للطلبات، وفي رسائل البريد الإلكتروني للطلبات (HTML ونص عادي). كما تعرض رسالة المسؤول معرّف الخزانة.

في شاشة الطلب في لوحة الإدارة، تحتوي الطلبات التي تستخدم هذه الطريقة على حقل The Courier Guy tracking reference. أدخل المرجع من بوابة The Courier Guy الخاصة بك، ثم انقر على Save. يظهر المرجع للعميل في صفحة الطلب وفي الرسائل المرسلة بعد ذلك.

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

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

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

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

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

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

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

لا يرى العملاء قائمة الخزائن: تحتاج الخزائن إلى مفتاح API، وطريقة منطقة بقيمة Delivery type "TCG locker"، وعنوان توصيل في جنوب أفريقيا. تعرض صفحة الإعدادات آخر خطأ من ShipLogic إن وُجد، مثل مفتاح مرفوض.

السعر دائمًا هو سعر الجدول: راجع التحذيرات في صفحة الإعدادات. يحتاج السعر الفوري إلى مفتاح API، وعنوان مُرسِل كامل، وللمتاجر غير المعتمدة على الراند، سعر تحويل ZAR. وفي التوصيل بالمندوب إلى الباب، يجب إكمال الشارع والمدينة والمحافظة والرمز البريدي للعميل. وللخزائن، يجب أن تجد ShipLogic خزانة قرب مدينة العميل. فعّل Debug log وافتح WooCommerce > Status > Logs، والمصدر vfd-the-courier-guy.

ShipLogic غير متاح: يُعرض سعر الجدول أو السعر الاحتياطي. يمكن إتمام طلبات الخزائن من دون خزانة، ويُعلَّم الطلب.

تبدو الأسعار قديمة بعد تغيير: احفظ صفحة الإعدادات. سيؤدي ذلك إلى مسح الأسعار والخزائن المخزنة مؤقتًا.

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

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

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

The Courier Guy وShipLogic علامتان تجاريتان لمالكيهما. هذه الإضافة غير تابعة لـ The Courier Guy أو ShipLogic ولا يصدر عنهما أي تأييد لها.