يخص: الحزمة الكاملة · واجهة API

مرجع الـ API

واجهة REST التي يستخدمها الموقع ومنطقة المتعلّم واللوحة (111 نقطة)، مع الدخول والأخطاء.

كل النقاط تحت /api، وتستقبل JSON وترده، وتستخدم شكل الخطأ نفسه:

{ "error": { "code": "validation", "message": "price: Too small: expected number to be >=0" } }
الحالة الرموز التي ستراها
400 bad_json
401 unauthorized وinvalid_credentials
403 forbidden وnot_enrolled وlocked وno_profile
404 not_found (وكذلك للسجلات خارج نطاق المدرّب)
409 conflict (رابط أو رمز أو بريد مستخدم) وin_use وhas_students وalready_passed وno_attempts_left وnot_eligible وowned وbad_transition وlast_admin وself
422 validation وcoupon_invalid وpayment_disabled وpayment_required وunavailable
429 rate_limited
502/503 payment_unavailable وai_failed وai_off

المبالغ دائمًا أعداد صحيحة بالبيسة (الريال = 1000 بيسة)، والتواريخ بصيغة ISO 8601.

الدخول

جلستان منفصلتان، كلتاهما ملف httpOnly موقَّع بـ AUTH_SECRET:

  • المتعلّمون: يضبط POST /api/account/login أو /register الملف maarifa_student (30 يومًا).
  • اللوحة: يضبط POST /api/auth/login الملف maarifa_staff (12 ساعة). ويُعاد قراءة الحساب في كل طلب، فإيقاف الحساب أو تغيير دوره يسري فورًا.

نقاط PATCH تغيّر الحقول المرسلة فقط: إرسال {"status":"ARCHIVED"} لدورة يُبقي كل ما سواه.

العامة

الطريقة المسار
GET /api/academy بيانات الأكاديمية وخيارات الدفع والمجالات بأعدادها والأرقام الرئيسية
GET /api/courses الدورات المنشورة. المعاملات: q وcategory (قائمة بفواصل) وlevel وprice=free|paid وlang وrating (3 أو 3.5 أو 4 أو 4.5) وduration=short,medium,long وsort=popular|rating|newest|price-asc|price-desc وpage وperPage
GET /api/courses/{slug} صفحة الدورة: المحتوى بعناوين الدروس وعلامات المعاينة، والمدرّب، والأسئلة، والتقييمات وتوزيعها؛ ويخبر viewer المتعلّم المسجّل هل هو مسجّل في الدورة أو حفظها
GET /api/courses/{slug}/reviews التقييمات المعتمدة
GET /api/instructors و/api/instructors/{slug} الملفات بالخبرة والمهارات والدورات
GET /api/blog و/api/blog/{slug} المقالات المنشورة
GET /api/certificates/{code} التحقق من شهادة
POST /api/cart/quote {courseIds, couponCode?} ← الأسطر وتنبيهاتها، ونتيجة الكوبون، والمجموع والخصم والضريبة والإجمالي، وخيارات الدفع
GET /api/learn/{slug}/lessons/{lessonId} درس: دروس المعاينة للجميع، وكل الدروس للمسجّلين، وإلا 403 locked
GET /api/payments/thawani/return رابط العودة من «ثواني»؛ يتحقق من الجلسة لدى «ثواني» ثم يحوّل إلى طلبات المتعلّم

المتعلّم

الطريقة المسار
POST /api/account/register {name, email, password (8+), phone?}
POST /api/account/login و/api/account/logout
GET وPATCH /api/account/me الملف، ومعرّفات الدورات المحفوظة والمسجّل فيها، والرسائل غير المقروءة؛ PATCH {name?, phone?, headline?}
PUT /api/account/password {current, next}
GET وPOST وDELETE /api/account/wishlist الدورات المحفوظة؛ الجسم {courseId}
GET /api/account/courses تسجيلاتي مع التقدّم ودرس المتابعة ورمز الشهادة
GET /api/account/certificates شهاداتي
GET /api/account/orders طلباتي
GET وPOST /api/account/messages محادثاتي؛ POST {courseSlug, subject, body} (للدورات المسجّل فيها فقط)
GET وPOST /api/account/messages/{id} محادثة (تُعلَّم مقروءة)؛ POST {body}
POST /api/courses/{slug}/enrol التسجيل في دورة مجانية
POST /api/courses/{slug}/reviews {rating 1-5, body} للمسجّلين فقط، وينتظر المراجعة
POST /api/orders {courseIds, couponCode?, paymentMethod: CARD|BANK, locale} ← {code, status} ومعها payUrl للبطاقة. الإجمالي الصفري يُدفع ويُسجَّل فورًا
GET /api/learn/{slug} المحتوى مع علامات الإتمام، وحالة الاختبارات، والتقدّم، ودرس المتابعة، والجلسات المباشرة بروابطها، وحالة الشهادة
POST /api/learn/{slug}/lessons/{lessonId}/complete {done: true|false} ← {progress}
PUT /api/learn/{slug}/lessons/{lessonId}/note {body} (الفارغ يحذف)
GET /api/learn/{slug}/quizzes/{quizId} الأسئلة دون الإجابات الصحيحة، ومحاولاتي، والمحاولات المتبقية
POST /api/learn/{slug}/quizzes/{quizId}/attempts {answers: [رقم الخيار أو -1, ...]} ← الدرجة والنجاح والمحاولات المتبقية والمراجعة بالإجابات الصحيحة وشرحها
POST /api/learn/{slug}/certificate يصدر الشهادة، أو 409 not_eligible مع ما ينقص

اللوحة

الصلاحية بين قوسين (راجع لوحة الإدارة والمدرّبين). لا يصل المدرّب إلا إلى دوراته وما يتعلق بها.

الطريقة المسار
POST /api/auth/login و/api/auth/logout
GET /api/auth/me الحساب وصلاحياته
GET /api/dashboard/stats أرقام النظرة العامة ورسومها
GET /api/dashboard/earnings المبيعات وحصة المدرّب [earnings]
GET وPOST /api/dashboard/courses القائمة (status وq) والإنشاء [courses]؛ والنشر يحتاج [publish]
GET وPATCH وDELETE /api/dashboard/courses/{id} بيانات المحرّر، والتعديل، والحذف (فقط دون متعلّمين أو طلبات)
POST /api/dashboard/courses/{id}/sections {titleAr, titleEn, sort?}
PATCH وDELETE /api/dashboard/sections/{id}
POST /api/dashboard/courses/{id}/lessons {sectionId, titleAr, titleEn, kind, videoUrl, bodyAr, bodyEn, minutes, preview}
GET وPATCH وDELETE /api/dashboard/lessons/{id} يُعاد حساب تقدّم المسجّلين بعد إضافة الدروس أو حذفها
GET وPOST /api/dashboard/quizzes [quizzes]
GET وPATCH وDELETE /api/dashboard/quizzes/{id} الاختبار بأسئلته وإجاباتها الصحيحة
POST /api/dashboard/quizzes/{id}/questions {kind: MCQ|TF, promptAr, promptEn, options:[{ar,en}], correct, explanationAr?, explanationEn?}
PATCH وDELETE /api/dashboard/questions/{id}
GET وPOST /api/dashboard/sessions الجلسات المباشرة (from وto) [schedule]
PATCH وDELETE /api/dashboard/sessions/{id}
GET /api/dashboard/messages المحادثات (status وunread) [messages]
GET وPOST وPATCH /api/dashboard/messages/{id} القراءة، والرد {body}، والإغلاق أو إعادة الفتح {status}
GET /api/dashboard/students و/api/dashboard/students/{id} [students]
GET وPOST /api/dashboard/enrolments القائمة؛ POST {studentId, courseId} (للمشرفين)
DELETE /api/dashboard/enrolments/{id} للمشرفين؛ التسجيل المدفوع يُسترد بدل حذفه
GET /api/dashboard/reviews (status وrating) [reviews]
PATCH وDELETE /api/dashboard/reviews/{id} {status?, featured?, reply?}؛ والتمييز والحذف للمشرفين
GET وPOST /api/dashboard/posts [blog]
GET وPATCH وDELETE /api/dashboard/posts/{id}
GET وPOST /api/dashboard/categories GET لأي حساب؛ والتغيير [categories]
PATCH وDELETE /api/dashboard/categories/{id}
GET وPOST /api/dashboard/instructors [instructors]
PATCH وDELETE /api/dashboard/instructors/{id}
GET /api/dashboard/orders (status وmethod وq) [orders]
GET وPATCH /api/dashboard/orders/{id} PATCH {status: PAID|CANCELLED|REFUNDED} وفق مسار الطلب
GET وPOST /api/dashboard/coupons [coupons]
PATCH وDELETE /api/dashboard/coupons/{id}
GET وPOST /api/dashboard/admins الحسابات [admins]
PATCH وDELETE /api/dashboard/admins/{id} يبقى مشرف فعّال واحد على الأقل
GET وPUT /api/dashboard/roles {INSTRUCTOR: [...]} [roles]
GET وPATCH /api/dashboard/settings [settings]
POST /api/dashboard/uploads multipart file: صورة JPEG أو PNG أو WebP أو AVIF أو GIF حتى 5 ميغابايت ← {url}
POST /api/dashboard/ai/describe {courseId, notes?} ← نصوص مقترحة [ai]
POST /api/dashboard/ai/quiz {lessonId, count} ← أسئلة مقترحة [ai]
POST /api/dashboard/ai/ask {messages: [{role, content}]} ← {answer} [ai]

مسار الطلب

PENDING ← PAID (بتأكيد «ثواني» للبطاقات، أو بالمشرف للتحويلات) أو CANCELLED/FAILED. وPAID ← REFUNDED (تُحذف تسجيلات الطلب). أما الطلبات المجانية فتُنشأ PAID.

اختبار الـ API

يشغّل python scripts/e2e_api.py المسارات الرئيسية على خادم يعمل بقاعدة بيانات تجريبية جديدة: الكتالوج والتصفية، والتسجيل، والتسجيل المجاني، والوصول إلى الدروس، والتقدّم، وتصحيح الاختبارات وحدود المحاولات، والشهادات والتحقق، والشراء بالكوبونات، وتأكيد التحويل والاسترداد، وصلاحيات المدرّبين، وأخطاء التحقق، والتعديل الجزئي بـ PATCH.