إدارة مفاتيح API

واجهة إدارة مفاتيح API توفر واجهة مستخدم قائمة على الويب لإنشاء ومراقبة وإدارة مفاتيح API المستخدمة للوصول البرمجي إلى واجهة OmniCRM API.

::: note ::: title ملاحظة :::

للحصول على مفاهيم المصادقة العامة لواجهة API وأمثلة الاستخدام، راجع concepts_api. :::

نظرة عامة

تمكن مفاتيح API من المصادقة الآمنة وطويلة الأمد لـ:

• تكاملات الخادم إلى الخادم
• سكربتات الأتمتة
• التطبيقات الخارجية
• المهام المجدولة ووظائف cron
• أنظمة المراقبة الخارجية

على عكس رموز JWT (التي تنتهي صلاحيتها بعد دقائق/ساعات)، تبقى مفاتيح API صالحة حتى يتم إلغاؤها يدويًا أو حتى تاريخ انتهاء صلاحيتها.

الوصول إلى إدارة مفاتيح API

انتقل إلى:

أو مباشرة:

الإذن المطلوب: MANAGE_API_KEYS (دور المسؤول)

عرض قائمة مفاتيح API

تعرض الصفحة الرئيسية جميع مفاتيح API بتنسيق جدول:

الأعمدة:

• الاسم - تسمية وصفية لمفتاح API (مثل "نظام التزويد"، "أداة المراقبة")
• تم إنشاؤه بواسطة - اسم المستخدم للشخص الذي أنشأ المفتاح
• مفتاح API - سلسلة المفتاح الفعلية (مخفية جزئيًا لأغراض الأمان)
• الحالة - نشط، منتهي، أو ملغى
• تاريخ الإنشاء - عندما تم إنشاء المفتاح
• تاريخ الانتهاء - عندما سينتهي صلاحية المفتاح تلقائيًا
• الإجراءات - أزرار تحرير، حذف، إعادة إنشاء

عرض المثال:

أدوات لوحة التحكم

في أعلى الصفحة، يتم عرض إحصائيات ملخصة:

• إجمالي مفاتيح API - عدد جميع مفاتيح API (نشطة وغير نشطة)
• المفاتيح النشطة - المفاتيح الصالحة حاليًا
• ستنتهي قريبًا - المفاتيح التي ستنتهي صلاحيتها في الأيام ��لثلاثين القادمة
• المفاتيح المنتهية - المفاتيح التي تجاوزت تاريخ انتهاء صلاحيتها

إنشاء مفتاح API

الخطوة 1: انقر على "إضافة مفتاح API"

انقر على زر + إضافة في أعلى يمين قائمة مفاتيح API.

الخطوة 2: املأ التفاصيل

يظهر نموذج منبثق يطلب:

الاسم: ________________________

: (مثل "نظام التزويد")

الوصف: __________________

: (اختياري - الغرض من هذا المفتاح)

تاريخ الانتهاء: [اختيار التاريخ]

: (اختياري - اترك فارغًا لعدم وجود انتهاء)

الأذونات: ☐ عرض العملاء ☐ إنشاء عملاء ☐ عرض الخدمات ☐ إنشاء خدمات ☐ تزويد ☐ عرض المخزون ☑ مسؤول (جميع الأذونات)

[إلغاء] [توليد المفتاح]

إرشادات الحقول:

الاسم (مطلوب)

• معرف قصير ووصف
• أمثلة: "نظام التزويد"، "تكامل الفواتير"، "المراقبة"
• يستخدم في سجلات التدقيق ويظهر في القائمة

الوصف (اختياري)

• تفسير أكثر تفصيلًا
• أمثلة: "يستخدم بواسطة خادم تزويد Ansible"، "تزامن الفواتير من طرف ثالث"
• يساعد المسؤولين المستقبليين على فهم غرض المفتاح

تاريخ الانتهاء (اختياري)

• إذا كان فارغًا: المفتاح لا ينتهي أبدًا (غير موصى به)
• إذا تم تعيينه: يصبح المفتاح غير صالح تلقائيًا بعد هذا التاريخ
• موصى به: تعيين تاريخ انتهاء للأمان (90 يومًا إلى سنة واحدة)

الأذونات

• اختر أذونات محددة أو تحقق من "مسؤول" للوصول الكامل
• يتبع نفس نموذج الأذونات المعتمد على الدور كما هو الحال مع حسابات المستخدمين
• أفضل ممارسة: تعيين الحد الأدنى من الأذونات الضرورية

الخطوة 3: توليد ونسخ المفتاح

بعد النقر على "توليد المفتاح"، يعرض النظام مفتاح API الذي تم إنشاؤه حديثًا:

⚠️ انسخ هذا المفتاح الآن - لن ��تم عرضه مرة أخرى!

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

[نسخ إلى الحافظة]

[إغلاق]

::: warning ::: title تحذير :::

احفظ مفتاح API على الفور!

بمجرد إغلاق هذه النافذة، لا يمكن استرداد المفتاح الكامل مرة أخرى. سترى فقط نسخة مخفية (sk_live_...XYZ) في عرض القائمة.

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

الخطوة 4: تكوين تطبيقك

استخدم مفتاح API في طلبات تطبيقك:

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

أو في متغيرات البيئة:

export CRM_API_KEY="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

إدارة المفاتيح الحالية

عرض تفاصيل المفتاح

انقر على أي اسم مفتاح API لعرض التفاصيل الكاملة:

• الاسم الكامل للمفتاح والوصف
• طابع الزمن لإنشاء المفتاح
• اسم المستخدم للمنشئ
• الأذونات المرتبطة
• إحصائيات الاستخدام (إذا تم تنفيذها)
• سجلات الوصول الأخيرة

إعادة إنشاء مفتاح API

إذا تم اختراق مفتاح API أو فقد، قم بإعادة إنشائه:

1. انقر على ⋮ (ثلاث نقاط) في عمود الإجراءات
2. اختر "إعادة إنشاء المفتاح"
3. أكد الإجراء

::: warning ::: title تحذير :::

إعادة الإنشاء تلغي المفتاح القديم على الفور.

ستتوقف أي تطبيقات تستخدم المفتاح القديم عن العمل. قم بتحديث جميع التكاملات بالمفتاح الجديد قبل إعادة الإنشاء. :::

ماذا يحدث:

• يتم إلغاء المفتاح القديم
• يتم إنشاء مفتاح جديد بنفس الأذونات
• يتم عرض المفتاح الجديد (انسخه على الفور)
• الاسم والوصف والأذونات تبقى دون تغيير

إلغاء (حذف) مفتاح API

لإزالة مفتاح API بشكل دائم:

1. انقر على ⋮ (ثلاث نقاط) في عمود الإجراءات
2. اختر "حذف"
3. أكد الحذف

ماذا يحدث:

• يتم إلغاء المفتاح على الفور
• جميع الطلبات التي تستخدم هذا المفتاح تعيد 401 غير مصرح
• يتم إزالة المفتاح من قاعدة البيانات
• لا يمكن التراجع عنه - لا يمكن استرداد المفتاح

متى يجب الإلغاء:

• لم يعد التكامل مطلوبًا
• تم اختراق المفتاح
• تم إيقاف النظام الذي يستخدم المفتاح
• استبداله بمفتاح جديد بأذونات مختلفة

تحرير تفاصيل مفتاح API

لتعديل تفاصيل مفتاح API:

1. انقر على ⋮ (ثلاث نقاط) في عمود الإجراءات
2. اختر "تحرير"
3. قم بتحديث الاسم، الوصف، تاريخ الانتهاء، أو الأذونات
4. انقر على "حفظ التغييرات"

الحقول القابلة للتحرير:

• الاسم
• الوصف
• تاريخ الانتهاء
• الأذونات

غير قابلة للتحرير:

• قيمة المفتاح نفسها (استخدم إعادة الإنشاء للتغيير)
• تاريخ الإنشاء
• تم إنشاؤه بواسطة المستخدم

حالة مفتاح API

يمكن أن تحتوي مفاتيح API على عدة ��الات:

نشط

• المفتاح صالح ويمكن استخدامه
• ضمن تاريخ الانتهاء (أو لا يوجد انتهاء محدد)
• لم يتم إلغاؤه يدويًا
• يظهر بشارة خضراء

ستنتهي قريبًا

• نشط ولكنه سينتهي في الأيام الثلاثين القادمة
• يظهر بشارة برتقالية/تحذيرية
• يُعتبر تدوير المفتاح قبل انتهاء الصلاحية

منتهي

• تجاوز تاريخ الانتهاء
• لم يعد يقبل المصادقة
• يظهر بشارة حمراء
• يمكن حذفه أو تمديد انتهاء الصلاحية

ملغى

• محذوف/معطل يدويًا
• غير صالح بشكل دائم
• لم يعد يظهر في القائمة النشطة

التصفية والبحث

تدعم قائمة مفاتيح API:

البحث:

ابحث بالاسم أو الوصف أو جزء من المفتاح:

تصفية حسب الحالة:

قائمة منسدلة للتصفية لإظهار:

• جميع المفاتيح
• المفاتيح النشطة فقط
• المفاتيح التي ستنتهي قريبًا (في الأيام الثلاثين القادمة)
• المفاتيح المنتهية

الف��ز:

انقر على رؤوس الأعمدة للفرز حسب:

• الاسم
• تاريخ الإنشاء
• تاريخ الانتهاء
• تم إنشاؤه بواسطة

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

إنشاء مفتاح API

• الطول: يجب أن تكون المفاتيح على الأقل 32 حرفًا (النظام يفرض ذلك)
• العشوائية: يتم إنشاؤها باستخدام مولدات أرقام عشوائية آمنة تشفيرياً
• التنسيق: عادةً ما يتم تمييزها (مثل sk_live_) للتعرف عليها

تخزين مفتاح API

في CRM:

• يتم تجزئة المفاتيح قبل التخزين (مثل كلمات المرور)
• يتم عرض المفتاح الكامل مرة واحدة فقط أثناء الإنشاء
• تخزن قاعدة البيانات التجزئة للتحقق
• حتى المسؤولين لا يمكنهم استرداد المفتاح الكامل لاحقًا

في تطبيقك:

• قم بتخزينه في متغيرات البيئة، وليس في الكود
• استخدم أنظمة إدارة الأسرار (AWS Secrets Manager، HashiCorp Vault)
• لا تقم بتسجيل المفاتيح في التحكم في الإصدارات
• قم بتدوير المفاتيح بشكل دوري (90-365 يومًا)

إدارة الأذونات

• مبدأ أقل الأذونات - منح الأذونات الضرورية فقط
• تجنب إنشاء مفاتيح المسؤولين ما لم يكن ذلك ضروريًا للغاية
• استخدم مفاتيح منفصلة للأنظمة/الأغراض المختلفة
• راجع الأذونات بانتظام

المراقبة والتدقيق

• راقب استخدام مفتاح API عبر سجلات النشاط
• قم بإعداد تنبيهات للأنماط غير العادية للوصول
• راجع طوابع الزمن "آخر استخدام" بانتظام
• قم بإزالة المفاتيح غير المستخدمة

تدوير المفاتيح

أنشئ سياسة لتدوير المفاتيح:

1. إنشاء مفتاح جديد بنفس الأذونات
2. تحديث التطبيقات لاستخدام المفتاح الجديد
3. مراقبة للتأكد من عدم استخدام المفتاح القديم
4. إلغاء المفتاح القديم بعد فترة السماح

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

"401 غير مصرح" عند استخدام مفتاح API

• السبب: المفتاح غير صالح، منت��ي، أو غير صحيح
• الإصلاح:
  • تحقق من نسخ المفتاح بشكل صحيح (لا توجد مسافات إضافية)
  • تحقق من حالة المفتاح (نشط مقابل منتهي)
  • تأكد من أن المفتاح لديه الأذونات المطلوبة
  • تأكد من استخدام رأس X-API-KEY (ليس Authorization)

"لم يتم العثور على مفتاح API" بعد الإنشاء

• السبب: قد يكون المفتاح قد تم إنشاؤه ولكن لم يتم تخزينه بشكل صحيح
• الإصلاح:
  • تحقق من قائمة مفاتيح API للمدخل الجديد
  • إذا كان مفقودًا، قم بإنشاء مفتاح جديد
  • أبلغ المسؤول عن المشكلة

مفتاح API سينتهي قريبًا

• السبب: تاريخ الانتهاء يقترب (في غضون 30 يومًا)
• الإصلاح:
  • إنشاء مفتاح جديد مع تاريخ انتهاء ممتد
  • تحديث التطبيقات لاستخدام المفتاح الجديد
  • إلغاء المفتاح القديم بعد الترحيل

لا يمكن حذف مفتاح API

• السبب: قد يكون محميًا أو قيد الاستخدام
• الإصلاح:
  • تأكد من أن لديك أذونات المسؤول
  • تحقق مما إذا كان المفتاح مقفلاً/محميًا
  • اتصل بالمسؤول إذا استمرت المشكلة

نقاط نهاية API (لإدارة برمجية)

يمكن أيضًا إدارة مفاتيح API عبر API (تتطلب أذونات المسؤول):

قائمة مفاتيح API

GET /crm/api-keys
Authorization: Bearer <admin-token>

إنشاء مفتاح API

POST /crm/api-keys
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "تكامل جديد",
  "description": "تزامن الفواتير من طرف ثالث",
  "expiry_date": "2026-01-10",
  "permissions": ["view_customer", "view_service"]
}

الاستجابة:

{
  "api_key_id": 123,
  "name": "تكامل جديد",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0",
  "status": "active",
  "created": "2025-01-10T10:00:00Z",
  "expiry_date": "2026-01-10T23:59:59Z"
}

إلغاء مفتاح API

DELETE /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>

تحديث مفتاح API

PATCH /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "اسم محدث",
  "expiry_date": "2026-12-31"
}

حالات الاستخدام الشائعة

حالة الاستخدام 1: تكامل نظام التزويد

إنشاء مفتاح API لخادم تزويد Ansible الخاص بك:

1. انتقل إلى مفاتيح API → إضافة
2. الاسم: "خادم تزويد Ansible"
3. الوصف: "يستخدم بواسطة أتمتة التزويد"
4. الأذونات: تزويد، عرض/إنشاء خدمات، عرض/تحديث المخزون
5. تاريخ الانتهاء: سنة واحدة
6. انسخ المفتاح وأضفه إلى crm_config.yaml في Ansible

حالة الاستخدام 2: تكامل الفواتير من طرف ثالث

إنشاء مفتاح للقراءة فقط لتصدير الفواتير:

1. الاسم: "تزامن الفواتير - QuickBooks"
2. الأذونات: عرض العملاء، عرض المعاملات، عرض الفواتير
3. تاريخ الانتهاء: 90 يومًا (تدوير ربع سنوي)
4. استخدمه في سكربت التصدير المجدول

حالة الاستخدام 3: المراقبة والتنبيه

إنشاء مفتاح لجمع مقاييس Prometheus/Grafana:

1. الاسم: "المراقبة - Grafana"
2. الأذونات: عرض الخدمات، عرض التزويد
3. تاريخ الانتهاء: أبدا (تحتاج المراقبة إلى وصول مستمر)
4. قم بتكوينه في مصدر بيانات Grafana

حالة الاستخدام 4: واجهة برمجة تطبيقات بوابة العملاء

إنشاء مفتاح لبوابة الخدمة الذاتية للعملاء:

1. الاسم: "واجهة بوابة العملاء الخلفية"
2. الأذونات: عرض العميل الخاص، عرض الخدمات الخاصة، إنشاء المدفوعات
3. تاريخ الانتهاء: 180 يومًا
4. استخدمه في مكالمات واجهة برمجة التطبيقات للبوابة

الوثائق ذات الصلة

• concepts_api - مفاهيم وأمثلة مصادقة API
• rbac - التحكم في الوصول المعتمد على الدور والأذونات
• 2fa - المصادقة الثنائية لمزيد من الأمان