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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل مفتاح API الخاص بـ DrEnvio، ويمكنك اختياريًا إدخال الرمز البريدي للمصدر. إذا لم تكن عملة متجرك MXN، فأدخل MXN exchange rate. وإذا أردت أن تبقى الطريقة ظاهرة عندما لا يكون لدى DrEnvio سعر، فحدّد سعرًا لدولة MX أو تكلفة احتياطية.

6. أضف VibeFox Estafeta إلى منطقة المكسيك في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

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

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

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

عام

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

Name: اسم طريقة الشحن الذي يراه العميل عند الدفع. الافتراضي: Estafeta.

Tax status: يتيح Taxable لـ WooCommerce إضافة الضريبة إلى تكلفة الشحن، بينما لا يفعل None ذلك. وما إذا كانت أسعار DrEnvio تتضمن IVA يعتمد على حسابك في DrEnvio. وإذا كانت تتضمنه بالفعل، فاختر None. الافتراضي: Taxable.

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

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

DrEnvio API key: مفتاح API من لوحة DrEnvio الخاصة بك.

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

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

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

Excluded shipping classes: إذا كان أي عنصر في السلة ينتمي إلى إحدى فئات شحن WooCommerce هذه، تُخفى الطريقة.

تُحوَّل أوزان المنتجات من وحدة متجرك إلى كيلوغرام.

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

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

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

متقدم

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

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

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

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

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

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

تعمل الطريقة على الدفع الكلاسيكي وعلى كتلتي Cart وCheckout. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

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

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

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

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

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

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

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

الأسعار الفورية لا تظهر: فعّل Debug log، ثم أعد تحميل صفحة الدفع وافتح WooCommerce > Status > Logs، بالمصدر vfd-estafeta. يُظهر السجل السبب: لا يوجد مفتاح API، أو لا يوجد سعر صرف لمتجر ليس بعملة MXN، أو الرمز البريدي مفقود أو غير صالح، أو رُفض مفتاح API (HTTP 401 أو 403)، أو لا يوجد سعر لـ Estafeta لهذا المسار.

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

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

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

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

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

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