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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Envioclick (للأسعار الفورية فقط): حساب Envioclick في المكسيك أو كولومبيا مع وصول إلى الواجهة البرمجية. يوجد مفتاح الواجهة في حسابك في Envioclick ضمن Mi cuenta (أعلى اليمين) > Información del API. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى حساب Envioclick.

User-Agent (المكسيك فقط): تشترط Envioclick Mexico قيمة User-Agent في كل طلب للواجهة البرمجية. اطلبها من دعم Envioclick (soporte.tecnico@envioclick.com).

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل مفتاح API، واختر دولة API، وأدخل User-Agent (المكسيك)، والرمز البريدي أو رمز DANE لنقطة الإرسال، وعنوان الإرسال. إذا لم تكن عملة متجرك MXN أو COP، فأدخل سعر الصرف.

6. اختياريًا: أضف أسعارًا ثابتة لكل دولة وتكلفة احتياطية.

7. أضف VibeFox Envioclick إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

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

Title (zone): الاسم الذي يراه العملاء لهذه المنطقة. اتركه فارغًا لاستخدام Method title العام.

عند تعيين مفتاح API، تعرض الإضافة تحذيرات أعلى الصفحة إذا تعذّر عمل الأسعار الفورية: لا يوجد سعر صرف لعملة متجر غير MXN أو COP، أو لا يوجد User-Agent للمكسيك، أو لا يوجد رمز بريدي أو رمز DANE للإرسال، أو لا يوجد عنوان إرسال لكولومبيا. وفي كل مرة تحفظ فيها الإعدادات تُمسح عروض الأسعار المخزنة مؤقتًا. وتقبل حقول الأرقام النقطة والفاصلة كفاصل عشري.

عام

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

Method title: اسم طريقة الشحن الظاهر في السلة وعند الدفع. ويمكن لأي منطقة تجاوزه. الافتراضي: Envioclick Shipping.

Carrier in the title: يُظهر شركة الشحن ومدة التسليم المقدّرة بجوار العنوان للأسعار الفورية، مثل «Envioclick Shipping (Estafeta Express, 1 day)». تُحفظ شركة الشحن في الطلب، وتظهر في رسائل البريد الإلكتروني للطلبات في كل الأحوال. الافتراضي: مفعّل.

Envioclick API (الأسعار الفورية)

اختياري. من دون مفتاح API تُستخدم الأسعار الثابتة فقط. وتُطلب الأسعار الفورية للوجهات داخل دولة API فقط. أما الشحن إلى دول أخرى فيستخدم الأسعار الثابتة.

API key: مفتاح API الخاص بك في Envioclick من Mi cuenta > Información del API.

API country: الدولة التي يتبعها حسابك في Envioclick.

User-Agent (Mexico): القيمة التي تصدرها دعم Envioclick (soporte.tecnico@envioclick.com). وهي مطلوبة للمكسيك؛ ومن دونها لا تُطلب أسعار فورية للمكسيك. وهي اختيارية لكولومبيا.

Carrier choice: Cheapest (الافتراضي) أو Fastest (then cheapest). تُرجع Envioclick عروض أسعار من عدة شركات شحن، ويحصل العميل على سعر واحد.

Branch pickup rates: يأخذ أيضًا أسعار «Ocurre» في الحسبان، وهي أسعار يستلم فيها العميل الطرد من فرع شركة الشحن. وعند الإيقاف لا تُستخدم إلا أسعار التوصيل إلى المنزل. ولا تُستخدم خدمات الدفع عند الاستلام (COD) أبدًا. الافتراضي: معطّل.

Currency conversion rate: تُحسب الأسعار في Envioclick بعملة MXN (المكسيك) أو COP (كولومبيا). إذا كانت عملة متجرك مختلفة، فأدخل قيمة 1 MXN أو 1 COP بعملة متجرك، مثل 0.05. ويُحوَّل قيمة الطرد المُعلنة بالطريقة نفسها. اتركه فارغًا إذا كانت عملة المتجر MXN أو COP. ومن دونه لا تُستخدم الأسعار الفورية بعملة أخرى.

الإرسال من

تُستخدم للأسعار الفورية. وتُملأ الحقول الفارغة من عنوان المتجر في WooCommerce > Settings > General إذا كان المتجر في دولة API.

Origin postcode / DANE code: المكسيك: الرمز البريدي المكوّن من 5 أرقام. كولومبيا: رمز DANE للبلدية المكوّن من 8 أرقام، مثل 11001000 لبوغوتا.

Origin address: الشارع ورقم عنوان الاستلام. مطلوب لكولومبيا، واختياري للمكسيك.

الأسعار الثابتة

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

Price per country: جدول بالدول والأسعار بعملة المتجر. انقر + Add country لإضافة صف، وعلامة × لحذف صف. ينطبق الصف * Default على كل الدول التي ليس لها صف خاص بها.

Fallback cost: يُستخدم عندما لا يوجد سعر فوري ولا يطابق أي صف في الجدول. اتركه فارغًا لإخفاء الطريقة في هذه الحالة.

Fixed price applies: Per order يحصّل السعر مرة واحدة. Per item (price × quantity) يضربه في عدد العناصر في السلة. أما الأسعار الفورية من Envioclick فهي دائمًا لكل شحنة.

الشروط

Minimum weight (kg): يُخفي الطريقة إذا كان وزن السلة أقل من هذا. 0 تعني بلا حد.

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

Minimum order amount: يُظهر الطريقة فقط إذا كان المجموع الفرعي للسلة (بعد الخصومات، قبل الضريبة) يساوي هذا المبلغ على الأقل. اتركه فارغًا لإظهارها دائمًا.

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

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. تتضمن أسعار Envioclick ضرائب شركات الشحن أصلًا، لذلك اختر None حتى لا تُفرض الضريبة على الشحن مرتين.

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

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

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

متقدم

Debug log: يسجّل حسابات الأسعار وأخطاء الواجهة البرمجية في WooCommerce > Status > Logs، بالمصدر vfd_envioclick. لا تُسجَّل مفاتيح API وعناوين العملاء. أوقفه عند الانتهاء.

Remove data on uninstall: عند التفعيل، يؤدي حذف الإضافة إلى إزالة كل إعدادات Envioclick وطرق المناطق وعروض الأسعار المخزنة مؤقتًا. ولا يحذف تعطيل الإضافة أي إعدادات أبدًا.

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

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

إذا كان مفتاح API معيّنًا وكانت الوجهة داخل دولة API، تطلب الإضافة عروض الأسعار من Envioclick. وفي المكسيك يُرسل الطلب بعد أن يُدخل العميل رمزًا بريديًا من 5 أرقام. وفي كولومبيا يُرسل الطلب بعد التعرف على القسم والبلدية (لا تهم الحروف الكبيرة والصغيرة ولا علامات التشكيل، و«Bogotá D.C.» مقبولة). وتختار الإضافة أرخص عرض توصيل إلى المنزل أو أسرعه، غير الدفع عند الاستلام، وتحوّله إلى عملة متجرك.

الطرد دائمًا صندوق واحد: الوزن الإجمالي محوَّل إلى كغ، وطول العنصر الأكبر وعرضه، مع ارتفاع يستوعب الحجم الإجمالي لكل العناصر. وتُحسب المنتجات التي لا أبعاد لها بمقاس 10 × 10 × 10 سم. وتُرسل السلة التي لا وزن لها بوزن 0.5 كغ. والقيمة المُعلنة هي المجموع الفرعي للسلة.

يُخزَّن كل عرض سعر مؤقتًا لمدة ساعة للمسار نفسه والطرد نفسه. ويُخزَّن الطلب الفاشل مؤقتًا لمدة 10 دقائق، حتى لا تُبطئ واجهة برمجية غير متاحة كل تحديث للدفع. ومهلة الواجهة البرمجية 10 ثوانٍ. وإذا أعادت Envioclick خطأ، أو لم توجد شركة شحن للمسار، فلن يرى العميل أي خطأ: تُستخدم السعر الثابت أو تُخفى الطريقة. ويُكتب السبب في سجل التصحيح.

تعمل الطريقة في الدفع الكلاسيكي وفي كتلتي السلة والدفع. وهي متوافقة مع High-Performance Order Storage (HPOS) في WooCommerce.

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

الطلبات

عند إجراء طلب بسعر فوري من Envioclick، تُحفظ شركة الشحن والخدمة في الطلب. وتعرض شاشة الطلب في لوحة الإدارة Envioclick carrier مع مدة التسليم المقدّرة أسفل عنوان الشحن. وتعرض صفحة طلب العميل ورسائل البريد الإلكتروني للطلب (HTML ونص عادي) Shipping carrier. ويُحفظ معرّف السعر الفوري من Envioclick للعرض مع سطر شحن الطلب كبيانات مخفية؛ ولا يظهر في شاشة الطلب. أنشئ البوليصة في حسابك في Envioclick.

الطلبات التي تمت بسعر ثابت لا تحمل شركة شحن.

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

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

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

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

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

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

لا يظهر Envioclick عند الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مفعّل والدولة مسموح بها). وراجع حدود الوزن وMinimum order amount وExcluded shipping classes. ومن دون سعر فوري تحتاج الطريقة إلى سعر ثابت للدولة، أو صف * Default، أو Fallback cost.

الأسعار الفورية لا تظهر: اقرأ التحذيرات أعلى صفحة الإعدادات، ثم فعّل Debug log، وأعد تحميل صفحة الدفع، وافتح WooCommerce > Status > Logs، بالمصدر vfd_envioclick. الأسباب الشائعة: لا يوجد سعر صرف (عملة المتجر ليست MXN أو COP)، ولا يوجد User-Agent (المكسيك)، ولا يوجد رمز بريدي أو رمز DANE للإرسال، أو لم يُدخل العميل بعد الرمز البريدي (المكسيك) أو المدينة (كولومبيا)، أو الوجهة خارج دولة API، أو لا توجد شركة شحن للمسار.

لماذا سعر صرف؟ تُرجع Envioclick الأسعار بالبيزو المكسيكي أو الكولومبي فقط. ولا تعرض الإضافة أبدًا مبلغًا بالبيزو كأنه عملة أخرى.

كولومبيا: المدينة غير معروفة: يجب أن يختار العميل القسم ويكتب اسم البلدية. ويعمل أيضًا رمز DANE مكوّن من 8 أرقام يُكتب في خانة الرمز البريدي. ويمكن للمطورين تمرير رمز DANE عبر الفلتر vfd_evc_dane_code.

الضريبة تُحتسب على الشحن مرتين: تتضمن أسعار Envioclick ضرائب شركات الشحن أصلًا. اضبط Tax status على None.

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

فلاتر للمطورين: vfd_evc_quotation_request (جسم الطلب)، وvfd_evc_api_url، وvfd_evc_dane_code، وvfd_evc_default_dimensions، وvfd_evc_package_description.

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

الإلغاء

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

Envioclick علامة تجارية تعود لمالكها. هذه الإضافة غير تابعة لـ Envioclick ولا معتمدة من Envioclick.