## نظرة عامة

واجهة Institflow البرمجية هي واجهة REST تُبنى حول الموارد، وتغطي كل جانب من إدارة مدرسة أو معهد تدريب: الأشخاص (الطلاب، أولياء الأمور، الموظفون)، الشؤون الأكاديمية (المساقات، المجموعات التدريسية، التسجيلات، الحصص)، الحضور، التقييم (الامتحانات، العلامات، تقارير التقدّم)، الفوترة (الفواتير، المدفوعات)، الإشعارات، والإدارة (الأعضاء، الأدوار، الإعدادات، الفروع). تتحدّث JSON فقط، وتستخدم أسماء موارد بصيغة الجمع (`/students`، `/invoices`)، وكل معرّف هو UUID من الإصدار السابع — قابل للترتيب حسب وقت الإنشاء، وهو ما يجعل التصفّح بالمؤشّر (انظر [الاصطلاحات](https://docs.institflow.com/ar/guides/conventions#pagination)) عملية خفيفة التكلفة.

بالإضافة إلى واجهة REST، توجد ثلاث وسائل تكامل للبناء فوق Institflow دون تدخّل بشري مباشر في كل خطوة: [الويب هوك (webhooks)](https://docs.institflow.com/ar/webhooks) (إشعارك عند حدوث أمر ما)، وأداة [التسجيل القابلة للتضمين](https://docs.institflow.com/ar/widget) (لإضافة نموذج جذب عملاء محتملين إلى أي موقع)، وخادم [MCP](https://docs.institflow.com/ar/mcp) (لتمكين وكيل ذكاء اصطناعي من تشغيل النظام بصلاحيات حقيقية ومحدودة).

## عنوان الأساس (Base URL)

كل نقطة نهاية في هذا المرجع تقع تحت المسار `/api/v1`. يُباع Institflow بالاستضافة الذاتية حصرًا، فلا يوجد عنوان بائع مشترك تتصل به: عنوان الأساس هو **عنوان معهدك الخاص في Institflow** — نفس المضيف الذي تسجّل دخولك عليه بالفعل. إن كنت لا تعرفه، اسأل مسؤول النظام لديك؛ لا تفترض أي نطاق أبدًا، بما في ذلك النطاق أدناه الذي هو مجرد عنصر نائب:

```bash
https://your-institute.example/api/v1/students
```

لا يوجد نطاق فرعي خاص بكل مستأجر ولا اسم مضيف مشترك متعدد المستأجرين: كل تثبيت مستضاف ذاتيًا (انظر [الاستضافة الذاتية والترخيص](https://docs.institflow.com/ar/guides/self-hosting)) يخدم معهده فقط، على أي مضيف نُشر عليه — نطاق عادي، أو نطاق مخصّص تم التحقّق منه، أو عنوان داخلي، بحسب كيفية إعداد المعهد له. يُحدَّد المستأجر من بيانات الاعتماد التي تُصادق بها (مفتاح API أو JWT مرتبط دائمًا بمستأجر واحد فقط)، وليس من اسم المضيف.

## إصدارات الواجهة

يُحدَّد إصدار الواجهة في مسار الرابط (`/api/v1`)، وليس عبر ترويسة أو معطى استعلام. ضمن خط إصدار واحد، تكون التغييرات إضافية ومتوافقة مع الإصدارات السابقة: حقول طلب اختيارية جديدة، حقول استجابة جديدة، نقاط نهاية جديدة، وقيم تعداد (enum) جديدة يجب أن يكون تعاملك معها متسامحًا أصلًا. أي تغيير غير متوافق سيصدر كـ `/api/v2` — يوجد إصدار واحد فقط اليوم.

## النشر

يُشحَن Institflow كحزمة Docker أحادية المستأجر تُشغّلها على خادمك الخاص، مقيّدة بترخيص موقّع (انظر [الاستضافة الذاتية والترخيص](https://docs.institflow.com/ar/guides/self-hosting)). لا يوجد بديل مستضاف من المزوّد متعدد المستأجرين: تبقى بيانات معهدك وواجهته البرمجية على بنية تحتية تتحكّم بها أنت، والعزل عن تثبيت أي معهد آخر عزل فعلي، وليس مجرد عزل مفروض في البرمجيات فحسب (انظر [تعدّد المستأجرين](https://docs.institflow.com/ar/guides/conventions#multi-tenancy) لمعرفة كيفية عمل العزل ضمن مستأجرك الخاص).

> **لا توجد بيئة تجريبية عامة**
>
> لا توجد بيئة تجريبية عامة مشتركة. لتجربة الواجهة، شغّل حزمة الاستضافة الذاتية محليًا — فهذا يمنحك مستأجرًا حقيقيًا ومعزولًا تبني فوقه، ولا يظهر ما تفعله فيه لأي طرف آخر.