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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

Econt: لا يلزم عقد Econt أو مفتاح API. قائمة المكاتب هي قائمة عامة تابعة لـ Econt. لا يُرسل إلى Econt سوى رمز الدولة، ولا تُرسل أي بيانات للعملاء. أدخل اسم مستخدم وكلمة مرور e-Econt فقط إذا طلبت Econt تفويض موقعك. وتُشرح طريقة تسجيل الدخول إلى e-Econt في صفحة المطورين لدى Econt (econt.com/developers).

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

التثبيت

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

2. انقر على Activate.

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

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

5. حدد الأسعار لكل دولة وراجع الخيارات الأخرى (انظر قسم الإعداد). انقر على Load offices from Econt now لاختبار الاتصال.

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

الإعداد

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

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

تعرض الإضافة في أعلى الصفحة تحذيرات: واجهة API التجريبية مفعّلة، أو لم يُحدَّد سعر لبلغاريا أو رومانيا (فلا تظهر الطريقة إطلاقًا في هذه الحالة)، أو فشل آخر طلب للمكاتب لدولة ما. تقبل حقول الأرقام الفاصلة العشرية، مثل 5,99. تُتجاهل القيمة التي ليست رقمًا، ويُبلَّغ عنها عند الحفظ.

عام

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

Name: اسم طريقة الشحن الذي يظهر في صفحة الدفع. يحل محله Title المحدد في المنطقة. الافتراضي: Econt Express.

Tax status: تُضيف Taxable ضريبة WooCommerce إلى تكلفة الشحن، بينما لا تضيفها None. الافتراضي: Taxable.

قائمة مكاتب Econt

تُحمَّل المكاتب وEcontomat من واجهة Econt API وتُخزَّن مؤقتًا لمدة 24 ساعة.

Demo API: استخدام واجهة Econt التجريبية مع بيانات اختبار. أبقها متوقفة في المتجر الفعلي. تختلف معرفات المكاتب التجريبية عن المكاتب الحقيقية. وفي الوضع التجريبي، إذا لم يُحدَّد تسجيل دخول، يُستخدم حساب الاختبار العام لدى Econt.

Econt username: اختياري. تسجيل دخول e-Econt الخاص بك لتفويض HTTP Basic.

Econt password: اختياري. يُخزَّن في قاعدة بيانات WordPress ولا يُكتب في السجل أبدًا.

Office list: يعرض عدد المكاتب المخزَّنة مؤقتًا لكل دولة ووقت تحميلها. يعيد زر Load offices from Econt now تحميل القوائم فورًا ويعرض النتيجة. إذا فشل التحميل، تبقى المكاتب من آخر تحميل ناجح. وحتى بدون هذا الزر، تُحمَّل القائمة تلقائيًا عند أول صفحة دفع. وعند تغيير Demo API أو اسم المستخدم أو كلمة المرور، تُمسح القوائم المخزَّنة مؤقتًا.

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

Show: النقاط التي يمكن للعميل اختيارها.

City order: يعرض المدن الأكبر أولًا (صوفيا وبلوفديف وفارنا وبوخارست وغيرها). وعند إيقافه، تُرتَّب المدن أبجديًا. الافتراضي: مفعّل.

City list width: عرض قائمة المدن بصيغة CSS في صفحة الدفع الكلاسيكية، مثل 100% أو 300px. الافتراضي: 100%.

Office list width: عرض قائمة المكاتب بصيغة CSS في صفحة الدفع الكلاسيكية، مثل 100% أو 400px. الافتراضي: 100%.

الأسعار (بعملة متجرك)

لا تطلب الإضافة من Econt أسعارًا مباشرة. تستخدم بلغاريا اليورو منذ 1 يناير 2026، لذلك يُدخل المتجر البلغاري عادةً أسعارًا باليورو (EUR).

Price per country: دولة واحدة في كل سطر (أو مفصولة بفاصلة): رمز الدولة، ثم نقطتان، ثم السعر، مثل BG:5.99 وRO:8.99 (هذه القيم الافتراضية). الفاصلة العشرية مقبولة أيضًا: BG:5,99. السعر 0 يعني توصيلًا مجانيًا. تُتجاهل الإدخالات بصيغة أخرى وتُدرج في رسالة خطأ عند الحفظ.

Calculation: تفرض Per order السعر مرة واحدة. أما Per item (price x quantity) فتضربه في عدد العناصر القابلة للشحن في السلة.

Price for other countries: يُستخدم لدولة من Econt (بلغاريا أو رومانيا) غير مدرجة أعلاه. القيمة الفارغة أو 0 تُخفي الطريقة في تلك الدولة.

الشروط

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

Minimum subtotal: تعرض الطريقة فقط عندما يكون المجموع الفرعي للسلة مساويًا لهذا المبلغ على الأقل. اتركه فارغًا لعرضها دائمًا.

Minimum weight (kg): يُخفي الطريقة عن السلال الأخف. تُحوَّل أوزان المنتجات من وحدة متجرك إلى كيلوغرام. اتركه فارغًا إذا لم يكن هناك حد.

Maximum weight (kg): يُخفي الطريقة عن السلال الأثقل. اتركه فارغًا إذا لم يكن هناك حد.

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

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

Ignore zones: يعرض Econt أيضًا للدول المذكورة أدناه عندما لا تضيفه أي منطقة. وتستمر المناطق التي تحتوي على الطريقة في العمل كالمعتاد.

Countries: بلغاريا و/أو رومانيا. يُستخدم فقط مع Ignore zones. اتركه فارغًا لجميع دول Econt التي يشحن إليها متجرك.

متقدم

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

Remove data on uninstall: عند التفعيل، يؤدي حذف الإضافة إلى إزالة إعدادات Econt وطرق الشحن في المناطق. ولا تحذف إلغاء تفعيل الإضافة الإعدادات أبدًا. وتبقى المكاتب المحفوظة في الطلبات دائمًا.

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

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

عندما يختار العميل Econt، تظهر قائمتان أسفل الطريقة: City وOffice / Econtomat. تُحمَّل قائمة المكاتب مرة واحدة في كل صفحة. وتُعلَّم Econtomat في القائمة. ويُحفظ اختيار العميل طوال الجلسة. وإذا تعذر تحميل قائمة المكاتب، يرى العميل رسالة تطلب منه المحاولة مرة أخرى بعد بضع دقائق أو اختيار طريقة شحن أخرى.

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

تُخزَّن قائمة المكاتب مؤقتًا لمدة 24 ساعة. وإذا تعذر الوصول إلى Econt، تُستخدم آخر قائمة ناجحة، ولا يُطلب من Econt مرة أخرى لمدة 10 دقائق. ومهلة انتظار API هي 15 ثانية.

تستخدم الإضافة الأسعار الثابتة فقط. فهي لا تطلب من Econt أسعارًا مباشرة، ولا تُنشئ بوليصات أو ملصقات، ولا تستدعي مندوبين، ولا تتتبع الطرود، ولا تتعامل مع الدفع عند الاستلام، ولا توصل إلى عنوان. ولا تتوفر قائمة مكاتب إلا لبلغاريا ورومانيا.

نقاط الاستلام

يُحفظ المكتب المختار مع الطلب: المدينة، واسم المكتب وعنوانه، ورمز مكتب Econt. استخدم رمز المكتب عند إنشاء الشحنة في e-Econt.

شاشة الطلب في الإدارة: يظهر المكتب ورمزه أسفل عنوان الشحن. انقر على Change لتحميل قائمة المكاتب واختيار مدينة ومكتب آخرين. يُحفظ التغيير فورًا، وتسجل ملاحظة الطلب المكتب القديم والجديد.

العميل: يظهر المكتب في صفحة الطلب الخاصة بالعميل وفي صفحة الشكر، وفي رسائل البريد الإلكتروني للطلبات (HTML ونص عادي).

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

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

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

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

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

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

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

لا يظهر Econt في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن دولة التوصيل بلغاريا أو رومانيا، وأن الطريقة مضافة إلى منطقة تلك الدولة (أو أن Ignore zones مفعّل وأن الدولة مسموح بها). تحقق من تحديد سعر للدولة، ومن حدود الوزن، وMinimum subtotal، وHide for shipping classes. راجع سطر Office list في الإعدادات: تُخفى الطريقة ما دامت قائمة المكاتب غير متاحة للدولة.

لا تُحمَّل قائمة المكاتب: انقر على Load offices from Econt now واقرأ النتيجة، أو راجع التحذير في أعلى صفحة الإعدادات. تُكتب الأخطاء في WooCommerce > Status > Logs، والمصدر vfd-econt. إذا طلبت Econt تفويضًا لموقعك، فأدخل Econt username وEcont password.

يرى العملاء مكاتب اختبار: Demo API مفعّل. أوقفه في المتجر الفعلي.

بأي عملة الأسعار؟ بعملة متجرك.

دول أخرى: يمكن للمطورين إضافة دول باستخدام المرشح vfd_ecn_countries (رمز من حرفين مقابل رمز من ثلاثة أحرف).

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

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

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

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