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

المتطلبات

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

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

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

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

التثبيت

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

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

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

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

5. لعرض نقاط Jadlog Pickup أيضًا، فعّل Enable Jadlog Pickup وانقر فوق Save.

عند التثبيت، تنشئ الوحدة ناقلَي شحن: Jadlog (توصيل إلى المنزل، مفعّل، ونص مدة التوصيل Jadlog delivery to your address) وJadlog Pickup (معطّل، ونص مدة التوصيل Pickup at a Jadlog Pickup point). يرتبط الناقلان بمنطقة البرازيل وبجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

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

تعرض الوحدة في أعلى الصفحة تحذيرات للإعداد غير المكتمل: لا يوجد رمز API (لا تُستخدم إلا الأسعار الثابتة، ولا يمكن عرض نقاط Pickup)، ولا يوجد رمز API ولا أسعار ثابتة (لا تظهر الطريقة أبدًا)، أو لا يوجد CNPJ أو حساب جاري، أو لا يوجد CEP للأصل، أو لا يوجد سعر صرف BRL لمتجر لا يبيع بـ BRL، أو وحدة وزن أو أبعاد للمتجر لا تتعرف عليها الوحدة (عندئذ تُعامل الأوزان بالكيلوغرام والأبعاد بالسنتيمتر؛ اضبط الوحدات في International > Localization، ضمن Local units)، أو ناقل Jadlog تم حذفه. وعند الحفظ تُبلَّغ القيم الخاطئة: CEP بغير 8 أرقام، أو CNPJ بغير 14 رقمًا (أو 11 لـ CPF)، أو رقم غير صالح، أو حد أدنى للوزن أعلى من الحد الأقصى (يحتفظ الوزنان بقيمهما المحفوظة)، أو دولة غير معروفة، أو سعر غير صالح في جدول الأسعار.

General

Enable/Disable: يفعّل توصيل Jadlog إلى المنزل أو يعطّله. وهو المفتاح نفسه لحالة الناقل في Shipping > Carriers.

Method title: اسم ناقل التوصيل إلى المنزل الذي يظهر في السلة وفي صفحة الدفع. الافتراضي: Jadlog. حقل مطلوب.

Tax status: None أو Taxable مع إحدى قواعد الضريبة لديك. يُحفظ في ناقلي Jadlog كليهما. أسعار Jadlog هي أسعار ناقل نهائية. اختر None إذا كان PrestaShop لا ينبغي أن يضيف ضريبة عليها.

Jadlog live prices

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

API token: رمز Embarcador من Jadlog. يمكنك لصقه مع كلمة "Bearer" أو بدونها. اتركه فارغًا إذا كنت تريد الأسعار الثابتة فقط. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Remove the saved API token: حدّد المربع وانقر فوق Save لحذف الرمز المحفوظ.

CNPJ: رقم CNPJ (14 رقمًا) أو CPF (11 رقمًا) للمرسل المسجل في عقد Jadlog. النقاط والشرطات المائلة والواصلات مسموح بها.

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

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

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

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). أما Jadlog Pickup (40) فهو الناقل الثاني.

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

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

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

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

Jadlog Pickup

ناقل شحن ثانٍ بخدمة Jadlog Pickup (40). يحتاج إلى رمز API. بدون نقاط يُخفى الناقل.

Enable Jadlog Pickup: يفعّل ناقل Jadlog Pickup أو يعطّله. وهو المفتاح نفسه لحالته في Shipping > Carriers. معطّل بعد التثبيت.

Jadlog Pickup carrier name: اسم هذا الخيار عند الدفع. الافتراضي: Jadlog Pickup. حقل مطلوب.

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

Fixed prices (تُستخدم عند غياب رمز 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 (other countries) لجميع الدول الأخرى. تُحذف الصفوف التي لا تحتوي على أي سعر عند الحفظ.

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

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

Conditions

Minimum weight (kg): إخفاء الناقلين عندما تكون السلة أخف من ذلك. 0 يعني بلا حد.

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

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

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

Availability without shipping zones

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

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

Advanced

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

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

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

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

في خطوة الشحن يطلب PrestaShop من الوحدة سعر كل ناقل Jadlog. لا يُحسب إلا المنتجات المادية: فالمنتجات الافتراضية لا تضيف وزنًا ولا تُدرج في مبلغ الطلب. تتحقق الوحدة أولًا من الشروط: وزن السلة والحد الأدنى لمبلغ الطلب، وعند تفعيل Ignore shipping zones الدول المسموح بها. فإذا وصل المجموع الفرعي للسلة إلى 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 أبدًا. ويُكتب السبب في السجل.

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

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

نقاط Pickup

يُعرض ناقل Jadlog Pickup فقط للعناوين داخل البرازيل، وفقط عند حفظ رمز API. عندما يُدخل العميل رمز CEP كاملًا من 8 أرقام، تطلب الوحدة من Jadlog أقرب نقاط Pickup النشطة وتعرض تحت الناقل حتى Points to show نقطة، كل منها بسعرها، مثل "اسم النقطة — السعر (3 business days) — العنوان". وإذا لم تكن القائمة مخزنة مؤقتًا بعد، تُحمَّل عندما يختار العميل الناقل، حتى لا تنتظر خطوة الشحن Jadlog.

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

اختيار النقطة إلزامي. وبدون نقطة لا يستطيع العميل المتابعة، ويرى Please select a Jadlog Pickup point. تتحقق الوحدة من أن النقطة موجودة في قائمة Jadlog لرمز CEP الخاص بالتوصيل. فإن لم تكن موجودة، يرى العميل The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. وعندما يكون CEP غير مكتمل، أو لا توجد نقاط قريبة، أو تكون Jadlog غير متاحة، تظهر رسالة أسفل الناقل.

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

الطلبات

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

تعرض صفحة الطلب في لوحة الإدارة كتلة Jadlog تتضمن Jadlog service وDelivery time، وبالنسبة إلى Jadlog Pickup: Pickup point وPickup point address وPickup point ID. يرى العميل النقطة المختارة في صفحة تأكيد الطلب وفي تفاصيل الطلب. وتُضاف النقطة إلى اسم الناقل في بريد تأكيد الطلب. كما يتضمن بريد الطلب الجديد للمتجر (إذا كنت تستخدم وحدة تنبيهات البريد الإلكتروني) معرّف النقطة.

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

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

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

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

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

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

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

لا تظهر إلا الأسعار الثابتة: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم راجع حقل Log في صفحة الوحدة. يُظهر الحقل السبب: لا يوجد CNPJ أو حساب جاري، أو لا يوجد CEP للأصل، أو CEP الوجهة غير مكتمل، أو لا يوجد سعر صرف BRL، أو رسالة الخطأ من Jadlog.

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

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

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

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

تُضاف ضريبة إلى أسعار Jadlog: اضبط Tax status على None.

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

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

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

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

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