مرجع API

يعرض Turbo EA REST API كاملة تشغّل كل ما يمكنك فعله في الواجهة الإلكترونية. يمكنك استخدامها لأتمتة تحديثات المخزون، والتكامل مع خطوط أنابيب CI/CD، وبناء لوحات معلومات مخصصة، أو سحب بيانات هندسة المؤسسة إلى أدوات أخرى (BI أو GRC أو ITSM أو جداول البيانات).

تُعرَض مواصفة OpenAPI 3 الكاملة بشكل حيّ أسفل هذه الصفحة — كل نقطة نهاية ومعامل وشكل استجابة، تُعاد توليدها من مصدر الواجهة الخلفية في كل إصدار.

---

عنوان URL الأساسي

تقع جميع نقاط نهاية API تحت البادئة /api/v1:

https://your-domain.example.com/api/v1

محليًا (إعداد Docker الافتراضي):

http://localhost:8920/api/v1

الاستثناء الوحيد هو نقطة نهاية الصحة، المركّبة على /api/health (دون بادئة إصدار).

---

مرجع API التفاعلي

المواصفة الكاملة لـ OpenAPI 3.1 متاحة في قسم API Endpoints من الشريط الجانبي. تتضمن كل صفحة نقطة نهاية ساحة تجربة تفاعلية يمكنك من خلالها إدخال رمز الحامل (bearer token) الخاص بك وتنفيذ طلبات حقيقية على بيئة Canopy الخاصة بك.

المواصفة الخام قابلة للتنزيل أيضًا لمولّدات الشيفرة:

https://docs.rhizo-tech.org/api/openapi.json

ملاحظة

لاستخدام ساحة التجربة التفاعلية، افتح أي صفحة نقطة نهاية في قسم API Endpoints من الشريط الجانبي، وأدخل رمز الحامل في حقل Authorization، واملأ المعاملات، وانقر Send.

---

المصادقة

تتطلب جميع نقاط النهاية باستثناء /auth/*، وفحص الصحة، والبوابات الإلكترونية العامة، رمز JSON Web Token مُرسَلًا في ترويسة Authorization:

Authorization: Bearer <access_token>

الحصول على رمز

POST /api/v1/auth/login ببريدك الإلكتروني وكلمة مرورك:

curl -X POST https://your-domain.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

تحتوي الاستجابة على access_token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

تكون الرموز صالحة لمدة 24 ساعة افتراضيًا (ACCESS_TOKEN_EXPIRE_MINUTES). استخدم POST /api/v1/auth/refresh لتمديد جلسة دون إعادة إدخال بيانات الاعتماد.

مستخدمو SSO

إذا كانت مؤسستك تستخدم الدخول الموحّد، فلا يمكنك تسجيل الدخول بالبريد الإلكتروني/كلمة المرور. إما أن تطلب من مسؤول إنشاء حساب خدمة بكلمة مرور محلية للأتمتة، أو التقاط رمز JWT من تخزين جلسة المتصفح بعد تسجيل دخول SSO عادي (للاستخدام في التطوير فقط).

استخدام الرمز

curl https://your-domain.example.com/api/v1/cards \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

---

الأذونات

تفرض واجهة API قواعد RBAC نفسها الخاصة بالواجهة الإلكترونية. فتتحقق كل نقطة نهاية مُعدِّلة من دور المستدعي على مستوى التطبيق ومن أي أدوار أصحاب مصلحة يحملها على البطاقة المتأثرة. ولا توجد "أذونات API" منفصلة أو تجاوزات لحسابات الخدمة — فتشغّل نصوص الأتمتة بأذونات المستخدم الذي تستخدم رمزه.

إذا فشل طلب بـ 403 Forbidden، فالرمز صالح لكن المستخدم يفتقر إلى الإذن المطلوب. راجع صفحة المستخدمون والأدوار لسجل الأذونات.

---

مجموعات نقاط النهاية الشائعة

المرجع الحيّ أعلاه هو المصدر الكامل للحقيقة؛ والجدول أدناه خريطة سريعة للمجموعات الأكثر استخدامًا:

البادئة	الغرض
/auth	تسجيل الدخول، والتسجيل، وردّ نداء SSO، وتحديث الرمز، ومعلومات المستخدم الحالي
/cards	عمليات CRUD على البطاقات (الكيان الأساسي)، والتسلسل الهرمي، والسجل، والموافقة، وتصدير CSV
/relations	عمليات CRUD على العلاقات بين البطاقات
/metamodel	أنواع البطاقات، والحقول، والأقسام، والأنواع الفرعية، وأنواع العلاقات
/reports	مؤشرات أداء لوحة المعلومات KPI، والمحفظة، والمصفوفة، ودورة الحياة، والاعتماديات، والتكلفة، وجودة البيانات
/bpm	إدارة عمليات الأعمال — المخططات، والعناصر، وإصدارات التدفق، والتقييمات
/ppm	إدارة محفظة المشاريع — المبادرات، وتقارير الحالة، وWBS، والمهام، والتكاليف، والمخاطر
/turbolens	تحليل مدعوم بالذكاء الاصطناعي (المزوّدون، والنُسخ المكررة، والأمان، وذكاء البنية الاصطناعي)
/risks	سجل مخاطر هندسة المؤسسة (TOGAF المرحلة G)
/diagrams	مخططات DrawIO
/soaw	مستندات بيان عمل البنية
/adr	سجلات قرارات البنية
/users, /roles	إدارة المستخدمين والأدوار (للمسؤول فقط)
/settings	إعدادات التطبيق (الشعار، والعملة، وSMTP، والذكاء الاصطناعي، ومفاتيح الوحدات)
/servicenow	مزامنة ثنائية الاتجاه مع ServiceNow CMDB
/events, /notifications	مسار التدقيق وإشعارات المستخدم (بما في ذلك بثّ SSE)

---

التقسيم إلى صفحات والتصفية والفرز

تقبل نقاط نهاية القوائم مجموعة متسقة من معاملات الاستعلام:

المعامل	الوصف
page	رقم الصفحة (يبدأ من 1)
page_size	عدد العناصر في الصفحة (الافتراضي 50، الأقصى 200)
sort_by	الحقل المُراد الفرز حسبه (مثل name أو updated_at)
sort_dir	asc أو desc
search	تصفية بنص حرّ (حيثما كانت مدعومة)

تُوثَّق عوامل التصفية الخاصة بكل مورد لكل نقطة نهاية في المرجع الحيّ أعلاه (مثل /cards التي تقبل type وstatus وparent_id وapproval_status).

---

الأحداث في الوقت الفعلي (Server-Sent Events)

GET /api/v1/events/stream هو اتصال SSE طويل الأمد يدفع الأحداث حال وقوعها (إنشاء بطاقة، أو تحديثها، أو الموافقة عليها، وما إلى ذلك). تستخدمه الواجهة الإلكترونية لتحديث الشارات والقوائم دون اقتراع متكرر. ويمكن لأي عميل HTTP يدعم SSE الاشتراك — وهو مفيد لبناء لوحات معلومات فورية أو جسور إشعارات خارجية.

---

توليد الشيفرة

لأن واجهة API موصوفة بالكامل بـ OpenAPI 3، يمكنك توليد عملاء آمنين من حيث النوع بأي لغة رئيسية:

# Download the schema (no running instance needed)
curl https://docs.turbo-ea.org/api/openapi.json -o turbo-ea-openapi.json

# Generate a Python client
openapi-generator-cli generate \
  -i turbo-ea-openapi.json \
  -g python \
  -o ./turbo-ea-client-py

# …or TypeScript, Go, Java, C#, etc.

لأتمتة Python، يكون أسهل مسار عادةً هو httpx أو requests باستدعاءات مكتوبة يدويًا — فواجهة API صغيرة بما يكفي ليندر أن يستحق المولّد عناء الاعتمادية.

---

تحديد المعدل

تُحدَّد معدلات نقاط النهاية الحساسة للمصادقة (تسجيل الدخول، والتسجيل، وإعادة تعيين كلمة المرور) عبر slowapi للحماية من هجمات القوة الغاشمة. أما نقاط النهاية الأخرى فلا يُحدَّد معدلها افتراضيًا؛ فإن احتجت إلى خنق نص أتمتة ثقيل، فافعل ذلك على جانب العميل أو خلف الوكيل العكسي لديك.

---

الإصدارات والاستقرار

• يجري إصدار واجهة API عبر البادئة /api/v1. وأي تغيير كاسر سيُدخِل /api/v2 إلى جانبها.
• ضمن v1، يمكن شحن التغييرات الإضافية (نقاط نهاية جديدة، وحقول اختيارية جديدة) في إصدارات ثانوية وترقيعية. أما عمليات الإزالة أو تغييرات العقد فمحجوزة لقفزة إصدار رئيسية.
• يُبلَّغ عن الإصدار الحالي عبر GET /api/health كي تتمكن من اكتشاف الترقيات من الأتمتة.

---

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

المشكلة	الحل
تُعيد /api/docs خطأ 404 على مثيلك الخاص	واجهة Swagger UI معطّلة في الإنتاج. اضبط ENVIRONMENT=development وأعد تشغيل الواجهة الخلفية، أو استخدم المرجع الحيّ أعلاه.
المرجع الحيّ أعلاه فارغ	تحقق من وحدة تحكّم المتصفح — يحمّل التضمين /api/openapi.json؛ وأحيانًا تحجب الوكلاء المؤسسية أو مانعات الإعلانات الصارمة النصوص المستضافة على CDN.
401 Unauthorized	الرمز مفقود أو مشوّه أو منتهي الصلاحية. أعد المصادقة عبر /auth/login أو /auth/refresh.
403 Forbidden	الرمز صالح لكن المستخدم يفتقر إلى الإذن المطلوب. تحقق من دور المستخدم في المستخدمون والأدوار.
422 Unprocessable Entity	فشل تحقق Pydantic. يسرد متن الاستجابة الحقول غير الصالحة وسبب ذلك.
أخطاء CORS من تطبيق متصفح	أضف أصل واجهتك الأمامية إلى ALLOWED_ORIGINS في .env وأعد تشغيل الواجهة الخلفية.