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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

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

الشحن إلى جنوب أفريقيا: الأسعار الفورية وخزائن الاستلام مخصصة لعناوين جنوب أفريقيا فقط. يجب أن تكون جنوب أفريقيا دولة نشطة في المتجر (International > Locations > Countries).

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

التثبيت

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

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

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

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

5. املأ جدول الأسعار و/أو التكلفة الاحتياطية، ثم انقر على Save.

6. للأسعار الفورية لشركة الشحن، انقر على Add South African provinces في قسم Advanced إذا أشارت الصفحة إلى أن عناوين جنوب أفريقيا لا تحتوي على مقاطعة.

عند التثبيت، تنشئ الوحدة شركتي شحن: The Courier Guy (نص مدة التوصيل The Courier Guy courier delivery to your door) وThe Courier Guy locker (Delivery to a TCG locker of your choice). كلتاهما نشطتان ومرتبطتان بمنطقة جنوب أفريقيا وبجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox The Courier Guy > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. كل حفظ يمسح الأسعار والخزائن المخزنة مؤقتًا وآخر خطأ من ShipLogic. تنبهك التحذيرات أعلى الصفحة إلى أن جنوب أفريقيا ليست دولة نشطة في المتجر، أو أن مفتاح API أو سعر تحويل ZAR أو عنوان المُرسِل مفقود، أو أنه لا يوجد جدول أسعار ولا تكلفة احتياطية، أو أن عناوين جنوب أفريقيا لا تحتوي على مقاطعة، أو أن الوحدة لا تعرف وحدة الوزن أو الأبعاد في المتجر، أو أن آخر طلب إلى ShipLogic فشل (مع تاريخه وخطئه). لا تُحفظ القيمة غير الصالحة (مثل القيمة السالبة): تسمّي الصفحة الحقل وتحتفظ بالقيمة السابقة.

عام

Courier to the door: يشغّل شركة شحن التوصيل بالمندوب أو يوقفها. وهذا هو المفتاح نفسه لحالة شركة الشحن في Shipping > Carriers.

Courier carrier name: اسم شركة شحن التوصيل بالمندوب في الدفع. الافتراضي: The Courier Guy. مطلوب.

TCG locker: يشغّل شركة شحن الخزائن أو يوقفها. يختار العميل خزانة الاستلام في الدفع. تُعرض فقط لعناوين جنوب أفريقيا وفقط مع مفتاح API من ShipLogic.

Locker carrier name: اسم شركة شحن الخزائن في الدفع. الافتراضي: The Courier Guy locker. مطلوب.

Tax status: قاعدة الضريبة لكلتا شركتي الشحن. Taxable: <tax rule>: تُؤخذ الأسعار الفورية بدون ضريبة القيمة المضافة، ويضيف PrestaShop ضريبة الشحن للقاعدة المحددة. None: تُؤخذ الأسعار الفورية شاملة ضريبة القيمة المضافة.

ShipLogic API (الأسعار الفورية وخزائن الاستلام)

API key: مفتاح API الخاص بـ ShipLogic من بوابة The Courier Guy. لا يُعرض أبدًا للعملاء ولا يُكتب في السجل. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. حدّد Remove the saved API key واحفظ لإزالة المفتاح المحفوظ.

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 لإضافة صف (يبدأ الصف الجديد بجنوب أفريقيا)، وعلى أيقونة سلة المهملات لحذف صف. الفئة الفارغة أو 0 تستخدم عمود Price. السعر 0 يعني شحنًا مجانيًا. يُطبَّق الصف * Any country على الدول التي ليس لها صف خاص، وعلى صف دولة بلا أي سعر. السعر غير الرقمي يُمسح، وتسرد الصفحة هذه الأسعار.

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

الشروط (شركتا الشحن)

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

Max weight (kg): يُخفي شركات الشحن إذا كان وزن السلة أكبر من هذه القيمة. الافتراضي: 30. 0 يعني بلا حد، والفراغ يعني 30 كغ. إذا كانت Min weight (kg) أكبر من Max weight (kg)، تعرض الصفحة تحذيرًا ويحتفظ الحدّان بقيمهما السابقة.

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

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

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

عادةً تُعرض شركات الشحن في مناطق الشحن المرتبطة بها في Shipping > Carriers.

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

Delivery type without zones: Courier to the door أو TCG locker (customer chooses a locker). يُستخدم فقط مع Ignore shipping zones.

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

متقدم

South African provinces: لا تحتوي PrestaShop على مقاطعات جنوب أفريقية، لكن سعر شركة الشحن الفوري يحتاج إلى مقاطعة العنوان. تضيف Add South African provinces المقاطعات التسع (EC وFS وGP وKZN وLP وMP وNC وNW وWC) كولايات لجنوب أفريقيا، وتعرض حقل الولاية في عناوين جنوب أفريقيا. لا تُضاف المقاطعات الموجودة مرة أخرى. وحتى ذلك الحين تحصل شركة الشحن على سعر جدول الأسعار.

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

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

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

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

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

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

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

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

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

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

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

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

عندما يختار العميل شركة شحن الخزائن، يظهر تحتها محدد للخزائن. يعرض الخزائن التي تعيدها ShipLogic لمدينة عنوان التوصيل، الأقرب أولًا. يمكن للعميل كتابة مدينة أو حي أو رمز بريدي آخر والنقر على Search. يجب اختيار خزانة قبل أن يتمكن العميل من المتابعة: وإلا تعرض خطوة الشحن الرسالة Please choose a The Courier Guy locker.

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

إذا تعذّر الوصول إلى ShipLogic، يوضح المحدد أنه تعذّر تحميل الخزائن، وأن المتجر سيتواصل مع العميل بشأن الخزانة. يمكن عندئذٍ إتمام الطلب بدون خزانة. ويُعلَّم الطلب في صفحة الطلب في لوحة الإدارة: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

الطلبات

تُحفظ الخزانة المختارة (الاسم والمعرّف والمزوّد) مع الطلب. وتظهر في كتلة The Courier Guy في صفحة الطلب في لوحة الإدارة، وفي صفحة تأكيد الطلب، وفي تفاصيل طلب العميل، وفي رسالة تأكيد الطلب الإلكترونية. كما تعرض رسالة "الطلب الجديد" في المتجر (وحدة Mail alerts) معرّف الخزانة، أو أنه لم تُختر أي خزانة لأن ShipLogic كان غير متاح.

مرجع تتبع The Courier Guy: احجز الطرد في بوابة The Courier Guy الخاصة بك وأدخل المرجع كرقم تتبع الشحنة في كتلة Shipping الخاصة بالطلب (Edit). تعرضه كتلة The Courier Guy. يراه العميل في تفاصيل الطلب، ويتلقى رسالة PrestaShop "قيد الشحن".

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

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

بدون مفتاح نشط، لا تُعرض أيٌّ من شركتي شحن The Courier Guy (courier to the door أو TCG locker) للعملاء عند الدفع، ولا يُحسب أي سعر. لا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى شركات الشحن عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager في تبويب Alerts. الطلبات الموجودة لا تتأثر.

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

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

لا تظهر The Courier Guy عند الدفع: تحقق من أن الترخيص نشط وأن شركة الشحن مفعّلة (Courier to the door أو TCG locker). في Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). تحقق من حدود الوزن وMinimum order amount. تأكد من أن الجدول أو Fallback cost يحتوي على سعر. تظهر شركة شحن الخزائن فقط لعناوين جنوب أفريقيا ومع مفتاح API. كذلك قد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج.

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

السعر دائمًا هو سعر الجدول: راجع التحذيرات في صفحة الإعدادات. يحتاج السعر الفوري إلى مفتاح API وعنوان المُرسِل كاملًا، وبالنسبة للمتاجر غير المسعّرة بالراند إلى سعر تحويل ZAR. للتوصيل بالمندوب، يحتاج عنوان العميل إلى شارع ومدينة ومقاطعة ورمز بريدي: أضف المقاطعات الجنوب أفريقية في قسم Advanced. للخزائن، يجب أن يجد ShipLogic خزانة قرب مدينة العميل. فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى حقل Log في صفحة الوحدة.

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

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

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

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

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

The Courier Guy وShipLogic علامتان تجاريتان تعودان لمالكيهما. هذه الوحدة غير تابعة لـ The Courier Guy أو ShipLogic ولا تحظى بتأييدهما.