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

اعمل على هذه الصفحة بالترتيب. فالأقسام الثلاثة الأولى تغطي الغالبية العظمى من طلبات الدعم.

وقبل أي شيء آخر، افتح Addons > Perfex CRM Bridge في WHMCS واقرأ Setup checklist. فهي مصممة للإشارة مباشرةً إلى المشكلة، وكل صف فيها مشروح في التهيئة.

مرجع سريع

العَرَض	السبب الأرجح	الحل
الوحدة مفقودة من قائمة Addons في WHMCS	لم يُؤشَّر على أي دور إداري تحت Access Control	أشّر على Access Control
كل عملية إرسال تفشل فوراً	عنوان Perfex يبدأ بـ http://	استخدم HTTPS
صفوف auth.rejected في سجل Perfex الوارد	السر المشترك غير متطابق	أعد الاقتران
رسالة "Two-way sync requires Pro" في طابور Perfex الصادر	جانب WHMCS على الخطة المجانية	فعّل Pro
الأحداث تُدرَج في الطابور لكن لا شيء يُسلَّم	المزامنة موقوفة مؤقتاً، أو cron الخاص بـ WHMCS لا يعمل	تحقق من cron
فاتورة واحدة لا تصل أبداً وتُعاد محاولتها بلا نهاية	عملة الفاتورة غير موجودة في Perfex	أضف العملة
الرخصة لا تُفعَّل	مفتاح مفقود، أو انعدام الاتصال بخدمة الترخيص	اقرأ لون الشريط
لا يوجد Connection code في صفحة Perfex	Perfex ليس على HTTPS، أو السر المحفوظ قصير جداً	Generate ثم Save
ربط الأقسام يعرض مربع نص بدلاً من قوائم منسدلة	الخطة المجانية، أو تعذر الوصول إلى WHMCS من Perfex	بدائل الربط
صفوف عالقة في الحالة dead	15 محاولة فاشلة للسبب نفسه	أعد تشغيل الصفوف الميتة

الوحدة غير موجودة في قائمة Addons

العَرَض. فعّلت Perfex CRM Bridge تحت System Settings > Addon Modules، وأعلن WHMCS نجاح التفعيل، لكن الوحدة غير موجودة في قائمة Addons على الجانب الأيسر.

السبب. لم يُمنح أي دور إداري صلاحية الوصول. فـ WHMCS يخفي وحدة الإضافة تماماً عن أي دور غير مؤشَّر عليه، وبذلك تكون الوحدة مثبّتة وتعمل بالكامل لكن لا يوجد رابط إليها في أي مكان في منطقة الإدارة. وهذا هو أكثر بلاغ شيوعاً بأن "الوحدة لم تُثبَّت".

الحل.

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

لا شيء آخر يوجد في شاشة Configure تلك

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

كل عملية إرسال تفشل فوراً، أو العنوان مرفوض

العَرَض. الأحداث تُدرَج في الطابور وتفشل فوراً. ويمتلئ سجل Recent activity بأخطاء اتصال. أو أن حقل Perfex CRM URL يرفض الحفظ من الأساس.

السبب. HTTPS مطلوب بحكم التصميم. فنقل HTTP مقيّد ببروتوكول https ويتحقق من شهادة TLS. وأي عنوان http:// يُفشل كل عملية إرسال، كما أن حقل WHMCS URL على جانب Perfex يرفض بدوره الحفظ ما لم يبدأ بـ https://.

الحل.

1. اضبط Perfex CRM URL على عنوان يبدأ بـ https:// على جانب WHMCS.
2. اضبط WHMCS URL على عنوان يبدأ بـ https:// على جانب Perfex.
3. تأكد من أن كلتا الشهادتين تجتازان التحقق فعلياً من الخادم الآخر، لا في متصفحك فقط. فالشهادة الموقّعة ذاتياً تعمل فقط إذا كان الخادم المُرسِل يثق بها.
4. انقر Test Connection في صفحة الوحدة داخل WHMCS.

لا يوجد إعداد لتعطيل التحقق من HTTPS

وهذا متعمّد. فسرّك المشترك وبيانات عملائك تنتقل عبر هذه القناة. وإذا لم تجتز شهادة ما التحقق، فأصلح الشهادة.

صفوف auth.rejected في سجل Perfex

العَرَض. يبلّغ WHMCS عن أخطاء HTTP 401. وفي Perfex، تعرض Setup > WHMCS Bridge > Recent inbound events صفوف auth.rejected حمراء.

السبب. السر المشترك غير متطابق على الجانبين، أو أن الطابع الزمني للطلب خارج نافذة الـ 300 ثانية. وعملياً يكون السبب دائماً تقريباً هو السر: فقد أعاد أحدهم توليده على جانب ولم يعد اقتران الجانب الآخر أبداً.

الحل، بالطريقة السريعة.

1. في Perfex، على المسار Setup > WHMCS Bridge، انسخ قيمة Connection code الحالية.
2. في WHMCS، على المسار Addons > Perfex CRM Bridge، الصقها في مربع Re-pair وانقر Connect.
3. انقر Test Connection. والمطلوب هو الشريط الأخضر "Connection OK".
4. انقر Run Sync Now. عندها تُسلَّم الأحداث المدرجة في الطابور التي كانت تفشل.

الحل، يدوياً. أعد لصق السر نفسه بالضبط في حقلَي Shared Secret على الجانبين واحفظ في كليهما. وتُقتطع المسافات البيضاء في البداية والنهاية تلقائياً، لكن كل ما بينهما يجب أن يتطابق حرفاً بحرف.

وإذا لم يكن السبب هو السر. تحقق من ساعتَي الخادمين. فانحراف يتجاوز 300 ثانية بينهما يؤدي إلى رفض كل طلب باعتباره إعادة تشغيل. ضع كلا المضيفين على NTP.

الصفوف المرفوضة محدودة المعدل

يسجّل Perfex ما لا يزيد عن 10 صفوف auth.rejected في الدقيقة، كي لا يستطيع مُرسِل خاطئ التهيئة ملء القرص لديك. فإذا رأيت 10 بالضبط في دقيقة واحدة، فافترض أن هناك المزيد.

"Two-way sync requires Pro" في طابور Perfex الصادر

العَرَض. تعدّل عميلاً في Perfex. فتعرض لوحة Outbound queue في Setup > WHMCS Bridge الصف مع الرسالة "Two-way sync requires Pro on the WHMCS side." ورابط Upgrade to Pro. وترتفع المحاولات، ثم ينتقل الصف في النهاية إلى الحالة dead.

السبب. المزامنة باتجاهين ميزة في Pro، والرخصة تعيش على جانب WHMCS. وتثبيت WHMCS لديك على الخطة المجانية، لذا ترد نقطة النهاية الواردة فيه برمز 403 على أي تغيير ناشئ من Perfex. أما مرافق Perfex فيتصرف بشكل صحيح بإدراج التغيير في الطابور وإعادة المحاولة.

الحل. فعّل رخصة Pro على جانب WHMCS. راجع الترخيص وتفعيل Pro. وبمجرد تفعيل Pro، يدفع WHMCS حالة الخطة الجديدة إلى Perfex فوراً، فتختفي رسالة الترقية، وتُسلَّم الصفوف المعلّقة في تشغيلة cron التالية لدى Perfex.

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

تحقق من لوحة الخطة أولاً

تقع لوحة WHMCS plan فوق Outbound queue مباشرةً في صفحة إعدادات Perfex، لهذا السبب بالذات. فإن كانت تعرض Free، فلديك إجابتك دون قراءة صف واحد من الطابور.

لا تتم أي مزامنة على الإطلاق

العَرَض. تظهر الأحداث في الطابور، ويرتفع Queue pending، ولا يصل شيء إلى Perfex أبداً. لا أخطاء، مجرد صمت.

وهناك سببان، وقائمة التحقق تميّز بينهما.

السبب أ: المزامنة موقوفة مؤقتاً

صف Sync enabled في قائمة التحقق أحمر.

الحل. في صفحة الوحدة داخل WHMCS، تحت Settings > Sync behaviour، أشّر على Enable Sync وانقر Save Settings. ولم يضع شيء أثناء الإيقاف؛ فقد استمرت الأحداث في الانضمام إلى الطابور وستُفرَّغ الآن.

السبب ب: cron النظام في WHMCS لا يعمل

صف Cron delivering في قائمة التحقق أحمر أو كهرماني.

الحل.

1. أثبت أن الجسر نفسه يعمل بالنقر على Run Sync Now. فإذا فُرِّغ طابورك، فالتسليم سليم والمشكلة في cron فعلاً.
2. تحقق من حالة cron الخاصة بـ WHMCS تحت Utilities > System > System Health Status. فـ WHMCS يبلّغ عن آخر تشغيل لـ cron النظام.
3. إذا لم يعمل cron مؤخراً، فأصلحه على مستوى الخادم. فمدير cron في لوحة الاستضافة لديك، أو crontab الخاص بخادمك، هو المكان الذي يوجد فيه أمر cron الخاص بـ WHMCS. وتوثيق WHMCS نفسه يوفر الأمر الدقيق لإصدارك.
4. وبمجرد عودة cron إلى العمل، يتحول صف Cron delivering إلى الأخضر عند أول تحميل للصفحة بعد إنجاز عمل حقيقي للجسر.

Run Sync Now لا يمكنه تحويل صف cron إلى الأخضر

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

الصف الكهرماني في cron ليس مشكلة دائماً

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

فاتورة عالقة ولا تصل إلى Perfex أبداً

العَرَض. تفشل فاتورة واحدة مراراً. وتذكر رسالة السجل عملة ما، ويستمر الصف في إعادة المحاولة بتأخير متزايد.

السبب. عملة الفاتورة غير مهيّأة في Perfex. فيرفض Perfex الفاتورة، وهو محق، لأنه لا يستطيع تسجيل إجمالي بعملة لا يعرفها.

الحل.

1. في Perfex، انتقل إلى Setup > Finance > Currencies.
2. أضف العملة، مستخدماً رمز ISO نفسه الذي يستخدمه WHMCS، مثل EUR أو USD.
3. لا تفعل شيئاً آخر. فالحدث المدرج في الطابور يُعاد محاولته وفق جدوله الخاص وينجح في المحاولة التالية.

أمامك نحو 40 ساعة

يتيح جدول إعادة المحاولة 15 محاولة تمتد لنحو 40 ساعة. أضف العملة داخل تلك النافذة، وإلا انتقل الصف إلى حالة الرسائل الميتة ووجب إعادة تشغيله يدوياً. وإذا كنت على وشك التعبئة الرجعية لفواتير تاريخية، فأضف كل عملة يستخدمها عملاؤك أولاً.

الحالة المرتبطة: "Not mapped (will retry)"

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

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

الرخصة لا تُفعَّل

العَرَض. لصقت مفتاحاً ولا يزال التثبيت يعرض Free.

يحتاج تفعيل Pro إلى أمرين: مفتاح صالح و اتصال من خادم WHMCS لديك بخدمة الترخيص. اقرأ لون الشريط، فهو يخبرك بالمفقود منهما.

الشريط	المعنى	الحل
🔴 أحمر	رفض خادم الترخيص المفتاح صراحةً، والرسالة تذكر السبب.	أعد نسخ المفتاح من بريد الشراء دفعة واحدة. طول المفاتيح 32 حرفاً وقد تحتوي على علامات ترقيم، فلا تحذف منها شيئاً ولا تعِد تنسيقها. وإذا ذكرت الرسالة عدد التثبيتات أو الحصة، فحرّر خانة تفعيل بإزالة المفتاح من تثبيت لم يعد بحاجة إليه.
🟠 كهرماني	تعذّر على خادمك الوصول إلى خدمة الترخيص. وهذا ليس رفضاً.	المفتاح محفوظ وتستمر المحاولات. اسمح بحركة HTTPS الصادرة إلى api.freemius.com عبر أي جدار ناري أو وكيل خروج على خادم WHMCS. ثم انقر Check licence now.
⚪ لا يوجد شريط إطلاقاً	حفظت المفتاح نفسه المخزّن أصلاً، فلم تجرِ إعادة أي فحص.	انقر Check licence now.
الرأس يعرض "awaiting first verification"	يوجد مفتاح مخزّن لكنه لم يُؤكَّد قط.	انقر Check licence now.

فحوصات أخرى:

• تأكد من أن المفتاح موجود في Pro License Key تحت Settings > Pro licence في صفحة الوحدة نفسها، لا في مكان ما داخل شاشة Configure الخاصة بـ WHMCS.
• اضغط Check licence now وانتظر بضع ثوانٍ بين الضغطات. فالضغطة الثانية السريعة تجيب بأن الفحص جرى قبل قليل دون إرسال طلب.
• إذا كانت Pro مفعّلة في WHMCS بينما لا يزال Perfex يعرض Free، فاضغط Check licence now أو Test Connection في WHMCS. فكلاهما يوصل حالة الخطة إلى Perfex فوراً. ثم أعد تحميل صفحة إعدادات Perfex.

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

لا يظهر أي Connection code في Perfex

العَرَض. أنت في Setup > WHMCS Bridge، وقد حفظت سراً، ولا يوجد حقل Connection code، بل مجرد ملاحظة رمادية.

الأسباب والحلول. الملاحظة نفسها تخبرك بأيها ينطبق.

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

الاقتران يفشل برسالة "the shared secret does not match"

العَرَض. لصقت Connection code في WHMCS وحصلت على شريط أحمر يذكر خطأ HTTP 401.

السبب. يحمل الرمز سراً لم يعد Perfex يملكه. وغالباً ما يكون هذا رمزاً منسوخاً قبل عملية Generate و Save لاحقة، أو عملية Generate لم تُحفظ قط.

الحل. في Perfex، انقر Save في صفحة الإعدادات كي يُخزَّن السر الحالي فعلياً، ثم انسخ Connection code جديداً والصقه. ولم يُخزَّن أي شيء على جانب WHMCS نتيجة المحاولة الفاشلة، لذا فإن تهيئتك السابقة العاملة سليمة.

ربط الأقسام يعرض مربع نص بدلاً من قوائم منسدلة

العَرَض. تعرض صفحة إعدادات Perfex مربع نص عادياً لربط الأقسام بدلاً من قائمة منسدلة لكل قسم في WHMCS.

السبب. تعذّر على الصفحة جلب دليل أقسام الدعم في WHMCS. والتلميح أسفل مربع النص يذكر الحالة المنطبقة:

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

ويظل مربع النص اليدوي بصيغة whmcs_deptid=perfex_department_id صالحاً للعمل في غضون ذلك، بمعدل ربط واحد في كل سطر. والمزامنة ليست معطّلة بسبب ذلك: فالتذكرة غير المربوطة تتراجع إلى قسمك الافتراضي، أو إلى أدنى معرّف قسم في Perfex.

صفوف عالقة في الحالة dead

العَرَض. عدّاد Dead events في صفحة الوحدة داخل WHMCS، أو عدد الصفوف الميتة في لوحة Outbound queue لدى Perfex، أكبر من صفر.

السبب. أخفقت تلك الصفوف 15 مرة على مدى نحو 40 ساعة للسبب نفسه. والصفوف الميتة لا تُعاد محاولتها تلقائياً ولا تُقلَّم أبداً، وذلك عن قصد، كي تتمكن من فحصها.

الحل.

1. اعرف السبب. افتح Recent activity في WHMCS، أو عمود "Last error" في Outbound queue داخل Perfex، واقرأ الخطأ على الصفوف المتأثرة. والسبب يكون دائماً تقريباً واحداً من: عملة مفقودة في Perfex، أو عدم تطابق السر، أو خطة مجانية تحجب حدثاً خاصاً بـ Pro، أو توقف Perfex عن العمل.

2. أصلح السبب الجذري أولاً. فإعادة تشغيل صف دون إصلاح السبب تحرق 40 ساعة أخرى ببساطة.

3. أعد إدراج العمل في الطابور. والمسار الأكثر أماناً لا يحتاج إلى أي وصول لقاعدة البيانات:

   • بالنسبة للعملاء وجهات الاتصال والفواتير والخدمات والنطاقات، أعد إطلاق الحدث. عدّل السجل واحفظه في WHMCS، أو شغّل معالج التعبئة الرجعية بالوضع Only new (not yet synced).
   • وبالنسبة لتغييرات جانب Perfex، عدّل سجل Perfex مجدداً لإدراج حدث جديد في الطابور.

4. وإذا فضّلت إعادة تشغيل الصف الأصلي وكان لديك وصول إلى قاعدة البيانات، فأعد ضبطه إلى الحالة pending. خذ نسخة احتياطية أولاً:

   UPDATE mod_perfexbridge_outbox
      SET status = 'pending', attempts = 0, next_attempt_ts = 0
    WHERE id = 123;

   استبدل 123 بمعرّف الصف الذي تريد إعادة تشغيله. والجدول المكافئ على جانب Perfex هو tblwhmcs_bridge_outbox، مع بادئة جداول Perfex لديك.

تغيير في Perfex لا يصل إلى WHMCS أبداً

اعمل على هذه القائمة بالترتيب:

1. هل جانب WHMCS على Pro؟ تحقق من لوحة WHMCS plan في صفحة إعدادات Perfex. فالمزامنة باتجاهين متاحة في Pro فقط.
2. هل WHMCS URL مضبوط على جانب Perfex؟ في Setup > WHMCS Bridge > WHMCS URL، بصيغة HTTPS ودون أي مسار لاحق. وعادةً يملأ الاقتران هذا الحقل في أول مرة، لكنه لا يستبدل أبداً قيمة كانت موجودة أصلاً.
3. هل يستطيع خادم Perfex الوصول إلى WHMCS عبر HTTPS؟ فعميل الدفع في Perfex مقيّد بـ HTTPS ويتحقق من الشهادة، تماماً كجانب WHMCS.
4. هل cron الخاص بـ Perfex يعمل؟ فالتغييرات الناشئة من Perfex تُسلَّم على cron الخاص بـ Perfex، لا على cron الخاص بـ WHMCS. تحقق من مهمة cron في Perfex.
5. هل السجل مرتبط؟ فالعملاء الذين جرت مزامنتهم من WHMCS هم وحدهم المرتبطون. والعميل المُنشأ مباشرةً في Perfex ليس له نظير في WHMCS ولا يُدفع أبداً. وكذلك التذاكر المُنشأة مباشرةً في Perfex تبقى في Perfex.
6. اقرأ لوحة Outbound queue. فهي تذكر آخر خطأ لكل صف.

تغيير ارتد عائداً وطمس تعديلي

العَرَض. عدّلت سجلاً في أحد النظامين، فعاد إلى قيمة النظام الآخر.

السبب. غيّر الجانبان السجل نفسه منذ آخر مزامنة، وحسمت Two-Way Conflict Policy لديك الفائز.

الحل. اختر السياسة التي تناسب طريقة عمل فريقك، تحت Settings > Sync behaviour في صفحة الوحدة داخل WHMCS:

• newest_wins (الافتراضي) - يفوز التعديل الأحدث. ويتطلب دقة ساعتَي الخادمين.
• whmcs_wins - يكون WHMCS هو المرجع دائماً.
• perfex_wins - يكون Perfex هو المرجع دائماً.

وإذا كانت ساعتا المضيفين خارج سيطرتك، فتجنّب newest_wins: فانحراف الساعة يزيح قراراتها بمقدار ذلك الانحراف.

العملاء يتلقون بريدين إلكترونيين لرد واحد على تذكرة

العَرَض. يرد موظف في Perfex على تذكرة مزامَنة، فيتلقى العميل إشعارين.

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

الحل. إذا كان عملاؤك يستخدمون بوابة العملاء في WHMCS، فعطّل قالب البريد ticket-reply في Perfex تحت Setup > Email Templates > Tickets داخل Perfex.

لا تزال عالقاً: ما الذي تجمعه قبل التواصل مع الدعم

جهّز ما يلي وستأتيك الإجابة عادةً من أول رد:

• إصدار الوحدتين، وهو حالياً 1.3.4، وتأكيد أن الجانبين على الإصدار نفسه.
• إصدار WHMCS، وإصدار Perfex CRM، وإصدار PHP على الخادمين.
• لقطة شاشة لـ Setup checklist من صفحة الوحدة داخل WHMCS.
• عددا Queue pending و Dead events.
• الصفوف ذات الصلة من Recent activity في WHMCS ومن Recent inbound events في Perfex، مع عمود الرسالة كاملاً.
• ما الذي كنت تفعله عند حدوث الإخفاق، وما إذا كان النظام قد عمل من قبل.

لا ترسل أبداً سرك المشترك أو Connection code

يحتوي Connection code على سرك المشترك. ولا مكان لأي منهما في تذكرة دعم أو لقطة شاشة أو رسالة محادثة. فالدعم لا يحتاج إلى أي منهما لتشخيص مشكلة.