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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر Activate.

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

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

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

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

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

الإعدادات

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

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

تعرض صفحة الإعدادات تحذيرات في الأعلى عندما لا تعمل الأسعار المباشرة أو عندما ستُخفى الطريقة: رمز DANE لمدينة الشحن مفقود أو غير صالح، أو سعر الصرف إلى COP مفقود، أو لا يوجد سعر ثابت لكولومبيا. وفي كل مرة تحفظ فيها الإعدادات تُمسح العروض المخزنة مؤقتًا. ويمكن كتابة الأرقام بنقطة أو فاصلة (9,99 = 9.99).

عام

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

Name: اسم طريقة الشحن الذي يراه العميل في صفحة الدفع. الافتراضي: Coordinadora. ويحل Title الخاص بالمنطقة محله.

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

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

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

API key: مفتاح Coordinadora لـ WooCommerce الخاص بك. ولا يُكتب في السجل أبدًا.

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. وإذا تركته فارغًا لا تُستخدم الأسعار المباشرة. وإذا كانت عملة متجرك 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: تُعرض الطريقة فقط إذا بلغ المجموع الفرعي للسلة هذا المبلغ على الأقل. اتركه فارغًا لعرضها دائمًا.

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

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

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

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Coordinadora لا يظهر في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). وراجع حدود الوزن، وMinimum order subtotal، وExcluded shipping classes. ومن دون سعر مباشر، يجب أن يوجد سعر ثابت للدولة أو لـ *.

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

مدينة الوجهة غير معروفة: ثبّت إضافة لأقسام ومدن كولومبيا في صفحة الدفع تكتب رمز DANE في حقل المدينة. ويمكن للمطورين ربط مدن أخرى باستخدام الفلترين vfd_crd_dane_cities وvfd_crd_destination_dane.

هل يتضمن السعر الضريبة؟ السعر هو ما تعرضه Coordinadora. وعند ضبط Tax status على Taxable، يضيف WooCommerce ضريبة الشحن فوقه؛ اختر None إذا كان العرض يتضمنها بالفعل.

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

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

الإلغاء

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

Coordinadora علامة تجارية مملوكة لصاحبها. وهذه الإضافة غير تابعة لـ Coordinadora ولا معتمدة من قِبلها.