VibeFox Sameday Easybox for PrestaShop — المساعدة

المتطلبات

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

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

اسم مستخدم وكلمة مرور Sameday API: الوصول إلى API جزء من حساب أعمال Sameday في رومانيا أو المجر أو بلغاريا. اسأل مدير حسابك لدى Sameday أو فريق التكامل لدى Sameday. غالبًا ما تكون بيانات الاعتماد نفسها المستخدمة في بوابة eAWB (eawb.sameday.ro أو .hu أو .bg). بالنسبة إلى واجهة API التجريبية، تقدم Sameday بيانات اعتماد اختبار منفصلة. بدون اسم مستخدم وكلمة مرور لـ API لا تُعرض شركة الشحن، لأن العميل لن يتمكن من اختيار خزانة.

المقاطعات في نموذج العنوان: يحتاج تقدير Sameday إلى مقاطعة عنوان التسليم. لا يحتوي PrestaShop على مقاطعات لرومانيا والمجر وبلغاريا افتراضيًا. يمكن للوحدة إضافتها لك (انظر قسم خزائن easybox أدناه). بدونها تأتي الأسعار من جدولك أو من التكلفة الاحتياطية.

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

التثبيت

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

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

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

4. أدخل API username وAPI password الخاصين بـ Sameday، واختر Sameday country وانقر على Save. يجب أن تعرض الصفحة "متصل بـ Sameday ... خزائن easybox". تُملأ Pickup point وEasybox service تلقائيًا من حسابك.

5. اضبط أسعارك: Exchange rate of the estimate إذا كانت عملة متجرك تختلف عن عملة Sameday، وصف في Country prices (مثلًا * Default) أو Fallback cost.

6. إذا أشارت الصفحة إلى أن المتجر لا يحتوي على مقاطعات لدولة Sameday لديك، فانقر على Add counties في قسم خزائن easybox.

عند التثبيت، تُنشئ الوحدة شركة الشحن Sameday easybox مع نص مدة التوصيل Delivery to a Sameday easybox locker. تُسنَد إلى جميع مجموعات العملاء ومنطقة رومانيا. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة Configure الخاصة بالوحدة، في ستة أقسام. يحفظ زر Save في أي قسم الصفحة كاملة.

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

تقبل جميع الأسعار والحدود الفاصلة العشرية الفاصلة أو النقطة (4,99 أو 4.99). لا يُحفظ الرقم غير الصالح أو السالب: يذكر التحذير الحقل، ويبقى القيمة السابقة.

عام

Enable/Disable: يفعّل شركة الشحن أو يعطّلها. وهو مطابق لحالة شركة الشحن في Shipping > Carriers.

Name: اسم طريقة الشحن الذي يراه العميل (اسم شركة الشحن). الافتراضي: Sameday easybox.

Tax status: None يعني أن السعر نهائي. Taxable مع قاعدة ضريبية يجعل PrestaShop يضيف ضريبة الشحن تلك فوق السعر.

حساب Sameday (API)

عند الحفظ، تسجّل الوحدة الدخول إلى Sameday وتحمّل خدماتك ونقاط الاستلام وقائمة خزائن easybox. تُحدَّث القائمة يوميًا.

API username: اسم مستخدم Sameday API الخاص بك.

API password: كلمة مرور Sameday API الخاصة بك. لا تُعرض مرة أخرى: اترك الحقل فارغًا للاحتفاظ بالكلمة المحفوظة. إفراغ اسم المستخدم يزيل كلمة المرور أيضًا. إذا رفضتها Sameday، فلا تُعاد المحاولة لمدة 10 دقائق.

Sameday country: دولة حساب Sameday الخاص بك: Romania (api.sameday.ro) (الافتراضي) أو Hungary (api.sameday.hu) أو Bulgaria (api.sameday.bg). تُعرض خزائن هذه الدولة، ولا تظهر شركة الشحن إلا لدولة الوجهة هذه. عند تغييرها، تُربط شركة الشحن أيضًا بمنطقة الدولة الجديدة.

Test mode: يستخدم واجهة Sameday التجريبية (sameday-api.demo.zitec.com) ببيانات اعتماد تجريبية.

الأسعار

ترتيب الاستخدام هو: تقدير Sameday (عند تعيين Pickup point وEasybox service)، ثم جدول الأسعار حسب الدولة، ثم التكلفة الاحتياطية. تُدخل أسعار الجدول بعملة المتجر الافتراضية. يرى العملاء الذين يدفعون بعملة أخرى السعر محوَّلًا.

Pickup point: نقطة استلام Sameday الخاصة بك، حيث تأخذ Sameday الطرود. بعد تسجيل دخول ناجح تكون قائمة بنقاط الاستلام في حسابك، ويُختار الافتراضي تلقائيًا. مطلوبة لتقدير Sameday. اختر - not set (price table only) - لاستخدام جدول الأسعار فقط.

Easybox service: خدمة Sameday لتوصيل easybox، عادةً "Locker NextDay" (الرمز LN)، ويُختار تلقائيًا. مطلوبة لتقدير Sameday.

Exchange rate of the estimate: تحسب Sameday التقدير بعملة دولة Sameday لديك: RON أو HUF أو BGN (وEUR للمتاجر البلغارية التي تبيع باليورو). إذا كان متجرك يبيع بعملة أخرى، فأدخل قيمة وحدة واحدة من عملة Sameday بعملة متجرك، مثلًا 0.20. يجب أن يكون السعر أكبر من 0. بدونه لا يُستخدم التقدير وتُطبَّق جداول الأسعار. يُحوَّل الليف واليورو تلقائيًا بسعر ثابت.

Table price: Per order يحتسب السعر مرة واحدة. Per item (price x quantity) يضربه في عدد العناصر. ينطبق هذا على سعر الجدول والتكلفة الاحتياطية. تقدير Sameday دائمًا للطرد كاملًا.

Country prices: سعر لكل دولة وجهة ولكل وزن للطرد. انقر على + Add country لإضافة صف، وعلى أيقونة سلة المهملات لحذفه. لكل صف عمود Price وأعمدة الوزن: XS حتى 1 كغ، وS من 1 إلى 2 كغ، وM من 2 إلى 3 كغ، وL من 3 إلى 5 كغ، وXL أكثر من 5 كغ. عمود الوزن المتروك على 0 يستخدم عمود Price. يُستخدم صف * Default للدول التي ليس لها صف خاص. يبدأ الصف الجديد باسم * Default مع جميع الأسعار بقيمة 0، أي شحن مجاني. اختر الدولة وأدخل الأسعار قبل الحفظ، أو احذف الصف. إذا وردت الدولة نفسها في صفين، فعند الحفظ يُحتفظ بالأول فقط، ويوضح تحذير ذلك. إذا لم تكن خانة ما رقمًا صالحًا، فلا يُحفظ الجدول.

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

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

التوفر

Minimum weight (kg): يخفي شركة الشحن عندما تكون السلة أخف من ذلك. يُحوَّل الوزن من وحدة وزن متجرك (كغ أو غ أو lb أو oz). الفارغ أو 0 يعني بلا حد.

Maximum weight (kg): لا يُعرض التوصيل إلى easybox للطرود الأثقل من ذلك. الافتراضي: 30. تحقق من حد عقدك مع Sameday وأحجام صناديق easybox. الفارغ أو 0 يعني بلا حد. لا يُحفظ حد أدنى للوزن أعلى من الحد الأقصى: يوضح تحذير ذلك، وتبقى القيم السابقة.

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

Ignore shipping zones: عند التفعيل، تُعرض شركة الشحن للدول المختارة أدناه (دولة Sameday إذا كانت القائمة فارغة)، حتى لو لم تكن منطقتها مُعدّة لشركة الشحن. عندئذ تُربط شركة الشحن بكل المناطق النشطة، بما فيها المناطق المنشأة لاحقًا. عند إيقافه مرة أخرى تستعيد شركة الشحن المناطق التي كانت لها من قبل. عند إيقافه تُعرض شركة الشحن فقط في مناطقها في Shipping > Carriers.

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

خزائن easybox

Locker list: يعرض عدد خزائن easybox المحمّلة في عدد المدن، ومتى حُمّلت. يحمّلها Refresh the locker list now من جديد. تُحدَّث القائمة عند حفظ الإعدادات، وبعد طلب الدفع إذا كانت أقدم من يوم. للتحديث اليومي الثابت، استدعِ Cron URL المعروض هنا مرة واحدة يوميًا من مهمة cron على خادمك. يحتوي الرابط على رمز سري. بدون الرمز يعيد خطأً ولا يتصل بـ Sameday.

Counties: يحتاج تقدير Sameday إلى مقاطعة العنوان. إذا لم تكن لدى PrestaShop مقاطعات (states) لدولة Sameday لديك، فانقر على Add counties. تضيف الوحدة مقاطعات رومانيا أو المجر أو بلغاريا وحقل المقاطعة إلى نموذج العنوان لتلك الدولة. لا تُضاف المقاطعات الموجودة مرتين. عند وجودها تعرض الصفحة عددها.

متقدم

Debug log: يكتب حسابات الأسعار واستدعاءات API واختيارات الخزائن في الملف logs/vfd_sdeb_debug.log.php داخل مجلد الوحدة، وهو ملف لا يمكن قراءته من الويب. أخطاء API تُسجَّل دائمًا. لا تُسجَّل أي كلمة مرور أو رمز أو بيانات شخصية للعميل. يعرض الحقل Log أدناه نهاية الملف، مع زر Clear log. أوقف السجل عند الانتهاء.

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

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

عندما يحسب المتجر الشحن لسلة، يطلب PrestaShop من الوحدة سعر شركة الشحن Sameday easybox. تتحقق الوحدة من الشروط: دولة التوصيل في حساب Sameday، وبيانات اعتماد API وقائمة خزائن قابلة للاستخدام، ودول Ignore shipping zones، ووزن السلة، والحد الأدنى للمجموع الفرعي للسلة. لا تُحتسب المنتجات التي لا تحتاج إلى شحن (المنتجات الافتراضية). إذا انطبق الشحن المجاني، يرى العميل شركة الشحن بلا تكلفة.

وإلا، تطلب الوحدة من Sameday تقديرًا، بعد أن يُدخل العميل مدينة ومقاطعة. تُرسل نقطة استلامك وخدمتك، ووزن الطرد، وعنوان العميل (الشارع والمدينة والمقاطعة والرمز البريدي). لا يُرسل الاسم أو البريد الإلكتروني أو رقم الهاتف. تُرسل بوخارست باسم "Sector 1"، كما تفعل الإضافة الرسمية لـ Sameday. يُحوَّل التقدير إلى عملة متجرك. إذا لم يوجد تقدير (غير مُعدّ، أو لا توجد مدينة أو مقاطعة بعد، أو خطأ، أو لا يوجد سعر صرف)، يأتي السعر من جدول الدولة، ثم من التكلفة الاحتياطية. إذا لم يوجد سعر، تُخفى شركة الشحن.

لا تُعطّل مشكلات Sameday الدفع أبدًا. يُخزَّن التقدير مؤقتًا لمدة ساعة. يُخزَّن الخطأ مؤقتًا لمدة 10 دقائق. بعد انتهاء المهلة أو خطأ في الخادم، لا يُطلب أي تقدير لمدة 5 دقائق. تنتهي الطلبات بعد 15 ثانية. تُقرأ قائمة الخزائن من خادمك، لا من Sameday، أثناء الدفع.

تعمل شركة الشحن في خطوة الشحن لقالب Classic (PrestaShop 8) وقالب Hummingbird (PrestaShop 9).

لا تُنشئ الوحدة AWB (شحنات)، ولا تطبع الملصقات، ولا تتتبع الطرود، ولا تتولى الدفع عند الاستلام. لا تتضمن توصيل المنزل بالمندوب ولا أداة الخريطة من Sameday. أنشئ AWB في بوابة Sameday eAWB أو في الأداة المعتادة لديك، مع معرّف الخزانة المعروض في الطلب.

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

عندما يختار العميل شركة الشحن، تظهر أسفلها كتلة easybox locker بقائمتين: - Select city - و- Select easybox locker -. تُختار مدينة عنوان التوصيل تلقائيًا إذا كانت فيها خزائن. يعرض كل خزانة اسمها وعنوانها. يُحفظ الاختيار في السلة فورًا، فيبقى عند تحديث خطوة الشحن أو إعادة تحميل الصفحة.

الخزانة مطلوبة. بدونها لا يستطيع العميل المتابعة، ويرى "يرجى اختيار خزانة Sameday easybox." عندما ينقر العميل على Continue، يتحقق الخادم من أن الخزانة المختارة موجودة في القائمة. يُرفض معرّف الخزانة المزوَّر أو المحذوف برسالة "خزانة easybox المختارة لم تعد متاحة. يرجى اختيار خزانة easybox أخرى." إذا تعذر تحميل القائمة، يرى العميل "تعذر تحميل خزائن easybox. يرجى المحاولة مرة أخرى بعد قليل أو اختيار طريقة شحن أخرى." الاسم والعنوان المحفوظان مع الطلب يأتيان من القائمة، لا من المتصفح. بعد تقديم الطلب لا تتغير خزانته.

صفحة الطلب في لوحة الإدارة: كتلة Sameday easybox locker بالاسم والعنوان وLocker ID لـ AWB الخاص بـ Sameday. إذا لم يكن لطلب easybox خزانة، تقول الكتلة "لم يُختر أي خزانة easybox لهذا الطلب."

صفحات تأكيد الطلب وسجل الطلبات: Sameday easybox locker: مع الاسم والعنوان.

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

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

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

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

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

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

لا تظهر Sameday easybox عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن اسم مستخدم API وكلمة المرور مُدخلان، وأن صفحة Configure تعرض "متصل بـ Sameday"، وأن دولة الوجهة هي دولة حساب Sameday لديك. تحقق من توفر سعر (تقدير Sameday، أو صف الدولة، أو صف * Default، أو Fallback cost) وحدود الوزن والمجموع الفرعي. في Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعته، أو فعّل Ignore shipping zones. قد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج. فعّل Debug log لرؤية السبب في الحقل Log.

رفضت Sameday اسم مستخدم API أو كلمة المرور: تحقق منهما ثم احفظ مرة أخرى. تعمل بيانات الاختبار فقط عند تفعيل Test mode، وبيانات الإنتاج فقط عند إيقافه. إلى ذلك الحين تُعرض قائمة الخزائن المحفوظة إن وُجدت، ولا يُستخدم تقدير Sameday.

السعر يأتي من جدولي، لا من Sameday: يحتاج التقدير إلى Pickup point وEasybox service ومقاطعات في نموذج العنوان، وإذا اختلفت عملة متجرك عن عملة Sameday فيحتاج إلى Exchange rate of the estimate. يُطلب التقدير فقط بعد أن يُدخل العميل مدينة ومقاطعة. عندما تكون Sameday غير متاحة أو تُرجع خطأً، يُستخدم الجدول أو التكلفة الاحتياطية؛ والسبب موجود في السجل.

قائمة الخزائن قديمة أو مفقودة: انقر على Refresh the locker list now أو احفظ الإعدادات. إذا فشل التحديث، تُستخدم القائمة السابقة، وتوضح الحالة ذلك. إذا كان المتجر في وضع الصيانة، يُحظر رابط cron مثل بقية المتجر، ما لم يُسمح بعنوان IP لخادم cron.

الشحن مجاني بالخطأ: تحقق من Free shipping from وصفوف Country prices ذات Price بقيمة 0، خاصةً صف * Default المضاف بـ + Add country وتُرك دون تعبئة.

حدود الوزن أو أعمدته غير متطابقة: إذا حذّرت الصفحة من أن وحدة وزن المتجر غير معروفة، فاضبط kg أو g أو lb أو oz في International > Localization (Local units).

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

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

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

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