VibeFox Correos CityPaq for PrestaShop — المساعدة

المتطلبات

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

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

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

بيانات اعتماد Correos API (لقائمة الخزائن المباشرة فقط): تقرأ قائمة Correos CityPaq الخزائن النشطة من واجهة Correos البرمجية "terminals". في بوابة مطوّري Correos، افتح واجهة "terminals" واستخدم Request access لتطبيقك. توافق Correos على طلبات عملائها من الشركات وترسل client ID وclient secret. وتظهر هذه القيم أيضًا تحت My applications في البوابة. إذا أدخل العملاء الخزانة بأنفسهم أو اختاروها من قائمتك، فلا تحتاج إلى بيانات اعتماد API.

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

التثبيت

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

2. عند انتهاء الرفع، اضغط Configure، أو ابحث لاحقًا عن VibeFox Correos CityPaq في قائمة الوحدات واضغط Configure.

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

4. املأ جدول الأسعار، واختر كيف يختار العميل الخزانة (انظر الإعدادات)، ثم اضغط Save.

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

الإعدادات

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

تخبرك التحذيرات فوق الإعدادات بالحالات التالية: عدم العثور على شركة الشحن، وعدم وجود صف لإسبانيا ولا صف افتراضي في جدول الأسعار، وعدم إمكانية عمل طريقة اختيار الخزانة المحددة (لا توجد خزائن في قائمتك، أو لا توجد بيانات اعتماد API)، وما كان آخر خطأ في Correos API، وعدم تعرّف الوحدة على وحدة الوزن في متجرك (تُقرأ أوزان المنتجات حينها بالكيلوغرام؛ اضبط kg أو g أو lb أو oz في International > Localization). إذا كان الاسم فارغًا أو غير صالح أو أطول من 64 حرفًا، أو كان وزن أو مبلغ ليس رقمًا صالحًا يساوي 0 أو أكبر، أو كانت قيمة Min weight (kg) أكبر من Max weight (kg)، تُظهر الصفحة خطأ ولا يُحفظ أي شيء. تُذكر الأسعار غير الصالحة في جدول الأسعار، والأسطر غير الصالحة أو المكررة في My lockers كتحذيرات، ويُحفظ الباقي.

عام

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

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

Name: اسم طريقة الشحن الذي يراه العميل عند الدفع. وهو أيضًا اسم شركة الشحن. الافتراضي: Correos CityPaq. حقل إلزامي، بحد أقصى 64 حرفًا.

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

الأسعار (يعرض عنوان القسم العملة الافتراضية لمتجرك)

لا تنشر Correos واجهة برمجية للتعرفة الخاصة بـ CityPaq، لذلك يأتي السعر من هذا الجدول. أدخل أسعار عقد Correos الخاص بك بالعملة الافتراضية للمتجر، دون الضريبة.

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

Calculation type: كيفية تحديد حجم الطرد.

Per order (size by the total cart weight): سعر واحد للسلة كلها، يُختار حسب الوزن الإجمالي. هذا هو الخيار الافتراضي.

Per item (size by each item weight, multiplied by quantity): يحصل كل منتج على سعر حجمه الخاص، مضروبًا في كميته، وتُجمع الأسعار.

تُحوَّل أوزان المنتجات إلى كغ من وحدة الوزن في متجرك (مثل kg أو g أو lb أو oz).

الشروط

Min weight (kg): يخفي شركة الشحن عندما تكون السلة أخف من هذا الوزن. القيمة 0 تعني بلا حد.

Max weight (kg): يخفي شركة الشحن عندما تكون السلة أثقل من هذا الوزن. الافتراضي: 30، لأن CityPaq يقبل طرودًا حتى 30 كغ. القيمة 0 تعني بلا حد.

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

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

Free shipping: يفعّل توصيل CityPaq المجاني ابتداءً من المبلغ الموضح أدناه.

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

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

يحتوي هذا القسم على رابط لأداة البحث الرسمية عن خزائن Correos CityPaq.

Locker selection: كيفية اختيار العميل للخزانة قبل تقديم الطلب. الافتراضي: يُدخل العميل الخزانة.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): يرى العميل خزائن CityPaq النشطة في الرمز البريدي لعنوان التوصيل، ويمكنه البحث عن رمز بريدي آخر مكوّن من 5 أرقام. عندما لا يحتوي الرمز البريدي على خزانة، تُعرض خزائن المنطقة نفسها ثم خزائن المحافظة نفسها، مع ظهور أقرب الرموز البريدية أولًا (حتى 50). تعرض كل خزانة اسمها وعنوانها ورمزها البريدي ومدينتها وساعات عملها. إذا تعذّر تحميل القائمة أو لم تجد شيئًا، يُدخل العميل الخزانة بدلًا من ذلك.

Customer enters the locker (code or address from the Correos finder): حقل إلزامي لرمز الخزانة (مثل S0000213D) أو لعنوانها، من 3 إلى 120 حرفًا، ويحتوي على رابط لأداة البحث الخاصة بـ Correos CityPaq.

Customer chooses from my list of lockers (below): قائمة منسدلة إلزامية بالخزائن الموجودة في My lockers. تُعرض الخزائن القريبة من الرمز البريدي للعميل أولًا.

Do not ask for a locker: لا يُطرح أي سؤال عن الخزانة عند الدفع.

إذا اخترت قائمة Correos بدون بيانات اعتماد API، أو قائمتك الخاصة بينما My lockers فارغة، يُطلب من العملاء إدخال الخزانة.

My lockers: يُستخدم عندما يكون Locker selection مضبوطًا على قائمتك. خزانة واحدة في كل سطر: CODE | Name | Address | Postal code | City. الرمز والاسم إلزاميان. إذا ظهر الرمز مرتين، يُستخدم السطر الأول فقط.

قائمة Correos CityPaq (API) (تُستخدم فقط مع قائمة Correos CityPaq)

يحتوي هذا القسم على رابط لصفحة واجهة "terminals" في بوابة مطوّري Correos. تُقرأ قائمة الخزائن فقط. تأتي الأسعار دائمًا من جدول الأسعار.

API client ID: قيمة client_id لتطبيقك في بوابة مطوّري Correos.

API client secret: قيمة client_secret لتطبيقك في بوابة مطوّري Correos.

بعد الحفظ، يبقى الحقلان فارغين ويعرضان Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. حدد Remove the saved client ID and client secret ثم اضغط Save لحذفهما. عندما لا يكون هناك شيء محفوظ، يعرض القسم No credentials saved. عند تغيير بيانات الاعتماد أو اختيار الخزانة، تُمسح قوائم الخزائن المخزنة مؤقتًا.

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

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

متقدم

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

Log: يعرض حجم السجل وأحدث إدخالاته. اضغط Clear log لتفريغه.

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

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

في خطوة الشحن، يطلب PrestaShop من الوحدة سعر CityPaq. تُحتسب المنتجات المادية فقط: لا تضيف المنتجات الافتراضية وزنًا، ولا تدخل في مبلغ الطلب. تتحقق الوحدة من أن عنوان التوصيل في إسبانيا، ومن وزن السلة والحد الأدنى لمبلغ الطلب، ثم تجد صف السعر لإسبانيا (أو صف *) وحجم الطرد، وتعيد السعر. إذا انطبق الشحن المجاني، يكون السعر 0. يُحسب السعر بالعملة الافتراضية لمتجرك، ثم يُعرض بعملة سلة العميل. تُضاف الضريبة بقاعدة الضريبة الخاصة بشركة الشحن.

عندما يختار العميل CityPaq، يظهر مربع CityPaq locker أسفل شركة الشحن. يُحفظ الاختيار في السلة بمجرد أن يقوم به العميل. تُرفض الخزانة غير المقبولة برسالة، ويبقى الاختيار السابق كما هو. مع قائمة Correos، لا يُقبل رمز الخزانة إلا إذا عرضته Correos للرمز البريدي الذي بُحث عنه، ويُؤخذ اسمها وعنوانها من Correos. يمكن للعميل البحث عن 30 رمزًا بريديًا مختلفًا كحد أقصى لكل سلة. بعد ذلك يرى الرسالة Too many searches. Please enter the CityPaq locker you found on the Correos map.

زر Continue في خطوة الشحن لا يتابع بدون خزانة صالحة. ويُتحقق من ذلك على الخادم أيضًا. يرى العميل، على سبيل المثال، الرسالة Please choose the CityPaq locker where you want to collect your parcel. عند تقديم الطلب، تُحفظ خزانة السلة في الطلب.

تُطلب قائمة Correos فقط عندما يختار العميل CityPaq، وليس لكل زائر في خطوة الشحن. تُخزَّن القائمة مؤقتًا لمدة 12 ساعة لكل رمز بريدي. يُخزَّن الطلب الفاشل مؤقتًا لمدة 10 دقائق، حتى لا ينتظر الدفع Correos مع كل تحديث للصفحة. مهلة انتظار API هي 12 ثانية. لا يرى العميل الخطأ التقني أبدًا، بل رسالة قصيرة وحقل الإدخال اليدوي فقط. يعمل مربع الخزانة مع القالبين Classic وHummingbird.

لا تحصل الوحدة على تعرفات مباشرة من Correos، ولا تعرض خريطة، ولا تسجّل الشحنات مسبقًا، ولا تطبع الملصقات، ولا تطلب الاستلام، ولا تتتبع الطرود. أنشئ الشحنة في حسابك لدى Correos باستخدام الخزانة المحفوظة في الطلب.

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

تُحفظ الخزانة المختارة في الطلب. يراها العميل باسم CityPaq locker: في صفحة تأكيد الطلب وفي صفحة تفاصيل الطلب في حسابه. في بريد تأكيد الطلب وفي بريد الطلب الجديد الخاص بوحدة Mail alerts، تُضاف الخزانة إلى سطر شركة الشحن، على سبيل المثال Correos CityPaq - CityPaq locker: ....

في صفحة الطلب في لوحة الإدارة، يعرض مربع CityPaq locker الخزانة، وعند اختيارها من قائمة يعرض أيضًا Locker code:. لتغييرها، استخدم حقل Change CityPaq locker واضغط Save: مع قائمتك، اختر خزانة أخرى من القائمة المنسدلة؛ مع قائمة Correos، أدخل رمز خزانة (يُبحث عنه لدى Correos) أو عنوانًا؛ وفي الحالات الأخرى، أدخل رمزًا أو عنوانًا جديدًا. اترك الحقل فارغًا للاحتفاظ بالخزانة الحالية. يضيف كل تغيير رسالة خاصة إلى الطلب: تم تغيير خزانة CityPaq إلى: .... يحتاج تغيير الخزانة إلى صلاحية تحرير الطلبات. لا يلزم الوصول إلى صفحات Modules.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Correos CityPaq هي أول كتلة في Modules > Module Manager > VibeFox Correos CityPaq > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. تحتها السطر Product: presta-shipping-correos-citypaq والرابط Manage licenses and domains in your account، الذي يفتح حسابك على vibefox.net. يمكن للموظفين الذين لديهم إذن Configure للوحدة فقط تغيير المفتاح. تتبع نصوص الكتلة لغة back office (تشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

يعمل مفتاح واحد على نطاق واحد: نطاق المتجر الرئيسي، وكذلك في إعداد المتاجر المتعددة. إزالة المفتاح من المتجر لا تحرر خانة النطاق. حررها في حسابك على vibefox.net.

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

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

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

لا تظهر Correos CityPaq عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن عنوان التوصيل في إسبانيا. في Shipping > Carriers، تحقق من أن شركة الشحن تغطي منطقة إسبانيا ومجموعة العميل (أو فعّل Ignore shipping zones). تحقق من أن جدول الأسعار يحتوي على صف لإسبانيا أو صف *، وأن السلة ضمن حدود الوزن وMinimum order amount. كذلك قد تكون المنتجات مقيّدة بشركات شحن معينة في صفحة المنتج.

يُضطر العملاء إلى كتابة الخزانة رغم اختيار قائمة Correos: تحقق من حفظ API client ID وAPI client secret، وراجع التحذير فوق الإعدادات. يعرض التحذير آخر خطأ في Correos API. يعني HTTP 401/403 أن Correos رفض بيانات الاعتماد: تحقق منها ومن أن تطبيقك لديه صلاحية الوصول إلى واجهة "terminals". بعد أي خطأ، تُجرى المحاولة التالية بعد 10 دقائق.

لا توجد خزائن لرمز بريدي: لم تجد Correos خزائن نشطة لهذا الرمز البريدي أو لمنطقته أو لمحافظته. يمكن للعميل البحث عن رمز بريدي آخر، أو إدخال الخزانة التي وجدها في أداة البحث الخاصة بـ Correos CityPaq.

لا تظهر القائمة المنسدلة لخزائني: My lockers فارغة أو أسطرها غير صالحة. يحتاج كل سطر إلى CODE | Name على الأقل.

أين يجد العملاء رمز الخزانة: في أداة البحث الخاصة بـ Correos CityPaq المرتبطة أسفل حقل الخزانة.

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

ملاحظات للمطورين: تُخزَّن خزانة السلة والطلب في الجدول vfd_cpq_locker (مع بادئة قاعدة البيانات لديك). تستخدم الوحدة واجهة "terminals" الإنتاجية الخاصة بـ Correos.

الإلغاء

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

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