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

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم لكلا إصدارَي OpenCart. فُكّ ضغطه على حاسوبك. ويحتوي على README.txt، وحزمة OpenCart 3 vfd_coordinadora-oc3-(version).ocmod.zip، وحزمة OpenCart 4 vfd_coordinadora.ocmod.zip. ثبّت فقط الحزمة الخاصة بإصدار OpenCart لديك. ومفتاح الترخيص هو نفسه في الإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف vfd_coordinadora-oc3-(version).ocmod.zip. لا يضيف الامتداد أي تعديلات OCMOD، لذلك لا تحتاج إلى تحديث Extensions > Modifications. وبدلًا من Installer يمكنك نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى مجلد الجذر في متجرك.

2. انتقل إلى Extensions > Extensions واختر نوع الامتداد Shipping. ابحث عن VibeFox Coordinadora واضغط Install (زر + الأخضر).

3. اضغط Edit (زر القلم الرصاص) لفتح صفحة الإعدادات.

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

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

6. تأكد من أن منتجاتك لها وزن وأبعاد.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف vfd_coordinadora.ocmod.zip. لا تُغيّر اسم الملف: فـ OpenCart 4 يأخذ رمز الامتداد من اسم الملف، والحزمة التي يُغيَّر اسمها لا تعمل.

2. تظهر الحزمة في قائمة الامتدادات المثبتة في الصفحة نفسها. اضغط Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر نوع الامتداد Shipping. ابحث عن VibeFox Coordinadora، واضغط Install (زر + الأخضر)، ثم Edit (زر القلم الرصاص).

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوات من 4 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

بعد التثبيت تبقى الطريقة متوقفة إلى أن تفعّل Enable Coordinadora وتحفظ. وإذا أعدت تثبيت الامتداد بعد إلغاء تثبيته، تُستخدم من جديد إعدادات Coordinadora التي احتفظت بها.

الإعدادات

جميع الإعدادات موجودة في صفحة الامتداد: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. تسري الإعدادات على كل المناطق الجغرافية؛ ويمكنك حصر الطريقة بمنطقة جغرافية وبدول محددة ضمن Conditions. تظهر الأقسام على اليسار. يحفظ زر Save الواحد في الأسفل الصفحة كلها دون إعادة تحميلها. وبعد الحفظ تظهر لك الرسالة Settings saved. Cached Coordinadora rates were cleared. ويمكن إدخال الأرقام بنقطة أو فاصلة (9,99 = 9.99). ولا يستطيع حفظ الإعدادات إلا مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذا الامتداد.

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

تعرض الصفحة تحذيرات فوق الإعدادات عندما لا يمكن أن تعمل التسعيرات الفورية أو عندما ستُخفى الطريقة: Origin city (DANE code) فارغ أو غير صالح؛ COP per 1 unit of store currency مفقود إذا لم تكن عملتك الافتراضية COP؛ لا يوجد سعر ثابت لكولومبيا (أو لـ *)؛ لا يوجد مفتاح API ولا سعر ثابت لكولومبيا، فلا تظهر الطريقة أبدًا للعناوين الكولومبية. ويظهر تحذير أيضًا عندما لا تملك الإدارة فئة وزن بالكيلوغرام أو فئة طول بالسنتيمتر، وكانت وحدتها الافتراضية غير معروفة للامتداد؛ فتُقرأ أوزان المنتجات حينها بالكيلوغرام والأبعاد بالسنتيمتر (استخدم kg أو g أو lb أو oz وcm أو mm أو m أو in في System > Localisation). تُحدَّث التحذيرات بعد كل حفظ.

عام

Enable Coordinadora: يُظهر Coordinadora أو يُخفيه في صفحة الدفع. الافتراضي: متوقف.

Name: اسم طريقة الشحن الذي يراه العميل في صفحة الدفع. الافتراضي: Coordinadora. حقل مطلوب، بحد أقصى 64 حرفًا.

Sort order: ترتيب Coordinadora بين طرق الشحن في صفحة الدفع. عدد صحيح.

التسعيرات الفورية من Coordinadora

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

API key: مفتاح API الخاص بـ Coordinadora WooCommerce. بعد الحفظ يبقى الحقل فارغًا ويعرض 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 (kg): يخفي الطريقة إذا كان وزن السلة أقل من هذا. 0 يعني بلا حد (الافتراضي).

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

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

Free shipping: يفعّل الشحن المجاني ابتداءً من المجموع الفرعي أدناه.

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

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

Geo zone: اعرض Coordinadora فقط للعناوين في هذه المنطقة الجغرافية. All zones (الافتراضي) يعني بلا حد. تُدار المناطق الجغرافية في System > Localisation > Geo Zones.

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

متقدم

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

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

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

الاستيراد / التصدير

Export: اضغط Download JSON لحفظ الإعدادات في ملف JSON. لا يُصدَّر مفتاح API.

Import: الصق ملف JSON مُصدَّرًا سابقًا واضغط Import لاستعادة الإعدادات، مثلًا في متجر آخر. تُفحص القيم كما في الحفظ العادي. يبقى مفتاح API المحفوظ كما هو.

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

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

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

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

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

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

في OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار Coordinadora في نافذة Shipping method options. وتعمل الطريقة بالطريقة نفسها كما في OpenCart 3.

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

يعمل الامتداد بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Coordinadora هي أول كتلة في Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit، فوق الإعدادات. ألصق المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مُخفى الأجزاء، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لحذف المفتاح من هذا المتجر. وتحتها السطر Product: opencart-shipping-coordinadora والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify لهذا الامتداد. تتبع نصوص الكتلة لغة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير مكان للنطاق في حسابك، اضغط Check now. وإذا تعذر الوصول إلى خادم التراخيص، يواصل الامتداد العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: عنوان المتجر من إعدادات OpenCart. وحذف المفتاح من المتجر لا يحرر مكان النطاق. حرّر المكان من حسابك في vibefox.net.

بدون مفتاح فعّال لا تُعرض Coordinadora للعملاء في صفحة الدفع، ولا تُحسب أي تسعيرة. يظل مستخدم الإدارة المسجَّل دخوله إلى الإدارة من المتصفح نفسه يرى الطريقة في المتجر، مع علامة (unlicensed — visible to admins only)، فيمكنك إعداد الامتداد واختباره قبل شراء المفتاح. وفي OpenCart 4 لا تتوفر هذه المعاينة: فالمتجر لا يرى تسجيل دخول الإدارة، لذلك بدون مفتاح فعّال تكون الطريقة مخفية عن الجميع. وبعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاصة بالإدارة. أغلقه بالزر × ليختفي لمدة 7 أيام. ولا تتأثر الطلبات الموجودة.

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

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

لا تظهر Coordinadora في صفحة الدفع: تحقق من أن الترخيص فعّال وأن Enable Coordinadora مفعّل. تحقق من التحذيرات في أعلى صفحة الامتداد، وGeo zone، وCountries، وحدود الوزن، وMinimum order subtotal. من دون تسعيرة فورية يجب أن يوجد سعر ثابت للبلد أو لـ *. تحقق من أن المنتجات لديها Requires Shipping على Yes.

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

مدينة الوجهة غير معروفة: ثبّت وحدة دفع كولومبية للأقسام والمدن تكتب رمز DANE في حقل المدينة. يمكن للمطورين إضافة مدن أكثر أو تغيير عنوان الواجهة البرمجية باستخدام أحداث OpenCart vfd_coordinadora/dane_cities وvfd_coordinadora/destination_dane وvfd_coordinadora/api_url؛ ويمكن أيضًا استبدال عنوان الواجهة البرمجية بالإعداد vfd_crd_api_url (للاختبارات)، وهو إعداد لا يوجد له حقل في صفحة الإعدادات.

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

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

تقول الصفحة "Warning: You do not have permission to modify VibeFox Coordinadora!": قد تملك مجموعة مستخدمي الإدارة لديك صلاحية العرض فقط للإعدادات. امنح المجموعة صلاحية التعديل على extension/shipping/vfd_coordinadora (OpenCart 3) أو extension/vfd_coordinadora/shipping/vfd_coordinadora (OpenCart 4) في System > Users > User Groups.

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

انتقل إلى Extensions > Extensions، واختر النوع Shipping، ثم اضغط Uninstall (الزر الأحمر −) بجوار VibeFox Coordinadora. يُحذف مفتاح الترخيص وحالة الترخيص لهذا الامتداد دائمًا. يعيد OpenCart دائمًا ضبط Enable Coordinadora وSort order وTax class وGeo zone. تُحذف التسعيرات المخزنة مؤقتًا دائمًا. إذا كان Remove data on uninstall مفعّلًا، تُحذف إعدادات Coordinadora والسجل أيضًا. وإذا كان متوقفًا، فتُحفظ الإعدادات الأخرى وتُستخدم من جديد عند إعادة تثبيت الامتداد. تحتفظ الطلبات الموجودة بطريقة شحنها وتكلفتها.

في OpenCart 4، لحذف ملفات الامتداد أيضًا، انتقل بعد إلغاء التثبيت إلى Extensions > Installer، واضغط Uninstall (الزر البرتقالي −) بجوار VibeFox Coordinadora في قائمة الامتدادات المثبتة، ثم اضغط Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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