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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

2. انقر على Activate.

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

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

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

6. أضف VibeFox Correios إلى منطقة شحن في WooCommerce > Settings > Shipping > Shipping zones، أو فعّل Ignore shipping zones واختر البلدان.

الإعدادات

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

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

تعرض صفحة الإعدادات تحذيرات عندما لا تعمل الأسعار اللحظية أو الطريقة: عندما تكون بعض بيانات الاعتماد الثلاث فقط مملوءة، أو عندما يكون الرمز البريدي CEP للمرسل مفقودًا، أو عندما لا يوجد سعر صرف BRL لمتجر بعملة أخرى، أو عندما لا توجد بيانات اعتماد ولا أسعار ثابتة. وفي كل مرة تحفظ فيها الإعدادات، تُمسح الأسعار المخزنة مؤقتًا ورمز API. ويمكن كتابة الأرقام بنقطة أو بفاصلة.

عام

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

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها.

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

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

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

Access code: رمز الوصول إلى API (código de acesso) الذي يُنشأ في بوابة Correios Web Services. وهو ليس كلمة مرور البوابة.

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

Homologation: يستخدم بيئة الاختبار (homologação) لدى Correios مع رمز وصول خاص بالاعتماد. أوقفه في المتجر الفعلي.

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 (kg): يُرسل إلى Correios لكل منتج لا وزن له. Default: 0.3. تُحوَّل أوزان المنتجات وأبعادها من وحدات متجرك، وتُحسب تكلفة السلة كطرد واحد.

BRL → store currency rate: يُظهر اسم الحقل عملة متجرك. أسعار Correios بالريال البرازيلي BRL. إذا لم تكن عملة متجرك BRL، فأدخل عدد وحدات عملتك التي تساوي BRL واحدًا، مثل 0.17. ومن دونه لا تُستخدم الأسعار اللحظية. وإذا كانت عملة متجرك 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 (kg): يُخفي الطريقة إذا كان وزن السلة أقل من هذا الحد. 0 يعني بلا حد.

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

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

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

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

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

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

Ignore shipping zones: يعرض الطريقة للبلدان المذكورة أدناه، أيًّا كانت المنطقة المطابقة.

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

متقدم

Debug log: يسجل حسابات الأسعار في WooCommerce > Status > Logs، بالمصدر vfd-correios. وتُسجَّل أخطاء API دائمًا حتى عند إيقاف هذا الخيار. ولا تُسجَّل بيانات مستخدم API ورمز الوصول وposting card والرمز ورموز CEP للعملاء.

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

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

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

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

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

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

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

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

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

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

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

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

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

استكشاف الأخطاء

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

تعرض الطريقة سعرًا ثابتًا بدلًا من سعر Correios: افتح WooCommerce > Status > Logs، واختر المصدر vfd-correios. يُسجَّل خطأ Correios هناك: رمز وصول خاطئ، أو خدمة غير موجودة في عقدك، أو رمز CEP غير مشمول بالخدمة، أو طرد يزيد على 30 كغ، أو يتجاوز حدود الحجم. تحقق أيضًا من أن الرمز CEP للمرسل مضبوط، وإذا لم تكن عملة المتجر BRL فمن أن سعر الصرف إلى BRL مضبوط. فعّل Debug log لرؤية كل حساب.

يفشل طلب الرمز: تحقق من مستخدم API، ورمز الوصول، وposting card، والبيئة. يعمل رمز وصول الاعتماد (homologação) فقط عند تفعيل Homologation، ويعمل رمز الإنتاج فقط عند تعطيله.

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

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

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

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

Correios علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ Correios ولا معتمدة من قبلها.