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

المتطلبات

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

PHP: 8.0 أو أحدث مع إضافة cURL.

حساب DrEnvio (للأسعار الفورية فقط): تأتي أسعار Estafeta الفورية من DrEnvio، وهي شريك Estafeta في المكسيك. أنشئ حسابًا على drenvio.com، وفعّل Estafeta، واضبط عنوان الاستلام هناك، وانسخ مفتاح API من لوحة DrEnvio. وهو المفتاح نفسه الذي تستخدمه الإضافة الرسمية لـ DrEnvio. وإذا كنت تستخدم أسعارك الخاصة فقط، فلست بحاجة إلى حساب DrEnvio.

المنتجات: تحتاج المنتجات إلى وزن لتُحسب الأسعار الفورية.

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

التثبيت

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

OpenCart 3

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

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

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

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

5. أدخل DrEnvio API key ويمكنك اختياريًا إدخال Origin postcode. إذا لم تكن عملتك الافتراضية MXN، فأدخل MXN exchange rate. اضبط سعرًا لدولة MX أو Fallback cost إذا كان يجب أن تظل طريقة الشحن ظاهرة عندما لا تُرجع DrEnvio أي سعر. فعّل Enable/Disable وانقر على Save.

OpenCart 4

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

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

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

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

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

الإعداد

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

وتعرض الإضافة في أعلى الصفحة تحذيرات: عدم وجود مفتاح DrEnvio API، أو أن العملة الافتراضية ليست MXN ولا يوجد سعر صرف، أو عدم وجود سعر لدولة MX ولا تكلفة احتياطية (وعندها تُخفى طريقة الشحن عند عدم توفر سعر فوري، أو لا تظهر أبدًا بدون مفتاح API)، أو عدم وجود فئة وزن بوحدة kg (وعندها تُحوَّل أوزان المنتجات حسب اسم الوحدة في فئة الوزن الخاصة بها، وتُعامل الوحدات غير المعروفة على أنها kg؛ أضف فئة kg في System > Localisation > Weight Classes). وتقبل حقول الأرقام النقطة العشرية أو الفاصلة. وعند الحفظ، يُبلَّغ عن أي قيمة خاطئة، وتُمسح أو تُعاد إلى قيمتها الافتراضية كما هو موضح في كل حقل، ويعرض النموذج القيمة المحفوظة، وتُحفظ الإعدادات الأخرى على أي حال (The other settings were saved.).

عام

تُعرض طريقة الشحن للمنطقة الجغرافية أدناه (أو لكل عنوان)، أو للدول الموجودة في Availability without shipping zones.

Enable/Disable: يفعّل شحن Estafeta أو يعطّله. الافتراضي: معطّل.

Name: اسم طريقة الشحن الذي يراه العميل عند الدفع. الافتراضي: Estafeta. مطلوب: من 1 إلى 64 حرفًا، دون الرموز < > ; = # { }. ويُبلَّغ عن الاسم غير الصالح ويُحتفظ بالاسم السابق.

Tax class: فئة الضريبة التي تُضاف إلى تكلفة الشحن، أو No tax (الافتراضي). ويعتمد ما إذا كانت أسعار DrEnvio تتضمن IVA على حساب DrEnvio الخاص بك. وإذا كانت تتضمنها بالفعل، فاختر No tax.

Geo zone: تقديم Estafeta فقط للعناوين داخل هذه المنطقة الجغرافية، مثلًا منطقة "Mexico". وAll zones (الافتراضي) يعني بلا حد. وتُدار المناطق الجغرافية في System > Localisation > Geo Zones. ولا تُستخدم عندما يكون Ignore shipping zones مفعّلًا.

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

الأسعار الفورية (واجهة DrEnvio API)

يوضح هذا القسم مكان الحصول على المفتاح. وتُعرض أرخص خدمة Estafeta للعنوان. وبدون مفتاح تُستخدم الأسعار الواردة في Prices without a live rate.

DrEnvio API key: مفتاح API من لوحة DrEnvio الخاصة بك. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Remove the saved API key: يظهر فقط عند وجود مفتاح محفوظ. فعّله واحفظ لحذف المفتاح. وبعدها لا تُستخدم إلا Country prices وFallback cost. والمفتاح المُدخل في الحقل أعلاه يحل محل المفتاح المحفوظ.

Origin country: رمز الدولة المكوَّن من حرفين لعنوان الاستلام. الافتراضي: MX. يُرسل فقط مع الرمز البريدي للمصدر. ويُبلَّغ عن الرمز غير الصالح ويُعاد إلى MX.

Origin postcode: الرمز البريدي المكوَّن من 5 أرقام لعنوان الاستلام. اتركه فارغًا لاستخدام عنوان المصدر المحفوظ في حساب DrEnvio. والرمز البريدي الذي لا يتكون من 5 أرقام يُمسح ويُبلَّغ عنه عند الحفظ.

MXN exchange rate: تُصدر DrEnvio عروض الأسعار بالبيزو المكسيكي. ولا يُحتاج إليه إلا إذا لم تكن عملتك الافتراضية MXN: قيمة 1 MXN بعملتك الافتراضية، مثل 0.05. وبدونه لا تُستخدم الأسعار الفورية. ويجب أن يكون أكبر من 0. وإذا كانت عملة المتجر MXN فاتركه فارغًا.

أسعار بدون سعر فوري

تُستخدم عندما لا يوجد مفتاح API أو عندما لا تُرجع DrEnvio أي سعر Estafeta (واجهة API غير متاحة، أو رمز بريدي غير معروف، أو لم يُدخل الرمز البريدي بعد). والأسعار بالعملة الافتراضية للمتجر، بدون الضريبة.

Country prices: دولة وجهة واحدة في كل سطر، بالصيغة CC:PRICE، مثل MX:150. استخدم النقطة العشرية أو الفاصلة، دون فاصل آلاف. وتُتجاهل الأجزاء ذات الصيغة المختلفة ويُبلَّغ عنها عند الحفظ.

Fallback cost: السعر عندما لا يتوفر سعر فوري ولا سعر لدولة الوجهة. اتركه فارغًا لإخفاء طريقة الشحن؛ والقيمة 0 تعني شحنًا مجانيًا.

Calculation type: Per order (الافتراضي) يحصّل السعر مرة واحدة. أما Per item (price x number of items) فيضربه في عدد العناصر في السلة. ويُطبَّق هذا على Country prices وFallback cost. والسعر الفوري من DrEnvio هو دائمًا سعر الطرد كاملًا.

الشروط

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

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

Min weight (kg): الحد الأدنى لوزن السلة حتى تظهر طريقة الشحن. والقيمة 0 تعني بلا حد (الافتراضي).

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

إذا كان Min weight أكبر من Max weight، فسيظهر خطأ عند الحفظ ويبقى الوزنان دون تغيير. وتُحوَّل أوزان المنتجات إلى kg حسب فئة الوزن لكل منتج.

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

Ignore shipping zones: تقديم طريقة الشحن للدول الواردة أدناه دون التحقق من المنطقة الجغرافية. الافتراضي: معطّل.

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

متقدم

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

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

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

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

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

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

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

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر Estafeta. وإذا كانت Geo zone معيّنة (وIgnore shipping zones معطّل) وكان العنوان خارجها، فلن يُعرض Estafeta. ولا تُحتسب إلا المنتجات التي تكون Requires Shipping فيها على Yes: فالمنتجات الأخرى لا تضيف وزنًا ولا تدخل في المجموع الفرعي. والمجموع الفرعي هو سعر هذه المنتجات بعد خصم القسيمة وقبل الضريبة؛ ولا تُحتسب بطاقات الهدايا ونقاط المكافآت ورصيد المتجر. ثم تتحقق الإضافة من الشروط: قائمة Countries (عندما يكون Ignore shipping zones مفعّلًا)، ووزن السلة، والحد الأدنى للمجموع الفرعي. وإذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى DrEnvio.

وفي الحالات الأخرى ترسل الإضافة إلى DrEnvio دولة الوجهة والرمز البريدي، ووزن السلة، وعدد العناصر، والمجموع الفرعي بالـ MXN، بالإضافة إلى الرمز البريدي للمصدر إن كنت قد حددته. ويجب أن تتكون الرموز البريدية المكسيكية من 5 أرقام؛ ولا يُرسل أي طلب حتى يدخل العميل عنوان توصيل بمثل هذا الرمز. وتُرجع DrEnvio عروض أسعار جميع شركات الشحن في حسابك. وتستخدم الإضافة عروض أسعار Estafeta فقط، وتتجاهل الأسعار الصفرية، وتختار الأرخص، وتحوّله إلى العملة الافتراضية لمتجرك. ويُقرَّب السعر إلى الخانات العشرية لتلك العملة ويُعرض للعميل بعملته، مع ضريبة Tax class المختارة.

تُخزَّن كل استجابة مؤقتًا لمدة ساعة واحدة. ويُتذكَّر الطلب الفاشل أو المسار الذي لا يملك سعر Estafeta لمدة 5 دقائق، حتى لا يُبطئ أي خادم API بطيء أو معطّل كل تحديث للدفع. ومهلة API هي 12 ثانية. وفي هذه الحالات لا يرى العميل أي خطأ: يُستخدم سعر الدولة أو التكلفة الاحتياطية، أو تُخفى طريقة الشحن إذا لم يوجد أي منهما. ويُكتب السبب في السجل.

لا يرى العميل سوى اسم طريقة الشحن والسعر. وتحسب الإضافة الأسعار فقط؛ فهي لا تنشئ شحنات، ولا تطبع الملصقات (guías)، ولا تتتبع الطرود؛ أنشئ الشحنة في حسابك على DrEnvio أو Estafeta. ولا يستطيع العميل اختيار خدمة Estafeta محددة أو مكتب Estafeta، ولا تُحدَّث أسعار الصرف تلقائيًا.

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

الطلبات

عندما يُنفَّذ طلب بـ Estafeta، تحفظ الإضافة السعر الذي عُرض على العميل دون طلب جديد إلى DrEnvio. ولا تغيّر التعديلات اللاحقة على الطلب في لوحة الإدارة هذا السعر. وفي OpenCart 4 يحتفظ الدفع بطلب واحد ويحدّثه في كل مرة يؤكد فيها العميل مجددًا، فيُستبدل السعر المحفوظ بأحدث سعر في الدفع. وإذا انتقل العميل إلى طريقة شحن أخرى، فلن تظهر اللوحة لذلك الطلب.

تعرض صفحة الطلب في Sales > Orders لوحة Estafeta:

Estafeta service: خدمة Estafeta في عرض سعر DrEnvio ومدة تسليمها. وتظهر فقط للأسعار الفورية.

Price source: Live DrEnvio rate، أو Country price (no live rate)، أو Fallback cost (no live rate)، أو Free shipping threshold.

Shipping cost: سعر الشحن المحسوب عند الدفع بالعملة الافتراضية لمتجرك، بدون الضريبة.

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

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

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

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

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

لا يظهر Estafeta عند الدفع: تحقق من أن الترخيص نشط وأن Enable/Disable مفعّل. تحقق من Geo zone، أو من Ignore shipping zones وCountries. تحقق من التحذيرات في أعلى صفحة الإضافة، وحدود الوزن، وMinimum subtotal. وبدون مفتاح API، أو عندما لا تُرجع DrEnvio سعر Estafeta، تحتاج طريقة الشحن إلى سعر لدولة الوجهة أو تكلفة احتياطية. تحقق من أن المنتجات لديها Requires Shipping على Yes.

لا تظهر الأسعار الفورية: فعّل Debug log، وأعد تحميل صفحة الدفع، وانظر إلى الحقل Log في صفحة الإضافة. يعرض السبب: عدم وجود مفتاح API، أو عدم وجود سعر صرف لمتجر عملته الافتراضية ليست MXN، أو رمز بريدي مفقود أو غير صالح، أو رفض مفتاح API (HTTP 401 أو 403 من DrEnvio، تحقق من مفتاح API)، أو عدم وجود سعر Estafeta لهذا المسار (يسرد السجل شركات الشحن التي أرجعتها DrEnvio)، أو سعر بعملة غير MXN.

هل يتضمن السعر IVA؟ يعتمد ذلك على حساب DrEnvio الخاص بك. وإذا كانت أسعار DrEnvio تتضمن IVA بالفعل، فاضبط Tax class على No tax.

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

لا توجد لوحة Estafeta في صفحة الطلب: تظهر اللوحة فقط للطلبات التي نُفِّذت بـ Estafeta أثناء تثبيت الإضافة وتفعيلها.

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

للمطورين: يمكن استبدال عنوان واجهة DrEnvio API بالإعداد vfd_est_api_url (للاختبارات)؛ وليس له حقل في صفحة الإعدادات.

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

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

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

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