مرجع 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 (دون بادئة إصدار).
مرجع OpenAPI الحيّ¶
تُولَّد واجهة Swagger UI التفاعلية أدناه مباشرةً من مصدر FastAPI في كل إصدار وتُشحَن مع دليل المستخدم — دون الحاجة إلى مثيل واجهة خلفية لتصفّحها. استخدم مربع التصفية لتضييق نقاط النهاية حسب الوسم، ووسّع أي عملية لرؤية المعاملات، ومخططات الطلب/الاستجابة، وأمثلة الحمولات. والمواصفة الخام قابلة للتنزيل بصيغة JSON من /api/openapi.json لمولّدات الشيفرة مثل openapi-generator-cli.
تجربة نقاط النهاية مقابل مثيلك الخاص
تجربة Try-it-out معطّلة هنا عن قصد — فموقع التوثيق لا يوكّل واجهة API الخاصة بك. لإرسال طلبات حقيقية، شغّل Turbo EA في وضع التطوير (ENVIRONMENT=development) وافتح /api/docs على مثيلك الخاص: انقر Authorize، والصق رمز JWT (دون البادئة Bearer)، واستخدم Try it out. في عمليات النشر الإنتاجية تكون تلك النقاط معطّلة لأسباب أمنية؛ وتظل هذه الصفحة المتصفّح للقراءة فقط.
المصادقة¶
تتطلب جميع نقاط النهاية باستثناء /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 وأعد تشغيل الواجهة الخلفية. |