واجهة برمجة التطبيقات OMTrader v1.0 لتكامل CRM

المقدمة

تتضمن واجهة برمجة التطبيقات OMTrader v1.0 لتكامل تطبيقات CRM كلاً من REST API و WebSocket API.

• إذا كان نظام CRM يدعم عميل WebSocket، فنُفضل هذا الخيار.
• معظم موفري CRM يدعمون REST فقط ويستخدمون الاستعلام الدوري لجلب البيانات من OMTrader.

مستويات الوصول إلى API

مستوى API	النطاق	الأمان
التاجر	حساب التاجر	مفتاح API
المدير	الوصول لجميع المجموعات أو بعضها	المصادقة الأساسية
المسؤول	للمسؤول فقط	المصادقة الأساسية

✅ يتطلب تكامل CRM مستوى API المدير.

المتطلبات المسبقة

قبل استخدام API للمدير:

• يجب على المسؤول إنشاء حساب بدور المدير عبر بوابة الإدارة.
• سيتم استخدام هذا الحساب لأغراض الانتحال عبر API.
• يجب أن يبقى الحساب نشطًا أثناء استخدام تطبيق CRM.
• لمنح صلاحية الوصول الكاملة، يجب ربط الحساب بأعلى مجموعة.

💡 نصيحة: سَمِّ الحساب باسم CRM API لتسهيل التعرّف عليه.

نظرة عامة على API

تحتوي واجهة API للمدير على العديد من الإمكانيات. في ما يلي أكثر النقاط استخدامًا في CRM.

التوثيق

• قم بتسجيل الدخول إلى: http://manager.dev.omtrader.io
• استعرض API من خلال لوحة Swagger.
• ستجد هناك تنسيق JSON الكامل للطلبات والاستجابات وأكواد الأخطاء.

المصادقة

نقطة تسجيل الدخول

POST {{url}}/api/v1/oauth2/login?remember_me=false

الرؤوس:

Authorization: Basic <base64(username:password)>

مثال (cURL):

curl --location --request POST 'api.dev.omtrader.io/api/v1/oauth2/login?remember_me=false' \
--header 'Authorization: Basic bWFuYWdlcjoxMjM='

الاستجابة:

{
  "success": true,
  "code": 200,
  "data": {
    "account_id": 2,
    "access_token": "...",
    "refresh_token": "...",
    "session_id": "...",
    "expires_in": 3600,
    "ip_address": "94.249.48.3",
    "scope": "Manager"
  },
  "error": "",
  "message": ""
}

استخدم access_token في جميع الطلبات اللاحقة:

مثال (REST API):

curl --location --globoff '{{url}}/api/v1/manager/accounts?page=2&limit=5' \
--header 'Authorization: Bearer <access_token>'

مثال (WebSocket):

{{ws}}/ws/v1?session_id={{session_id}}&access_token={{token}}

بنية API

المكون	الوصف
الفعل	GET، POST، PUT، DELETE، BATCH
الخادم	خادم API المستهدف
API	ثابت /api
الإصدار	v1، v2، ...
النطاق	trader، manager، admin
الكيان	accounts، groups، commissions ...
الصفحة / الحد	للطلبات من نوع GET فقط

API حساب المدير

الوصف	الفعل	الرابط
جلب جميع الحسابات	GET	/api/v1/manager/accounts
جلب حساب محدد	GET	/api/v1/manager/accounts/:id
تحديث الحساب	PUT	/api/v1/manager/accounts/:id
حذف الحساب	DELETE	/api/v1/manager/accounts/:id
إنشاء حساب	POST	/api/v1/manager/accounts
تحويل الأموال	POST	/api/v1/manager/accounts/1/money
عرض المعاملات	GET	/api/v1/manager/accounts/1/transactions/history

API المجموعات للمدير

الوصف	الفعل	الرابط
جلب جميع المجموعات	GET	/api/v1/manager/groups
جلب مجموعة حسب ID	GET	/api/v1/manager/group/:id
تحديث مجموعة	PUT	/api/v1/manager/group/:id

API العمولات للمجموعات

الوصف	الفعل	الرابط
جلب العمولات	GET	/api/v1/manager/groups/1/commissions
إنشاء عمولة	POST	/api/v1/manager/commissions
تحديث عمولة	PUT	/api/v1/manager/commissions/:id
حذف عمولة	DELETE	/api/v1/manager/commissions/:id

WebSocket API

تنسيق URL لـ WebSocket

{{ws}}/ws/v1?session_id={{session_id}}&access_token={{token}}

• استخدم wss:// في بيئة الإنتاج.

الاتصال

GET {{ws}}/ws/v1?session_id={{session_id}}&access_token={{token}}

مثال استجابة:

Connected to api.dev.omtrader.io/ws/v1?session_id=...&access_token=...

تنسيق حدث WebSocket

{
  "type": "event_name",
  "data": { ... }
}

أحداث الاشتراك

الحدث	البيانات	الوصف
subscribe_group	group_id	الاشتراك في بيانات مجموعة معينة
subscribe_group_session	group_id	الاشتراك في جميع جلسات المجموعة

أحداث إلغاء الاشتراك

الحدث	البيانات	الوصف
unsubscribe_group	group_id	إلغاء الاشتراك في مجموعة معينة
unsubscribe_group_session	group_id	إلغاء الاشتراك في جميع جلسات المجموعة

الحفاظ على اتصال WebSocket

لضمان بقاء الاتصال نشطًا، أرسل "نبض" كل 30 ثانية بالقيمة 9:

private startHeartbeat() {
  if (this.heartbeatInterval) {
    clearInterval(this.heartbeatInterval);
  }
  this.heartbeatInterval = setInterval(() => {
    if (this.webSocket && this.webSocket.readyState === WebSocket.OPEN) {
      this.sendString("9");
    }
  }, 30000); // كل 30 ثانية
}