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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

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

عند التثبيت، تنشئ الوحدة شركة الشحن Servientrega مع نص مدة التوصيل Servientrega courier delivery. تُخصَّص شركة الشحن لجميع المناطق ولجميع مجموعات العملاء. يمكنك تغيير المناطق ومجموعات العملاء ومدة التوصيل والشعار وحدود الحجم من Shipping > Carriers. لا تضبط الأسعار هناك: فالسعر يأتي دائمًا من الوحدة.

الإعدادات

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

إذا تعذّر عمل الأسعار الفورية بالإعدادات المحفوظة، يوضح تحذير أعلى النموذج السبب: اسم مستخدم أو كلمة مرور أو رمز فوترة مفقود، أو سعر صرف مفقود، أو رمز DANE لنقطة الانطلاق مفقود. ويظهر تحذير أيضًا إذا كانت وحدة الوزن أو الأبعاد في متجرك (International > Localization، Local units) غير معروفة للوحدة؛ عندها تُقرأ الأوزان بالكيلوغرام والأبعاد بالسنتيمتر. وعند الحفظ، يُرفض بخطأ أي قيمة ليست رقمًا، أو رقم سالب، أو سعر صرف يساوي 0، أو حد أدنى للوزن أعلى من الحد الأقصى، أو سعر خاطئ في الجدول، أو عنوان طريقة أطول من 64 حرفًا، ولا يُحفظ شيء.

عام

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

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

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

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

Colombian departments: يساعد القسم على التمييز بين البلديات التي لها الاسم نفسه. لا تتضمن PrestaShop أقسام كولومبيا افتراضيًا؛ ومن دونها لا يُتعرَّف إلا على أسماء المدن الفريدة في كولومبيا. انقر على Add Colombian departments لإضافة الأقسام الـ 33 كولايات لكولومبيا (رموز ISO ANT وDC…)، وفعِّل Contains states لكولومبيا، وأضف حقل القسم إلى نموذج العنوان الكولومبي. لا تُضاف الأقسام الموجودة مسبقًا مرة ثانية. وعند اكتمال كل شيء، يعرض الحقل عدد الأقسام التي تملكها العناوين الكولومبية.

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

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

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

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: يُخفي شركة الشحن عندما يكون وزن السلة أقل من هذا الحد، بالكيلوغرام. القيمة 0 تعني بلا حد.

Maximum weight: يُخفي شركة الشحن عندما يكون وزن السلة أكبر من هذا الحد، بالكيلوغرام. الافتراضي: 50. القيمة 0 تعني بلا حد.

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

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

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

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

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

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

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

متقدم

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لا تظهر Servientrega عند الدفع: تحقق من أن الترخيص نشط وأن Enable Servientrega مفعّل. في Shipping > Carriers، تحقق من أن شركة الشحن تغطي منطقة دولة العميل ومجموعة العميل، أو فعّل Ignore shipping zones وتحقق من Countries. تحقق من حدود الوزن وMinimum order amount. وإذا لم يوجد سعر فوري، فتحقق من أن الدولة أو الصف * Default له سعر، أو أن Fallback cost مضبوط. وقد تكون المنتجات مقصورة على شركات شحن معينة في صفحة المنتج.

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

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

لا يُتعرَّف على مدينة العميل: انقر على Add Colombian departments ليتمكن العملاء من اختيار أقسامهم. وفي حالات الكتابة النادرة، يمكن للعميل كتابة رمز DANE المكون من 8 أرقام في الرمز البريدي.

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

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

للمطورين: تتيح الخطافات actionVfdSvtgDaneCode وactionVfdSvtgQuoteRequest تغيير رمز DANE للوجهة وطلب عرض السعر.

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

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

Servientrega علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Servientrega ولا معتمدة من قِبلها.