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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

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

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

التثبيت

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

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

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

4. حدِّد الاسم، ومصدر الأسعار، وأسعار الدول (مثل AR=5000)، وفي حالة الأسعار الفورية، بيانات اعتماد واجهة البرمجة وكود العميل ورقم العقد (انظر الإعدادات). انقر على Save.

عند التثبيت، تُنشئ الوحدة شركتي شحن:

تُسنَد الشركتان إلى منطقة الأرجنتين وإلى جميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Andreani > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. بعد الحفظ تظهر لك الرسالة Settings saved. Cached token, branches and rates were cleared. تظهر التحذيرات بشأن الإعدادات الناقصة (بيانات اعتماد واجهة البرمجة، ورقم العقد، وسعر صرف ARS، وعدم وجود سعر للأرجنتين، وشركة شحن محذوفة) أعلى الصفحة. يظهر تحذير أيضًا إذا لم تتعرف الوحدة على وحدة وزن المتجر أو أبعاده (عندها يُقرأ الوزن بالكيلوغرام والأبعاد بالسنتيمتر). عند الحفظ، يُرفض اسم أطول من 64 حرفًا أو Min weight (kg) أكبر من Max weight (kg)، ولا يُحفظ أي شيء. لا تُحفظ القيمة غير الرقمية، أو الرقم السالب، أو ARS exchange rate الذي يساوي 0 أو أقل، ويذكر التحذير الحقل المعني.

General

Enable/Disable: يفعّل شحن Andreani أو يعطّله. وهو المفتاح نفسه الذي يحدد حالة شركة الشحن الرئيسية في Shipping > Carriers. للخيار الثاني مفتاحه الخاص.

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

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

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

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

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

API password: كلمة مرور واجهة برمجة Andreani. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. Clearing the API username removes it too. أدخل قيمة جديدة فقط إذا أردت تغييرها.

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

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

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

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

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

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

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

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

الخيار الثاني

شركة شحن ثانية من Andreani باسمها ونمط التوصيل وعقدها الخاصين، مثل "a domicilio" في شركة الشحن الرئيسية و"retiro en sucursal" هنا، لتقديم الخيارين معًا. جميع الإعدادات الأخرى مشتركة.

Enable second option: يفعّل الشركة الثانية أو يعطّلها. وهو المفتاح نفسه الذي يحدد حالتها في Shipping > Carriers. الافتراضي: معطّل.

Second option name: اسم هذا الخيار في الدفع. الافتراضي: Andreani - branch pickup. حقل مطلوب.

Delivery modality: Use global setting أو أحد الأنماط الأربعة. الافتراضي: Door to branch (Puerta a Sucursal).

Contract number: تصدر Andreani عقدًا منفصلًا لكل خدمة (التوصيل المنزلي، والاستلام من الفرع). اتركه فارغًا لاستخدام العقد العام.

منتقي الفرع في الدفع (يظهر لـ door to branch وbranch to branch)

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

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

متقدم

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

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

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

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

في خطوة التوصيل، تطلب PrestaShop من الوحدة سعر كل شركة شحن من Andreani. يُحتسب المنتجات المادية فقط: لا تضيف المنتجات الافتراضية وزنًا ولا تدخل في المجموع الفرعي. تتحقق الوحدة من الدول (عندما يكون Ignore shipping zones مفعّلًا)، ووزن السلة (تُحوَّل أوزان المنتجات إلى كيلوغرامات، وتستخدم المنتجات بلا وزن Default product weight (kg))، وMinimum subtotal.

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

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

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

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

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

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

عند اختيار شركة شحن بـ Door to branch أو Branch to branch، تظهر تحتها في خطوة التوصيل قائمة بالمحافظات وقائمة بالفروع. تُختار المحافظة مسبقًا من عنوان الشحن. تأتي قائمة الفروع من واجهة Andreani العامة للفروع، وتُخزَّن مؤقتًا لمدة 12 ساعة. لا تُدرج الفروع التي لا تسلّم الطرود. إذا لم تتوفر أي فروع، يرى العميل الرسالة No Andreani branches available right now. Please try again later or choose another shipping method.

يُحفظ الاختيار في السلة فور أن يختاره العميل. يُقبل فقط فرع من القائمة الحالية لـ Andreani. دون فرع، لا ينجح Continue في خطوة التوصيل ولا زر الطلب في خطوة الدفع، ويرى العميل Please select an Andreani pickup branch. يتحقق الخادم من الفرع مرة أخرى عندما يتابع العميل. إذا لم يعد الفرع في القائمة، يرى العميل The selected Andreani branch is not available. Please choose another one.

الفرع الذي اختير ضمن Andreani قبل أن ينتقل العميل إلى شركة شحن أخرى لا ينتمي إلى الطلب.

الطلبات

يحفظ الطلب نمط التوصيل، وفي أنماط الفروع يحفظ الفرع المختار.

Admin order page: كتلة Andreani تعرض النمط والفرع (الاسم والمعرّف والمحافظة). انقر على Edit، واختر محافظة وفرعًا آخرين، ثم انقر على Save لتغييره. سترى Branch updated. لا يمكن حفظ إلا الفروع الموجودة في قائمة Andreani. إذا لم تكن القائمة متاحة، لا يمكن تغيير الفرع.

العميل: يُعرض الفرع بعبارة Andreani pickup branch: في صفحة تأكيد الطلب وفي صفحة تفاصيل الطلب.

رسائل البريد الإلكتروني: في رسالة تأكيد الطلب وفي رسالة الطلب الجديد إلى المتجر (وحدة Mail alerts)، يُضاف الفرع إلى اسم شركة الشحن. ترسل رسالة المتجر أيضًا معرّف الفرع.

تحتفظ الطلبات الحالية ببيانات فروعها.

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

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

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

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

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

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

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

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

تبدو ضريبة الشحن خاطئة: مع قاعدة ضريبية في Tax status يُستخدم سعر Andreani بدون IVA وتضيف PrestaShop ضريبتها الخاصة. مع None يُستخدم السعر شاملًا IVA ولا تُضاف ضريبة. تحقق من تفعيل الضرائب ومن إعداد قاعدة الضريبة للأرجنتين.

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

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

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

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

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

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