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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

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

نيجيريا في متجرك: تُطلب الأسعار الفورية لعناوين التوصيل في نيجيريا فقط، لذلك يجب أن تكون الدولة Nigeria موجودة ومفعّلة في International > Locations > Countries.

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

التثبيت

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

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

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

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

5. إذا أظهر حقل Nigerian states الزر Add Nigerian states، فانقر عليه (راجع الإعدادات).

عند التثبيت، تُنشئ الوحدة شركة الشحن GIG Logistics مع نص مدة التوصيل Courier delivery. تُربط شركة الشحن بمنطقة نيجيريا (في المتجر الافتراضي، أفريقيا) وبجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: يأتي السعر دائمًا من الوحدة.

الإعدادات

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

فوق الأقسام، تعرض الصفحة تحذيرات عندما لا يمكن استخدام الأسعار الفورية: إذا أُدخل اسم المستخدم أو كلمة المرور لواجهة API فقط، أو إذا كان Sender phone أو مدينة الاستلام أو ولايته ناقصة، أو إذا لم تكن عملتك الافتراضية NGN ولم يُضبط Currency conversion rate. وتظهر تحذيرات أيضًا عندما لا يُعثر على شركة الشحن GIG Logistics، أو عندما تكون وحدة الوزن في متجرك (International > Localization > Local units) غير معروفة للوحدة، وفي هذه الحالة تُقرأ أوزان المنتجات بالكيلوغرام. وعند الحفظ، يُبلَّغ عن رقم غير صحيح (مبلغ سالب، أو Currency conversion rate يساوي 0، أو خط عرض خارج النطاق من -90 إلى 90، أو خط طول خارج النطاق من -180 إلى 180)، أو عن Min weight (kg) أكبر من Max weight (kg)، أو عن Method title فارغ أو غير صالح، أو عن قاعدة ضريبة غير معروفة، ولا يُحفظ شيء.

General

تنطبق الإعدادات في هذه الصفحة على جميع مناطق شركة الشحن.

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

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

Tax: قاعدة الضريبة لشركة الشحن، أو No tax. تضيف قاعدة الضريبة ضريبة الشحن الخاصة بك فوق التكلفة. اختر No tax إذا كان سعر GIG يتضمن بالفعل كل ما تريد تحصيله.

GIG Logistics API (live prices) (اختياري)

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

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

API password: كلمة مرور واجهة API الخاصة بطرف ثالث من GIG Logistics. تُستخدم فقط لتسجيل الدخول إلى API ولا تُسجَّل في السجل أبدًا. بعد الحفظ، يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. لإزالة كلمة المرور، امسح API username ثم احفظ.

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

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

Pickup (sender) address

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

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

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

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

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

State: الولاية النيجيرية لعنوان الاستلام، وتُختار من بين الولايات السبع والثلاثين. يستخدم الخيار الافتراضي Shop state (Shop parameters > Contact > Stores) ولاية عنوان المتجر. مطلوب للأسعار الفورية.

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

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

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

Nigerian states: تُرسل ولاية عنوان التوصيل إلى GIG Logistics وإلى بحث العناوين. لا تحتوي PrestaShop على ولايات نيجيرية افتراضيًا؛ وبدونها تُستخدم الشارع والمدينة فقط. يضيف الزر Add Nigerian states الولايات السبع والثلاثين (برموز مثل LA وFC وغيرها)، ويفعّل Contains states لنيجيريا، ويضيف حقل الولاية إلى نموذج العنوان النيجيري. لا تُضاف الولايات الموجودة بالفعل (حسب الرمز أو الاسم) مرة أخرى. وعندما تكون كل الأمور جاهزة، يعرض الحقل عدد الولايات المتاحة للعناوين النيجيرية. لا يتغير شيء حتى تنقر على الزر.

Price table and fallback

يُستخدم للدول الأخرى، عندما لا تُضبط الأسعار الفورية، أو عندما لا تُعيد 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 الفورية تنطبق دائمًا على الطلب بأكمله.

Conditions

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

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

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

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

Availability without shipping zones

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

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

Advanced

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

السعر يأتي من الجدول وليس من GIG Logistics: تحتاج الأسعار الفورية إلى اسم مستخدم API وكلمة مروره، وSender phone، ومدينة الاستلام وولايته، وعنوان توصيل نيجيري بمدينة أو ولاية، وبالنسبة للمتاجر التي لا تكون عملتها الافتراضية NGN، إلى Currency conversion rate. انظر التحذيرات أعلى صفحة Configure. فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى حقل Log في صفحة الوحدة لمعرفة السبب. تُعاد المحاولة الفاشلة بعد 10 دقائق.

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

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

يبقى تحذير مدينة الاستلام وولايته: اختر ولاية في State واملأ City / area. لا يُستخدم عنوان المتجر إلا عندما يكون بلد المتجر نيجيريا، ولا تُعرف ولاية المتجر إلا بعد إضافة الولايات النيجيرية واختيارها في Shop Parameters > Contact > Stores.

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

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

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

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

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

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