VibeFox CTT for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب التجارة الإلكترونية لدى CTT (للأسعار الفورية ونقاط CTT فقط): تستخدم الأسعار الفورية والتوصيل إلى نقطة CTT واجهة برمجة التجارة الإلكترونية لدى CTT. تحتاج إلى حساب تجارة إلكترونية لدى CTT على enviosecommerce.ctt.pt (لعملاء عقد CTT Expresso، أو اطلب عرضًا من CTT). في صفحة إدارة المفاتيح في ذلك الحساب، أنشئ زوج مفاتيح عام وخاص. يُصدر CTT معرّف التطبيق App ID (X-APPID) لتكاملك: اسأل جهة الاتصال لديك في CTT للتجارة الإلكترونية. كما تحدد CTT وظائف الواجهة البرمجية (تقدير التكلفة، نقاط CTT) التي يمكن لمعرّف التطبيق الخاص بك استخدامها. وأخيرًا، تحتاج إلى معرّف الناقل Carrier ID لدى CTT في حسابك. تعرض صفحة الإعدادات ناقلي حسابك بعد حفظ المفاتيح. وإذا كنت تستخدم جدول الأسعار والتوصيل المنزلي فقط، فلا تحتاج إلى مفاتيح API.

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

التثبيت

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

2. انقر Activate.

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

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

5. املأ جدول الأسعار (صف واحد على الأقل Portugal أو * Default). ويمكنك اختياريًا إدخال مفاتيح API الخاصة بـ CTT ومعرّف الناقل، ثم تفعيل Live rates (انظر الإعدادات).

6. في WooCommerce > Settings > Shipping > Shipping zones، افتح منطقة لـ Portugal أو أنشئها، وأضف VibeFox CTT. في إعدادات الطريقة، اختر العنوان ونوع التوصيل. أو فعّل Ignore shipping zones واختر الدول.

الإعدادات

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

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

Delivery: To the customer's address (الافتراضي) أو To a CTT point or parcel locker chosen at checkout. تحتاج نقطة CTT إلى مفاتيح API الخاصة بـ CTT ومعرّف الناقل في الإعدادات العامة. أضف الطريقة إلى المنطقة مرتين لتعرض التوصيل المنزلي وتوصيل نقطة CTT جنبًا إلى جنب.

تنبهك التحذيرات أعلى الإعدادات إلى سعر مفقود لـ Portugal، ومفاتيح API غير مكتملة، ومعرّف ناقل مفقود، وعملة متجر بلا سعر صرف، وفشل الاتصال بواجهة CTT البرمجية. وفي كل مرة تحفظ فيها الإعدادات، تُمسح ردود CTT المخزنة مؤقتًا.

عام

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

Name: اسم طريقة الشحن الذي يظهر في صفحة الدفع، مثل "CTT Expresso". الافتراضي: CTT. وTitle المنطقة يحل محله.

Tax status: Taxable يضيف ضريبة شحن WooCommerce (مثل IVA) فوق السعر، وNone يعني أن السعر نهائي.

واجهة CTT e-commerce البرمجية (الأسعار الفورية، نقاط CTT) (اختياري؛ من دون مفاتيح يُستخدم جدول الأسعار)

Public key: المفتاح العام من صفحة إدارة المفاتيح في حساب CTT e-commerce الخاص بك.

Private key: المفتاح السري المستخدم لتوقيع كل طلب (HMAC-SHA256). لا يُرسل إلى CTT أبدًا ولا يُكتب في السجل.

App ID (X-APPID): مفتاح التطبيق الذي يُصدره CTT لتكاملك.

Carrier ID: معرّف ناقل CTT في حسابك، ويُستخدم للأسعار الفورية والبحث عن نقاط CTT. بعد حفظ المفاتيح، يُعرض ناقلو حسابك أسفل الحقل، ويُعلَّم منهم من يدعم نقاط CTT.

Live rates: يطلب من CTT السعر (تقدير التكلفة) بمجرد أن يُدخل العميل الشارع والرمز البريدي والمدينة. يُستخدم جدول الأسعار طالما كان العنوان غير مكتمل، وكلما لم تُعِد CTT سعرًا. وتسمي CTT هذا السعر تقديرًا. الافتراضي: مُعطّل.

Service ID: اختياري. عندما تعيد CTT عدة خدمات، تُستخدم الخدمة التي تحمل هذا ServiceId. اتركه فارغًا لاستخدام الأرخص.

Exchange rate: أسعار CTT بالأورو. إذا كانت عملة متجرك مختلفة، فأدخل عدد وحدات عملة متجرك التي تساوي وحدة واحدة من عملة CTT. من دون ذلك لا تُستخدم الأسعار الفورية بعملة أخرى، ويُطبَّق جدول الأسعار.

Default product size (cm): الطول × العرض × الارتفاع المرسلة إلى CTT للمنتجات التي ليس لها أبعاد. الافتراضي: 30x20x15. المنتجات التي لها أبعاد تستخدم أبعادها الخاصة. تُحوَّل الأبعاد إلى سم، والأوزان إلى غرامات من وحدات متجرك.

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

أدخل أسعار عقد CTT الخاص بك أو قائمة أسعار CTT العامة، بعملة المتجر. عندما تكون الأسعار الفورية مُعطّلة، يحدد هذا الجدول السعر. وعندما تكون مُفعّلة، يكون جدول الأسعار هو البديل.

Price table: صف لكل وجهة. اختر دولة، أو Portugal - Azores (PT-AC)، أو Portugal - Madeira (PT-MA)، أو * Default (other destinations). يحتوي كل صف على سعر أساسي (Price) وأسعار اختيارية للأحجام XS (حتى 1 كغ)، وS (حتى 2 كغ)، وM (حتى 3 كغ)، وL (حتى 5 كغ)، وXL (أكثر من 5 كغ). إذا كان سعر الحجم فارغًا (أو 0) يُستخدم السعر الأساسي. والصف الذي يكون فيه الاثنان فارغين يُخفي الطريقة. يُطبَّق صف Azores على الرموز البريدية البرتغالية 9500-9999، ويُطبَّق صف Madeira (بما في ذلك Porto Santo) على 9000-9499. ومن دونهما يُطبَّق صف Portugal. انقر + Add destination لإضافة صف، والعلامة × لحذف صف. تقبل الأسعار النقطة أو الفاصلة العشرية. تُعرض الصفوف غير الصالحة عند الحفظ.

Calculation: كيفية تحديد سعر الجدول.

السعر الفوري من CTT يكون دائمًا للشحنة كاملة.

الشروط

Min weight (kg): الحد الأدنى لوزن السلة لكي تظهر الطريقة. 0 يعني بلا حد.

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

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

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

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

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

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

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

Ignore shipping zones: اعرض الطريقة في الدول أدناه عندما لا تحتوي منطقة العميل عليها.

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

متقدم

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

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

كيف تعمل في صفحة الدفع

عندما يُدخل العميل عنوان التوصيل، يطلب WooCommerce من الإضافة سعرًا. تتحقق الإضافة أولًا من وزن السلة والحد الأدنى لمبلغ الطلب وفئات الشحن المستثناة. مع تفعيل Live rates وعنوان مكتمل، ترسل إلى CTT عنوان التوصيل، ولكل سطر في السلة الكمية والوزن بالغرام والأبعاد بالسم، وتعرض السعر الذي تعيده. وإلا، أو عندما لا تعيد CTT سعرًا (خطأ في الواجهة البرمجية، أو انتهاء المهلة، أو عدم وجود تغطية، أو عدم تفعيل الوظيفة لمعرّف التطبيق الخاص بك)، يأتي السعر من الجدول. وإذا انطبق الشحن المجاني، يكون السعر 0.

يُخزَّن سعر CTT مؤقتًا لمدة ساعة، فلا يُرسل الطلب نفسه طلبًا جديدًا. ويُتذكَّر الطلب الفاشل لمدة 5 دقائق، فلا تنتظر صفحة الدفع CTT عند كل تحديث. مهلة الواجهة البرمجية 12 ثانية.

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

عند ملء مفاتيح API، ترسل الإضافة إلى CTT عنوان التوصيل وأوزان المنتجات وأبعادها ورابط متجرك، لتحصل على سعر أو على أقرب نقاط CTT.

لا تنشئ الإضافة شحنات، ولا تطبع ملصقات، ولا تطلب عمليات استلام، ولا توفر أرقام تتبع، ولا تعرض خريطة لنقاط CTT. يوجد جدول أسعار واحد ومجموعة واحدة من إعدادات API للمتجر بأكمله. وتختلف المناطق بالعنوان ونوع التوصيل فقط.

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

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

تُحفظ النقطة المختارة في الطلب. وتظهر في شاشة إدارة الطلب أسفل عنوان الشحن، وفي صفحة الطلب المستلم، وفي My account > Orders، وفي رسائل البريد الإلكتروني للطلبات (HTML ونص عادي) باسم CTT point.

في شاشة إدارة الطلب، انقر Change بجوار نقطة CTT، وابحث بالرمز البريدي أو المدينة، واختر نقطة أخرى. يُحفظ التغيير فورًا ويُضيف ملاحظة إلى الطلب.

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

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

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

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

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

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

لا يظهر CTT في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مُفعّل، وأن الطريقة مضافة إلى منطقة دولة العميل (أو أن Ignore shipping zones مُفعّل والدولة مسموح بها). تحقق من أن الوجهة لها صف في جدول الأسعار (أو صف * Default)، وأن وزن السلة ضمن Min weight وMax weight، وأن Minimum order amount قد تحقق، وأن لا منتج ينتمي إلى فئة شحن مستثناة.

لا يستطيع العميل اختيار نقطة CTT: لا يظهر المحدد إلا لطريقة منطقة يكون فيها Delivery نقطة CTT، وفقط عند ملء المفتاح العام والمفتاح الخاص و App ID و Carrier ID. فعّل Debug log وتحقق من WooCommerce > Status > Logs.

لا تظهر الأسعار الفورية: يُستخدم جدول الأسعار حتى يُدخل العميل الشارع والرمز البريدي والمدينة. تحقق من التحذيرات أعلى الإعدادات ومن السجل. الرد "405" يعني أن الوظيفة غير مفعّلة لمعرّف التطبيق الخاص بك: اسأل CTT. وفي متجر لا يستخدم اليورو، املأ Exchange rate.

فشل الاتصال بواجهة CTT البرمجية: يعرض التحذير أعلى الإعدادات الخطأ. تحقق من المفاتيح ومن App ID. تعيد الإضافة المحاولة تلقائيًا بعد بضع دقائق.

أسعار شاملة الضريبة أو غير شاملة: مع Tax status على Taxable، يضيف WooCommerce ضريبة الشحن فوق السعر. مع None، يكون السعر نهائيًا.

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

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

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

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