أربعة استدعاءات، بالترتيب: إنشاء طالب، تسجيله في مجموعة تدريسية، تسجيل حضوره في حصّة، وإصدار فاتورة له. كل معرّف في الاستجابات أدناه يُغذّي الاستدعاء التالي — انسخه أثناء التقدّم، أو اقرأ المعرّفات من كل استجابة بدلًا من تثبيت هذه القيم كما هي.

> **قبل أن تبدأ**
>
> ستحتاج إلى `branchId` و`groupId` موجودَين مسبقًا في مستأجرك (`GET /api/v1/branches`، `GET /api/v1/groups`) ومفتاح API يملك صلاحيات `students.write` و`enrollments.write` و`attendance.mark` و`invoices.write`. انظر [المصادقة](https://docs.institflow.com/ar/guides/authentication#api-keys).

## 1. إنشاء طالب

`POST /api/v1/students` — الحقول `branchId` و`firstName` و`lastName` فقط مطلوبة؛ `studentNumber` يُخصَّص تلقائيًا إن حُذف.

```bash
curl -X POST "https://api.yourdomain.com/api/v1/students" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "branchId": "0190a1b2-0000-7000-8000-000000000001",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada.lovelace@example.com",
    "phone": "+15551234567"
  }'
```

```javascript
const res = await fetch('https://api.yourdomain.com/api/v1/students', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.INSTITFLOW_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    "branchId": "0190a1b2-0000-7000-8000-000000000001",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada.lovelace@example.com",
    "phone": "+15551234567"
  }),
});
const data = await res.json();
```

الاستجابة هي الطالب المُنشأ، بمعرّف `0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b` أدناه.

## 2. تسجيله في مجموعة

`POST /api/v1/enrollments` — `priceMinor`/`currency` يحدّدان ما يُحصَّل من هذا الطالب مقابل هذه المجموعة (يمكن لجدول رسوم أن يحسب هذا نيابة عنك؛ انظر [الفوترة](https://docs.institflow.com/ar/reference/billing)).

```bash
curl -X POST "https://api.yourdomain.com/api/v1/enrollments" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "studentId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "groupId": "0190a1b2-0000-7000-8000-000000000002",
    "priceMinor": 12000,
    "currency": "ILS"
  }'
```

```javascript
const res = await fetch('https://api.yourdomain.com/api/v1/enrollments', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.INSTITFLOW_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    "studentId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "groupId": "0190a1b2-0000-7000-8000-000000000002",
    "priceMinor": 12000,
    "currency": "ILS"
  }),
});
const data = await res.json();
```

## 3. تسجيل الحضور

الحضور لكل حصّة على حدة، ويُحدَّث بالجملة: `PUT /api/v1/sessions/:id/attendance` مع سجلّ واحد لكل طالب في القائمة. إعادة إرسال حضور نفس الحصّة لاحقًا يحدّثه في مكانه — العملية غير تراكمية (idempotent) بحكم تصميمها، لا بفضل ترويسة `Idempotency-Key` فقط.

```bash
curl -X PUT "https://api.yourdomain.com/api/v1/sessions/0190a1b2-0000-7000-8000-000000000003/attendance" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "entries": [
      {
        "studentId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
        "status": "present"
      }
    ]
  }'
```

```javascript
const res = await fetch('https://api.yourdomain.com/api/v1/sessions/0190a1b2-0000-7000-8000-000000000003/attendance', {
  method: 'PUT',
  headers: { 'Authorization': `Bearer ${process.env.INSTITFLOW_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    "entries": [
      {
        "studentId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
        "status": "present"
      }
    ]
  }),
});
const data = await res.json();
```

## 4. إصدار فاتورة

تُنشأ الفواتير كمسوّدات أوّلًا، ثم تُصدَر — الإصدار استدعاء منفصل لأن المسوّدة يمكن تعديلها (أو التخلّي عنها) بحرّية، بينما الفاتورة المُصدرة مستند مالي حقيقي ومرقّم. الإجمالي يُحسب دائمًا من جهة الخادم من `lines`؛ لا ترسل إجماليًا بنفسك أبدًا.

```bash
curl -X POST "https://api.yourdomain.com/api/v1/invoices" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "branchId": "0190a1b2-0000-7000-8000-000000000001",
    "studentId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "issueDate": "2026-03-02",
    "dueDate": "2026-03-16",
    "currency": "ILS",
    "lines": [
      {
        "description": "March tuition — Algebra I",
        "quantity": 1,
        "unitMinor": 12000,
        "enrollmentId": "0190a1b2-0000-7000-8000-000000000004"
      }
    ]
  }'
```

```javascript
const res = await fetch('https://api.yourdomain.com/api/v1/invoices', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.INSTITFLOW_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    "branchId": "0190a1b2-0000-7000-8000-000000000001",
    "studentId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "issueDate": "2026-03-02",
    "dueDate": "2026-03-16",
    "currency": "ILS",
    "lines": [
      {
        "description": "March tuition — Algebra I",
        "quantity": 1,
        "unitMinor": 12000,
        "enrollmentId": "0190a1b2-0000-7000-8000-000000000004"
      }
    ]
  }),
});
const data = await res.json();
```

ثم أصدرها (معرّف المسوّدة من الاستجابة السابقة):

```bash
curl -X POST "https://api.yourdomain.com/api/v1/invoices/0190a1b2-0000-7000-8000-000000000005/issue" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"
```

```javascript
const res = await fetch('https://api.yourdomain.com/api/v1/invoices/0190a1b2-0000-7000-8000-000000000005/issue', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.INSTITFLOW_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
});
const data = await res.json();
```

هذه هي الحلقة الأساسية. من هنا: [اشترك في ويب هوك](https://docs.institflow.com/ar/webhooks) ليسمع نظامك بأحداث `invoice.issued`/`payment.recorded` دون استطلاع دوري، أو تصفّح مرجع [الفوترة](https://docs.institflow.com/ar/reference/billing) الكامل للمدفوعات والكشوف وجداول الرسوم.