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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Servientrega (للأسعار الفورية فقط): تستخدم الأسعار الفورية واجهة Servientrega Cotizador Corporativo (واجهة عروض الأسعار للشركات). تحتاج إلى حساب شركات (ائتماني) لدى Servientrega بصلاحية الوصول إليها. تحتاج إلى ثلاث قيم: اسم المستخدم وكلمة المرور ورمز الفوترة (código de facturación، ويبدأ عادةً بـ SER). وهي بيانات اعتماد SISCLINET الخاصة بك، ويصدرها مستشارك التجاري لدى Servientrega. إذا كنت تستخدم الأسعار الثابتة فقط، فلا تحتاج إلى حساب Servientrega.

الوصول إلى الخادم (للأسعار الفورية فقط): يجب أن يتمكن خادمك من الوصول إلى web.servientrega.com عبر HTTP على المنفذ 8058 (واجهة عروض الأسعار) والمنفذ 8081 (خدمة الويب لتشفير كلمات المرور).

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

التثبيت

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

2. انقر على Activate.

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

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

5. للأسعار الفورية، أدخل المستخدم وكلمة المرور ورمز الفوترة، واختر منتج Servientrega، وأدخل رمز DANE لنقطة الانطلاق، وإذا لم تكن عملة متجرك COP فأدخل سعر صرف العملة (انظر الإعدادات).

6. اختياريًا، أضف أسعارًا ثابتة حسب الدولة والوزن، وتكلفة احتياطية.

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

الإعدادات

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

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

في كل مرة تحفظ فيها الإعدادات، تُمسح عروض أسعار Servientrega المخزنة مؤقتًا ورمز تسجيل الدخول. وإذا تعذّر عمل الأسعار الفورية بالإعدادات المحفوظة، فسيعرض تحذير أعلى الإعدادات السبب: غياب اسم المستخدم أو كلمة المرور أو رمز الفوترة، أو غياب سعر الصرف، أو غياب رمز DANE لنقطة الانطلاق.

عام

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

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

واجهة Servientrega البرمجية (أسعار فورية لكولومبيا) (اختياري؛ بدون بيانات الاعتماد تُستخدم الأسعار الثابتة فقط)

User (login): اسم مستخدم Servientrega / SISCLINET الخاص بك.

Password: كلمة مرور Servientrega / SISCLINET كما تكتبها. يُشفّرها البرنامج الإضافي عبر خدمة Servientrega الإلكترونية قبل تسجيل الدخول، كما يفعل عميل Servientrega الرسمي.

Billing code: رمز الفوترة (código de facturación) لحسابك في Servientrega، ويظهر في SISCLINET. ويبدأ عادةً بـ SER.

الحقول الثلاثة كلها مطلوبة للأسعار الفورية. تُطلب الأسعار الفورية للوجهات داخل كولومبيا فقط. تستخدم الدول الأخرى الأسعار الثابتة.

Servientrega product: الخدمة في اتفاقيتك مع Servientrega التي يُطلب عرض سعرها.

الوزن المحاسَب هو الأكبر بين الوزن الفعلي والوزن الحجمي.

Currency conversion rate: تُسعِّر Servientrega بعملة COP. إذا لم تكن عملة متجرك COP، فأدخل قيمة 1 COP بعملة متجرك، على سبيل المثال 0.00023. وتُحوَّل القيمة المعلنة للطرد إلى COP بالطريقة نفسها. اتركه فارغًا إذا كانت عملة متجرك COP. وإذا كان متجرك يستخدم عملة أخرى وكان هذا الحقل فارغًا، فلا تُستخدم الأسعار الفورية وتُطبَّق الأسعار الثابتة. لا يجلب البرنامج الإضافي أسعار الصرف. ويُقبل كل من النقطة والفاصلة كفاصل عشري.

نقطة الانطلاق (تُستخدم للأسعار الفورية)

Origin city (DANE code): رمز DANE المكوّن من 8 أرقام للبلدية التي تشحن منها، على سبيل المثال 11001000 Bogotá، أو 05001000 Medellín، أو 76001000 Cali، أو 08001000 Barranquilla. ويُقبل أيضًا رمز البلدية المكوَّن من 5 أرقام. إذا كان فارغًا وكان عنوان متجرك في WooCommerce > Settings > General في كولومبيا، فتُستخدم بلدية عنوان المتجر.

الأسعار الثابتة (تُستخدم عند عدم وجود سعر فوري: لا توجد بيانات اعتماد، أو الوجهة خارج كولومبيا، أو البلدية غير معروفة، أو سعر الصرف مفقود، أو خطأ في الواجهة البرمجية، أو لا تغطية للمسار)

Price per country: جدول بالدول والأسعار بعملة متجرك. انقر على + Add country لإضافة صف، وعلى علامة × لحذف صف. يُطبَّق Price على أي وزن. تحل أعمدة الأوزان XS ≤1 kg وS 1–2 kg وM 2–3 kg وL 3–5 kg وXL >5 kg محل Price لذلك الوزن عندما تكون قيمتها أكبر من 0. ويُطبَّق الصف * Default على جميع الدول التي ليس لها صف خاص.

Fallback cost: يُستخدم عند عدم وجود سعر فوري ولا يطابق أي صف في الجدول. اتركه فارغًا لإخفاء الطريقة في هذه الحالة.

Fixed price applies: كيفية تحصيل الأسعار الثابتة.

الأسعار الفورية من Servientrega تُحسب دائمًا لكل شحنة.

الشروط

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

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

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

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

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

Tax status: Taxable يضيف ضريبة WooCommerce إلى تكلفة الشحن، وNone لا يضيفها. تتضمن عروض أسعار Servientrega (ValorTotal) رسوم الناقل مسبقًا. اختر None إذا كنت لا تريد إضافة ضريبة فوقها.

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

Ignore shipping zones: يعرض Servientrega للدول المذكورة أدناه، حتى لو لم تُضف الطريقة إلى أي منطقة شحن.

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

متقدم

Debug log: يكتب حسابات الأسعار وأخطاء الواجهة البرمجية في سجل WooCommerce: WooCommerce > Status > Logs، المصدر vfd_servientrega. لا تُسجَّل بيانات الاعتماد ولا الرموز ولا عناوين العملاء. أوقف السجل عند الانتهاء.

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

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

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

بالنسبة إلى وجهة في كولومبيا مع بيانات اعتماد مُعدّة، يجد البرنامج رمز DANE لبلدية العميل. يستخدم رمز DANE المكتوب في الرمز البريدي أو في حقل المدينة، أو يطابق القسم والمدينة مع الجدول المدمج الذي يضم نحو 1,130 بلدية. تُتجاهل علامات التشكيل و"D.C.". ويُعثر على اسم المدينة الموجود في قسم واحد فقط حتى بدون ذكر القسم.

ثم يرسل البرنامج إلى Servientrega قطعة واحدة لكل طلب: الوزن الإجمالي محوّلًا من وحدة متجرك إلى كجم، وصندوقًا بطول وعرض أكبر منتج والحجم الإجمالي لجميع المنتجات، محوّلًا إلى سم. وتُحسب المنتجات التي لا أبعاد لها بأبعاد 10 × 10 × 10 سم. والقيمة المعلنة هي المجموع الفرعي للسلة محوّلًا إلى COP، بحد أدنى 6,000 COP. تعيد Servientrega الإجمالي بعملة COP، ويحوّله البرنامج إلى عملة متجرك.

يُحفظ رمز تسجيل الدخول حتى انتهاء صلاحيته، لمدة أقصاها 4 أيام. يُجدَّد الرمز المرفوض تلقائيًا مرة واحدة. تُخزَّن كل عروض الأسعار مؤقتًا لمدة ساعة واحدة لكل مسار وطرد، فلا تُنشئ السلة نفسها طلبًا جديدًا. ويُخزَّن الطلب الفاشل (التشفير أو تسجيل الدخول أو عرض السعر) مؤقتًا لمدة 10 دقائق، حتى لا تنتظر صفحة الدفع Servientrega عند كل تحديث. مهلة الانتظار 10 ثوانٍ لكل طلب.

إذا لم يوجد سعر فوري، يأتي السعر من جدول الأسعار الثابتة، ثم من Fallback cost. وإذا لم ينطبق أيٌّ منهما، تُخفى الطريقة. ولا يرى العميل أي خطأ من الواجهة البرمجية أبدًا. ويُكتب السبب في سجل التصحيح.

تعمل الطريقة في صفحة الدفع الكلاسيكية وفي كتلتي Cart وCheckout. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS). وتتضمن ترجمات إسبانية (كولومبيا، إسبانيا).

يحسب البرنامج الإضافي الأسعار فقط. ولا ينشئ بوالص الشحن (guías) أو الملصقات أو الستيكرات، ولا يطلب استلام الشحنات، ولا يتتبع الشحنات أو يلغيها، ولا يتيح للعملاء اختيار مكتب Servientrega (Centro de Soluciones). أنشئ البوليصة في SISCLINET أو في بوابة Servientrega الخاصة بك. ولا يُقدَّم تسعير للدفع عند الاستلام (logística de recaudo). والأسعار الفورية للشحنات المحلية داخل كولومبيا فقط. وتستخدم إكوادور وبيرو وبنما والشحنات الدولية الأسعار الثابتة.

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

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

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

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

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

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

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

الأسعار الفورية لا تظهر: فعّل Debug log، وأعد تحميل صفحة الدفع، وافتح WooCommerce > Status > Logs، مع اختيار المصدر vfd_servientrega. ومن الأسباب الشائعة: غياب سعر الصرف (عملة المتجر ليست COP)، أو غياب رمز DANE لنقطة الانطلاق، أو أن قسم العميل أو مدينته لم تُدخل بعد أو ليست بلدية معروفة، أو بيانات اعتماد خاطئة، أو عدم وجود تغطية للمسار. وتغطي الأسعار الثابتة هذه الحالات إذا حددتها.

فشل تسجيل الدخول: تحقّق من المستخدم وكلمة المرور ورمز الفوترة مع مستشارك التجاري لدى Servientrega. وبعد فشل تسجيل الدخول ينتظر البرنامج الإضافي 10 دقائق قبل المحاولة التالية. احفظ الإعدادات لإعادة المحاولة فورًا.

مدينة العميل غير معروفة: يُطابَق القسم والمدينة مع جدول DANE المدمج. وللكتابات النادرة، يمكن للعميل إدخال رمز DANE المكوّن من 8 أرقام في مكان الرمز البريدي. ويمكن للمطورين ربطه بالفلتر vfd_svtg_dane_code.

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

للمطورين: تعدّل الفلاتر vfd_svtg_quote_request وvfd_svtg_default_dimensions طلب عرض السعر وأبعاد المنتجات التي لا أبعاد لها. وتغيّر vfd_svtg_api_base وvfd_svtg_soap_url نقاط النهاية، على سبيل المثال إذا زوّدتك Servientrega بخادم آخر.

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

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

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

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