---
title: "نظرة عامة"
url: https://docs.growamal.com/ar/
language: ar
---

# توثيق مطوّري أمل

**أمل** هو نظام القرار لمحو الأمية العربية، الموجَّه للمعلمين في العالم العربي. يوثّق هذا الموقع
واجهته البرمجية (API): واجهة REST + JSON، موصوفة بالكامل عبر مواصفة **OpenAPI 3.1**.

يوثّق هذا الموقع طبقتين. **طبقة التزويد** (المصادقة، والبنية المستأجِرة للمؤسسات والمدارس والصفوف،
وإدارة المستخدمين) مشروحة في [البدء السريع](https://docs.growamal.com/ar/getting-started/) و[الأدلة](https://docs.growamal.com/ar/guides/provision-users/).
أما **محرّك الاستجابة للتدخّل القائم على القياس** (حلقة التشخيص، وقرارات حالة المهارة، وملفات الطلاب،
وحزم التدخّل، ومراقبة التقدّم، والتقارير) فقد أُطلق الآن ويُوثَّق في
[كيف تعمل المرحلة الأولى](https://docs.growamal.com/ar/how-it-works/) وأدلة كل نظام فرعي.

جديد على المنصّة؟ اقرأ **[كيف تعمل المرحلة الأولى ← حلقة الاستجابة للتدخل](https://docs.growamal.com/ar/how-it-works/)** للقصّة
الكاملة من طرف إلى طرف قبل التعمّق في أي نظام فرعي بمفرده.

## الرابط الأساسي والإصدار

تُقدَّم الواجهة تحت المسار `/api`. المواصفة الحالية هي `version: 1.0.0-phase0`. الموجة الأولى موقع
توثيق واحد غير مُصدَّر؛ والمسار `/v1/…` محجوز لإصدار مستقبلي مُصدَّر من الواجهة.

في كامل هذا التوثيق يُكتب الرابط الأساسي بصيغة `http://localhost:8787` (المنفذ الافتراضي 8787؛
قابل للضبط عبر متغير البيئة `PORT`)، استبدله بعنوان خادمك `apps/server`. يعمل خادم التطوير الخاص
بـ Next.js على المنفذ 3000 -- لا تخلط بين الاثنين.

## كيف تُجمَّع الواجهة

تُجمَّع العمليات حسب الوسم؛ ويعرضها [مرجع الواجهة البرمجية](https://docs.growamal.com/ar/api-reference/) بهذا الشكل. وسوم
التزويد:

- **`auth`**: التسجيل، تسجيل الدخول، التجديد، `me`، تسجيل الخروج، إعادة تعيين كلمة المرور، رمز
  الطالب السريع. انظر [المصادقة](https://docs.growamal.com/ar/authentication/).
- **`tenancy`**: المؤسسات، المدارس، الصفوف، التجميع المؤسسي. انظر [المفاهيم الأساسية](https://docs.growamal.com/ar/core-concepts/).
- **`users`**: التزويد، ملفات الأدوار، القوائم، المدراء، المنسقون، روابط أولياء الأمور.
  انظر [إنشاء المستخدمين](https://docs.growamal.com/ar/guides/provision-users/).
- **`system`**: فحص الجاهزية.

أما وسوم محرّك الاستجابة للتدخّل والوسوم الداعمة (`diagnostic-session` و`practice` و`engine`
و`sub-skills` و`sse` و`profile` و`bundle` و`cluster` و`workflow` و`monitoring` و`orf` و`cbm`
و`standards` و`delivery` و`reporting` و`parent-pdf` و`warmup` و`language-safety` و`qa` و`logging`
و`gamification` و`leaderboard` و`notifications` و`lms` و`session-catalog` و`sync` و`fidelity`
و`rti` و`data-room` و`decision-packet` و`audit` و`blob` و`paper-results` و`onboarding`
و`student-flow` و`parent-portal` وغيرها) فجميعها مُعروضة في
[مرجع الواجهة البرمجية](https://docs.growamal.com/ar/api-reference/). ابدأ بـ [كيف تعمل المرحلة الأولى](https://docs.growamal.com/ar/how-it-works/)
لترى كيف تترابط.

## المصادقة بجملة واحدة

كل طلب بعد تسجيل الدخول يحمل رمز **Bearer JWT**: `Authorization: Bearer <accessToken>`. انظر
[المصادقة](https://docs.growamal.com/ar/authentication/) للنموذج الكامل.

## الاصطلاحات

- **الأجسام والاستجابات بصيغة JSON.**
- **كل خطأ** يستخدم مغلَّفًا واحدًا: `{ code, message, details?, retryAfter? }`. انظر [الأخطاء](https://docs.growamal.com/ar/errors/).
- **نوعان من المعرّفات، بحسب التصميم.** موارد البنية المستأجِرة (المؤسسة، المدرسة، الصف) تستخدم
  معرّفات **cuid** نصّية تطابق `^c[a-z0-9]{24}$`. أما المستخدمون وملفات الأدوار فيستخدمون معرّفات
  **عددية صحيحة**. لا تفترض نوعًا واحدًا في كامل الواجهة: معرّف الصف نصّ cuid، ومعرّف المستخدم عدد صحيح.

## من أين تبدأ

جديد هنا؟ انتقل مباشرةً إلى **[البدء السريع](https://docs.growamal.com/ar/getting-started/)**، يمشي بك من تزويد المسؤول الأول
حتى أول طلب مُصادَق عليه، بأمثلة جاهزة للنسخ تعمل مع خادم قيد التشغيل.