تخطَّ إلى المحتوى
دليل وقار

المصادقة واختيار النطاقات

يستخدم كل طلب API بيانات اعتماد Bearer صادرة من المدرسة. وليست ملفات تعريف المتصفح أو كلمات المرور أو معرّف المدرسة مصادقة لـ API.

إرسال بيانات الاعتماد

Section titled “إرسال بيانات الاعتماد”
GET /api/v1/school HTTP/1.1
Host: waqar.app
Authorization: Bearer <API_KEY>
Accept: application/json

استخدم TLS وأرسل ترويسة Authorization واحدة فقط وأبقِ بيانات الاعتماد خارج العنوان والجسم. ابدأ بـ GET /school؛ إذ يؤكد data.id المستأجر المرتبط بالمفتاح.

نطاقات القراءة

Section titled “نطاقات القراءة”
النطاقالمورد المسموح
school:readملف المدرسة المصادق عليها
semesters:readالفصول
halqas:readالحلقات
sheikhs:readالشيوخ المؤهلون
students:readالطلاب
sessions:readالجلسات
attendance:readالحضور
recitations:readالتلاوات
learning_plans:readخطط التعلّم المفعلة وتكليفاتها

النطاق students:sensitive:read محجوز وغير قابل للإسناد، ولا يعرض v1 حقول الطالب الحساسة. تتطلب عمليات مرجع السور بيانات اعتماد API صحيحة، لكن لا تتطلب نطاق مورد إضافياً.

نطاقات الكتابة

Section titled “نطاقات الكتابة”
النطاقالمورد المسموح
students:writeعمليات إنشاء الطالب وتحديثه المدعومة
sessions:writeعمليات إنشاء الجلسة وتحديثها وإنهائها المدعومة
attendance:writeإنشاء دفعة الحضور أو تحديثها
recitations:writeإنشاء التلاوة

وجود نطاق كتابة في المفتاح لازم لكنه غير كافٍ. يجب أيضاً أن تكون قدرة الكتابة والإطلاق وسياسة النطاق الحالية فعالة للمدرسة. ولا تعني أهلية القراءة أهلية الكتابة.

تطبيق أقل صلاحية

Section titled “تطبيق أقل صلاحية”
  1. اسرد عمليات التكامل الدقيقة.
  2. طابق كل عملية مع النطاق المطلوب في مرجع نقاط النهاية.
  3. أنشئ مفاتيح منفصلة للأنظمة والبيئات غير المرتبطة.
  4. استبعد النطاقات المستقبلية أو الاحتياطية.
  5. استبدل المفتاح إذا لزم تغيير نطاقاته.
  6. أزل المفاتيح والنطاقات غير المستخدمة دورياً بالتدوير.

تفسير فشل التفويض

Section titled “تفسير فشل التفويض”
  • 401 invalid_api_key: بيانات الاعتماد غائبة أو غير صحيحة أو مجهولة أو منتهية أو ملغاة.
  • 403 insufficient_scope: النطاق الفعلي أو نطاق المفتاح لا يسمح بالعملية؛ استخدم error.details.required_scope للتشخيص.
  • قد تعكس أخطاء 403 الأخرى تعليقاً أو إطلاقاً أو ميزة أو شبكة أو سياسة كتابة.

لا تعِد 401 أو 403 بلا نهاية. صحح بيانات الاعتماد أو احصل على تغيير سياسة مخول. راجع مرجع نقاط النهاية.