مرجع الواجهات البرمجية REST API v1
ملخص نقاط النهاية الأساسية للاكتشاف، الانضمام، المصادقة، السياسات، القنوات، التعاميم، مركز الإجراءات، البحث، ولوحة الإدارة.
نقاط النهاية الرئيسية (/api/v1)
تتطلب جميع المسارات المحمية ترويسة Authorization: Bearer <access_token>، كما تفرض مسارات الإدارة تحت /api/v1/admin/* حماية مستوى التحكم المعزول (X-Madar-Control-Plane-Key).
| الطريقة والمسار | النطاق | الوظيفة |
|---|---|---|
| GET /.well-known/madar-workspace.json | عام | وثيقة اكتشاف المؤسسة ومفتاح Ed25519 العام وحالة توثيق النطاق ومزودي SSO |
| POST /api/v1/enroll | عام (رمز موقّع) | تسجيل جهاز الموظف وربط مفتاحه العام Ed25519 عبر رمز الانضمام |
| POST /api/v1/auth/login | مساحة العمل | تسجيل الدخول بالرقم الوظيفي أو البريد وكلمة المرور ورمز TOTP |
| POST /api/v1/auth/sso/login | دخول موحد SSO | المصادقة عبر OIDC أو SAML 2.0 أو Active Directory LDAP |
| GET /api/v1/policy/me | موثّق | جلب حزمة السياسات الموقعة رقمياً (Ed25519 JWS) للمستخدم الحالي |
| POST /api/v1/broadcasts | ناشر / مسؤول | نشر تعميم رسمي موثق مع خيار سؤال الفهم quiz_ack |
| POST /api/v1/channels/:id/decisions | موثّق | تسجيل قرار معتمد داخل القناة وربطه برسالة المصدر |
| GET /api/v1/hub | موثّق | جلب عناصر مركز الإجراءات (التعاميم العاجلة، المتابعات، القرارات) |
| GET /api/v1/search?q=... | موثّق | البحث العربي الموحد عبر الرسائل والقرارات والتعاميم والدليل |
| POST /v1/handles & POST /v1/wake | مرحّل صامت | تسجيل مقبض الإشعارات 128-بت وإرسال إشارة الإيقاظ الخالية من المحتوى |