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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل API username وAPI password الخاصين بـ Sameday، واختر Sameday country، ثم احفظ. يجب أن تظهر الصفحة الرسالة "Connected to Sameday ... easybox lockers". تُملأ حقول Pickup point وEasybox service تلقائيًا من حسابك.

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

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

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Sameday Easybox. تنطبق على كل مناطق الشحن. عندما تضيف الطريقة إلى منطقة، تحتوي نافذة المنطقة على حقل واحد فقط:

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

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

تقبل جميع الأسعار والحدود الفاصلة العشرية بوصفها فاصلة أو نقطة (4,99 أو 4.99). يُرفض الرقم غير الصالح مع رسالة توضيحية.

عام

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

Name: اسم طريقة الشحن الذي يراه العميل. يمكن لمنطقة أن تستبدله بـTitle خاص بها. Default: Sameday easybox.

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها.

حساب 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 (عند ضبط 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. بدون ذلك لا يُستخدم التقدير، ويُطبَّق جدول الأسعار. يُحوَّل الليف واليورو تلقائيًا بسعر صرف ثابت.

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 عنده مجانيًا. ينطبق فقط حيث يُعثر على سعر: صف دولة، أو صف * Default، أو التكلفة الاحتياطية (وعندها لا يُطلب تقدير)، أو تقدير Sameday. اتركه فارغًا لعدم عرض الشحن المجاني أبدًا.

التوفر

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

Maximum weight (kg): لا يُعرض توصيل easybox للطرود الأثقل من هذا الحد. Default: 30. تحقق من حد عقدك مع Sameday ومن أحجام صناديق easybox. الفارغ أو 0 يعني بلا حد.

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

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

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

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

متقدم

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

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

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

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

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

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

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

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

اختيار الخزانة

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

الخزانة مطلوبة. بدونها يتوقف الدفع مع الرسالة "Please choose a Sameday easybox locker.". يتحقق الخادم من وجود الخزانة المختارة في القائمة، في صفحة الدفع الكلاسيكية وفي صفحة الدفع بالكتل. يُرفض معرّف الخزانة المزوَّر أو المحذوف مع الرسالة "The selected easybox locker is not available any more. Please choose another easybox locker.". الاسم والعنوان المحفوظان مع الطلب يأتيان من القائمة، لا من المتصفح.

شاشة الطلب في لوحة الإدارة: Sameday easybox locker مع الاسم والعنوان وLocker ID الخاص بـ AWB في Sameday، أسفل عنوان الشحن. إذا لم يكن لطلب easybox خزانة، تعرض الشاشة "No easybox locker was selected for this order.".

صفحة الشكر وعرض الطلب: Sameday easybox locker: مع الاسم والعنوان.

رسائل البريد الإلكتروني للطلبات: اسم الخزانة وعنوانها في رسائل HTML والنص العادي. تتضمن رسائل المسؤول أيضًا Locker ID.

في قاعدة البيانات تُحفظ الخزانة في بيانات الطلب الوصفية _vfd_sdeb_locker_id (معرّف خزانة Sameday لـ AWB) و_vfd_sdeb_locker_name (الاسم والعنوان).

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

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

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

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

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

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

لا يظهر Sameday easybox في الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن اسم مستخدم API وكلمة المرور مُدخلان وأن صفحة الإعدادات تقول "Connected to Sameday"، وأن دولة الوجهة هي دولة حساب Sameday. تحقق من توفر سعر (تقدير Sameday، أو صف الدولة، أو صف * Default، أو Fallback cost)، وحدود الوزن والمجموع الفرعي، وExcluded shipping classes، وأن الطريقة مضافة إلى المنطقة المناسبة (أو أن Ignore shipping zones مفعّل). فعّل Debug log لرؤية السبب في WooCommerce > Status > Logs.

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

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

قائمة الخزائن قديمة أو مفقودة: احفظ الإعدادات. تُعاد تحميل القائمة عندما تكون فارغة، أو أقدم من ساعة، أو عندما يفشل آخر تحميل. إذا فشل التحديث تُستخدم القائمة السابقة، وتذكر الحالة ذلك.

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

خزائن عبر الحدود: يمكن للمطورين إضافة دول وجهة بالفلتر vfd_sdeb_countries. قائمة الخزائن هي دائمًا قائمة حسابك.

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

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

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

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