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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب 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. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر Install Now. يمكنك أيضًا رفع مجلد vfd_loggi إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

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

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

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

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

الإعدادات

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

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

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

عام

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

Method title: اسم طريقة الشحن الذي يظهر في السلة وفي صفحة الدفع. ويمكن لأي منطقة أن تستبدله. القيمة الافتراضية: Loggi.

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

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

API key: مفتاح Loggi API الخاص بك. يُرسل إلى Loggi فقط ولا يُسجَّل في أي سجل.

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

Staging: استخدم بيئة Loggi التجريبية (staging) ببيانات اعتماد اختبار. وبيئتا staging والإنتاج لهما حسابان ومفتاحان مختلفان. القيمة الافتراضية: غير مفعّل.

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

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

الأسعار الثابتة (بعملة متجرك)

تُستخدم الأسعار الثابتة عندما لا تكون Loggi API مُعدّة، أو للوجهات خارج البرازيل أو عند عدم وجود رمز 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) يُستخدم السعر الأساسي. والسعر الأساسي 0 يعني شحنًا مجانيًا. ويُقبل كلٌّ من "9.99" و"9,99". تُحذف الصفوف الفارغة والصف الثاني لنفس الدولة عند الحفظ.

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

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

Per order (one parcel, tier by total cart weight): سعر واحد للسلة، ويُختار عمود الوزن حسب الوزن الإجمالي للسلة. هذا هو الخيار الافتراضي.

Per item (every item is a separate parcel, tier by its own weight): يُسعَّر كل منتج بوزنه الخاص، وتُجمع الأسعار.

الشروط

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

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

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

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

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. اختر None إذا كانت أسعارك وسعر Loggi تشمل الضرائب بالفعل.

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تظهر الأسعار الثابتة فقط: افتح WooCommerce > Status > Logs، المصدر vfd-loggi. وتُسجَّل الأخطاء دائمًا. فعّل 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 بعملة متجرك). وتبقى الأسعار الثابتة دائمًا بعملة متجرك.

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

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

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

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

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

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

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