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

المتطلبات

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

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

حساب 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. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

4. أدخل مفتاح الواجهة البرمجية، واختر دولة الواجهة البرمجية، وأدخل User-Agent (المكسيك)، والرمز البريدي أو رمز DANE لنقطة الانطلاق، وعنوان نقطة الانطلاق. إذا لم تكن عملة المتجر الافتراضية MXN أو COP، فأدخل سعر صرف العملة. بالنسبة إلى كولومبيا، انقر على Add Colombian departments إذا كانت الصفحة تعرضه.

5. اختياريًا، أضف أسعارًا ثابتة لكل دولة وتكلفة احتياطية، ثم انقر على Save.

عند التثبيت، تُنشئ الوحدة شركة الشحن Envioclick Shipping بنص مدة التسليم Courier delivery by the best Envioclick carrier. تُسنَد شركة الشحن إلى جميع المناطق وجميع فئات العملاء. يمكنك تغيير المناطق وفئات العملاء ومدة التسليم والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

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

عند تعيين مفتاح الواجهة البرمجية، تظهر تحذيرات أعلى الصفحة إذا لم تتمكن الأسعار الفورية من العمل: لا يوجد سعر صرف لعملة متجر غير MXN أو COP، أو لا يوجد User-Agent للمكسيك، أو لا يوجد رمز بريدي أو رمز DANE لنقطة الانطلاق، أو لا يوجد عنوان انطلاق لكولومبيا. كما تحذر الصفحة إذا لم تُتعرَّف وحدة الوزن أو الأبعاد في متجرك؛ اضبط kg أو g أو lb أو oz، وcm أو mm أو m أو in في International > Localization (Local units). عند الحفظ، تتحقق الوحدة من أن Method title اسم شركة شحن صالح، وأن حقول الأرقام تحتوي على أعداد غير سالبة، وأن Currency conversion rate أكبر من 0، وأن Minimum weight لا يتجاوز Maximum weight، وأن رمز الانطلاق مكون من 5 أرقام للمكسيك أو 8 أرقام (أو رمز البلدية المكون من 5 أرقام) لكولومبيا. إذا فشل أي فحص، يظهر خطأ ولا يُحفظ شيء.

عام

تُحدَّد المناطق وفئات العملاء وحدود الحجم الخاصة بشركة الشحن في Shipping > Carriers (أو استخدم Ignore shipping zones أدناه). تنطبق الإعدادات في هذه الصفحة على جميع المناطق.

Enable Envioclick: يُفعّل شركة الشحن أو يُعطّلها. وهو المفتاح نفسه الموجود في حالة شركة الشحن في Shipping > Carriers.

Method title: اسم شركة الشحن الذي يراه العميل في السلة وعند الدفع. الافتراضي: Envioclick Shipping. مطلوب.

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

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

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

API key: مفتاح واجهة Envioclick البرمجية من Mi cuenta > Información del API. يُرسل في ترويسة «Authorization». بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره.

Remove the saved API key: يظهر فقط أثناء حفظ مفتاح. اختر Yes واحفظ لحذف المفتاح؛ عندئذ لا تُستخدم سوى الأسعار الثابتة. المفتاح المدخل في API key يحل محل المفتاح المحفوظ.

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

Colombian departments: لكولومبيا فقط. لا يحتوي PrestaShop على أقسام كولومبية افتراضيًا. ومن دونها لا تُتعرَّف سوى أسماء المدن الفريدة في كولومبيا؛ ويميّز القسم بين البلديات التي تحمل الاسم نفسه. يضيف زر Add Colombian departments الأقسام الـ 33 ولايات لكولومبيا (برموز ISO مثل ANT وDC وغيرها)، ويفعّل «Contains states» لكولومبيا، ويضيف حقل القسم إلى نموذج العنوان الكولومبي. لا تُضاف الأقسام الموجودة مسبقًا مرة ثانية. وعند اكتمال كل شيء، يعرض الحقل عدد الأقسام التي تملكها العناوين الكولومبية.

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

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

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

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

نقطة الانطلاق

تُستخدم للأسعار الفورية. تُملأ الحقول الفارغة من عنوان المتجر في Shop Parameters > Contact > Stores إذا كان المتجر في دولة الواجهة البرمجية.

Origin postcode / DANE code: المكسيك: الرمز البريدي المكون من 5 أرقام. كولومبيا: رمز DANE المكون من 8 أرقام للبلدية، مثل 11001000 لبوغوتا؛ ويعمل أيضًا رمز البلدية المكون من 5 أرقام (11001).

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

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

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

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

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

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

الشروط

Minimum weight: يخفي شركة الشحن إذا كان وزن السلة أقل من هذا الحد، بالكيلوغرام. الصفر يعني عدم وجود حد.

Maximum weight: يخفي شركة الشحن إذا كان وزن السلة أعلى من هذا الحد، بالكيلوغرام. الافتراضي: 25. الصفر يعني عدم وجود حد.

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

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

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

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

عادةً تُعرض شركة الشحن في المناطق المُسنَدة إليها في Shipping > Carriers.

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

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

متقدم

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

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

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

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

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

إذا كان مفتاح الواجهة البرمجية معيّنًا وكانت الوجهة في دولة الواجهة البرمجية، تطلب الوحدة عروض الأسعار من Envioclick. في المكسيك يُرسل الطلب بمجرد أن يدخل العميل رمزًا بريديًا مكونًا من 5 أرقام. وفي كولومبيا يُرسل الطلب بمجرد التعرف على القسم والبلدية (لا تهم العلامات الصوتية وحالة الأحرف). تختار الوحدة أرخص عرض سعر أو أسرعه، وليس الدفع عند الاستلام، وتحوّله إلى عملة المتجر الافتراضية. ثم يُعرض السعر بعملة سلة العميل.

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

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

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

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

الطلبات

عند تقديم طلب مع شركة الشحن Envioclick، يُحفظ السعر المحسوب لسلته مع الطلب ولا يتغير بعد ذلك. تعرض صفحة الطلب في لوحة الإدارة كتلة Envioclick shipping تتضمن Envioclick carrier وEstimated delivery وEnvioclick rate ID (للسعر الفوري)، وPrice source (Envioclick live rate أو Fixed price per country أو Fallback cost أو Free shipping threshold)، وCalculated price (excl. tax). وبالنسبة إلى السعر الفوري، تعرض صفحة طلب العميل Shipping carrier. أنشئ بوليصة الشحن في حسابك في Envioclick.

لا توجد شركة شحن Envioclick للطلبات المقدمة بسعر ثابت.

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

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

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

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

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

لا تظهر Envioclick عند الدفع: تحقق من أن الترخيص نشط وأن Enable Envioclick مفعّل. وفي Shipping > Carriers، تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته، أو فعّل Ignore shipping zones وتحقق من Countries. وتحقق من حدود الوزن وMinimum order amount. من دون سعر فوري، تحتاج شركة الشحن إلى سعر ثابت للدولة، أو صف *، أو Fallback cost. وقد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج.

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

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

كولومبيا: المدينة غير معترف بها: انقر على Add Colombian departments في صفحة الوحدة كي يتمكن العملاء من اختيار القسم، وتحقق من كتابة اسم البلدية بشكل صحيح. ويعمل أيضًا رمز DANE المكون من 8 أرقام إذا أُدخل كرمز بريدي.

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

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

تقول الصفحة إن شركة الشحن Envioclick غير موجودة: حُذفت شركة الشحن في Shipping > Carriers. أعد ضبط الوحدة في Modules > Module Manager لإنشائها من جديد.

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

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

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