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

المتطلبات

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

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

مفتاح API من Coordinadora (للأسعار المباشرة فقط): تأتي الأسعار المباشرة من Coordinadora Cotizador عبر خدمة Coordinadora WooCommerce، وهي الخدمة نفسها التي تستخدمها إضافة Coordinadora الرسمية. تصدر Coordinadora مفتاح API للعملاء الذين لديهم اتفاقية تجارية نشطة. اطلب ذلك من مدير حسابك لدى Coordinadora، أو راجع wc.coordinadora.com. كما تحتاج إلى رمز DANE المكون من 8 أرقام للمدينة التي تشحن منها. وبدون مفتاح تعمل شركة الشحن بالأسعار الثابتة فقط.

المنتجات: للحصول على سعر مباشر، يجب أن يكون لكل منتج في السلة وزن وأبعاد (العرض والارتفاع والعمق).

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

التثبيت

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

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

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

4. أدخل مفتاح API ورمز DANE لمدينة الشحن، وإذا لم تكن العملة الافتراضية هي COP فأدخل سعر صرف COP. أضف سعرًا ثابتًا واحدًا على الأقل لكولومبيا كبديل (انظر الإعدادات). انقر على Save.

5. تأكد من أن كولومبيا مفعّلة في متجرك وأن منتجاتك لها وزن وأبعاد.

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

الإعدادات

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

ترفض الصفحة الحفظ وتعرض خطأً عندما يكون رقم أو سعر في الجدول غير صالح أو سالبًا، أو عندما تكون COP per 1 unit of store currency تساوي 0، أو عندما تكون Min weight أكبر من Max weight، أو عندما يتجاوز Name 64 حرفًا. لا يُحفظ شيء حتى تصحح الخطأ.

تعرض الصفحة تحذيرات في الأعلى عندما لا تستطيع الأسعار المباشرة العمل أو عندما ستُخفى شركة الشحن: Origin city (DANE code) فارغ أو غير صالح، أو COP per 1 unit of store currency غير موجود بينما عملتك الافتراضية ليست COP، أو لا يوجد سعر ثابت لكولومبيا (أو *). بدون مفتاح API وبدون سعر ثابت كهذا، لا تُعرض شركة الشحن أبدًا للعناوين الكولومبية. ويظهر تحذير أيضًا عندما تكون وحدة الوزن أو البُعد في المتجر ضمن International > Localization (Local units) غير معروفة للوحدة؛ عندها تُقرأ أوزان المنتجات بوحدة كغ وأبعادها بوحدة سم.

عام

Enable Coordinadora: يُفعّل شركة الشحن أو يُوقفها. وهو المفتاح نفسه الذي يمثل حالة شركة الشحن في Shipping > Carriers.

Name: اسم شركة الشحن الذي يراه العميل في صفحة الدفع. القيمة الافتراضية: Coordinadora. حقل إلزامي.

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

الأسعار المباشرة من Coordinadora

تُطلب الأسعار المباشرة للوجهات داخل كولومبيا. اترك المفتاح فارغًا لاستخدام الأسعار الثابتة فقط.

API key: مفتاح Coordinadora WooCommerce API الخاص بك، الذي تحصل عليه من Coordinadora. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره. لا يُكتب المفتاح في السجل أبدًا.

Remove the saved API key: يظهر فقط عندما يكون هناك مفتاح محفوظ. فعّله وانقر على Save لحذف المفتاح؛ وبعدها تستخدم شركة الشحن الأسعار الثابتة فقط.

Origin city (DANE code): رمز DANE المكون من 8 أرقام للمدينة التي تشحن منها، مثل 11001000 Bogotá أو 05001000 Medellín أو 76001000 Cali أو 08001000 Barranquilla. كما يُقبل رمز البلدية المكون من 5 أرقام ويُكمَل إلى 8 أرقام.

COP per 1 unit of store currency: تُسعِّر Coordinadora بالبيزو الكولومبي. إذا كانت عملتك الافتراضية ليست COP، فأدخل عدد وحدات COP التي تعادل وحدة واحدة من عملتك، مثل 4300. ويُستخدم السعر أيضًا لإرسال القيمة المعلنة بالـ COP. إذا تركته فارغًا فلن تُستخدم الأسعار المباشرة. يجب أن يكون السعر أكبر من 0. وإذا كانت عملتك الافتراضية هي COP فاتركه فارغًا.

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

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

Fixed price per: Order يحتسب السعر مرة واحدة. Item (price × quantity) يضربه في عدد العناصر في السلة. ينطبق هذا على الأسعار الثابتة فقط؛ أما سعر Coordinadora المباشر فيغطي الطلب كاملًا دائمًا.

الشروط

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

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

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

Free shipping: يُفعّل التوصيل المجاني ابتداءً من المجموع الفرعي المذكور أدناه.

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

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

متقدم

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

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

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

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

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

بالنسبة لعنوان في كولومبيا مع مفتاح API، تجد الوحدة رمز DANE لمدينة الوجهة بهذا الترتيب: رمز DANE في حقل المدينة (تكتبه وحدات دفع أقسام ومدن كولومبيا، مثل MEDELLIN (ANT) (05001000))، أو الرمز البريدي المكون من 8 أرقام، أو القائمة المدمجة بعواصم الأقسام ونحو 40 من أكبر المدن. وإذا كان للعنوان قسم (ولاية)، تُتحقق المدينة من القائمة بالنسبة إليه. ويتم تجاهل التشكيل وحالة الأحرف.

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

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

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

تحسب الوحدة الأسعار فقط. فهي لا تُنشئ الشحنات أو بوليصات الشحن (guías)، ولا تطبع الملصقات، ولا تحجز مواعيد الاستلام (recogidas)، ولا تتتبع الطرود، ولا تتولى التحصيل عند الاستلام (recaudo)، ولا تقدم نقاط استلام Droop؛ استخدم بوابة Coordinadora لهذه المهام. وتستخدم الوجهات الدولية الأسعار الثابتة.

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

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

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

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

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

لا تظهر Coordinadora في صفحة الدفع: تحقق من أن الترخيص نشط وأن Enable Coordinadora مفعّل. وفي Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعة العميل. تحقق من Countries وحدود الوزن وMinimum order subtotal. وبدون سعر مباشر، يجب أن يوجد سعر ثابت للدولة أو لـ *. ويمكن أيضًا حصر المنتجات في شركات شحن معينة من صفحة المنتج.

لا يظهر السعر المباشر، بل السعر الثابت فقط: فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى حقل Log في صفحة الوحدة. الأسباب الشائعة: لم يُتعرف على مدينة الوجهة، أو لا يملك منتج وزنًا أو أبعادًا، أو يغيب رمز DANE لمدينة الشحن أو سعر صرف COP، أو أعادت Coordinadora خطأً.

لم يُتعرف على مدينة الوجهة: ثبّت وحدة دفع لأقسام ومدن كولومبيا تكتب رمز DANE في حقل المدينة. ويمكن للمطورين ربط مدن إضافية عبر خطافات الوحدة actionVfdCrdDaneCities وactionVfdCrdDestinationDane، أو تغيير عنوان API عبر actionVfdCrdApiUrl.

هل يتضمن السعر الضريبة؟ السعر هو ما تحسبه Coordinadora. مع قاعدة Tax يضيف PrestaShop ضريبة الشحن فوقه؛ اختر No tax إذا كان عرض Coordinadora يتضمنها بالفعل.

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

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

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

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

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