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

المتطلبات

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

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

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

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

التثبيت

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

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

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

4. املأ جدول الأسعار (صف واحد على الأقل Portugal أو * Default) وانقر على Save. اختياريًا، املأ مفاتيح API الخاصة بـ CTT وCarrier ID، وفعّل Live rates وEnable CTT point carrier (انظر الإعدادات).

عند التثبيت، تنشئ الوحدة شركتي شحن. CTT (توصيل إلى عنوان العميل، ونص مدة التوصيل CTT delivery to your address) مفعّلة. أما CTT point / parcel locker (ونص مدة التوصيل Pickup at a CTT point or parcel locker) فتبقى معطلة حتى تفعّلها. وكلتاهما مرتبطتان بمنطقة البرتغال وبجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

توجد جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox CTT > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. تنطبق الأسعار والشروط على شركتي CTT كلتيهما. يمسح كل حفظ ردود CTT المخزنة مؤقتًا، بما في ذلك رمز API وقوائم نقاط CTT.

تنبهك التحذيرات أعلى الإعدادات إلى: جدول أسعار فارغ، أو سعر مفقود لمنطقة البرتغال، أو مفاتيح API غير مكتملة، أو Carrier ID مفقود، أو عملة متجر غير اليورو بدون سعر صرف، أو فشل الاتصال بواجهة CTT، أو حذف شركة CTT. تُبلَّغ القيم غير الصالحة عند الحفظ: فالرقم غير الصالح لا يُحفظ، والوجهة غير المعروفة أو الصف المكرر في جدول الأسعار يُحذف. وإذا لم تتعرف الوحدة على وحدة الوزن أو الأبعاد في متجرك، يطلب منك تحذير ضبط الوحدات في International > Localization (Local units).

عام

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

Name: اسم شركة الشحن الذي يراه العميل أثناء الدفع، مثل "CTT Expresso". الافتراضي: CTT. حقل إلزامي، بحد أقصى 64 حرفًا.

Tax status: تعني None أن الأسعار نهائية. وتعني Taxable مع قاعدة ضريبة أن PrestaShop تضيف ضريبة الشحن تلك (مثل IVA) فوق الأسعار. يُحفظ الاختيار لشركتي CTT كلتيهما.

التوصيل إلى نقطة CTT أو خزانة استلام آلية

شركة CTT الثانية. يبحث العميل عن نقاط CTT بالرمز البريدي أو المدينة، ويجب أن يختار إحداها قبل المتابعة. وتحتاج إلى مفاتيح API الخاصة بـ CTT وCarrier ID. ومن دونها تكون شركة شحن بلا اختيار للنقطة.

Enable CTT point carrier: يفعّل شركة نقاط CTT أو يعطلها. وهو المفتاح نفسه لحالتها في Shipping > Carriers. الافتراضي: معطل.

CTT point carrier name: اسم هذا الخيار أثناء الدفع. الافتراضي: CTT point / parcel locker. حقل إلزامي، بحد أقصى 64 حرفًا.

واجهة برمجة التجارة الإلكترونية الخاصة بـ CTT (الأسعار الفورية، نقاط CTT) (اختياري؛ من دون المفاتيح يُستخدم جدول الأسعار)

Public key: المفتاح العام من صفحة إدارة المفاتيح في حساب CTT للتجارة الإلكترونية.

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

لا تُعرض المفاتيح مرة أخرى بعد الحفظ. عندها يعرض وصف الحقل Saved - leave empty to keep it. أدخل قيمة جديدة فقط عند الرغبة في تغييرها. فعّل Remove the saved public and private key واحفظ لحذف المفتاحين.

App ID (X-APPID): مفتاح التطبيق الصادر من CTT، ويُرسل في الترويسة X-APPID.

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

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

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

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

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

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

أدخل أسعار عقدك مع CTT أو أسعار قائمة CTT العامة على ctt.pt، بعملة المتجر الافتراضية، من دون الضرائب. عند تعطيل الأسعار الفورية يحدد هذا الجدول السعر. وعند تفعيلها يكون الجدول هو السعر البديل.

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 تعني بلا حد. لا يمكن أن تكون قيمة Min weight (kg) أكبر من Max weight (kg): فلا تُحفظ الإعدادات.

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

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

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

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

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

عادةً تُعرض شركات الشحن في مناطق الشحن المرتبطة بها في Shipping > Carriers.

Ignore shipping zones: يعرض شركات الشحن في الدول الواردة أدناه من دون ربطها بمنطقتها. عند تفعيله ترتبط الشركتان بكل منطقة نشطة (بما فيها المناطق التي تنشئها لاحقًا). وعند تعطيله تستعيدان المناطق التي كانتا مرتبطتين بها من قبل.

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

متقدم

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

Log: يعرض حجم السجل وآخر إدخالاته. انقر على Clear log لتفريغه.

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

كيف يعمل أثناء الدفع

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

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

إذا عدّلت شركة شحن في Shipping > Carriers بعد أن صارت لها طلبات، تحفظها PrestaShop كنسخة جديدة من شركة الشحن. وتتبع الوحدة النسخة الجديدة تلقائيًا.

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

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

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

عندما يختار العميل شركة نقاط CTT، يظهر تحتها حقل بحث وقائمة. يُملأ الرمز البريدي لعنوان التوصيل ويُبحث عنه تلقائيًا. يمكن للعميل البحث عن نقاط CTT أخرى بالرمز البريدي أو المدينة (زر Search أو مفتاح Enter) واختيار إحداها من القائمة. يُحفظ الاختيار في السلة فورًا. ولا يُقبل إلا نقطة من قائمة CTT لذلك البحث.

يجب اختيار نقطة قبل أن يتمكن العميل من المتابعة. عندما ينقر العميل على Continue في خطوة الشحن، تتحقق الوحدة من النقطة مرة أخرى على الخادم. وبدون نقطة يرى العميل Please select a CTT point.، وبنقطة ليست في قائمة CTT يرى The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. تُخزَّن قوائم نقاط CTT مؤقتًا لمدة 6 ساعات. وإذا تعذر الوصول إلى CTT، يرى العميل CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

يعمل اختيار النقطة مع قالبي Classic وHummingbird. ولا يكون نشطًا إلا عند ملء المفتاح العام والمفتاح الخاص ومعرّف التطبيق وCarrier ID.

تُحفظ النقطة المختارة في الطلب. وتظهر في صفحة الطلب في شاشة الإدارة ضمن كتلة CTT point (الاسم والمعرّف)، وفي صفحة تأكيد الطلب، وفي تفاصيل الطلب في حساب العميل، وفي بريد تأكيد الطلب الإلكتروني بالصيغة CTT point: بجوار اسم شركة الشحن. كما يعرض بريد الطلب الجديد الخاص بوحدة Mail alerts معرّف النقطة.

في صفحة الطلب في شاشة الإدارة، أدخل رمزًا بريديًا أو مدينة تحت Change CTT point، وانقر على Search، واختر نقطة، ثم انقر على Save. تعرض الصفحة CTT point updated. وتُضاف رسالة خاصة للطلب CTT point changed to: مع النقطة الجديدة. ويتطلب تغيير النقطة صلاحية تعديل الطلبات.

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

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

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

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

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

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

لا يستطيع العميل اختيار نقطة CTT: يظهر المحدد فقط تحت شركة نقاط CTT، ولا يظهر إلا عند ملء المفتاح العام والمفتاح الخاص ومعرّف التطبيق وCarrier ID. تحقق من التحذيرات أعلى الإعدادات، وفعّل Debug log، وانظر إلى حقل Log في صفحة الوحدة.

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

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

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

تبدو الأسعار قديمة بعد تغيير: انقر على Save في صفحة الوحدة. يؤدي ذلك إلى مسح ردود CTT المخزنة مؤقتًا.

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

للمطورين: يمكن تغيير عنوان API الخاص بـ CTT بمفتاح الإعداد vfd_ctt_API_URL.

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

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

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