انتقل إلى المحتوى الرئيسي

OmniCRM API

جميع الوظائف داخل OmniCRM متاحة عبر واجهة برمجة التطبيقات - لا توجد وظائف متاحة فقط في واجهة المستخدم.

هذا يتيح لك دمج OmniCRM مع أنظمة أخرى أو أتمتة المهام.

واجهة برمجة التطبيقات هي واجهة RESTful، ومحمية باستخدام عدة طرق للمصادقة بما في ذلك رموز JWT، ومفاتيح API، وقوائم IP البيضاء.

تم توثيق واجهة برمجة التطبيقات باستخدام Swagger، وهي أداة تسمح بقراءة سهلة وفهم واختبار وظائف واجهة برمجة التطبيقات.

تتوفر وثائق واجهة برمجة التطبيقات على عنوان URL التالي:

<https://yourcrm/crm/docs/>

OmniCRM Swagger Page

طرق المصادقة​

يدعم OmniCRM ثلاث طرق للمصادقة، كل منها مصمم لحالات استخدام مختلفة:

  1. رموز JWT Bearer - لجلسات المستخدم التفاع��ية (واجهة الويب، تطبيقات الهاتف المحمول)
  2. مفاتيح API - للتكاملات بين الخوادم وسكربتات الأتمتة
  3. قائمة IP البيضاء - للأنظمة الداخلية الموثوقة (خوادم التوزيع، أدوات المراقبة)

مصادقة رموز JWT Bearer​

هذه هي الطريقة الأساسية للمصادقة لجلسات المستخدم. يقوم المستخدمون بتسجيل الدخول باستخدام البريد الإلكتروني وكلمة المرور، ويتلقون رمز JWT، ويستخدمونه في الطلبات اللاحقة.

حالات الاستخدام:

  • مصادقة واجهة الويب
  • مصادقة تطبيق الهاتف المحمول
  • الوصول البرمجي قصير الأمد

كيفية المصادقة:

لتسجيل الدخول، أرسل جسم JSON بالهيكل التالي إلى /crm/auth/login كطلب POST:

{
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}

ستعيد واجهة برمجة التطبيقات كائن JSON يحتوي على حقل token، والذي يستخدم لمصادقة جميع الطلبات المستقبلية. بالإضافة إلى ذلك، تتض��ن الاستجابة حقل refresh_token يمكن استخدامه لتجديد الرمز عند انتهاء صلاحيته، جنبًا إلى جنب مع أذونات المستخدم وأدواره.

يمكنك اختبار ذلك من صفحة Swagger عن طريق اختيار نقطة النهاية /auth/login ، وملء اسم المستخدم وكلمة المرور، والنقر على زر Try it out.

OmniCRM Swagger Page

لتفويض الجلسة، انسخ قيمة الرمز وانقر على زر "Authorize" في أعلى يمين صفحة Swagger. ألصق الرمز في حقل "Value"، مسبوقًا بـ Bearer وانقر "Authorize".

OmniCRM Swagger Bearer Auth

الآن، سيتم مصادقة جميع الطلبات اللاحقة باستخدام هذا الرمز.

مصادقة مفتاح API​

توفر مفاتيح API مصادقة آمنة وطويلة الأمد للتكاملات بين الخوادم وسكربتات الأتمتة دون الحاجة إلى كلمات مرور المستخدمين.

حالات الاستخدام:

  • أنظمة التوزيع الآلي
  • أدوات المراقبة والتنبيه
  • التكامل مع الأنظمة الخارجية
  • المهام المجدولة ووظائف cron

كيفية عمل مفاتيح API:

يتم تكوين مفاتيح API في ملف crm_config.yaml وترتبط بدور وأذونات محددة. كل مفتاح API هو سلسلة عشوائية آمنة (حد أدنى 32 حرفًا) تقوم بمصادقة الطلبات عند تمريرها في رأس X-API-KEY.

تكوين مفاتيح API:

يجب إضافة مفاتيح API إلى crm_config.yaml بواسطة مسؤول لديه وصول إلى الخادم:

api_keys:
  your-secure-api-key-here-minimum-32-chars:
    roles:
      - admin
    description: "Provisioning automation system"
  another-api-key-for-monitoring-system:
    roles:
      - view_customer
      - view_service
    description: "Monitoring and alerting"

استخدام مفاتيح API:

قم بتضمين مفتاح API في رأس X-API-KEY لطلباتك:

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: your-secure-api-key-here-minimum-32-chars"

مثال Python:

import requests

crm_url = 'https://yourcrm.com'
api_key = 'your-secure-api-key-here-minimum-32-chars'

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": api_key
}

# Get Customers
response = requests.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)

أفضل الممارسات:

  • توليد مفاتيح API باستخدام مولدات عشوائية آمنة من الناحية التشفيرية (openssl rand -base64 48)
  • استخدام مفاتيح API مختلفة للأنظمة المختلفة
  • توثيق الغرض من كل مفتاح API في حقل description
  • تدوير مفاتيح API بشكل دوري
  • عدم الالتزام بمفاتيح API في التحكم في الإصدارات
  • تعيين الحد الأدنى من الأذونات الضرورية لكل مفتاح API

مصادقة قائمة IP البيضاء​

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

حالات الاستخدام:

  • خوادم التوزيع الداخلية
  • أنظمة مراقبة الشبكة على VLANs الإدارية
  • كتب تشغيل Ansible تعمل على بنية تحتية مسيطر عليها

تكوين قائمة IP البيضاء:

أضف عناوين IP الموثوقة إلى crm_config.yaml:

ip_whitelist:
  - 192.168.1.100
  - 10.0.0.0/24
  - 172.16.50.10

اعتبارات الأمان:

  • استخدم قائمة IP البيضاء فقط على الشبكات الخاصة والمحمية
  • لا تقم بإضافة عناوين IP العامة إلى القائمة البيضاء
  • استخدم أكثر نطاقات IP تحديدًا ممكنة
  • وثق سبب إضافة كل IP إلى القائمة البيضاء
  • قم بتدقيق عناوين IP المضافة إلى القائمة البيضاء بانتظام

مثال على استدعاءات API باستخدام Python​

إليك مثال على كيفية تسجيل الدخول واسترداد قائمة العملاء باستخدام مصادقة رمز JWT:

import requests

crm_url = 'https://yourcrm.com'
session = requests.Session()

print("Provisioning data to server: " + str(crm_url))

headers = {
    "Content-Type": "application/json"
}

# Get Auth Token
response = session.post(crm_url + '/crm/auth/login', json={
    "email": "youruser@yourdomain.com",
    "password": "yourpassword"
}, headers=headers)

print(response.status_code)
print(response.json())
assert response.status_code == 200

headers['Authorization'] = 'Bearer ' + response.json()['token']
print("Authenticated to CRM successfully")

# Get Customers
response = session.get(crm_url + '/crm/customers', headers=headers)
for customer in response.json()['data']:
    print(customer)