كل النقاط تحت /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.