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

المتطلبات

WordPress: الإصدار 5.8 أو أحدث.

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

PHP: الإصدار 8.0 أو أحدث.

عقد Jadlog (للأسعار الحية ونقاط Pickup): تأتي الأسعار الحية وقائمة نقاط Pickup من Jadlog Embarcador API. تُصدر فرنشايز Jadlog الخاصة بك الوصول بعد توقيع العقد. تحتاج إلى رمز Embarcador API، ورقم CNPJ (أو CPF) للمرسِل المسجل في العقد، والحساب الجاري (conta corrente)، ورقم العقد إن وُجد. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى عقد Jadlog.

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

التثبيت

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

2. انقر على Activate.

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

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

5. الصق رمز API، وأدخل رقم CNPJ والحساب الجاري ورقم العقد ورمز CEP للمنشأ، واختر خدمة Jadlog، وإذا لم تكن عملة متجرك BRL فأدخل سعر صرف BRL. أضف أسعارًا ثابتة أو تكلفة احتياطية إن أردت (انظر الإعدادات).

6. أضف VibeFox Jadlog إلى منطقة شحن للبرازيل من WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول. ولعرض نقاط Jadlog Pickup أيضًا، أضف الطريقة إلى المنطقة نفسها مرة ثانية واختر Pickup (40) خدمةً لها.

الإعدادات

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

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

Jadlog service (zone): خدمة طريقة المنطقة هذه. يستخدم Same as the global setting الخدمة الموجودة في صفحة الإعدادات الرئيسية. أضف الطريقة مرتين لتقديم التوصيل إلى المنزل (.Package) ونقاط Jadlog Pickup في المنطقة نفسها، على سبيل المثال.

عندما يكون عنوان المنطقة فارغًا والخدمة Pickup، تُضاف كلمة "Pickup" إلى العنوان العام، حتى يكون لكل من الطريقتين اسم مختلف.

تعرض الإضافة في أعلى صفحة الإعدادات تحذيرات للإعداد غير المكتمل: عدم وجود رمز API، أو عدم وجود رقم CNPJ أو الحساب الجاري، أو عدم وجود رمز CEP للمنشأ، أو عدم وجود سعر صرف BRL لمتجر لا يبيع بالريال. وكلما حفظت الإعدادات، تُمسح الأسعار المخزنة مؤقتًا من Jadlog وقوائم نقاط Pickup.

عام

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

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

أسعار Jadlog الحية

تُطلب الأسعار الحية فقط للعناوين داخل البرازيل التي تتضمن رمز CEP كاملًا من 8 أرقام.

API token: رمز Embarcador من Jadlog. يمكنك لصقه مع كلمة "Bearer" أو دونها. اتركه فارغًا لاستخدام الأسعار الثابتة فقط.

CNPJ: رقم CNPJ (14 رقمًا) أو CPF (11 رقمًا) للمرسِل المسجل في عقد Jadlog. تُقبل النقاط والشرطات المائلة والواصلات. تُحذّرك الإضافة إذا كان عدد الأرقام غير صحيح.

Current account (conta corrente): رقم حسابك الجاري لدى Jadlog. وبدونه وبدون CNPJ لا تستطيع Jadlog تقديم عرض سعر، ولا تُستخدم إلا الأسعار الثابتة.

Contract number: رقم عقدك مع Jadlog، إذا منحتك إياه فرنشايز Jadlog.

Origin CEP: الرمز البريدي الذي تُشحن منه الطرود، ويتكون من 8 أرقام. يُحفظ بالصيغة 00000-000. اتركه فارغًا لاستخدام الرمز البريدي للمتجر من WooCommerce > Settings > General، إذا كان عنوان المتجر داخل البرازيل.

Jadlog service: خدمة (modalidade) عقدك: .Package (3، الافتراضي)، و.Com (9)، وExpresso (0)، وRodoviário (4)، وEconômico (5)، وDoc (6)، وCorporate (7)، وInternacional (10)، وCargo (12)، وEmergencial (14)، أو Pickup (40). تعرض Pickup نقاط Jadlog Pickup القريبة من العميل. ويمكن لطريقة المنطقة أن تستخدم خدمة أخرى.

Insurance type: Normal (N) (الافتراضي) أو Own insurance policy (A — apólice)، حسبما هو متفق عليه في عقد Jadlog الخاص بك.

Volumetric weight: تحتسب Jadlog الأكبر من الوزن الفعلي والوزن الحجمي.

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

Delivery time: يعرض مدة التوصيل التي تُعيدها Jadlog بجانب عنوان الطريقة، مثل "Jadlog (3 أيام عمل)". مُفعّل افتراضيًا. تُحفظ مدة التوصيل دائمًا في الطلب.

نقاط Jadlog Pickup (تستخدمها خدمة Pickup (40)؛ وتحتاج إلى رمز API)

Points to show: عدد نقاط Pickup التي تُعرض، من 1 إلى 10. الافتراضي: 5.

الأسعار الثابتة (تُستخدم عند عدم وجود رمز API، وللدول التي لا تخدمها Jadlog، وكلما لم تُعِد Jadlog أي سعر)

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

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

Fixed price applies: Per order يُحصّل السعر مرة واحدة. وPer item (price × quantity) يضربه في عدد العناصر في السلة. ويسري هذا على الأسعار الثابتة والتكلفة الاحتياطية فقط. أما أسعار Jadlog فتغطي السلة بأكملها أصلًا.

الشروط

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

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

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

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

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

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

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

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

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

متقدم

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

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

كيف تعمل في صفحة الدفع

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

بالنسبة إلى عنوان توصيل داخل البرازيل يتضمن رمز CEP كاملًا من 8 أرقام، ترسل الإضافة إلى Jadlog رمز CEP للمنشأ والوجهة، والوزن، ورقم CNPJ الخاص بك، والحساب الجاري، والعقد، والخدمة، ونوع التأمين، وقيمة الطلب المُعلنة، وتعرض السعر المُعاد بعملة متجرك. تُسعّر السلال التي لا تحتوي على وزن بوزن 0.1 كجم. وإذا لم يتوفر سعر حي (لا يوجد رمز، أو العنوان خارج البرازيل، أو رمز CEP غير مكتمل، أو لا يوجد سعر صرف BRL، أو خطأ من Jadlog)، تستخدم الإضافة جدول Price per country ثم Fallback cost. وإذا لم يُعطِ أي منهما سعرًا، تُخفى الطريقة لتلك السلة.

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

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

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

نقاط Pickup

تُعرض الطريقة التي تحمل خدمة Pickup (40) فقط للعناوين داخل البرازيل. عندما يُدخل العميل رمز CEP كاملًا من 8 أرقام، تطلب الإضافة من Jadlog نقاط Pickup النشطة الأقرب إليه، وتعرض حتى Points to show نقطة. كل نقطة خيار شحن منفصل بسعره الخاص، مثل "Jadlog Pickup: اسم النقطة — العنوان". يختار العميل نقطته باختيار خيار الشحن، سواء في صفحة الدفع الكلاسيكية أو في كتلتي Cart وCheckout.

يُطلب السعر لكل نقطة من Jadlog. وإذا لم تُعطِ Jadlog سعرًا لنقطة ما، يُستخدم السعر الثابت، وتُستبعد النقطة التي لا تحتوي على أي سعر. وتُخزَّن قوائم النقاط مؤقتًا لمدة 12 ساعة.

بدون رمز API، أو بدون رمز CEP من 8 أرقام، أو عندما تكون Jadlog غير متاحة، أو عندما لا توجد نقاط نشطة قريبة، تُخفى طريقة Pickup. فالطلب الذي لا يحتوي على نقطة لا يمكن شحنه.

الطلبات

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

احجز الشحنة في نظام Jadlog بنفسك. يعرض الطلب الخدمة ومعرّف نقطة Pickup اللازمين لذلك.

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

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

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

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

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

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

لا تظهر Jadlog في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الطريقة مُضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). راجع التحذيرات في أعلى صفحة الإعدادات، وحدود الوزن، وMinimum order amount، وExcluded shipping classes. إذا لم يُدخل العميل رمز CEP كاملًا من 8 أرقام بعد، فلا يمكن إلا استخدام الأسعار الثابتة، لذا أضف صفًا في Price per country أو Fallback cost.

تظهر الأسعار الثابتة فقط: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs بالمصدر vfd-jadlog. يعرض السجل السبب: عدم وجود CNPJ أو الحساب الجاري، أو عدم وجود رمز CEP للمنشأ، أو رمز CEP للوجهة غير مكتمل، أو عدم وجود سعر صرف BRL، أو رسالة خطأ Jadlog.

HTTP 401 أو 403 في السجل: رفضت Jadlog رمز API. تحقق منه مع فرنشايز Jadlog الخاصة بك. يتوقف API لمدة 10 دقائق بعد هذا الخطأ. ويؤدي حفظ الإعدادات إلى إلغاء الإيقاف، فيمكنك المحاولة فورًا.

لا تظهر نقاط Pickup: تحتاج طريقة Pickup إلى رمز API ورمز CEP كامل من 8 أرقام داخل البرازيل. إذا لم تكن لدى Jadlog نقاط نشطة قرب رمز CEP، تُخفى الطريقة. تحقق من السجل لمعرفة السبب.

تظهر الأسعار بالريال بدلًا من عملتي: أدخل BRL exchange rate (قيمة 1 BRL بعملة متجرك).

تبدو الأسعار منخفضة جدًا أو مرتفعة جدًا: أكمل أوزان المنتجات وأبعادها. تُسعّر السلال التي لا تحتوي على وزن بوزن 0.1 كجم، ويحتاج الوزن الحجمي إلى الأبعاد.

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

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

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

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

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