كيف يعمل والاستخدام اليومي

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

محرك المزامنة بلغة بسيطة

1. التغيير يُطلق حدثاً

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

والخطاف لا يجري أي اتصال HTTP. بل يكتب حدثاً صغيراً في جدول outbox (mod_perfexbridge_outbox) ويعود فوراً.

لماذا يوجد outbox

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

2. cron يفرّغ الطابور

عند كل نبضة من cron النظام في WHMCS، يأخذ الموزّع دفعة من الأحداث المستحقة من outbox ويرسل كلاً منها عبر POST إلى تثبيت Perfex لديك عبر HTTPS.

ويحمل كل طلب ترويستين إلى جانب جسم JSON: طابعاً زمنياً، وتوقيع HMAC-SHA256 محسوباً على ذلك الطابع الزمني إضافةً إلى جسم الطلب بالضبط، باستخدام سرك المشترك. ثم يعيد Perfex حساب التوقيع بنسخته الخاصة من السر ويرفض أي شيء لا يتطابق، أو يزيد عمر طابعه الزمني عن 300 ثانية.

ويمكنك فرض تفريغ فوري في أي وقت عبر Run Sync Now في صفحة الوحدة داخل WHMCS.

3. الإخفاقات تُعاد محاولتها، ثم تنتقل إلى حالة الرسائل الميتة

الإرسال الفاشل لا يضيع، ولا تُعاد محاولته في حلقة متلاحقة. بل تُعاد جدولته بـ تأخير أسّي: نحو 60 ثانية بعد أول إخفاق، ثم دقيقتان، ثم 4، ثم 8، وهكذا، بحد أقصى 6 ساعات بين المحاولات.

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

الحدث الميت إشارة لا كارثة

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

4. الإيقاف المؤقت لا يفقد شيئاً

إزالة التأشير عن Enable Sync توقف التسليم فقط. فتستمر الخطافات في كتابة الأحداث داخل outbox، ولا يُسقَط شيء أثناء الإيقاف. أعد التفعيل وسيُفرَّغ المتراكم في النبضة التالية، أو فوراً عبر Run Sync Now.

5. قمع الصدى يمنع الحلقات اللانهائية

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

ويمنع الجسر ذلك بحواجز متعددة الطبقات، تُطبَّق على الجانبين:

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

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

6. أعمال الصيانة

يشغّل الجانبان عملية تقليم يومية ذاتية التنظيم، مرة واحدة كل 24 ساعة على الأكثر:

• تُحذف صفوف outbox المُسلَّمة الأقدم من 7 أيام؛
• تُحذف صفوف السجل الأقدم من 90 يوماً؛
• أما الصفوف المعلّقة والميتة فلا تُقلَّم أبداً، لأن المعلّق عمل لم يُسلَّم بعد، والميت هو درج الرسائل الميتة لديك.

ما الذي يُزامَن، وفي أي اتجاه

من WHMCS إلى Perfex CRM

البيانات	Free	Pro	ما الذي يصل إلى Perfex
👥 العملاء	✅	✅	عميل في Perfex، إضافةً إلى جهة اتصال أساسية تحمل اسم العميل وبريده الإلكتروني
👤 جهات الاتصال	✅	✅	جهات اتصال إضافية تحت عميل Perfex نفسه
🗑️ حذف عميل	✅	✅	يُعطَّل عميل Perfex، ولا يُتلَف
📄 الفواتير	➖	✅	فاتورة في Perfex ببنودها وصف ضريبة وإجماليات مطابقة وحالة، مع رقم فاتورة WHMCS في ملاحظة المسؤول
💳 المدفوعات والمعاملات	➖	✅	سجل دفعة مقابل الفاتورة المنسوخة، مع بوابة الدفع ومعرّف المعاملة. وتُرفض التكرارات
💸 المبالغ المستردة	➖	✅	تُلغى النسخة في Perfex ويُضاف إليها تعليق
🛒 الطلبات	➖	✅	عميل محتمل في Perfex لكل طلب، أو ملاحظة على العميل، أو لا شيء، حسب Order Sync Target
📦 الخدمات	➖	✅	صفوف في تبويب WHMCS لدى العميل: اسم المنتج والنطاق والحالة ودورة الفوترة والمبلغ وتاريخ الاستحقاق التالي
🌐 النطاقات	➖	✅	صفوف في التبويب نفسه: المُسجِّل والحالة وتاريخ الانتهاء وتاريخ الاستحقاق التالي
🎫 التذاكر والردود	➖	✅	تذكرة في Perfex تحت العميل، في القسم المربوط، مع الردود والحالة

تفصيل خاص بالمستوى المجاني

في الخطة المجانية، تنتقل حالة العميل وملاحظاته ضمن الحمولة لكنها لا تُكتب داخل Perfex. وحذف العميل وحده هو ما يؤثر على سجل Perfex، وذلك بتعطيل العميل.

من Perfex CRM إلى WHMCS (في Pro فقط)

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

عمليات الحذف في جانب Perfex لا تُدفع أبداً إلى WHMCS

حذف عميل أو سجل في Perfex لا يحذف أي شيء في WHMCS. فسجلات الفوترة محفوظة بغض النظر عمّا يحدث في الـ CRM. وهذا سلوك متعمّد وغير قابل للتهيئة.

سلوكيات معروفة يجدر الاطلاع عليها قبل الاعتماد على النظام

هذه قرارات موثّقة، وليست أخطاء برمجية:

• التذاكر المُنشأة مباشرةً في Perfex تبقى في Perfex. فهي لا تُنشأ أبداً في WHMCS، لأن تذكرة WHMCS تحتاج إلى حساب عميل وقسم دعم قد لا يتوفران لتذكرة منشأة من جانب الـ CRM.
• تغيير حالة التذكرة عبر نموذج إعدادات التذكرة الكامل في Perfex لا ينتشر. أما القائمة المنسدلة لحالة تذكرة مفردة، والردود، وتغييرات الحالة الجماعية، والإغلاق التلقائي، فتُزامَن كلها بشكل صحيح.
• الوقت المسجَّل على مهمة Perfex الخاصة بتذكرة لا يُزامَن عائداً إلى WHMCS. فالمهمة موجودة لأغراض تقارير الجداول الزمنية الأصلية في Perfex.
• دورية الفواتير المتكررة غير مُنمذجة. إذ تُنسخ فواتير WHMCS كفواتير Perfex عادية لمرة واحدة.
• دمج عميلين في WHMCS غير مدعوم. وبعد الدمج، أعد ربط صفوف الخريطة للعميل المُستوعَب أو أزلها.
• رد موظف Perfex على تذكرة مزامَنة قد ينتج عنه بريدان إلكترونيان للعميل، أحدهما من Perfex والآخر من WHMCS. فإذا كان عملاؤك يستخدمون بوابة العملاء في WHMCS، فعطّل قالب البريد ticket-reply في Perfex تحت Setup > Email Templates > Tickets.

أين توجد السجلات

هذا هو القسم الذي يوفر أكبر قدر من الوقت. فالناس معتادون على البحث في المكان الخطأ.

جانب WHMCS: صفحة الوحدة نفسها

انتقل إلى Addons > Perfex CRM Bridge ومرّر إلى Recent activity.

ليس سجل النشاط في WHMCS

الجسر لا يكتب في WHMCS Activity Log تحت Utilities > Logs. بل يُعرض جدوله الخاص في لوحة Recent activity ضمن صفحة الوحدة، وهذا هو المكان الوحيد الذي تبحث فيه على جانب WHMCS.

يعرض الجدول آخر 50 حدثاً، بهذه الأعمدة:

العمود	المعنى
Time	وقت كتابة الصف
Dir	القيمة out تعني من WHMCS إلى Perfex، و in تعني من Perfex إلى WHMCS
Event	مثل client.upsert أو invoice.upsert أو cron.drain
Entity	مثل client أو contact أو invoice أو ticket، وهكذا
WHMCS ID	معرّف السجل في WHMCS
Status	القيمة ok بالأخضر أو error بالأحمر
Message	النتيجة، أو نص الخطأ بالضبط

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

جانب Perfex: لوحتان في صفحة الإعدادات

انتقل إلى Setup > WHMCS Bridge.

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

وتسرد Outbound queue تغييرات جانب Perfex المنتظرة للدفع إلى WHMCS، مع:

• عددي pending و dead في عنوان اللوحة؛
• صف واحد لكل تغيير في الطابور يعرض الحدث والكيان والحالة وعدد المحاولات ووقت المحاولة التالية وآخر خطأ؛
• شرح بلغة واضحة بدلاً من خطأ خام حيثما يكون السبب معروفاً. فالرمز 403 الوارد من WHMCS غير مرخّص يُقرأ على أنه "Two-way sync requires Pro on the WHMCS side" مع رابط ترقية، بدلاً من مخرجات JSON خام.

ولا تُعرض سوى آخر 20 صفاً. وتُمحى الصفوف المُسلَّمة تلقائياً بعد 7 أيام؛ أما الصفوف المعلّقة والميتة فيُحتفظ بها.

أي سجل يجيب عن أي سؤال

السؤال	ابحث هنا
📤 هل غادر تغييري نظام WHMCS؟	في WHMCS: Recent activity، الاتجاه out
📥 هل قبله Perfex؟	في Perfex: Recent inbound events
🔑 هل سري المشترك خاطئ؟	في Perfex: صفوف auth.rejected ضمن Recent inbound events
🔁 هل وصل تعديلي في Perfex إلى WHMCS؟	في Perfex: Outbound queue، ثم في WHMCS: Recent activity، الاتجاه in
⏰ هل cron يعمل؟	في WHMCS: صف Cron delivering في قائمة التحقق
🔇 لماذا المزامنة باتجاهين صامتة؟	في Perfex: لوحة WHMCS plan. فإن كانت تعرض Free، فتلك هي إجابتك

معالج التعبئة الرجعية (Pro)

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

ويقع Backfill wizard في صفحة الوحدة داخل WHMCS، أسفل نموذج الإعدادات. وهو يدرج سجلاتك الحالية في نفس outbox الذي تستخدمه المزامنة الحية، فترث التوقيع وإعادة المحاولات والتأخير وحالة الرسائل الميتة نفسها.

النطاقات

أشّر على واحد أو أكثر:

النطاق	ما الذي يدرجه في الطابور
Clients + contacts	كل عميل ضمن المدى المحدد. وتُرافقه جهات الاتصال تلقائياً مع عميلها
Invoices	كل فاتورة ضمن المدى المحدد
Services + domains	كل خدمة ونطاق ضمن المدى المحدد، مع تعبئة تبويب WHMCS في Perfex

التذاكر غير قابلة للتعبئة الرجعية

التذاكر التاريخية لا تُزامَن. فلا ينتقل سوى نشاط التذاكر الجديد بعد تشغيل الجسر. وهذا قيد موثّق، وليس مشكلة تهيئة.

الأوضاع

الوضع	السلوك
All history	كل سجل ضمن النطاقات المختارة
Date range	السجلات المُنشأة داخل نافذة "من" و"إلى" بصيغة YYYY-MM-DD فقط. أما المدى غير الصالح، مثل تاريخ "من" لاحق لتاريخ "إلى"، فيُرفض برسالة واضحة ولا يُدرَج شيء في الطابور
Only new (not yet synced)	يتخطى السجلات المرتبطة أصلاً. وهذا هو الوضع الذي تستخدمه في التشغيلات المتكررة

حد الـ 500 كيان وكيفية المتابعة

تدرج كل عملية تشغيل ما لا يزيد عن 500 كيان، بحيث لا يمكن لعملية تعبئة رجعية على تثبيت كبير أن تُغرق الطابور أو تعطّل cron لديك.

وعند بلوغ الحد، يخبرك المعالج بذلك. والروتين هو:

1. انقر Queue Backfill. ويُبلّغ شريط معلومات بعدد ما جرى التخطيط له، وعدد ما أُدرج في الطابور، وعدد ما أخفق، وما إذا كانت العملية قد اقتُطعت.
2. راقب انخفاض عدّاد Queue pending في أعلى الصفحة، إما عبر cron أو عبر Run Sync Now.
3. أعد تشغيل المعالج بالوضع Only new (not yet synced).
4. كرّر ذلك إلى أن لا تخطط أي عملية تشغيل لشيء جديد.

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

قاعدتان في الترتيب توفران عليك الوقت

عبّئ العملاء رجعياً قبل الخدمات والفواتير، أو معها

السجل الفرعي الذي لم يصل عميله الأب إلى Perfex بعد يُجاب عنه بـ "not mapped, will retry" ويبقى في الطابور إلى أن يصل الأب. وعادةً ما يحل ترتيب الطابور نفسه هذه المسألة. لكن إذا عبّأت رجعياً الخدمات أو الفواتير وحدها على تثبيت لم تُزامَن عملاؤه قط، فستُعاد محاولة تلك الأحداث لنحو 40 ساعة ثم تنتقل إلى حالة الرسائل الميتة.

فإما أن تؤشّر على Clients + contacts في التشغيلة نفسها، أو أن تعبّئ العملاء أولاً.

هيّئ عملات Perfex أولاً

الفاتورة بعملة لا يعرفها Perfex تُرفض وتُعاد محاولتها، ثم تنتقل إلى حالة الرسائل الميتة بعد نحو 40 ساعة. وقبل التعبئة الرجعية للفواتير، أضف كل عملة يستخدمها عملاؤك في WHMCS تحت Setup > Finance > Currencies في Perfex، مستخدماً رمز ISO بدقة.

الفواتير التاريخية المدفوعة

الفواتير المُعبَّأة رجعياً والمدفوعة أصلاً في WHMCS تُسوَّى في Perfex بسجل دفعة اصطناعي، فتظهر بحالة Paid لا Overdue. وإعادة تشغيل التعبئة الرجعية لا تنشئ مدفوعات مكررة.

التشغيل اليومي

بعد اكتمال الإعداد، لا يبقى إلا القليل لتفعله. فنظرة أسبوعية قصيرة على صفحة الوحدة في WHMCS تكفي:

ما الذي تنظر إليه	الحالة السليمة
Setup checklist	أخضر بالكامل، مع الرمادي في صف الرخصة إن كنت تستخدم الخطة المجانية
Queue pending	صغير، ومتناقص بين نبضات cron
Dead events	0
Recent activity	صفوف ok في معظمها
Outbound queue في Perfex	0 معلّق و 0 ميت، في تثبيتات Pro ثنائية الاتجاه

فإذا كان أي شيء في تلك القائمة غير سليم، ففي استكشاف الأخطاء وإصلاحها السبب والحل.