ארבע קריאות, לפי הסדר: יצירת תלמיד, רישום שלו לקבוצת לימוד, סימונו כנוכח במפגש, והפקת חשבונית עבור הרישום. כל מזהה שמופיע בתשובה מזין את הקריאה הבאה — העתיקו אותם תוך כדי, או קראו את המזהים מכל תשובה במקום לקבע את מחזיקי המקום שכאן.

> **לפני שמתחילים**
>
> תצטרכו `branchId` ו-`groupId` שכבר קיימים בדייר שלכם (`GET /api/v1/branches`, `GET /api/v1/groups`) ומפתח API עם `students.write`, `enrollments.write`, `attendance.mark` ו-`invoices.write`. ראו [אימות](https://docs.institflow.com/he/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` קובעים כמה התלמיד הזה מחויב עבור הקבוצה הזו (מדרגת תשלום יכולה לחשב זאת עבורכם; ראו [Billing](https://docs.institflow.com/he/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` עם רשומה אחת לכל תלמיד ברשימת הקבוצה. שליחה חוזרת של נוכחות אותו מפגש בהמשך מעדכנת אותה במקום — היא אידמפוטנטית מעצם התכנון, לא רק בזכות הכותרת `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();
```

זו הלולאה המרכזית. מכאן: [הירשמו ל-webhook](https://docs.institflow.com/he/webhooks) כדי שהמערכת שלכם תשמע על `invoice.issued`/`payment.recorded` בלי לתשאל, או עיינו ברפרנס המלא של [Billing](https://docs.institflow.com/he/reference/billing) לתשלומים, דוחות חשבון ומדרגות תשלום.