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

المتطلبات

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

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

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

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

التثبيت

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

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

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

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

عند التثبيت، تُنشئ الوحدة شركة الشحن Econt Express بنص مدة التوصيل Delivery to an Econt office or Econtomat. تُعيَّن شركة الشحن لمناطق بلغاريا ورومانيا ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Econt > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. يُطبَّق السعر والشروط على كل مناطق شركة الشحن.

في أعلى الصفحة تعرض الوحدة تحذيرات: لم تُعثر على شركة الشحن Econt، وواجهة API التجريبية مفعّلة، ولا يوجد سعر محدد لبلغاريا أو رومانيا (عندئذ لا تظهر شركة الشحن أبدًا)، أو فشل آخر طلب للمكاتب لدولة ما، أو أن وحدة الوزن في متجرك غير معروفة للوحدة (عندئذ تُعامَل الأوزان بالكيلوغرام؛ اضبط الوحدة في International > Localization، ضمن Local units). تقبل حقول الأرقام الفاصلة العشرية، مثل 5,99. إذا احتوى حقل رقمي على شيء ليس رقمًا أو رقمًا سالبًا، أو إذا كان Minimum weight (kg) أكبر من Maximum weight (kg)، فإن رسالة الخطأ تسمّي الحقل ولا يُحفظ أي شيء.

عام

Enable/Disable: يفعّل توصيل Econt أو يعطّله. وهو المفتاح نفسه الذي يمثل حالة شركة الشحن في Shipping > Carriers.

Name: اسم شركة الشحن الذي يظهر في السلة وفي الدفع. الافتراضي: Econt Express. حقل إلزامي، بحد أقصى 64 حرفًا.

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

قائمة مكاتب Econt

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

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

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

Econt password: اختياري. يُحفظ في قاعدة بيانات المتجر ولا يُكتب في السجل أبدًا. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها. لحذف كلمة المرور المحفوظة، ضع علامة على Remove the saved password ثم احفظ.

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

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): أخفِ شركة الشحن عن السلال الأثقل. اتركه فارغًا لعدم وجود حد.

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

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

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

متقدم

Debug log: يكتب رسائل التصحيح في logs/vfd_ecn_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل أخطاء API دائمًا. لا تُكتب كلمات المرور ولا بيانات العملاء.

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

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

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

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

عندما يختار العميل Econt تظهر قائمتان أسفل شركة الشحن: City وOffice / Econtomat. تُحمَّل قائمة المكاتب مرة واحدة لكل صفحة، وفقط عندما يكون Econt مختارًا. تُعلَّم Econtomat في القائمة. يُحفظ الاختيار في السلة فورًا. إذا تعذر تحميل قائمة المكاتب، يرى العميل Econt offices cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

عندما ينقر العميل على Continue في خطوة الشحن، تتحقق الوحدة على الخادم من أن مكتبًا قد اختير وأنه موجود في قائمة Econt لدولة التوصيل (مُصفّاة حسب Show). بدون مكتب يرى العميل Please select an Econt office or Econtomat. يُرفض المكتب غير الموجود في القائمة برسالة The selected Econt office is not available for the shipping country. Please select it again. يُؤخذ اسم المكتب دائمًا من قائمة Econt، لا من المتصفح. يعمل المنتقي مع القالب Classic ومع Hummingbird.

تُخزَّن قائمة المكاتب مؤقتًا لمدة 24 ساعة، بشكل منفصل لواجهة API الحية وواجهة API التجريبية. إذا تعذر الوصول إلى Econt تُستخدم آخر قائمة ناجحة، ولا يُسأل Econt مرة أخرى لمدة 10 دقائق. مهلة API هي 15 ثانية. تأتي قائمة المكاتب من https://ee.econt.com/services/ (الحية) أو https://demo.econt.com/ee/services/ (التجريبية).

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

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

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

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

صفحة الطلب في لوحة الإدارة: يعرض مربع Econt office / Econtomat المكتب وOffice code. ضمن Change اختر مدينة ومكتبًا آخرين في دولة الطلب وانقر على Save. يُحفظ التغيير فورًا وتسجّل رسالة خاصة بالطلب المكتب القديم والجديد. إذا نقرت على Save دون اختيار مكتب يقول المربع Select a city and an office first - nothing was changed. يستطيع أي موظف يحق له تعديل الطلبات تغيير المكتب؛ ولا يلزم الوصول إلى صفحة الوحدة. إذا تعذر تحميل قائمة المكاتب يعرض المربع Econt offices cannot be loaded right now.

عدة طلبات من سلة واحدة: يتبع المكتب الطلب الأول. لا يحصل طلب آخر قُدّم من السلة نفسها على مكتب: تُكتب رسالة خطأ في السجل، ويوضح مربعه أن مكتب هذه السلة يتبع طلبًا آخر. اتفق على المكتب مع العميل وأنشئ الشحنة يدويًا في e-Econt.

العميل: يظهر المكتب في صفحة الطلب الخاصة بالعميل وفي صفحة تأكيد الطلب، ويُضاف إلى اسم شركة الشحن في بريد تأكيد الطلب وفي بريد الطلب الجديد المرسل إلى المتجر.

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

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

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

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

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

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

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

قائمة المكاتب لا تُحمَّل: انقر على Load offices from Econt now واقرأ النتيجة، أو اقرأ التحذير أعلى صفحة الإعدادات. تُكتب الأخطاء دائمًا في السجل؛ فعّل Debug log للحصول على تفاصيل أكثر وانظر إلى الحقل Log. إذا كانت Econt تشترط تفويضًا لمتجرك فاملأ Econt username وEcont password.

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

بأي عملة الأسعار؟ بعملة المتجر الافتراضية، دون الضريبة. يراها العملاء بعملة سلتهم.

تُضاف الضريبة فوق السعر: لشركة الشحن قاعدة ضريبية. اضبط Tax على No tax إذا كانت أسعارك تتضمن ضريبة القيمة المضافة بالفعل.

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

الإزالة

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

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