مفاتيح API

يخوّل مفتاح API نظامًا خارجيًا، مثل نظام ERP لديكم، استخدام REST API v1 الخاصة بـ exoCortex: فتح التذاكر، وقراءة حالتها، وإضافة التعليقات. ينتمي كل مفتاح إلى مستأجر (tenant) واحد ولا يرى إلا تذاكر ذلك المستأجر.

إنشاء مفتاح

1. في exoCortex Core افتحوا Integrations → API keys. يلزم دور إداري، مثل it_admin أو integration_admin.
2. أعطوا المفتاح اسمًا يدل على الجهة التي تستخدمه، مثل «موصِّل ERP».
3. اختاروا النطاقات (scope)، أي ما يمكن للمفتاح فعله (انظروا أدناه).
4. انسخوا المفتاح الكامل واحفظوه في أداة إدارة الأسرار الخاصة بالنظام الذي سيستخدمه. يعرضه exoCortex مرة واحدة فقط ولا يحتفظ إلا ببصمته: إذا فقدتموه، أنشئوا مفتاحًا جديدًا.

يأخذ المفتاح الشكل nhk.<keyid>.<secret>. يعرّف keyid المفتاح في القائمة؛ أما secret فيبقى لديكم وحدكم.

النطاقات (Scope)

النطاق	ما الذي يسمح به
tickets:create	فتح التذاكر
tickets:read	قراءة حالة تذكرة
tickets:comment	إضافة تعليقات إلى تذكرة
tickets:*	جميع العمليات على التذاكر
*	كل ما تسمح به API v1

أسندوا إلى كل مفتاح النطاقات التي يحتاجها فقط. المفتاح الذي لا يحمل نطاقات يتمتع بوصول كامل إلى API v1: وهذا مسموح، لكنه غير مستحسن.

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

أرسلوا المفتاح في الترويسة Authorization لكل طلب:

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

بدلًا من ذلك يمكنكم استخدام الترويسة X-NH-API-Key. لا حاجة إلى تحديد المستأجر: يستنتجه exoCortex من المفتاح.

استخدموا دائمًا Idempotency-Key عند فتح تذكرة: إذا كرّرتم الطلب بمفتاح عدم التكرار (idempotency) نفسه، تتلقون التذكرة المنشأة سابقًا بدلًا من نسخة مكررة.

حدود معدّل الطلبات

لكل مفتاح حد للطلبات: القيمة الافتراضية هي 600 طلب كل 60 ثانية. تبيّن كل استجابة موقعكم من هذا الحد:

الترويسة	المعنى
RateLimit-Limit	عدد الطلبات المسموح بها في النافذة الزمنية
RateLimit-Remaining	عدد الطلبات المتبقية
RateLimit-Reset	عدد الثواني حتى بدء النافذة الجديدة
Retry-After	مع الاستجابة 429 فقط: عدد الثواني الواجب انتظارها قبل إعادة المحاولة

الأخطاء

تُعيد أخطاء API v1 كائن JSON يتضمن ok: false، ورسالة مقروءة في error، ورمزًا ثابتًا في code. ابنوا منطق العميل الخاص بكم على code، لا على الرسالة.

code	حالة HTTP	ما العمل
missing_api_key	401	أضيفوا الترويسة Authorization
invalid_api_key	401	تحققوا من المفتاح: قد يكون خاطئًا أو ملغى
insufficient_scope	403	أضيفوا إلى المفتاح النطاق المحدد في required_scope
api_key_disabled	403	المفتاح معطّل: استخدموا مفتاحًا فعّالًا
validation_error	400	صحّحوا الحقل المحدد في field
not_found	404	التذكرة غير موجودة أو لا تنتمي إلى مستأجر المفتاح
rate_limited	429	انتظروا عدد الثواني المحدد في Retry-After
ingest_failed	500	أعيدوا المحاولة بالقيمة نفسها لـ Idempotency-Key

قد يضيف exoCortex رموزًا جديدة: إذا تلقيتم رمزًا لا تعرفونه، فقرّروا بناءً على حالة HTTP.

إلغاء مفتاح

من Integrations → API keys تلغون مفتاحًا عندما لا يعود أي نظام يستخدمه، أو إذا اشتبهتم في أنه قد كُشف. يسري الإلغاء فورًا. تعرض القائمة أيضًا آخر استخدام لكل مفتاح: وهذا يساعدكم على العثور على المفاتيح غير النشطة.

مفاتيح nh_… المُهمَلة

تعمل المفاتيح بالصيغة القديمة nh_… حتى 30 يونيو 2027. تتضمن الاستجابات لهذه المفاتيح الترويستين Deprecation وSunset. للانتقال أنشئوا مفتاح nhk. بالنطاقات اللازمة، وحدّثوا النظام الذي يستخدمه، ثم ألغوا المفتاح القديم.