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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. املأ جدول الأسعار، واختر الطريقة التي يختار بها العميل الخزانة (راجع الإعدادات).

6. أضف VibeFox Correos CityPaq إلى منطقة الشحن الخاصة بإسبانيا في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. وهي تنطبق على جميع مناطق الشحن. عندما تضيف الطريقة إلى منطقة، لا يظهر في نافذة المنطقة سوى حقل واحد:

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

تخبرك التحذيرات أعلى الإعدادات متى لا يحتوي جدول الأسعار على أي صف صالح، ومتى لا يمكن أن يعمل خيار اختيار الخزانة المحدد (لا توجد خزائن في قائمتك، أو لا توجد بيانات اعتماد API)، وما هو آخر خطأ في Correos API. تقبل الأسعار والمبالغ الفاصلة العشرية بالفاصلة أو بالنقطة.

عام

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

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

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى الأسعار الواردة في الجدول، وNone لا يضيفها.

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

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

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

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

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

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

الشروط

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

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

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

Excluded shipping classes: يُخفي الطريقة إذا احتوت السلة على منتج من فئات شحن WooCommerce هذه، مثل الأغراض الكبيرة التي لا تتسع لها الخزانة. لا تتحقق الإضافة من أبعاد الطرود.

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

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

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

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

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

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

Customer enters the locker (code or address from the Correos finder): حقل إلزامي لرمز الخزانة (مثل S0000213D) أو لعنوانها، مع رابط إلى أداة البحث الرسمية لـ 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.

عند تغيير بيانات الاعتماد أو اختيار الخزانة، تُمسح قوائم الخزائن المخزّنة مؤقتًا.

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

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

متقدم

Debug log: يكتب أسطر التصحيح في WooCommerce > Status > Logs، ومصدرها vfd-correos-citypaq. تُسجَّل أخطاء Correos API دائمًا، حتى عندما يكون هذا الخيار متوقفًا. لا تُسجَّل بيانات الاعتماد والبيانات الشخصية أبدًا.

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

طريقة العمل عند الدفع

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

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

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

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

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

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

تُحفظ الخزانة المختارة في الطلب. وتظهر في إدارة الطلب تحت عنوان الشحن، وفي صفحة استلام الطلب، وفي My account > Orders، وفي جميع رسائل الطلبات (HTML والنص العادي) باسم CityPaq locker.

في إدارة الطلب، يمكنك تغيير الخزانة من الحقل Change CityPaq locker: اختر خزانة أخرى من قائمتك، أو اكتب رمزًا جديدًا أو عنوانًا جديدًا. مع قائمة Correos، يُتحقق من رمز الخزانة المُدخل لدى Correos. اترك الحقل فارغًا للإبقاء على الخزانة الحالية. كل تغيير يضيف ملاحظة إلى الطلب.

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

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

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

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

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

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

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

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

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

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

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

ملاحظات للمطوّرين: تُحفظ الخزانة في بيانات الطلب الوصفية _vfd_cpq_locker (النص الظاهر في كل مكان) و_vfd_cpq_locker_id (رمز الخزانة، عند اختيارها من قائمة Correos أو من قائمتك). تستخدم الإضافة واجهة "terminals" الإنتاجية الخاصة بـ Correos. لا يوجد بيئة sandbox موثّقة لهذه الواجهة.

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

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

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

Correos وCityPaq علامتان تجاريتان لمالكيهما. هذه الإضافة غير تابعة لـ Correos ولا معتمدة من قِبلها.