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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

عقد Correios (للأسعار اللحظية فقط): تستخدم الأسعار اللحظية واجهة برمجة أسعار Correios Web Services (CWS) وتحتاج إلى بيانات اعتماد عقد Correios مع بطاقة posting card. تحتاج إلى ثلاث قيم: مستخدم Meu Correios الخاص بك (عادةً رقم CNPJ أو CPF للعقد)، ورمز وصول API، ورقم posting card. أنشئ رمز الوصول في بوابة Correios Web Services (cws.correios.com.br؛ وللاعتماد cwshom.correios.com.br). تحتاج أيضًا إلى الرمز البريدي (CEP) الذي تشحن منه. ومن دون بيانات الاعتماد تعمل الوحدة بالأسعار الثابتة فقط.

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

التثبيت

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

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

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

4. أدخل مستخدم API الخاص بـ Correios، ورمز الوصول، ورقم posting card، والرمز البريدي (CEP) للمرسل، والخدمة. إذا لم تكن العملة الافتراضية لمتجرك هي BRL، فأدخل سعر الصرف إلى BRL. املأ الأسعار الثابتة للبلدان الأخرى وكبديل احتياطي (انظر قسم الإعدادات) ثم انقر على Save.

عند التثبيت تنشئ الوحدة شركة الشحن Correios مع نص مدة التسليم Correios (Brazilian Post). تُعيَّن شركة الشحن لجميع المناطق ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التسليم والشعار وحدود الحجم في Shipping > Carriers. لا تحدد الأسعار هناك: السعر يأتي دائمًا من الوحدة.

الإعدادات

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

تعرض الصفحة تحذيرات عندما لا تستطيع الأسعار اللحظية أو شركة الشحن العمل: ملء بعض بيانات الاعتماد الثلاث فقط، أو غياب الرمز البريدي (CEP) للمرسل، أو غياب سعر الصرف إلى BRL لمتجر بعملة أخرى، أو عدم وجود بيانات اعتماد ولا أسعار ثابتة. يوضح كل تحذير ما إذا كانت الأسعار الثابتة مستخدمة في الأثناء أو أن شركة الشحن مخفية. كما يظهر تحذير إذا كانت وحدة وزن المتجر أو وحدة أبعاده غير معروفة للوحدة (عندها تُقرأ على أنها كغ أو سم)؛ اضبط kg أو g أو lb أو oz و cm أو mm أو m أو in في International > Localization (Local units).

يُرفض الحفظ مع رسالة إذا كان عنوان الطريقة فارغًا أو غير صالح (64 حرفًا كحد أقصى)، أو إذا كان حقل رقمي أو سعر في Country prices ليس رقمًا يساوي 0 أو أكبر، أو إذا كان سعر الصرف إلى BRL يساوي 0، أو إذا كان Min cart weight أكبر من Max cart weight، أو إذا لم يكن الرمز البريدي (CEP) للمرسل مكوّنًا من 8 أرقام، أو إذا كان رمز الخدمة الآخر أطول من 5 أرقام. لا يُحفظ شيء حتى تصحح القيمة.

عام

Enable Correios: يشغّل شركة الشحن أو يوقفها في جميع المناطق دفعة واحدة. هذا هو المفتاح نفسه الذي يمثل حالة شركة الشحن في Shipping > Carriers.

Method title: اسم شركة الشحن الذي يظهر في السلة وعند الدفع. الافتراضي: Correios. مطلوب.

Tax: قاعدة الضريبة المضافة إلى تكلفة الشحن، أو No tax (الافتراضي).

واجهة Correios API (الأسعار اللحظية في البرازيل)

بالنسبة إلى العناوين في البرازيل يأتي السعر من واجهة برمجة أسعار Correios. إذا لم تعطِ API سعرًا (API متوقفة، أو الرمز البريدي غير مخدوم، أو الطرد كبير جدًا)، يُستخدم السعر الثابت من Country prices، أو تُخفى شركة الشحن إذا لم يوجد سعر ثابت. تذهب تفاصيل الأخطاء إلى السجل، ولا تصل إلى العميل أبدًا.

API user: اسم دخولك إلى بوابة Meu Correios، وعادةً رقم CNPJ أو CPF للعقد.

Access code: رمز وصول API (código de acesso) الذي يُنشأ في بوابة Correios Web Services. وهو ليس كلمة مرور البوابة. بعد الحفظ يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it (empty the API user as well to remove it). اكتب قيمة جديدة فقط إذا أردت تغييرها. لإزالة الرمز المحفوظ، أفرغ API user وAccess code معًا ثم احفظ.

Posting card: رقم posting card (cartão de postagem) الخاص بعقدك: 10 أرقام، وعادةً يبدأ برقمين صفريين، مثل 0012345678. تُكمَل الأرقام الأقصر بأصفار في البداية. يمكنك التحقق من الرقم في صفحة Correios Fácil على موقع Correios.

Homologation: يستخدم بيئة الاختبار (الاعتماد) لدى Correios: تذهب الطلبات إلى apihom.correios.com.br برمز وصول اعتماد. أوقفه في متجر فعلي.

Origin CEP: الرمز البريدي (CEP) المكوّن من 8 أرقام الذي تُرسل منه الطرود، مثل 01001-000.

Service: خدمة Correios التي تُسعَّر عند الدفع. رموز التجزئة: PAC (04510، الافتراضي)، وSEDEX (04014)، وSEDEX 12 (04782)، وSEDEX 10 (04790)، وSEDEX Hoje (04804). رموز العقد: PAC (03298)، وSEDEX (03220)، وSEDEX 12 (03140)، وSEDEX 10 (03158)، وSEDEX Hoje (03204)، وCorreios Mini Envios (04227). تحتاج رموز العقد إلى بطاقة posting card لعقد يتضمن الخدمة.

Other service code: اختياري، رمز خدمة مكوّن من 5 أرقام من عقدك غير موجود في القائمة، مثل 03085. يُكمَل الرمز الأقصر بأصفار في البداية. عند ملئه يُستخدم بدلًا من Service.

Package format: نوع الشحنة المرسلة إلى Correios.

Default product weight: بالكيلوغرام، يُرسل إلى Correios لكل منتج لا وزن له. الافتراضي: 0.3. تُحوَّل أوزان المنتجات وأبعادها من وحدات متجرك (يعرضها وصف الحقل)، ويُسعَّر الطلب كطرد واحد.

BRL → store currency rate: يعرض اسم الحقل عملة متجرك الافتراضية، مثل BRL → EUR rate. أسعار Correios بالريال البرازيلي (BRL). إذا لم تكن عملتك الافتراضية BRL، فأدخل عدد وحدات عملتك التي تساوي BRL واحدًا، مثل 0.17. من دون هذا السعر لا تُستخدم الأسعار اللحظية. يجب أن يكون سعر الصرف أكبر من 0. إذا كانت عملتك الافتراضية BRL فاترك الحقل فارغًا.

الأسعار الثابتة (تُستخدم للبلدان خارج البرازيل، ومن دون بيانات اعتماد API، وكبديل احتياطي عندما لا تعطي API سعرًا)

Country prices: جدول بالبلدان، لكل بلد سعر Base وأسعار حسب وزن السلة بعملة متجرك الافتراضية، من دون ضريبة: XS حتى 1 كغ، وS من 1 إلى 2 كغ، وM من 2 إلى 3 كغ، وL من 3 إلى 5 كغ، وXL أكثر من 5 كغ. إذا كان سعر الحجم فارغًا أو صفرًا يُستخدم سعر Base. انقر على Add country لإضافة صف، وعلى علامة الإغلاق لحذف صف. يحدد الصف * Default (all other countries) الأسعار لجميع البلدان التي ليس لها صف خاص بها. البلد الذي لا يملك صفًا (ولا يندرج تحت *) لا يحصل على سعر ثابت. لا يُحفظ أي صف من دون أي سعر. السعر الذي ليس رقمًا، أو السالب، يوقف الحفظ برسالة خطأ. سعر أساسي يساوي 0 يعني شحنًا مجانيًا لذلك البلد.

Fixed price per: Order يحتسب السعر مرة واحدة. Item (price × quantity) يضربه في عدد العناصر في السلة. هذا ينطبق على الأسعار الثابتة فقط. تُحسب الأسعار اللحظية دائمًا للطرد كاملًا.

الشروط

Min cart weight: بالكيلوغرام، يخفي شركة الشحن إذا كان وزن السلة أقل من هذا. 0 يعني بلا حد. لا يمكن أن يكون أكبر من Max cart weight.

Max cart weight: بالكيلوغرام، يخفي شركة الشحن إذا كان وزن السلة أعلى من هذا. الافتراضي: 30. 0 يعني بلا حد، والحقل الفارغ يعني 30 كغ. يمكن أن يصل وزن طرود Correios PAC وSEDEX إلى 30 كغ.

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

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

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

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

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

Ignore shipping zones: يعرض شركة الشحن للبلدان أدناه، أيًا كانت المنطقة المطابقة. عند الحفظ تُضاف شركة الشحن إلى جميع المناطق. إيقاف الخيار يزيل المناطق التي أضافها. المنطقة التي تُنشأ لاحقًا والخيار مفعّل تُضاف تلقائيًا.

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

متقدم

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

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

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

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

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

بالنسبة إلى عنوان في البرازيل مع بيانات اعتماد مُعدّة، تحصل الوحدة أولًا على رمز API لـ posting card الخاصة بك. يعطي الرمز أيضًا أرقام العقد ومكتب المنطقة، لذلك يكون السعر هو سعر عقدك. ثم تطلب سعر الخدمة المختارة بحسب الرمز البريدي (CEP) للمرسل والمستلم، ووزن الطرد بالغرام، وحجم الطرد بالسم. لا يُطلب السعر إلا عندما يكون الرمز البريدي للمستلم مكوّنًا من 8 أرقام. عندما تكون أبعاد جميع المنتجات معروفة، يُقدَّر حجم الطرد منها؛ وإلا يُرسل الحد الأدنى لحجم Correios. لا تُرسل الطرود التي تزيد على 30 كغ إلى API. يُحوَّل سعر BRL بسعر صرفك. يُحسب السعر بالعملة الافتراضية لمتجرك ثم يُعرض بعملة سلة العميل.

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

إذا لم تعطِ API سعرًا، يُستخدم السعر الثابت، أو تُخفى شركة الشحن إذا لم يوجد سعر ثابت. لا يرى العميل تفاصيل أخطاء API أبدًا؛ فهي تذهب إلى سجل التصحيح.

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

تحسب الوحدة الأسعار فقط. لا تحصل على أسعار Correios الدولية (Exporta Fácil وPacket)، ولا تقديرات مدة التسليم، ولا الملصقات، ولا التسجيلات المسبقة، ولا الإقرارات الجمركية، ولا التتبع. لا يستطيع العملاء اختيار وكالة Correios أو خزانة استلام. لا تُضاف الخدمات الإضافية (القيمة المصرّح بها، والتسليم باليد، وإشعار الاستلام). تعرض الوحدة خدمة Correios واحدة لكل متجر، ولا تُحدَّث أسعار صرف العملات تلقائيًا.

الطلبات

عند تقديم طلب بشركة الشحن Correios تحفظ الوحدة طريقة احتساب سعر شحنه. تعرض صفحة الطلب في back office عندها كتلة Correios تتضمن Correios service (للسعر اللحظي، مثل PAC — contract (03298)) وPrice source: Live price (Correios API) أو Fixed price أو Free shipping.

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

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

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

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

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

لا يظهر Correios عند الدفع: تحقق من أن الترخيص نشط وأن Enable Correios مفعّل. في Shipping > Carriers تحقق من أن شركة الشحن تغطي منطقة بلد العميل ومجموعة العميل (أو أن Ignore shipping zones مفعّل والبلد مسموح به). راجع حدود الوزن وMinimum order amount. من دون سعر لحظي يجب أن يوجد سعر ثابت للبلد أو لـ *. قد تكون المنتجات مقيّدة أيضًا بشركات شحن معينة في صفحة المنتج.

تعرض شركة الشحن سعرًا ثابتًا بدلًا من سعر Correios: انظر إلى حقل Log في صفحة الوحدة. تُسجَّل أخطاء Correios هناك: رمز وصول خاطئ، أو خدمة غير موجودة في عقدك، أو رمز بريدي غير مخدوم، أو طرد يزيد على 30 كغ أو على حدود الحجم. تحقق أيضًا من تعيين الرمز البريدي للمرسل، ومن أن الرمز البريدي للعميل مكوّن من 8 أرقام، وإذا لم تكن العملة الافتراضية BRL فمن سعر الصرف إلى BRL. فعّل Debug log لرؤية كل حساب.

يفشل طلب الرمز: تحقق من مستخدم API ورمز الوصول وposting card والبيئة. يعمل رمز وصول الاعتماد فقط عندما يكون Homologation مفعّلًا، ويعمل رمز الإنتاج فقط عندما يكون متوقفًا.

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

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

يقول الحفظ إنك لا تملك الإذن: يمكن لملف الموظف الخاص بك عرض الوحدة لكن لا يمكنه ضبطها. يحتاج حفظ الإعدادات وتفريغ السجل إلى إذن إعداد الوحدة.

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

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

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