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

المتطلبات

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

PHP: 8.0 أو أحدث.

البلدان: يجب تفعيل بلغاريا ورومانيا في System > Localisation > Countries.

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

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

التثبيت

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

OpenCart 3

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

2. انتقل إلى Extensions > Extensions واختر نوع الإضافات Shipping. ابحث عن VibeFox Econt وانقر على Install (الزر الأخضر +).

3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات.

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

5. حدد الأسعار لكل بلد وراجع الخيارات الأخرى (انظر Configuration)، ثم فعّل Enable/Disable وانقر على Save. انقر على Load offices from Econt now لاختبار الاتصال.

OpenCart 4

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

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

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

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

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

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Shipping > VibeFox Econt > Edit. تظهر الأقسام في القائمة على اليسار. يحفظ زر Save واحد الصفحة كاملة من دون إعادة تحميلها. لا يستطيع حفظ الإعدادات أو تحميل المكاتب أو مسح السجل إلا مستخدمو الإدارة الذين لديهم صلاحية التعديل لهذه الإضافة.

تعرض الإضافة في أعلى الصفحة تحذيرات: واجهة API التجريبية مفعّلة، أو لم يُحدَّد سعر لبلغاريا أو رومانيا (وعندئذ لا تظهر الطريقة أبدًا)، أو فشل آخر طلب للمكاتب لبلد ما، أو لا توجد لدى متجرك فئة وزن وحدتها kg (عندئذ تُقرأ أوزان المنتجات حسب اسم وحدتها: kg أو g أو lb أو oz). تقبل حقول الأرقام الفاصلة العشرية، على سبيل المثال 5,99. إذا احتوى حقل رقمي على ما ليس رقمًا أو رقمًا سالبًا، أو إذا كانت قيمة Minimum weight (kg) أكبر من Maximum weight (kg)، فستحدد رسالة الخطأ الحقل، ولن يُحفَظ شيء. ويحدث الأمر نفسه مع Name فارغ أو يزيد طوله على 64 حرفًا، أو مع Sort order ليس عددًا صحيحًا، أو مع فئة ضريبة أو منطقة جغرافية غير معروفة.

عام

Enable/Disable: يعرض توصيل Econt عند الدفع أو يخفيه. الافتراضي: متوقف.

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

Sort order: موضع الطريقة بين طرق الشحن عند الدفع. عدد صحيح.

Tax class: فئة الضريبة على سعر الشحن، أو --- None --- (الافتراضي). تضيف OpenCart هذه الضريبة فوق الأسعار أدناه. مع --- None --- تكون الأسعار نهائية.

قائمة مكاتب 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: فعّله ثم انقر على Save لحذف كلمة المرور المحفوظة.

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. تُتجاهل المدخلات بصيغة أخرى وتُدرج في تحذير عند الحفظ. وتُحفظ بقية المدخلات.

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

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

الشروط

المجموع الفرعي للسلة يعني المنتجات التي تحتاج إلى شحن، بعد تطبيق القسيمة وقبل الضريبة.

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

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

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

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

التوفر

تُوصّل Econt إلى بلغاريا ورومانيا فقط. وعادةً تحدد المنطقة الجغرافية المكان الذي تُعرض فيه الطريقة؛ ومع Ignore geo zone تحدد البلدان المختارة ذلك بدلًا منها.

Geo zone: تقديم Econt فقط للعناوين داخل هذه المنطقة الجغرافية. يعني All Zones (الافتراضي) في كل مكان في بلغاريا ورومانيا. تُدار المناطق الجغرافية في System > Localisation > Geo Zones. لا تُستخدم المنطقة الجغرافية مع Ignore geo zone.

Ignore geo zone: لا تُفحص المنطقة الجغرافية. تُقدَّم Econt في البلدان المذكورة أدناه، سواء كان العنوان داخل المنطقة الجغرافية أو لم يكن.

Countries: بلغاريا و/أو رومانيا. يُستخدم فقط مع Ignore geo zone. وإذا لم يُختر أي بلد فالمقصود جميع بلدان Econt.

متقدم

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

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

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

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

Export: انقر على Download JSON لحفظ الإعدادات كملف JSON. لا تُصدَّر كلمة المرور.

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

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

تُعرض الطريقة لبلغاريا ورومانيا فقط. عندما تعرض OpenCart طرق الشحن، تطلب من الإضافة سعر Econt. ومع Ignore geo zone لا تُفحص المنطقة الجغرافية، وتُعرض الطريقة فقط للبلدان المختارة في Countries (إذا لم يُختر شيء = بلغاريا ورومانيا). وإلا، إذا كانت Geo zone محددة، فيجب أن يكون العنوان داخلها. لا تُحتسب إلا المنتجات التي تكون فيها Requires Shipping على Yes: أما المنتجات الأخرى فلا تضيف وزنًا ولا تدخل في المجموع الفرعي. تتحقق الإضافة من حدود الوزن ومن الحد الأدنى للمجموع الفرعي، ثم تأخذ سعر البلد. إذا بلغ المجموع الفرعي للسلة قيمة Free shipping from يصبح السعر 0. وإذا لم تتوفر قائمة مكاتب للبلد تُخفى الطريقة، لأن التوصيل يتم دائمًا إلى مكتب. يُحسب السعر بالعملة الافتراضية لمتجرك، ويُعرض للعميل بعملته مع ضريبة Tax class المختارة.

عندما يختار العميل Econt، تظهر تحت الطريقة قائمتان: City وOffice / Econtomat. تُحمَّل قائمة المكاتب مرة واحدة لكل صفحة، وفقط عندما تكون Econt مختارة. وتظهر علامة على الخزانات في القائمة. يُحفظ الاختيار فورًا. وإذا تعذر تحميل قائمة المكاتب، يرى العميل الرسالة 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، لا من المتصفح.

في OpenCart 4 ينقر العميل على Choose في كتلة طريقة الشحن في صفحة الدفع، ويختار Econt في النافذة Shipping method options. تظهر القائمتان City وOffice / Econtomat في هذه النافذة تحت الطريقة وتعملان كما هو موضح أعلاه. ولا يتجاوز زر Continue في النافذة من دون مكتب صالح، وتظهر الرسائل نفسها.

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

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

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

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

العميل: يُضاف المكتب إلى طريقة شحن الطلب، على سبيل المثال Econt Express - Econt office / Econtomat: city, office (address) (بحد أقصى 128 حرفًا؛ في OpenCart 4 لا يُختصر النص). وبهذا يظهر في سجل طلبات العميل، وفي رسائل الطلب الإلكترونية، وفي الفاتورة، وفي الطلب داخل الإدارة. يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه في كل مرة يؤكد فيها العميل مجددًا، ويُحدَّث مكتب الطلب معه.

صفحة الطلب في الإدارة: في Sales > Orders، تعرض اللوحة Econt office / Econtomat أعلى السجل المكتب ورمزه، حتى لو أُوقفت الطريقة لاحقًا. تحت Change اختر مدينة ومكتبًا آخرين في بلد الطلب، ثم انقر على Save. تعرض اللوحة Saved.، ويُحدَّث نص طريقة شحن الطلب، وتسجل ملاحظة في سجل الطلب (لا تُرسل إلى العميل) المكتب القديم والجديد. وإذا نقرت على Save من دون اختيار مكتب، تقول اللوحة Select a city and an office first - nothing was changed. ويُرفض المكتب الذي ليس في قائمة بلد الطلب برسالة The selected Econt office is not available for the shipping country - nothing was changed. ويستطيع أي مستخدم إدارة لديه صلاحية تعديل الطلبات تغيير المكتب؛ ولا يلزم الوصول إلى إعدادات الإضافة. وإذا تعذر تحميل قائمة المكاتب تعرض اللوحة Econt offices cannot be loaded right now. ويعرض الطلب الذي قُدِّم من دون مكتب الرسالة No Econt office is saved for this order.، ويوجد لذلك خطأ في السجل.

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

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

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

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

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

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

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

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

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

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

تُضاف الضريبة فوق السعر: فئة ضريبة مختارة. اضبط Tax class على --- None --- إذا كانت أسعارك تتضمن ضريبة القيمة المضافة بالفعل.

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

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

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

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

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