التثبيت

تشرح هذه الصفحة تثبيت نصفَي Perfex CRM Integration for WHMCS. اتبعها بالترتيب. تتم العملية بأكملها من تبويبَي متصفح إضافةً إلى File Manager في لوحة الاستضافة لديك. لا حاجة إلى SSH ولا إلى سطر الأوامر.

يفترض أن يكون لديك upload.zip مفكوك الضغط، وأن يعطيك ملفين:

الملف	يذهب إلى
🧩 perfex-module/module.zip	Perfex CRM
⚙️ whmcs-addon/addon.zip	WHMCS

التثبيت السريع (النسخة المختصرة)

بالنسبة لمسؤول استضافة متمرّس، تنحصر المهمة كلها في خمس خطوات. نفّذها بهذا الترتيب.

1. 🧩 Perfex أولاً. في Perfex CRM، انتقل إلى Setup > Modules > Upload Module، وارفع module.zip، ثم Activate. تثبيت جانب Perfex أولاً يعني أن نقطة النهاية المستقبِلة موجودة قبل أن يرسل WHMCS أي شيء إطلاقاً.
2. ⚙️ إضافة WHMCS. ارفع addon.zip وفُك ضغطه داخل modules/addons/ بحيث ينتهي بك الأمر إلى modules/addons/perfexbridge/perfexbridge.php، ثم فعّل Perfex CRM Bridge تحت System Settings > Addon Modules.
3. 🔓 أشّر على Access Control. في شاشة Configure الخاصة بالإضافة، أشّر على Full Administrator (إضافةً إلى أي دور آخر ينبغي أن يستخدمها) وانقر Save Changes. بدون ذلك تبقى الوحدة غير مرئية - إذ لا تظهر إطلاقاً في قائمة Addons.
4. 🔗 اقرن الجانبين. افتح Addons > Perfex CRM Bridge، والصق Connection code المنسوخ من Perfex في مربع Quick setup، ثم انقر Connect. التفاصيل في التهيئة.
5. ✅ تحقّق. أنشئ عميلاً تجريبياً في WHMCS، وانقر Run Sync Now، وتأكد من ظهوره في Perfex تحت Customers.

كل نقرة، وكل صف في قائمة التحقق، والتحقق الكامل من طرف إلى طرف موجودة في الشرح التفصيلي أدناه.

الشرح التفصيلي

الترتيب مهم

ثبّت مرافق Perfex أولاً. فهو ينشئ نقطة النهاية المستقبِلة. وإذا ثبّتّ إضافة WHMCS أولاً وبدأت المزامنة، سيفشل كل حدث إلى أن يوجد جانب Perfex، وستضيّع وقتك في قراءة سجلات أخطاء عن مشكلة لم تتسبب بها بعد.

الخطوة 1: تثبيت مرافق Perfex CRM

مرافق Perfex مجاني، ولا يحمل مفتاح رخصة، ويُثبَّت بالكامل من منطقة إدارة Perfex.

1. سجّل الدخول إلى Perfex CRM بصفة Administrator.
2. انتقل إلى Setup > Modules.
3. انقر زر Upload Module.
4. اختر module.zip من نافذة اختيار الملفات وارفعه.
5. يدرج Perfex الوحدة باسم WHMCS Bridge. انقر Install إذا طُلب منك ذلك، ثم انقر Activate.

إذا رُفض الرفع بسبب الحجم

يرسل زر Upload Module ملف zip عبر PHP، لذا يجب أن تكون قيمتا upload_max_filesize و post_max_size على خادمك أكبر من حجم الملف. وإذا فشل الرفع، فإما أن ترفع هذين الحدّين في إعدادات PHP، أو تستخدم البديل اليدوي أدناه.

البديل اليدوي: فُك ضغط module.zip على جهازك وارفع مجلد whmcs_bridge الناتج إلى الدليل modules/ داخل تثبيت Perfex عبر FTP أو File Manager في لوحة الاستضافة. يجب أن تكون النتيجة modules/whmcs_bridge/whmcs_bridge.php. ثم عد إلى Setup > Modules وانقر Activate.

تأكد من أن جانب Perfex ثُبّت بشكل صحيح

• يظهر عنصر جديد باسم WHMCS Bridge تحت قائمة Setup في Perfex. تلك الصفحة هي المكان الذي ستولّد فيه السر المشترك في الفصل التالي.

الخطوة 2: تثبيت إضافة WHMCS

لا يوفر WHMCS أي مثبّت وحدات داخل لوحة الإدارة. أنت من يضع الملفات على القرص بنفسك، ثم تفعّلها من منطقة الإدارة. ويقوم File Manager في لوحة الاستضافة بكل شيء.

1. افتح File Manager في لوحة الاستضافة وانتقل إلى الدليل modules/addons/ داخل تثبيت WHMCS.
2. ارفع addon.zip إلى modules/addons/.
3. استخدم إجراء Extract في File Manager على الملف المرفوع، مع فك الضغط داخل الدليل modules/addons/ نفسه.
4. تأكد من أن النتيجة هي modules/addons/perfexbridge/perfexbridge.php. وإذا انتهى بك الأمر إلى modules/addons/perfexbridge/perfexbridge/perfexbridge.php، فهذا يعني أن فك الضغط تداخل مستوى إضافياً. انقل المجلد الداخلي إلى الأعلى واحذف الغلاف الفارغ.
5. احذف ملف addon.zip المرفوع من الخادم بعد نجاح فك الضغط.

بديل FTP

فُك ضغط addon.zip على جهازك أولاً، ثم ارفع مجلد perfexbridge الناتج إلى modules/addons/ عبر FTP. النتيجة النهائية متطابقة.

والآن فعّلها:

6. في WHMCS، انتقل إلى System Settings > Addon Modules.
7. ابحث عن Perfex CRM Bridge في القائمة وانقر Activate.

الخطوة 3: أشّر على Access Control، وإلا بقيت الوحدة غير مرئية

هذا هو أكثر بلاغ متكرر بأن "الوحدة لم تُثبَّت"

بعد التفعيل، يعرض WHMCS لوحة تهيئة الوحدة مع قسم Access Control يسرد أدوار المسؤولين لديك. يجب أن تؤشّر على Full Administrator على الأقل، إضافةً إلى أي دور آخر ينبغي أن يستخدم الوحدة، ثم تنقر Save Changes.

وإلى أن يُؤشَّر على دور ما، لا تظهر الوحدة إطلاقاً في قائمة Addons على الجانب الأيسر. الوحدة مثبّتة، وجداولها موجودة، وصفحة إعداداتها تعمل تماماً، لكن لا يوجد أي رابط إليها في منطقة الإدارة. في تسع حالات من كل عشر، تعني عبارة "الوحدة لم تُثبَّت" أن هذا المربع لم يُؤشَّر عليه أبداً.

وبشكل عملي:

1. وأنت لا تزال في System Settings > Addon Modules، انقر Configure بجانب Perfex CRM Bridge. عادةً يفتح WHMCS هذه اللوحة تلقائياً بعد التفعيل مباشرةً.
2. تحت Access Control، أشّر على Full Administrator. وأشّر على أي دور إداري آخر ينبغي أن يتمكن من فتح الجسر وتهيئته.
3. انقر Save Changes.
4. حدّث منطقة الإدارة. سيظهر Perfex CRM Bridge الآن تحت قائمة Addons.

Access Control هو الشيء الوحيد في شاشة Configure

كل إعداد فعلي لهذه الوحدة موجود في صفحتها الخاصة على المسار Addons > Perfex CRM Bridge، وليس في شاشة Configure الخاصة بـ WHMCS. تحتفظ شاشة Configure بـ Access Control فقط، لأن WHMCS يعرضه في نواته ولا يمكن نقله. فإذا فتحت Configure بحثاً عن عنوان Perfex أو مفتاح الرخصة، فأنت في الشاشة الخطأ. راجع التهيئة.

الخطوة 4: افتح صفحة الوحدة

انتقل إلى Addons > Perfex CRM Bridge.

تُفتح الصفحة على Setup checklist. وفي التثبيت الجديد تبدو هكذا:

صف قائمة التحقق	الحالة المتوقعة الآن
Module tables present	🟢 علامة صح خضراء
Connection configured	🔴 علامة X حمراء، إذ لم يجرِ أي اقتران بعد
Connection verified	⚪ شرطة رمادية، لم يُفحص قط
Sync enabled	🔴 علامة X حمراء إلى أن تؤشّر على Enable Sync
Cron delivering	🔴 علامة X حمراء، إذ لم يُسجَّل نشاط cron بعد
License / plan	⚪ شرطة رمادية، الخطة المجانية

هذه هي الحالة الصحيحة لجسر حديث التثبيت وغير مهيّأ. وكل صف مشروح في التهيئة.

بعد ذلك، اقرن الجانبين: التهيئة.

الخطوة 5: تحقق من أول مزامنة من طرف إلى طرف

افعل هذا مرة واحدة، مباشرةً بعد الاقتران، وقبل أن تأتمن الجسر على بيانات حقيقية. يستغرق الأمر دقيقتين ويثبت سلامة المسار بأكمله.

1. أكمل عملية الاقتران الموصوفة في التهيئة. يجب أن يكون صفّا قائمة التحقق Connection configured و Connection verified أخضرين معاً.
2. في الصفحة نفسها، تحت Settings > Sync behaviour، تأكد من التأشير على Enable Sync، ثم انقر Save Settings. عندها يتحول صف Sync enabled إلى الأخضر.
3. في WHMCS، أنشئ عميلاً تجريبياً. أي اسم وبريد إلكتروني يفي بالغرض، مثل شركة باسم Bridge Test Ltd.
4. عد إلى Addons > Perfex CRM Bridge. ينبغي أن يُظهر عدّاد Queue pending قرب الأعلى الرقم 1 على الأقل.
5. انقر Run Sync Now. يفرض هذا محاولة تسليم فورية دون انتظار cron. وتُبلّغ الصفحة بعدد الأحداث التي أُرسلت وأخفقت وانتقلت إلى حالة الرسائل الميتة.
6. في Perfex CRM، افتح Customers. أصبح العميل التجريبي موجوداً الآن كعميل، باسم عميل WHMCS وبريده الإلكتروني كجهة اتصال أساسية.
7. تأكد من أن السجلين وثّقا ذلك:
   • جانب WHMCS: يعرض جدول Recent activity أسفل صفحة الوحدة صفاً بعنوان client.upsert بالحالة ok.
   • جانب Perfex: في Setup > WHMCS Bridge، ضمن لوحة Recent inbound events، يظهر صف مطابق بعنوان client.upsert مع شارة ok خضراء.
8. احذف العميل التجريبي من كلا النظامين إن لم ترغب في الاحتفاظ به.

زر "Run Sync Now" لا يثبت أن cron لديك يعمل

يثبت Run Sync Now أن التسليم يعمل. لكنه لا يحوّل صف Cron delivering إلى الأخضر، لأن ذلك الصف يتتبع عمداً نشاط cron النظام الحقيقي في WHMCS. فإذا بقي ذلك الصف أحمر أو كهرمانياً بعد ساعة، فإن cron النظام لديك لا يعمل ولن تتم أي مزامنة تلقائياً. أصلح cron قبل الانتقال إلى التشغيل الفعلي. راجع استكشاف الأخطاء وإصلاحها.

التحديث إلى إصدار أحدث

تحمل الوحدتان الإصدار نفسه، وينبغي تحديثهما معاً دائماً.

جانب Perfex. ارفع ملف module.zip الجديد عبر Setup > Modules > Upload Module مع الكتابة فوق الوحدة الحالية، ثم افتح أي صفحة إدارة. يكتشف المرافق أن إصدار قاعدة البيانات قديم ويطبّق ترحيلاته الخاصة في مكانها. وإن فضّلت، عطّل الوحدة ثم أعد تفعيلها بدلاً من ذلك. كلا المسارين آمن: فكل عبارة ترحيل محميّة، وإعادة تشغيلها لا تغيّر أي شيء صحيح أصلاً.

جانب WHMCS. ارفع ملف addon.zip الجديد وفُك ضغطه فوق modules/addons/perfexbridge/. يشغّل WHMCS روتين ترقية الوحدة عندما يرى رقم الإصدار الجديد. وعند الشك، عطّل الإضافة ثم أعد تفعيلها تحت System Settings > Addon Modules.

إعداداتك تبقى بعد الترقية

تعيش الإعدادات والسر المشترك ومفتاح الرخصة وخريطة الكيانات والسجلات كلها في جداول قاعدة بيانات لا تحذفها الترقيات أبداً. كما أن تعطيل إضافة WHMCS لا يحذف بياناتها أيضاً.

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

1. في WHMCS: System Settings > Addon Modules > Perfex CRM Bridge > Deactivate، ثم احذف modules/addons/perfexbridge/ من القرص.
2. في Perfex: Setup > Modules، عطّل WHMCS Bridge، ثم أزل الوحدة.
3. إذا أردت التخلص من البيانات كذلك، احذف جداول قاعدة بيانات الوحدة في كل نظام (خذ نسخة احتياطية أولاً).
4. إذا كانت رخصة Pro مفعّلة، فأزل المفتاح قبل إلغاء التثبيت كي تُحرَّر خانة التفعيل ويمكن إعادة استخدام الرخصة في مكان آخر. راجع الترخيص وتفعيل Pro.