تكامل WHMCS

قبل البدء

أكمل:

1. إعداد المتجر
2. فهم الفلو

استخدم هذا المسار إذا كان موقعك يعمل على WHMCS (Web Host Manager Complete Solution) وتريد إضافة رصيد تلقائيًا لحساب العميل عند مطابقة دفعة VodafoneCash.

كيف يعمل

عند مطابقة الدفعة على منصتنا، يقوم الخادم لدينا باستدعاء WHMCS API مباشرةً:

• المسار: POST https://your-whmcs.com/includes/api.php
• الإجراء: AddCredit
• المعاملات:
  • identifier — معرّف API في WHMCS
  • secret — مفتاح API السري في WHMCS
  • clientid — رقم معرّف العميل في WHMCS (يُرسَل عبر user_name من نموذج الدفع)
  • description — VodafoneCash payment - trans_id: {trans_id}
  • amount — الرصيد المحوَّل (بعد تطبيق معدل العملة في المتجر)

يرد WHMCS بـ { "result": "success", ... } عند النجاح.

لا تحتاج إلى إنشاء endpoint callback مخصص في موقعك — يقوم الخادم بالاتصال بـ WHMCS API مباشرةً باستخدام بياناتك.

إعدادات المتجر

API URL

أدخل رابط WHMCS الأساسي (بدون شرطة مائلة في النهاية):

https://your-whmcs.com

يضيف النظام تلقائيًا /includes/api.php إلى الرابط.

WHMCS Identifier & Secret

كيفية الحصول على بيانات API في WHMCS:

1. سجّل الدخول إلى لوحة تحكم WHMCS.
2. اذهب إلى Configuration → Manage API Credentials (أو System Settings → API Credentials).
3. انقر على Generate New API Credential.
4. اربطه بمسؤول وحدد صلاحية Add/Remove Credit (أو صلاحيات أوسع).
5. ⚠️ انسخ Identifier وSecret فورًا — لن يظهر Secret مرة أخرى.
6. الصق القيم مباشرة في حقلي WHMCS Identifier وWHMCS Secret.

تعيين user_name

عند تحديد من سيتلقى الرصيد التلقائي، يجب أن يتطابق حقل user_name المرسل في طلب التحقق مع رقم معرّف العميل في WHMCS (رقمي).

مثال على اتصال التحقق من الدفع:

GET /api/payment_link_check?phone=01000000000&amount=100&user_name=42&store_id=5&lang=ar

user_name=42 يعني أن العميل رقم 42 في WHMCS سيُضاف إليه الرصيد بمجرد المطابقة.

إضافة الدفع الرسمية لـ WHMCS (موصى بها)

لعرض نموذج الدفع في فواتير العملاء وتشغيل التحقق بأمان دون كشف store_id الخاص بك، نوفر إضافة بوابة دفع رسمية لـ WHMCS.

الإضافة مفتوحة المصدر ومتاحة على GitHub: vodafoncash-whmcs-module.

1. افتح صفحة الإصدارات Releases (v1.0.0) وحمّل أحدث ملف .zip.
2. فك ضغط محتويات الملف مباشرة داخل المجلد الرئيسي (root directory) لتثبيت WHMCS الخاص بك. (هذا سيضع الملفات بشكل آمن في مجلد modules/gateways/).
3. سجّل الدخول إلى منطقة إدارة WHMCS.
4. اذهب إلى System Settings (الضبط أو أيقونة المفك) ← Payment Gateways (بوابات الدفع).
5. انقر على تبويب All Payment Gateways وانقر على VodafoneCash لتفعيلها.
6. قم بضبط إعدادات الموديول:
   • VodafoneCash System URL: أدخل رابط المنصة الخاص بنا (مثال: https://vodafoncash.com).
   • Store ID: أدخل معرف المتجر الخاص بك.
7. حدد استعراض البوابة في نموذج الطلب (Show on Order Form).

ماذا يفعل الموديول؟

عندما يعرض العميل فاتورة غير مدفوعة ويختار VodafoneCash، تظهر تلقائيًا استمارة تطلب منه إدخال رقم المحفظة.

عند التأكيد:

1. يرسل الموديول البيانات (رقم المحفظة، المبلغ، معرّف العميل) بشكل آمن إلى ملف callback خلفي مخصص (modules/gateways/callback/vodafoncash.php).
2. من الخلفية، يتم استخدام الـ Store ID الخاص بك بأمان لإجراء استدعاء GET /api/payment_link_check مع خوادمنا.
3. في حال النجاح، تتطابق الدفعة في منصتنا والتي تقوم فوراً باستدعاء واجهة برمجة تطبيقات AddCredit الخاصة بك في WHMCS لإضافة الرصيد للعميل.
4. تظهر رسالة نجاح للعميل ويتم إعادته لمشاهدة فاتورته المحدثة.

Anti-Spam

إذا كانت ميزة Anti-Spam مفعّلة في متجرك، قد تدخل الدفعة في حالة انتظار الموافقة قبل إضافة الرصيد. يجب أن يتعامل نموذج الدفع مع استجابة requires_verification: true — راجع دليل نموذج التحقق للتفاصيل.

قائمة التحقق السريع

قبل الإطلاق:

• [ ] تم إنشاء بيانات WHMCS API (identifier + secret)
• [ ] تم تعيين API URL على رابط WHMCS الأساسي (مثال: https://your-whmcs.com)
• [ ] تم ملء حقلي WHMCS Identifier و Secret
• [ ] نموذج الدفع يرسل user_name = رقم معرّف العميل في WHMCS
• [ ] تم ضبط معدل العملة في إعدادات المتجر