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

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعدها (تم الاختبار على 4.1.0.3).

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. يعمل مفتاح واحد على نطاق واحد.

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم لكلا إصداري OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt، وحزمة OpenCart 3 vfd_servientrega-oc3-(version).ocmod.zip، وحزمة OpenCart 4 vfd_servientrega.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص هو نفسه للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف vfd_servientrega-oc3-(version).ocmod.zip. لا تضيف الإضافة أي تعديلات OCMOD، لذا لا تحتاج إلى تحديث Extensions > Modifications. بدلاً من Installer، يمكنك نسخ محتويات مجلد upload الموجود في الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر نوع الإضافات Shipping، وابحث عن VibeFox Servientrega، ثم انقر على Install (زر + الأخضر).

3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات.

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

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

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

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف vfd_servientrega.ocmod.zip. لا تغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، والحزمة المعاد تسميتها لا تعمل.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions، واختر نوع الإضافات Shipping، وابحث عن VibeFox Servientrega، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوات 4 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

بعد التثبيت تبقى الطريقة معطّلة حتى تفعّل Enable Servientrega وتحفظ. إذا أعدت تثبيت الإضافة بعد إلغاء تثبيتها، فستُستخدم إعدادات Servientrega التي احتفظت بها من جديد.

الإعدادات

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

إذا تعذر عمل الأسعار الفورية مع الإعدادات المحفوظة، فإن تحذيراً فوق الإعدادات يوضح السبب: غياب المستخدم أو كلمة المرور أو رمز الفوترة، أو غياب سعر الصرف، أو غياب رمز DANE للمنشأ. يظهر تحذير أيضاً إذا لم يكن لدى المتجر فئة وزن بالكيلوغرام أو فئة طول بالسنتيمتر ولم تكن وحدته الافتراضية معروفة للإضافة؛ فتُقرأ الأوزان بالكيلوغرام والأبعاد بالسنتيمتر. عند الحفظ، تُرفض بخطأ ودون حفظ أي شيء: القيمة غير الرقمية، والعدد السالب، وسعر الصرف 0، والحد الأدنى للوزن الأكبر من الحد الأقصى، والسعر الخاطئ في الجدول، وعنوان الطريقة الفارغ أو الذي يتجاوز 64 حرفاً أو يحتوي على < > ; = # { }، أو ترتيب الفرز الذي ليس عدداً صحيحاً.

عام

Enable Servientrega: يعرض Servientrega عند الدفع أو يخفيها. الافتراضي: معطّل.

Method title: اسم طريقة الشحن الذي يراه العميل في السلة وعند الدفع. الافتراضي: Servientrega. مطلوب، بحد أقصى 64 حرفاً.

Sort order: ترتيب Servientrega بين طرق الشحن عند الدفع. رقم صحيح.

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

User (login): مستخدم Servientrega / SISCLINET الخاص بك. مسح هذا الحقل يحذف كلمة المرور المحفوظة أيضاً.

Password: كلمة مرور Servientrega / SISCLINET الخاصة بك، كما تكتبها. تُشفّرها الإضافة عبر خدمة Servientrega الإلكترونية قبل تسجيل الدخول. بعد الحفظ يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

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، يوضح الحقل أنه لا حاجة إلى تحويل: اتركه فارغاً. إذا كان متجرك يستخدم عملة أخرى وكان هذا الحقل فارغاً، فلا تُستخدم الأسعار الفورية وتُطبَّق الأسعار الثابتة. لا تجلب الإضافة أسعار الصرف. ويُقبل كل من النقطة والفاصلة كفاصل عشري.

Ship from (يُستخدم للأسعار الفورية)

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

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

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

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

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

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

Conditions

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

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

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

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

Tax class: فئة الضريبة لتكلفة الشحن، أو No tax (الافتراضي). تتضمن عروض Servientrega (ValorTotal) رسوم الناقل مسبقاً. اختر No tax إذا كنت لا تريد إضافة ضريبة فوقها.

Geo zone: اعرض Servientrega فقط للعناوين في هذه المنطقة الجغرافية. All zones (الافتراضي) يعني دون حد. تُدار المناطق الجغرافية في System > Localisation > Geo Zones. لا يتم التحقق منها عندما تكون Ignore shipping zones مفعّلة.

Availability without geo zone

عادةً تُعرض الطريقة في المنطقة الجغرافية المحددة في Conditions، أو في كل مكان.

Ignore shipping zones: اعرض Servientrega للبلدان أدناه بغض النظر عن المنطقة الجغرافية.

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

Advanced

Debug log: يكتب حسابات الأسعار وأخطاء API في storage/logs/vfd_svtg_debug.log.php. لا يمكن قراءة الملف من الويب. لا تُسجَّل بيانات الاعتماد أو الرموز أو عناوين العملاء. عندما يكون السجل معطّلاً، لا يُكتب شيء، بما في ذلك أخطاء API. عندما يصل الملف إلى 5 ميغابايت، يُنقل إلى vfd_svtg_debug.old.log.php ويبدأ سجل جديد. أوقف السجل عندما تنتهي.

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

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

Import / Export

Export: انقر على Download JSON لحفظ الإعدادات كملف JSON. لا تُصدَّر كلمة المرور.

Import: الصق ملف JSON المُصدَّر سابقاً وانقر على Import لاستعادة الإعدادات، مثلاً في متجر آخر. تُفحص القيم كما في الحفظ العادي. تبقى كلمة المرور المحفوظة ما دام المستخدم مُعدّاً.

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

عندما يعرض OpenCart طرق الشحن، يطلب من الإضافة سعر Servientrega. إذا كانت Geo zone محددة والعنوان خارجها، فلا تُعرض Servientrega (إلا إذا كانت Ignore shipping zones مفعّلة). لا تُحتسب إلا المنتجات التي يكون فيها Requires Shipping على Yes: أما الأخرى فلا تضيف وزناً ولا تدخل في مبلغ الطلب. مبلغ الطلب هو سعر هذه المنتجات بعد خصم القسيمة وقبل الضريبة. لا تُحتسب بطاقات الهدايا ونقاط المكافآت. تتحقق الإضافة أولاً من الشروط: بلد التوصيل (مع Ignore shipping zones)، ووزن السلة، والحد الأدنى لمبلغ الطلب. إذا انطبق الشحن المجاني، يكون السعر 0 ولا يُرسل أي طلب إلى Servientrega. ثم تبحث عن سعر: السعر الفوري لـ Servientrega، ثم جدول الأسعار، وأخيراً التكلفة الاحتياطية. إذا لم يوجد سعر، تُخفى الطريقة لتلك السلة.

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

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

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

لا يرى العميل أبداً خطأ API. يُكتب السبب في سجل التصحيح عندما يكون مفعّلاً.

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

في OpenCart 4 ينقر العميل على Choose في كتلة طرق الشحن في صفحة الدفع، ويختار Servientrega في النافذة Shipping method options، حيث يظهر عنوان الطريقة مع السعر. تعمل الطريقة بالطريقة نفسها في OpenCart 3.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Servientrega هي الكتلة الأولى في صفحة Extensions > Extensions > Shipping > VibeFox Servientrega > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموهاً، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. تحتها السطر Product: opencart-shipping-servientrega والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يمكن تغيير المفتاح إلا للمستخدمين المديرين الذين لديهم صلاحية Modify لهذه الإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (الإنجليزية والروسية مضمنتان).

إذا لم يُقبل المفتاح، فإن الكتلة توضح السبب، مثلاً Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذر الوصول إلى خادم التراخيص، تستمر الإضافة بالعمل بآخر حالة معروفة.

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

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

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

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

لا تظهر Servientrega عند الدفع: تحقق من أن الترخيص نشط، وأن Enable Servientrega مفعّل. تحقق من Geo zone، أو فعّل Ignore shipping zones وتحقق من Countries. تحقق من حدود الوزن وMinimum order amount. بدون سعر فوري، تحقق من أن البلد أو * Default لديه سعر، أو أن Fallback cost مُعدّة. تحقق من أن المنتجات لديها Requires Shipping على Yes.

لا تظهر الأسعار الفورية: فعّل Debug log، وأعد تحميل الدفع، وانظر إلى الحقل Log على صفحة الإضافة. الأسباب الشائعة: غياب سعر الصرف (عملة المتجر ليست COP)، أو غياب رمز DANE للمنشأ، أو أن قسم العميل أو مدينته لم تُدخل بعد أو ليست بلدية معروفة، أو بيانات اعتماد خاطئة، أو عدم وجود تغطية للمسار، أو تعذر وصول الخادم إلى web.servientrega.com عبر المنفذين 8058 و8081. تغطي الأسعار الثابتة هذه الحالات إذا ضبطتها.

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

لا تُتعرف على مدينة العميل: يجب على العميل اختيار القسم الإداري في حقل Region / State. للتهجئات النادرة، يمكن للعميل كتابة رمز DANE المكون من 8 أرقام كرمز بريدي.

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

تقول الصفحة "Warning: You do not have permission to modify VibeFox Servientrega!": قد تتمكن مجموعة المستخدمين المديرين لديك من عرض الإعدادات فقط. امنح المجموعة صلاحية التعديل لـ extension/shipping/vfd_servientrega (OpenCart 3) أو extension/vfd_servientrega/shipping/vfd_servientrega (OpenCart 4) في System > Users > User Groups.

للمطورين: تتيح أحداث OpenCart vfd_servientrega/dane_code وvfd_servientrega/quote_request لإضافة أخرى تغيير رمز DANE الخاص بالوجهة وطلب العرض.

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

انتقل إلى Extensions > Extensions، واختر النوع Shipping، وانقر على Uninstall (زر − الأحمر) بجوار VibeFox Servientrega. تُحذف دائماً مفتاح الترخيص وحالة الترخيص لهذه الإضافة. يعيد OpenCart دائماً تعيين Enable Servientrega وSort order وTax class وGeo zone. تُحذف دائماً العروض المخزنة مؤقتاً والرموز وكلمة المرور المشفرة. إذا كانت Remove data on uninstall مفعّلة، فتُحذف الإعدادات الأخرى والسجل أيضاً. إذا كانت معطّلة، فتُحفظ وتُستخدم من جديد عند إعادة تثبيت الإضافة. تحتفظ الطلبات الحالية بطريقة الشحن وتكلفتها.

على OpenCart 4، لإزالة ملفات الإضافة أيضاً، انتقل بعد إلغاء التثبيت إلى Extensions > Installer، وانقر في قائمة الإضافات المثبتة على Uninstall (زر − البرتقالي) بجوار VibeFox Servientrega، ثم انقر على Delete (زر سلة المهملات الأحمر) لإزالة الحزمة المرفوعة.

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