التهيئة

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

كيف يصادق الجانبان أحدهما الآخر

تصادق نقطتا النهاية كل طلب باستخدام توقيع HMAC-SHA256 مشتق من سر مشترك.

وبعبارة بسيطة: يوقّع المُرسِل جسم الطلب بالسر ويختمه بطابع زمني. ثم يعيد المستقبِل حساب التوقيع بنسخته الخاصة من السر ويرفض أي شيء لا يتطابق توقيعه، أو يزيد عمر طابعه الزمني عن 300 ثانية. هذه النافذة الزمنية هي ما يمنع أي شخص من إعادة تشغيل طلب ملتقط في وقت لاحق.

والنتيجة: يجب أن يكون السر متطابقاً حرفاً بحرف على الجانبين، وإلا فشل كل طلب برمز 401. كما ترفض كل نقطة نهاية حركة المرور بالكامل ما دام سرّها فارغاً، بحيث يكون الجسر نصف المهيّأ مغلقاً لا مفتوحاً.

ويقتطع الجانبان المسافات البيضاء في البداية والنهاية قبل الاستخدام، فلا تضرّك مسافة أو سطر جديد يلتقطهما النسخ واللصق. أما ما بينهما فيجب أن يتطابق تماماً.

تعامل مع السر المشترك بوصفه بيانات اعتماد

يمنح السر المشترك صلاحية الكتابة على عملاء Perfex وجهات الاتصال، ومع رخصة Pro على الفواتير والمدفوعات والطلبات والتذاكر على الجانبين. غيّره فوراً على الجانبين إذا انكشفت أي من قاعدتَي البيانات أو نسخة احتياطية منهما. تُخزَّن الأسرار كنص عادي في tbladdonmodules (في WHMCS) و tbloptions (في Perfex)، وهو ممارسة قياسية في كلتا البيئتين، ما يعني أن كل من يملك وصولاً إلى قاعدة البيانات يملك السر.

الاقتران: المسار السريع (موصى به)

لست بحاجة إلى نقل الإعدادات ذهاباً وإياباً يدوياً. يولّد Perfex قيمة Connection code واحدة تحمل عنوان Perfex والسر المشترك معاً، ويستهلكها WHMCS بلصقة واحدة.

الخطوة 1: توليد السر في Perfex

1. في Perfex CRM، انتقل إلى Setup > WHMCS Bridge.
2. بجانب Shared Secret، انقر Generate. يمتلئ الحقل بسر عشوائي قوي من 64 حرفاً ويصبح ظاهراً كي ترى ما أنت على وشك حفظه. ويعيد زر العين إخفاءه.
3. انقر Save.

الخطوة 2: انسخ Connection code

تُعاد الصفحة وتعرض الآن حقل Connection code للقراءة فقط. وقيمته سلسلة واحدة تبدأ بـ PBC1..

انقر Copy. ويومض الزر بكلمة "Copied!" عندما يصبح الرمز في حافظتك.

Connection code هو كلمة مرور

الرمز هو PBC1. متبوعاً بـ JSON مشفّر بصيغة base64url يحتوي على عنوان Perfex لديك وسرّك المشترك. وهذا ترميز لا تشفير. فأي شخص يحصل على الرمز يمكنه التخاطب مع نقاط نهاية الجسر لديك. لا تلصقه في تذكرة عامة، أو قناة محادثة، أو لقطة شاشة، أو طلب دعم.

إذا لم يظهر أي Connection code

لا يظهر الرمز إلا عند تحقق شرطين: أن يكون تثبيت Perfex لديك مقدَّماً عبر HTTPS، وأن يكون السر المشترك المحفوظ بطول 32 حرفاً على الأقل. والسبب المعتاد هو النقر على Generate دون النقر على Save. وتخبرك الصفحة بالشرط الذي أخفق:

• "not served over HTTPS" - يتطلب الاقتران HTTPS. استخدم الإعداد اليدوي بدلاً من ذلك، أو أصلح الشهادة.
• "shorter than 32 characters" - انقر Generate، ثم Save، وسيظهر الرمز.

الخطوة 3: الصقه في WHMCS

1. في WHMCS، افتح Addons > Perfex CRM Bridge.
2. ابحث عن مربع Quick setup الأخضر قرب أعلى الصفحة.
3. الصق الرمز في الحقل.
4. انقر Connect.

ماذا يفعل Connect فعلياً

في خطوة واحدة، وبهذا الترتيب:

1. يفك ترميز الرمز ويتحقق منه بصرامة: البادئة PBC1.، وصيغة base64url الصارمة، وكائن JSON سليم البنية، وعنوان URL يبدأ بـ https:// ويجتاز التحقق، وسر لا يقل عن 32 حرفاً.
2. يرسل نداء ping موقّعاً إلى تثبيت Perfex لديك باستخدام العنوان والسر بعد فك الترميز، وينتظر رد pong.
3. وفقط إذا نجح ذلك النداء يحفظ Perfex CRM URL و Shared Secret على جانب WHMCS.
4. وفي عملية الاقتران الأولى فقط، يحمل النداء أيضاً عنوان WHMCS الأساسي لديك، فيُملأ حقل WHMCS URL على جانب Perfex نيابةً عنك. ويحدث هذا فقط عندما يكون WHMCS لديك مقدَّماً عبر HTTPS، ولا يستبدل أبداً قيمة مضبوطة مسبقاً.
5. يسجّل الفحص الناجح، فيتحول صف قائمة التحقق Connection verified إلى الأخضر في نفس تحميل الصفحة.

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

إعادة الاقتران لاحقاً

بمجرد تهيئة WHMCS، يتحول مربع Quick setup إلى نموذج Re-pair غير بارز. الصق رمزاً جديداً في أي وقت تغيّر فيه السر أو تنقل Perfex إلى نطاق جديد. وتنطبق القاعدة نفسها: الرمز الذي يفشل في التحقق لا يغيّر شيئاً.

غيّر السر، ثم أعد الاقتران، بهذا الترتيب

إذا نقرت Generate ثم Save على جانب Perfex، فسيبدأ كل طلب قائم من WHMCS بالفشل فوراً برمز HTTP 401 إلى أن تلصق الرمز الجديد في WHMCS. نفّذ الخطوتين واحدة تلو الأخرى مباشرةً. أما الرمز القديم المنسوخ قبل التغيير فسيُرفض، وسيخبرك الشريط بأن Perfex ردّ برمز 401.

الاقتران: البديل اليدوي

Connection code وسيلة راحة لا سحر. فكل ما يفعله يمكن إنجازه يدوياً، وستحتاج إلى هذا المسار إذا لم يكن تثبيت Perfex لديك على HTTPS بعد، أو إذا كان سير عملك يمنع لصق بيانات اعتماد مدمجة.

1. ولّد سراً عشوائياً قوياً لا يقل عن 32 حرفاً. استخدم زر Generate في صفحة إعدادات Perfex، أو أداتك الخاصة، مثل openssl rand -hex 32.
2. في Perfex، على المسار Setup > WHMCS Bridge، الصقه في Shared Secret وانقر Save.
3. في WHMCS، افتح Addons > Perfex CRM Bridge، ومرّر إلى Settings > Connection، ثم:
   • اضبط Perfex CRM URL على عنوان Perfex الأساسي لديك، مثل https://crm.example.com، عبر HTTPS ودون أي مسار لاحق؛
   • الصق نفس السر في Shared Secret.
4. انقر Save Settings.
5. انقر Test Connection في أعلى الصفحة. والمطلوب هو الشريط الأخضر "Connection OK".
6. وللمزامنة باتجاهين في Pro، اضبط أيضاً WHMCS URL في صفحة إعدادات Perfex. وهذا ما كان الاقتران سيفعله نيابةً عنك.

إعدادات WHMCS، قسماً بقسم

كل الإعدادات موجودة في صفحة الوحدة نفسها

افتح Addons > Perfex CRM Bridge ومرّر إلى Settings. لا تبحث في شاشة Configure الخاصة بـ WHMCS تحت System Settings > Addon Modules؛ فتلك الشاشة تحتفظ بـ Access Control فقط، وهو ما تعرضه نواة WHMCS ولا يمكن نقله.

انقر Save Settings للتطبيق. والنموذج يعمل بمبدأ الكل أو لا شيء: أي إدخال غير صالح، مثل عنوان لا يستخدم HTTPS، يرفض الإرسال بأكمله ولا يغيّر شيئاً.

مربعا السر لا يعرضان قيمتهما المخزّنة أبداً

يظهر Shared Secret و Pro License Key فارغين دائماً، حتى لا تبقى بيانات اعتماد مخزّنة موجودة في شيفرة مصدر الصفحة لدى كل مسؤول يستطيع فتح الوحدة. اترك المربع فارغاً للإبقاء على قيمته الحالية. واكتب فيه لاستبدال تلك القيمة. ولإزالة مفتاح Pro تماماً، أشّر على Remove the stored key.

الاتصال

الإعداد	ماذا يفعل	القيمة المعقولة
Perfex CRM URL	العنوان الأساسي لتثبيت Perfex لديك، مثل https://crm.example.com. يجب أن يكون HTTPS: فالجسر يرفض الإرسال عبر HTTP العادي.	يُضبط تلقائياً بالاقتران
Shared Secret	سر HMAC. يجب أن يطابق السر المهيّأ في Perfex تحت Setup > WHMCS Bridge. اتركه فارغاً للإبقاء على السر المخزّن.	يُضبط تلقائياً بالاقتران

سلوك المزامنة

الإعداد	ماذا يفعل	القيمة المعقولة
Enable Sync	المفتاح الرئيسي. أزل التأشير لإيقاف كل التسليم الصادر مؤقتاً. وتبقى الأحداث في الطابور أثناء الإيقاف، فلا يضيع شيء؛ وتُسلَّم في النبضة التالية بعد إعادة التفعيل.	مُفعّل، بعد اكتمال التهيئة
Order Sync Target (Pro)	ما الذي يصبح عليه طلب WHMCS داخل Perfex. القيمة lead تنشئ عميلاً محتملاً واحداً في Perfex لكل طلب. والقيمة note تضيف ملاحظة على عميل Perfex بدلاً من ذلك. والقيمة off لا تزامن الطلبات إطلاقاً.	lead
Two-Way Conflict Policy (Pro)	أي جانب يفوز عندما يغيّر كلا النظامين العميل نفسه أو جهة الاتصال نفسها منذ آخر مزامنة. انظر أدناه.	newest_wins

خيارات سياسة التعارض، سطر واحد لكل منها:

• newest_wins (الافتراضي) - يقارن وقت حدث Perfex الوارد بوقت آخر مزامنة، ويفوز التعديل الأحدث.
• whmcs_wins - يبقي على بيانات WHMCS ويتجاهل تعديل Perfex المتعارض.
• perfex_wins - يطبّق تعديل Perfex فوق بيانات WHMCS.

سياسة التعارض لا تعمل إلا عند وجود تعارض حقيقي

تنطبق فقط عندما يكون الجانبان قد غيّرا السجل نفسه منذ آخر مزامنة ناجحة. أما التعديل العادي على جانب واحد، مع بقاء الجانب الآخر دون مساس، فيُطبَّق دائماً. أنت لا تختار أي نظام "يفوز" بشكل عام، بل تحدد كيفية حسم التعادل فقط.

ملاحظة حول newest_wins وساعات الخوادم

تقارن كلمة "الأحدث" الطابع الزمني للخادم المُرسِل بوقت آخر مزامنة لدى الخادم المستقبِل، لذا فإن ساعتَي المضيفين مهمتان. أبقِ الخادمين على NTP. وإذا كان انحراف الساعة بين مضيف WHMCS ومضيف Perfex خارج سيطرتك، ففضّل whmcs_wins أو perfex_wins، فكلاهما حتمي النتيجة.

التذاكر

الإعداد	ماذا يفعل	القيمة المعقولة
Ticket Reply Admin (Pro)	اسم مستخدم مسؤول WHMCS الذي يُستخدم عند مزامنة رد موظف من Perfex إلى تذكرة في WHMCS. اتركه فارغاً لنسب الرد إلى اسم موظف Perfex بدلاً من ذلك، ويُنشر عندئذ كرد غير إداري.	فارغ

رخصة Pro

الإعداد	ماذا يفعل	القيمة المعقولة
Pro License Key	اتركه فارغاً للخطة المجانية. الصق مفتاح Pro هنا لفتح ميزات Pro. تبدأ المفاتيح بـ sk_. وحفظ مفتاح تغيّر فعلياً يتحقق منه مباشرةً وفوراً.	فارغ (Free)
Remove the stored key	مربع تأشير يظهر فقط عند وجود مفتاح مخزّن. التأشير عليه والحفظ يعيدان التثبيت إلى Free ويحرّران خانة تفعيل هذا الموقع، فتصبح الرخصة قابلة للاستخدام في مكان آخر.	غير مؤشَّر
Check licence now (زر، أعلى الصفحة)	يفرض إعادة فحص فورية للمفتاح المخزّن أصلاً، متجاوزاً حد الفحص مرة واحدة يومياً.	-
Upgrade to Pro / Buy a Pro licence (روابط)	تفتح صفحة الدفع. وفي التثبيتات غير المرخّصة بـ Pro تظهر هذه الروابط بجانب مربع المفتاح، وعلى صف الرخصة في قائمة التحقق، وفي مربعات التعريف بـ Pro.	-

التفاصيل الكاملة في الترخيص وتفعيل Pro.

إعدادات Pro آمنة التهيئة على الخطة المجانية

تُحفظ خيارات Order Sync Target و Two-Way Conflict Policy و Ticket Reply Admin بشكل سليم تماماً في التثبيت المجاني. لكنها ببساطة لا تُحدث أي أثر حتى تُفعَّل رخصة صالحة، والصفحة تذكر ذلك أسفل كل حقل. هيّئها مسبقاً إن أردت.

إعدادات Perfex CRM، حقلاً بحقل

افتح Setup > WHMCS Bridge في منطقة إدارة Perfex، ثم انقر Save.

الاتصال

الحقل	ماذا يفعل	القيمة الافتراضية / البديل
Shared Secret	يجب أن يطابق Shared Secret في WHMCS. استخدم Generate للحصول على سر قوي، ثم Save. ويكشفه زر العين أو يخفيه. وترفض نقطة النهاية كل حركة المرور ما دام هذا الحقل فارغاً.	فارغ، ونقطة النهاية مغلقة
Connection code	للقراءة فقط. يظهر بمجرد أن يبلغ السر المحفوظ 32 حرفاً أو أكثر ويكون Perfex على HTTPS. انسخه إلى مربع Quick setup في WHMCS.	يُعرض تلقائياً
WHMCS URL	العنوان الأساسي لتثبيت WHMCS الذي يشغّل الإضافة. لا يلزم إلا لحركة المرور من Perfex إلى WHMCS، وهي ميزة في Pro. يجب أن يبدأ بـ https:// وإلا لم يُحفظ.	يُملأ تلقائياً عند أول اقتران، ولا يُستبدل بعد ضبطه

مزامنة التذاكر (Pro)

الحقل	ماذا يفعل	القيمة الافتراضية / البديل
Department mapping (WHMCS to Perfex)	يربط كل قسم تذاكر في WHMCS بقسم في Perfex. يُعرض كقائمة منسدلة لكل قسم في WHMCS عندما يمكن جلب الدليل، أو كمربع نص يدوي خلاف ذلك.	فارغ، ولا شيء مربوط
Default department for unmapped WHMCS tickets	قسم Perfex المستخدَم لأي تذكرة WHMCS لا يوجد قسمها في الخريطة.	"Lowest department id (automatic)"
Staff author for synced WHMCS staff replies	موظف Perfex الذي يُنسب إليه تأليف ردود موظفي WHMCS المنسوخة إلى Perfex.	"First active admin (automatic)"
Create a Perfex task per synced ticket	عند التأشير عليه، تحصل كل تذكرة مزامَنة على مهمة Perfex مرتبطة بها كي يتمكن موظفوك من تسجيل الوقت عليها عبر الجداول الزمنية الأصلية في Perfex.	مُعطّل

كيف يُعرض ربط الأقسام

التجربة الاعتيادية هي قوائم منسدلة. فعند تحميل صفحة الإعدادات، تجلب الصفحة دليل أقسام الدعم في WHMCS عبر الجسر الموقّع وتعرض صفاً واحداً لكل قسم في WHMCS، مع قائمة منسدلة بأقسام Perfex لديك. اختر وجهة لكل صف، أو اتركه على - not mapped -، ثم انقر Save.

ويحتاج هذا الجلب إلى اتصال يعمل وإلى تثبيت WHMCS مرخّص بـ Pro، لأن دليل الأقسام يقع خلف بوابة الترخيص نفسها التي تقع خلفها مزامنة التذاكر. وعندما يتعذر تنفيذه، تتراجع الصفحة تلقائياً إلى مربع نص يدوي وتخبرك بالسبب:

ما تراه	ماذا يعني
قوائم منسدلة، واحدة لكل قسم في WHMCS	كل شيء يعمل
مربع نص، مع "Couldn't fetch WHMCS departments (needs Pro + working connection)"	الجسر غير مهيّأ بعد، أو WHMCS غير قابل للوصول من خادم Perfex، أو تثبيت WHMCS على الخطة المجانية
مربع نص، مع "Connection OK, but WHMCS has no support departments yet"	نجح الجلب. أنشئ أقساماً في WHMCS تحت Support > Support Departments، ثم أعد تحميل هذه الصفحة

ومدة الجلب محدودة ببضع ثوانٍ، لذا فإن تعذر الوصول إلى WHMCS يبطئ صفحة الإعدادات قليلاً لكنه لا يعلّقها أبداً.

الصيغة اليدوية هي ربط واحد في كل سطر، مع معرّف قسم WHMCS على اليسار ومعرّف قسم Perfex على اليمين:

1=2
2=5
3=5

ومع ظهور القوائم المنسدلة، يفتح الرابط Advanced: edit the mapping manually مربع النص نفسه. وما دام هذا المحرر اليدوي مفتوحاً، فإن نصه هو ما يُحفظ، متجاوزاً اختيارات القوائم المنسدلة.

ترتيب الحسم لقسم أي تذكرة واردة:

1. تطابق تام في الخريطة.
2. وإلا، فـ Default department المهيّأ.
3. وإلا، فأدنى معرّف قسم في Perfex، ويُختار تلقائياً.

والخطأ المطبعي في سطر ربط يتراجع بسلاسة إلى البديل. فهو لا يعطّل الحفظ ولا يعطّل المزامنة.

الوقت المسجَّل على مهمة التذكرة يبقى في Perfex

توجد مهمة Perfex الاختيارية كي يتمكن موظفوك من استخدام الجداول الزمنية الأصلية في Perfex مع تذكرة ما. وهذه المدخلات الزمنية لا تُزامَن عائدةً إلى WHMCS، كما أن المهمة لا تُغلق تلقائياً عند إغلاق التذكرة.

اللوحات في الصفحة نفسها

يحمل العمود الجانبي في Setup > WHMCS Bridge ثلاث لوحات للقراءة فقط:

• WHMCS plan - الخطة التي أبلغ عنها جانب WHMCS آخر مرة (Pro أو Free أو Unknown)، وموعد آخر فحص للرخصة، وزر Upgrade to Pro عندما يكون هناك ما يمكن شراؤه.
• Outbound queue - تغييرات جانب Perfex المنتظرة للدفع إلى WHMCS، مع أعداد المعلّق والميت، وعدد المحاولات، ووقت المحاولة التالية، وآخر خطأ لكل صف.
• Recent inbound events - ما أرسله WHMCS إلى تثبيت Perfex هذا، مع الحالة والرسالة.

هذه هي أدوات التشخيص لديك على جانب Perfex. راجع كيف يعمل والاستخدام اليومي.

قائمة تحقق الإعداد، صفاً صفاً

تُفتح صفحة الوحدة في WHMCS على Setup checklist المكوّنة من ستة صفوف. ويحمل كل صف علامة صح خضراء، أو تحذيراً كهرمانياً، أو علامة X حمراء، أو شرطة رمادية، إضافةً إلى تلميح من سطر واحد. واللون الأخضر في كل الصفوف، مع الرمادي في صف الرخصة إن كنت على الخطة المجانية، يعني أن الجسر بصحة جيدة.

الصف	الأخضر يعني	وأي شيء آخر يعني
Module tables present	جداول outbox و map و log موجودة كلها.	🔴 أحمر: جدول مفقود. عطّل الوحدة وأعد تفعيلها تحت System Settings > Addon Modules لإعادة إنشائه.
Connection configured	عنوان Perfex والسر المشترك مضبوطان معاً.	🔴 أحمر: لم يُضبطا بعد. الصق Connection code في Quick setup، أو املأ الحقلين تحت Settings > Connection.
Connection verified	نداء ping موقّع تلقّى رد pong، ويعرض الصف منذ متى.	🔴 أحمر: أخفق آخر فحص، ويعرض الصف الخطأ. أصلحه، ثم انقر Test Connection. ⚪ رمادي: لم يُفحص قط، أو مضى على آخر فحص أكثر من 24 ساعة. انقر Test Connection لتحديثه.
Sync enabled	التسليم الصادر مُفعّل.	🔴 أحمر: المزامنة موقوفة مؤقتاً. تبقى الأحداث في الطابور لكنها لا تُسلَّم. أشّر على Enable Sync تحت Settings > Sync behaviour واحفظ.
Cron delivering	نفّذ cron النظام في WHMCS عملاً حقيقياً للجسر مؤخراً، ويعرض الصف مدى قرب ذلك.	🟠 كهرماني: لا نشاط لـ cron منذ فترة. تحقق من أن cron النظام في WHMCS يعمل. 🔴 أحمر: لم يُسجَّل أي نشاط لـ cron إطلاقاً. وهذا طبيعي في تثبيت جديد تماماً حتى أول تسليم؛ فإن استمر، فإن cron لديك لا يعمل.
License / plan	خطة Pro مفعّلة.	⚪ رمادي: لا يوجد مفتاح رخصة، وهذه هي الخطة المجانية وطريقة مدعومة تماماً لتشغيل هذه الوحدة. 🔴 أحمر: مفتاح مضبوط لكنه لا يجتاز التحقق. راجع المفتاح، ثم انقر Check licence now.

صف "Cron delivering" يصعب تزييفه عمداً

لا يحوّل هذا الصف إلى الأخضر إلا نبضة حقيقية من cron النظام في WHMCS. أما Run Sync Now فيسلّم أحداثك المدرجة في الطابور، ويثبت أن التسليم يعمل، لكنه لا يمس هذا الصف. وهذا هو المقصود بالضبط: فالصف يجيب عن سؤال "هل سيستمر هذا في العمل عندما لا يراقبه أحد؟"، وضغطة زر لا يمكنها الإجابة عن هذا السؤال.

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

ويحدّث كل من Connect (الاقتران) و Test Connection صف Connection verified.

إلى أين بعد ذلك

• تحقق من المسار من طرف إلى طرف: التثبيت، الخطوة 5.
• افتح المزامنة باتجاهين والفواتير والتذاكر: الترخيص وتفعيل Pro.
• افهم ما الذي يُزامَن وأين توجد السجلات: كيف يعمل والاستخدام اليومي.