VibeFox GIG Logistics for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

بيانات اعتماد API لـ GIG Logistics (للأسعار الفورية فقط): تستخدم الأسعار الفورية API الخاصة بطرف ثالث من GIG Logistics. تمنح GIG Logistics عملاءها من الشركات اسم مستخدم API (عادةً عنوان بريد إلكتروني) وكلمة مرور. اطلبهما من صفحة المطورين في GIG Logistics (giglogistics.com/developer). تعمل بيانات الاختبار مع API الاختباري فقط. إذا كنت تستخدم جدول الأسعار والتكلفة الاحتياطية فقط، فلا تحتاج إلى بيانات اعتماد API.

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

التثبيت

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

2. انقر على Activate.

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

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

5. املأ جدول الأسعار و/أو التكلفة الاحتياطية. للأسعار الفورية، أدخل أيضًا اسم مستخدم API وكلمة المرور، وهاتف المرسل، والمدينة والولاية للاستلام، وسعر تحويل العملة إذا لم تكن عملة متجرك NGN (انظر الإعدادات).

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

الإعدادات

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

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

فوق الحقول، تعرض الصفحة تحذيرات عندما لا يمكن استخدام الأسعار الفورية: إدخال اسم المستخدم أو كلمة المرور لـ API فقط، أو نقص Sender phone أو مدينة الاستلام وولايته، أو أن عملة المتجر ليست NGN ولم يُضبط Currency conversion rate. وفي كل مرة تحفظ الإعدادات، تُمسح الأسعار المخزنة مؤقتًا ورموز API.

General

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

Method title: اسم طريقة الشحن الظاهر في السلة وصفحة الدفع. الافتراضي: GIG Logistics. ويحل عنوان المنطقة محله.

Tax status: Taxable يضيف ضريبة شحن متجرك إلى التكلفة، وNone لا يضيفها. اختر None إذا كان سعر GIG يشمل بالفعل كل ما تريد تحصيله.

API GIG Logistics (الأسعار الفورية) (اختياري)

مع بيانات اعتماد API، يُطلب السعر من GIG Logistics لكل عنوان في نيجيريا. وبدون بيانات الاعتماد، أو عندما لا تُعيد API سعرًا، يُستخدم جدول الأسعار والتكلفة الاحتياطية.

API username: اسم مستخدم API الخاص بطرف ثالث من GIG Logistics، عادةً عنوان بريدك الإلكتروني.

API password: كلمة مرور API الخاصة بطرف ثالث من GIG Logistics. تُستخدم فقط لتسجيل الدخول إلى API ولا تُسجَّل في السجل أبدًا.

Test mode: يستخدم API الاختباري (dev) من GIG Logistics. تعمل بيانات الاختبار مع API الاختباري فقط. أوقفه للحصول على أسعار حقيقية. الافتراضي: معطّل.

Currency conversion rate: تُعيد GIG Logistics الأسعار بالنايرا (NGN). إذا لم تكن عملة متجرك NGN، فأدخل قيمة النايرا الواحدة بعملة متجرك (1 NGN = ? من عملتك، مثلًا 0.0006). وبدونه لا تُستخدم أسعار GIG الفورية. وإذا كانت عملة متجرك NGN، فلا حاجة لهذا الحقل. ويُقبل كل من النقطة والفاصلة كفاصل عشري.

عنوان الاستلام (المرسل)

المكان الذي تستلم منه GIG Logistics الطرود في نيجيريا. إذا كان متجرك في نيجيريا، فإن حقول الشارع والمدينة والولاية الفارغة تستخدم عنوان المتجر من WooCommerce > Settings > General.

Sender name: اسم المرسل الذي يُرسل إلى GIG Logistics. إذا كان فارغًا فيُستخدم اسم الموقع.

Sender phone: رقم هاتفك، مثل 08030000000. تطلبه GIG Logistics للأسعار الفورية.

Street address: عنوان شارع الاستلام.

City / area: مدينة الاستلام أو منطقته، مثل Victoria Island. مطلوب للأسعار الفورية.

State: ولاية نيجيريا لعنوان الاستلام. افتراضيًا تُستخدم ولاية المتجر. مطلوب للأسعار الفورية.

Pickup latitude: خط عرض اختياري لنقطة الاستلام على الخريطة، مثل 6.4281. تحسب GIG Logistics السعر حسب المسافة. إذا كان فارغًا، تُستخرج الإحداثيات من العنوان.

Pickup longitude: خط طول اختياري لنقطة الاستلام على الخريطة، مثل 3.4219.

Address lookup: يبحث عن إحداثيات العناوين على الخريطة عبر OpenStreetMap (Nominatim). تحسب GIG Logistics السعر من إحداثيات الاستلام والتوصيل. تُرسل الشارع والمدينة والولاية الخاصة بالعميل إلى nominatim.openstreetmap.org، وتُخزَّن النتائج مؤقتًا لمدة 30 يومًا. وبدون هذا الخيار يُرسل نص العنوان فقط، وقد لا تُعيد GIG Logistics سعرًا. الافتراضي: مفعّل.

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

يُستخدم للدول الأخرى، أو عندما لا تكون الأسعار الفورية مُعدّة، أو عندما لا تُعيد GIG Logistics سعرًا. الأسعار بعملة متجرك.

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

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

Table / fallback price is: Per order يحصّل السعر مرة واحدة. Per item (multiplied by the number of items) يضربه في عدد العناصر في السلة. أسعار GIG الفورية تكون دائمًا للطلب كاملًا.

الشروط

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

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

Min weight (kg): الحد الأدنى لوزن السلة بالكيلوغرام. تُحوَّل أوزان المنتجات من وحدة الوزن في متجرك. 0 يعني بلا حد.

Max weight (kg): الحد الأقصى لوزن السلة بالكيلوغرام. الافتراضي: 30. 0 يعني بلا حد.

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

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

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

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

متقدم

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

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

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

عندما يُدخل العميل عنوان التوصيل، يطلب WooCommerce سعرًا من الإضافة. تتحقق الإضافة أولًا من الشروط: دولة التوصيل، ووزن السلة، والحد الأدنى للمجموع الفرعي، وفئات الشحن المستثناة. إذا بلغ المجموع الفرعي Free shipping from، تُعرض الطريقة بسعر 0، ولكن فقط إذا كان للدولة سعر: صف في Country prices، أو Fallback cost، أو سعر GIG Logistics فوري. ولا يُستعلم من GIG Logistics إلا عندما لا يعطي الجدول والتكلفة الاحتياطية سعرًا.

ثم يُؤخذ السعر من أول مصدر يعطي سعرًا. أولًا سعر GIG Logistics الفوري، إذا أُدخلت بيانات اعتماد API، وكان العنوان في نيجيريا، وأدخل العميل مدينة أو ولاية، وكان هاتف الاستلام ومدينته وولايته مضبوطة، وضُبط سعر التحويل للمتاجر التي لا تستخدم NGN. تسجّل الإضافة الدخول إلى API الخاصة بـ GIG Logistics وترسل عناوين الاستلام والتوصيل وإحداثياتهما، وعناصر السلة بأسمائها وكمياتها وأوزانها وقيمها. تُرسل المنتجات التي لا وزن لها بوزن 1 كغ. يُطلب السعر لتوصيل bike. ثانيًا، جدول Country prices. ثالثًا، Fallback cost. وإذا لم يُعطِ أي مصدر سعرًا، تُخفى الطريقة لتلك السلة.

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

إذا أعادت GIG Logistics خطأ أو سعرًا صفريًا، فلن يرى العميل أي خطأ. يُستخدم سعر الجدول أو التكلفة الاحتياطية، ويُسجَّل الخطأ في السجل.

تعمل الطريقة في الدفع الكلاسيكي وفي كتلتي السلة والدفع. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce (HPOS).

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

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

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

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

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

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

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

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

السعر يأتي من الجدول، وليس من GIG Logistics: تتطلب الأسعار الفورية اسم مستخدم API وكلمة المرور، وSender phone، ومدينة الاستلام وولايته، وعنوان توصيل نيجيري مع مدينة أو ولاية، ولمتاجر غير NGN، Currency conversion rate. راجع التحذيرات أعلى صفحة الإعدادات. فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs، المصدر vfd-gig-logistics، لمعرفة السبب. تُعاد محاولة الطلب الفاشل بعد 10 دقائق.

Login failed في السجل: رفضت GIG Logistics اسم مستخدم API أو كلمة المرور. تحقق منهما، وتحقق من Test mode: بيانات الاختبار تعمل مع API الاختباري فقط. احفظ الإعدادات لإعادة المحاولة فورًا.

GIG Logistics لا تُعيد سعرًا: تحسب GIG الأسعار حسب المسافة. أبقِ Address lookup مفعّلًا، أو أدخل Pickup latitude وPickup longitude. تحقق من الأسعار مع حسابك لدى GIG Logistics قبل التشغيل الفعلي.

تُضاف الضريبة فوق سعر GIG: اضبط Tax status على None إذا كان سعر GIG يشمل بالفعل كل ما تريد تحصيله.

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

مُرمِّز عناوين خاص بك: يمكن للمطورين توفير بحث العناوين الخاص بهم عبر الفلتر vfd_gigl_pre_geocode.

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

الإلغاء والحذف

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

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