VibeFox Loggi for PrestaShop — المساعدة

المتطلبات

PrestaShop: 8.0 إلى 9.x.

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

حساب Loggi (للأسعار المباشرة فقط): يستخدم السعر المباشر واجهة Loggi البرمجية GraphQL بمفتاح API تُصدره Loggi لحسابات الأعمال. اطلب ذلك من مدير حسابك لدى Loggi أو من دعم تكامل Loggi (integracoes@loggi.com)، وانظر أيضًا وثائق واجهة Loggi البرمجية على docs.api.loggi.com. تحتاج إلى ثلاث قيم: بريد حساب Loggi الإلكتروني، ومفتاح API، والمعرّف الرقمي لمتجرك. وإذا كان حساب Loggi لديك يحتوي فقط على بيانات اعتماد لواجهة منصة Loggi REST الأحدث (client ID وsecret)، فالسعر المباشر غير متاح وتُستخدم الأسعار الثابتة. وإذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى حساب Loggi.

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

التثبيت

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

2. عند اكتمال الرفع، انقر Configure، أو ابحث عن VibeFox Loggi لاحقًا في قائمة الوحدات وانقر Configure.

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

4. أدخل بريد Loggi API الإلكتروني ومفتاح API وShop ID وعنوان الاستلام، وإذا لم تكن العملة الافتراضية لمتجرك BRL فأدخل سعر صرف BRL أيضًا. أضف أسعارًا ثابتة كشبكة أمان (انظر الإعدادات) وانقر Save.

5. أضف البرازيل إلى مناطق شركة Loggi في Shipping > Carriers، أو فعّل Ignore shipping zones واختر الدول.

عند التثبيت تُنشئ الوحدة شركة الشحن Loggi بنص مدة التوصيل Courier delivery in Brazil. تُخصَّص الشركة لجميع المناطق ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Loggi > Configure. وتُطبَّق على جميع مناطق شركة الشحن. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وكل حفظ يمسح أيضًا أسعار Loggi المخزنة مؤقتًا.

تُظهر التحذيرات أعلى الصفحة إعدادًا غير مكتمل: لا توجد بيانات اعتماد لواجهة API (تُستخدم الأسعار الثابتة فقط)، أو لا توجد بيانات اعتماد ولا أسعار ثابتة (لا تظهر شركة الشحن أبدًا)، أو لا يوجد عنوان استلام، أو لا يوجد سعر صرف BRL، أو وحدة الوزن أو الأبعاد في المتجر غير معروفة للوحدة (فتُحسب بالكيلوغرام أو السنتيمتر؛ اضبط الوحدات في International > Localization). وإذا كانت قيمة غير صالحة، مثل رقم سالب، تعرض الصفحة خطأ ولا يُحفظ أي شيء.

عام

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

Method title: اسم شركة الشحن الذي يراه العميل في السلة وعند الدفع. القيمة الافتراضية: Loggi. حقل إلزامي، بحد أقصى 64 حرفًا.

واجهة Loggi البرمجية (السعر المباشر) (اترك بيانات الاعتماد فارغة لاستخدام الأسعار الثابتة فقط)

API e-mail: بريد حساب Loggi الإلكتروني. ينتمي مفتاح API إلى هذا الحساب. ويجب أن يكون عنوان بريد إلكتروني صالحًا.

API key: مفتاح Loggi API الخاص بك. يُرسل إلى Loggi فقط ولا يُسجَّل أبدًا. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it; clear the API e-mail to remove it. أدخل قيمة جديدة فقط إذا أردت تغييرها. وإذا غيّرت API e-mail، فأدخل أيضًا مفتاح API للبريد الجديد، وإلا تعرض الصفحة خطأ ولا يُحفظ أي شيء. ولحذف المفتاح المحفوظ، امسح API e-mail واحفظ.

Shop ID: المعرّف الرقمي (pk) لمتجرك في لوحة Loggi. يُقبل رقم موجب فقط. وأي قيمة أخرى تُرفض بخطأ.

Staging: يستخدم بيئة Staging الخاصة بـ Loggi مع بيانات اعتماد تجريبية. وتختلف الحسابات والمفاتيح بين Staging والإنتاج. القيمة الافتراضية: معطّل.

Pickup address: المكان الذي تستلم منه Loggi الطرود، في سطر واحد: الشارع ورقم المبنى، والحي، والمدينة، والولاية، ورمز CEP، على سبيل المثال Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. اتركه فارغًا لاستخدام عنوان المتجر من Shop Parameters > Contact > Stores إذا كان في البرازيل ويحتوي على عنوان ومدينة. ومن دون عنوان استلام لا تستطيع Loggi تقدير السعر، وتُستخدم الأسعار الثابتة فقط.

BRL exchange rate: أسعار Loggi بالريال البرازيلي. إذا كانت العملة الافتراضية لمتجرك BRL فلا حاجة لهذا الحقل، وتذكر الصفحة ذلك. وإلا فأدخل قيمة 1 BRL بعملة متجرك، على سبيل المثال 0.16. ومن دون هذه القيمة لا تُستخدم الأسعار المباشرة. ولا يُقبل إلا رقم موجب. ويُقبل كل من النقطة والفاصلة كفاصل عشري.

الأسعار الثابتة (بالعملة الافتراضية لمتجرك، دون الضريبة)

تُستخدم الأسعار الثابتة عندما لا تكون واجهة Loggi البرمجية مُعدّة، أو للوجهات خارج البرازيل أو بدون رمز CEP كامل، وكلما لم تُعد Loggi أي سعر (الواجهة غير متاحة، أو المفتاح مرفوض، أو العنوان خارج منطقة التغطية).

Price table: صف واحد لكل دولة وجهة. انقر Add country لإضافة صف، وأيقونة سلة المهملات لحذفه. اختر * All other countries لجميع الدول التي ليس لها صف خاص. ولكل صف Base price وأعمدة وزن: XS ≤1 kg، وS ≤2 kg، وM ≤3 kg، وL ≤5 kg، وXL >5 kg. والعمود الفارغ (أو الصفر) يستخدم السعر الأساسي. والسعر الأساسي 0 يعني شحنًا مجانيًا. ويُقبل كل من "9.99" و"9,99". وتُحذف الصفوف الفارغة والصف الثاني لنفس الدولة عند الحفظ.

Price for countries not in the table: يُستخدم عندما لا يوجد سعر Loggi مباشر ولا يوجد في الجدول صف لدولة الوجهة (ولا صف *). اتركه فارغًا لإخفاء شركة الشحن في تلك الحالة.

Fixed price applies: طريقة احتساب الأسعار الثابتة. يغطي سعر Loggi المباشر السلة كاملة ولا يُضرب أبدًا.

الشروط

Minimum weight: يخفي شركة الشحن عندما تكون السلة أخف من ذلك، بالكيلوغرام. 0 يعني بلا حد.

Maximum weight: يخفي شركة الشحن عندما تكون السلة أثقل من ذلك، بالكيلوغرام. الافتراضي: 30. 0 يعني بلا حد. ولا يمكن أن تكون Minimum weight أكبر من Maximum weight.

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

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

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

بالنسبة لحدود الوزن وأعمدة الوزن، يُحتسب المنتج الذي لا وزن له بوزن 0 كغ.

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

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

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

متقدم

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

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

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

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

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

بالنسبة لعنوان في البرازيل يحتوي على رمز CEP كامل من 8 أرقام، تُنشئ الوحدة طرود Loggi: يُدوَّر كل منتج بحيث يصبح أقصر جانب فيه هو الارتفاع، وتُكدَّس المنتجات في طرد واحد ما دام لا يتجاوز 55 × 55 × 55 سم و20 كغ. وتُحتسب المنتجات التي لا وزن لها أو أبعاد بسنتيمتر واحد لكل جانب، ويُحتسب كل طرد بوزن 100 غرام على الأقل. وتقبل Loggi طردين لكل تقدير، لذلك تُرسل السلال الكبيرة عبر عدة طلبات وتُجمع الإجماليات. وترسل الوحدة إلى Loggi معرّف Shop ID وعنوان الاستلام وعنوان التسليم والطرود، وتحوّل الإجمالي من BRL إلى العملة الافتراضية لمتجرك. ثم يُعرض السعر بعملة سلة العميل.

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

تُستخدم الأسعار الثابتة بدلًا من ذلك عندما لا تكون الواجهة البرمجية مُعدّة، أو يكون العنوان خارج البرازيل أو لا يحتوي بعد على رمز CEP كامل، أو يغيب سعر صرف BRL، أو لا يوجد عنوان استلام، أو يكون منتج أكبر من طرد Loggi، أو تحتاج السلة إلى أكثر من 10 طرود، أو تُعيد Loggi خطأ أو طردًا مرفوضًا أو عنوانًا خارج التغطية أو إجمالي صفر. وإذا لم يوجد سعر ثابت أيضًا، تُخفى شركة الشحن. ولا يرى العميل أبدًا خطأ من الواجهة البرمجية. ويُكتب السبب في سجل التصحيح.

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

تحسب الوحدة الأسعار فقط. ولا تُنشئ طلبات أو شحنات Loggi، ولا تطبع ملصقات، ولا تتتبع الطرود، ولا تعرض مدة التوصيل عند الدفع، ولا تقدم نقاط استلام أو خزائن. أنشئ الشحنات في لوحة Loggi. وتوصّل Loggi داخل البرازيل فقط. استخدم الأسعار الثابتة للدول الأخرى.

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

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

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

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

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

لا يظهر Loggi عند الدفع: تحقق من أن الترخيص نشط وأن Enable Loggi مفعّل. وفي Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). راجع التحذيرات أعلى صفحة الوحدة، وحدود الوزن، وMinimum order amount. وإذا لم يُدخل العميل رمز CEP كاملًا بعد، أو لم تُعد Loggi أي سعر، تحتاج شركة الشحن إلى سعر ثابت: صف للدولة، أو صف *، أو Price for countries not in the table. ويمكن أيضًا قصر المنتجات على شركات شحن معينة في صفحة المنتج.

تظهر الأسعار الثابتة فقط: انظر حقل Log في صفحة الوحدة. تُسجَّل الأخطاء دائمًا. فعّل Debug log لرؤية كل خطوة، ثم أعد تحميل صفحة الدفع. الأسباب الشائعة: بريد API أو مفتاحه أو Shop ID مفقود، أو لا يوجد عنوان استلام، أو لا يوجد BRL exchange rate لعملة متجر غير BRL، أو لم يُدخل العميل رمز CEP كاملًا من 8 أرقام بعد، أو منتج أكبر من 55 سم أو أثقل من 20 كغ، أو عنوان خارج تغطية Loggi.

HTTP 401 أو 403 في السجل: رفضت Loggi بريد API أو المفتاح. تحقق منهما مع Loggi، وتأكد من أن Staging يتطابق مع بيانات الاعتماد: مفاتيح Staging والإنتاج مختلفة.

متجري يبيع باليورو أو الدولار: تُجيب Loggi بالريال البرازيلي BRL. أدخل BRL exchange rate (كم يساوي 1 BRL بالعملة الافتراضية لمتجرك). وتبقى الأسعار الثابتة دائمًا بالعملة الافتراضية لمتجرك.

الأسعار غير دقيقة: أدخل وزن منتجاتك وأبعادها. ومن دونها تُحسب المنتجات بسنتيمتر واحد لكل جانب، وكل طرد بـ100 غرام على الأقل.

Per item لا يضرب سعر Loggi: هذا مقصود. يغطي سعر Loggi المباشر السلة كاملة. ويُطبَّق Per item على الأسعار الثابتة فقط.

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

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

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

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

Loggi علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Loggi ولا معتمدة من قِبلها.