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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Andreani (للأسعار الفورية فقط): تستخدم الأسعار الفورية واجهة عروض أسعار Andreani. تُصدر Andreani لعملائها من الشركات بيانات اعتماد الواجهة البرمجية ورمز العميل وأرقام العقود، عادةً عند تجاوز نحو 300 شحنة شهريًا. راجع developers.andreani.com أو راسل ventapyme@andreani.com. تحتاج إلى اسم مستخدم الواجهة البرمجية وكلمة المرور، ورمز العميل، ورقم العقد. تصدر Andreani عقدًا منفصلًا لكل خدمة (التوصيل المنزلي، والاستلام من الفرع). وبدون وصول إلى الواجهة البرمجية، استخدم الأسعار الثابتة. يعمل منتقي الفرع دون بيانات اعتماد.

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

التثبيت

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

2. انقر على Activate.

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

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

5. اضبط الاسم، ومصدر الأسعار، والأسعار حسب الدولة (مثل AR=5000)، وإذا كنت تستخدم الأسعار الفورية، فبيانات اعتماد الواجهة البرمجية ورمز العميل ورقم العقد (انظر الإعداد).

6. انتقل إلى WooCommerce > Settings > Shipping > Shipping zones، وافتح منطقة للأرجنتين أو أنشئ واحدة، ثم أضف VibeFox Andreani. في نافذة المنطقة يمكنك تحديد العنوان ونمط التوصيل وعقد مختلف لهذا الخيار. ويمكنك أيضًا تفعيل Ignore shipping zones واختيار الدول بدلًا من ذلك.

الإعداد

توجد الإعدادات الرئيسية في WooCommerce > Settings > Shipping > VibeFox Andreani. وتنطبق على جميع مناطق الشحن. وتظهر أعلى الصفحة تحذيرات بشأن الإعدادات الناقصة (بيانات اعتماد الواجهة البرمجية، ورقم العقد، وسعر الصرف، وعدم وجود سعر للأرجنتين). وفي كل مرة تحفظ فيها الإعدادات، يُمسح الرمز المميز والفروع والأسعار المخزنة مؤقتًا.

نافذة المنطقة (عند إضافة الطريقة إلى منطقة شحن)

Title: اسم هذا الخيار في صفحة الدفع. اتركه فارغًا لاستخدام Name العام.

Delivery modality: Use global setting أو أحد الأنماط الأربعة (انظر أدناه). أضف الطريقة إلى المنطقة مرتين، مثلًا من الباب إلى الباب ومن الفرع إلى الباب، لتقديم الخيارين معًا.

Contract number: عقد Andreani لهذا الخيار. اتركه فارغًا لاستخدام العقد العام.

عام

Enable/Disable: يفعّل خدمة الشحن عبر Andreani أو يعطّلها في جميع المناطق دفعة واحدة.

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

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

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

Environment: Sandbox / QA (apisqa.andreani.com) (الافتراضي) أو Production (apis.andreani.com). استخدم البيئة التي تنتمي إليها بيانات اعتمادك.

API username: اسم مستخدم واجهة Andreani البرمجية.

API password: كلمة مرور واجهة Andreani البرمجية.

Client code: رمز العميل (código de cliente) الذي تقدمه Andreani، مثل CL0000000.

Contract number: عقد الخدمة المستخدم للأسعار، مثل التوصيل المنزلي. يمكن لمنطقة أن تستخدم عقدًا آخر، مثل الاستلام من الفرع.

Origin branch code: فرع المنشأ الاختياري (sucursalOrigen) لعروض الأسعار. اتركه فارغًا لاستخدام الفرع المُعدّ في عقدك.

التوصيل والأسعار

Delivery modality: يحدد الجزء الأول المكان الذي تستلم منه Andreani الطرد (عنوانك أو فرع تسلّم فيه الطرد). ويحدد الجزء الثاني المكان الذي يستلم منه العميل الطرد.

Rate source: كيفية حساب السعر.

Country prices: سعر ثابت لكل دولة وجهة بعملة متجرك، سطر واحد لكل دولة بالصيغة CC=PRICE، مثل AR=5000. يُستخدم في الوضع الثابت، وكبديل عند تعطل الواجهة البرمجية. تُتجاهل الأسطر ذات الصيغ الأخرى، ويعرض التحذير عند الحفظ قائمة بها.

ARS exchange rate: تُصدر Andreani عروض أسعارها بالبيزو الأرجنتيني. ولا يلزم هذا الحقل إلا إذا لم تكن عملة متجرك ARS: سعر 1 ARS بعملة متجرك، مثل 0.001. وبدونه لا تُستخدم أسعار الواجهة البرمجية. والأسعار الثابتة دائمًا بعملة متجرك.

Default product weight (kg): يُستخدم للمنتجات التي لا وزن لها عند طلب أسعار الواجهة البرمجية وعند التحقق من حدود الوزن. الافتراضي: 0.5.

Calculation type: Per order يحصّل السعر مرة واحدة. أما Per item (price x number of items) فيضرب السعر الثابت من Country prices في عدد العناصر بالسلة. وسعر Andreani الفوري يشمل السلة كاملة ولا يُضرب.

التوفر

Min weight (kg): الحد الأدنى لوزن السلة لكي تظهر الطريقة. الصفر يعني دون حد.

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

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

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

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

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

الشحن المجاني

Free shipping: يفعّل حد الشحن المجاني.

Free shipping from: المجموع الفرعي للسلة الذي يصبح عنده الشحن مجانيًا. ويتطلب تفعيل Free shipping.

منتقي الفرع في صفحة الدفع (يظهر لـ Door to branch وBranch to branch)

Province select width: عرض قائمة المحافظات بصيغة CSS، مثل 100% أو 300px. الافتراضي: 100%.

Branch select width: عرض قائمة الفروع بصيغة CSS، مثل 100% أو 400px. الافتراضي: 100%.

متقدم

Debug log: يسجّل طلبات الواجهة البرمجية وحسابات الأسعار في WooCommerce > Status > Logs (المصدر "vfd-andreani"). وتُسجَّل الأخطاء دائمًا. ولا تُسجَّل بيانات الاعتماد والرموز المميزة أبدًا.

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

كيف تعمل في صفحة الدفع

عندما يُدخل العميل عنوان الشحن، تتحقق الإضافة من وزن السلة (تُحوَّل أوزان المنتجات إلى كغ، وتستخدم المنتجات بلا وزن Default product weight (kg))، وMinimum subtotal، وExcluded shipping classes.

في الوضع الثابت يُؤخذ السعر من Country prices. وفي الأوضاع الفورية تسجّل الإضافة الدخول إلى واجهة Andreani البرمجية، وتطلب عرض سعر بالرمز البريدي للوجهة والعقد ورمز العميل والوزن بالكغ والحجم المحسوب من أبعاد المنتجات والقيمة المصرّح بها (المجموع الفرعي للسلة بالـ ARS). ولا يُطلب سعر فوري إلا لرمز بريدي أرجنتيني صالح. ويُحوَّل المبلغ بالـ ARS باستخدام ARS exchange rate عندما لا تكون عملة متجرك ARS.

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

إذا كان Free shipping مفعّلًا وبلغ المجموع الفرعي للسلة Free shipping from، يكون السعر 0. ولا يُطبَّق الشحن المجاني إلا حيث للطريقة سعر: فإذا لم تُرجع واجهة Andreani البرمجية سعرًا (ولا يوجد سعر ثابت للرجوع إليه)، فلن تظهر الطريقة. ومع Per item يُضرب السعر الثابت في عدد العناصر.

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

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

نقاط الاستلام

عند اختيار Door to branch أو Branch to branch، تظهر قائمة المحافظات وقائمة الفروع أسفل خيار Andreani في صفحة الدفع، سواء في صفحة الدفع الكلاسيكية أو في كتلة Checkout. تُختار المحافظة مسبقًا من عنوان الشحن. وتأتي قائمة الفروع من واجهة Andreani البرمجية العامة للفروع، وتُخزَّن مؤقتًا لمدة 12 ساعة. ولا تُدرج الفروع التي لا تسلّم الطرود. وإذا لم تتوفر فروع، يرى العميل رسالة ويمكنه اختيار طريقة شحن أخرى.

لا يمكن إتمام الطلب دون فرع: يرى العميل الرسالة Please select an Andreani pickup branch. ويُتحقق من ذلك على الخادم في الصفحتين معًا.

يُحفظ الفرع المختار في الطلب. وفي شاشة طلب المدير تظهر طريقة التوصيل والفرع أسفل عنوان الشحن. انقر على Edit لاختيار محافظة وفرع آخرين. ويرى العميل الفرع باسم Andreani pickup branch في صفحة الطلب وفي رسائل البريد الإلكتروني للطلبات (بصيغتي HTML والنص العادي). وتحتفظ الطلبات الحالية ببيانات فروعها.

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

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

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

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

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

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

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

لا تظهر الأسعار الفورية: فعّل Debug log، وأعد تحميل صفحة الدفع، ثم افتح WooCommerce > Status > Logs (المصدر "vfd-andreani"). يُظهر السجل السبب: بيانات اعتماد أو رقم عقد مفقود، أو فشل تسجيل الدخول (اسم مستخدم أو كلمة مرور أو بيئة غير صحيحة)، أو عدم وجود رمز بريدي أرجنتيني صالح بعد، أو غياب سعر الصرف، أو خطأ HTTP من Andreani. ومع Andreani API, fixed price if the API fails يحصل العملاء على السعر الثابت أثناء إصلاحك للمشكلة.

متجري لا يستخدم البيزو الأرجنتيني: اضبط ARS exchange rate على قيمة 1 ARS بعملة متجرك.

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

لا توجد فروع في القائمة: لم تستجب واجهة Andreani البرمجية للفروع. يُعاد الطلب الفاشل بعد 5 دقائق. تحقق من السجل.

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

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

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

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

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