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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتداد cURL. ترفض الوحدة التثبيت على إصدارات PHP الأقدم أو دون cURL.

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

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

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

التثبيت

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

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

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

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

عند التثبيت، تُنشئ الوحدة شركة الشحن Estafeta بنص مدة التوصيل Estafeta courier (Mexico). تُعيَّن شركة الشحن لجميع المناطق ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: يأتي السعر دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Estafeta > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. كل حفظ يمسح أيضًا أسعار DrEnvio المخزنة مؤقتًا.

تعرض الوحدة في أعلى الصفحة تحذيرات: لا يوجد مفتاح API لـ DrEnvio؛ العملة الافتراضية ليست MXN بدون سعر صرف؛ لا يوجد سعر حسب البلد لـ MX ولا تكلفة احتياطية (عندئذٍ تُخفى شركة الشحن عندما لا يتوفر سعر فوري، أو لا تظهر أبدًا دون مفتاح API)؛ أو توجد وحدة وزن للمتجر لا تعرفها الوحدة (عندئذٍ تُعامَل أوزان المنتجات على أنها كجم؛ اضبط الوحدة في International > Localization، ضمن Local units). تقبل حقول الأرقام الفاصلة العشرية نقطة أو فاصلة. تُمسح القيمة التي ليست رقمًا صالحًا وتُبلَّغ عند الحفظ؛ وتُحفظ الإعدادات الأخرى كالمعتاد.

عام

تُضبط مناطق شركة الشحن ومجموعات العملاء وحدود الحجم في Shipping > Carriers. تُطبَّق هذه الإعدادات على كل منطقة.

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

Name: اسم شركة الشحن الذي يراه العميل عند الدفع. الافتراضي: Estafeta. حقل مطلوب. يُبلَّغ عن الاسم غير الصالح ويُحتفظ بالاسم السابق.

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

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

يُعرض أرخص خدمة Estafeta للعنوان. دون مفتاح تُستخدم الأسعار في القسم التالي.

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

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

Origin country: رمز الدولة المكوّن من حرفين لعنوان الاستلام. الافتراضي: MX. يُرسل فقط مع Origin postcode.

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

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

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

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

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: الحد الأدنى لوزن السلة بالكيلوغرام حتى تظهر شركة الشحن. القيمة 0 تعني دون حد.

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

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

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

Ignore shipping zones: يعرض شركة الشحن للدول المذكورة أدناه دون إعداد مناطق لها. طالما هذا الخيار مفعّل، تحصل شركة الشحن على كل المناطق، بما فيها المناطق التي تنشئها لاحقًا. وإيقافه يعيد لشركة الشحن مناطقها الخاصة.

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

متقدم

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

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

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

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر Estafeta. تُحتسب المنتجات المادية فقط: المنتجات الافتراضية لا تضيف وزنًا ولا تدخل في المجموع الفرعي. تتحقق الوحدة أولًا من الشروط: قائمة Countries (عندما يكون Ignore shipping zones مفعّلًا)، ووزن السلة، والحد الأدنى للمجموع الفرعي. إذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى DrEnvio.

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

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

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

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

الطلبات

عند تقديم طلب بشركة الشحن Estafeta، تحتفظ الوحدة بالسعر المحسوب لسلته. إعادة الحساب لاحقًا، مثلًا في صفحة الطلب في لوحة الإدارة، لا تغيّره.

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

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

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

Calculated price (excl. tax): سعر الشحن بالعملة الافتراضية لمتجرك.

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

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

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

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

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

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

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

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

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

تقول الصفحة إن شركة شحن Estafeta غير موجودة: حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإعادة إنشائها. ينطبق الأمر نفسه على الرسالة The settings were saved, but the carrier could not be updated.

لا توجد كتلة Estafeta في صفحة الطلب: تُعرض الكتلة فقط للطلبات التي قُدِّمت بشركة الشحن Estafeta أثناء تثبيت الوحدة. إلغاء التثبيت مع تفعيل Remove data on uninstall يحذف الخدمات المحفوظة.

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

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

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