התחלה מהירה

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

לפני שמתחילים

תצטרכו branchId ו-groupId שכבר קיימים בדייר שלכם (GET /api/v1/branches, GET /api/v1/groups) ומפתח API עם students.write, enrollments.write, attendance.mark ו-invoices.write. ראו אימות.

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"
  }'

התשובה היא התלמיד שנוצר, עם המזהה 0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b שמופיע בהמשך.

2. רישום לקבוצה

POST /api/v1/enrollments — priceMinor/currency קובעים כמה התלמיד הזה מחויב עבור הקבוצה הזו (מדרגת תשלום יכולה לחשב זאת עבורכם; ראו 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"
  }'

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"
      }
    ]
  }'

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"
      }
    ]
  }'

ואז הנפיקו אותה (מזהה הטיוטה מגיע מהתשובה הקודמת):

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

זו הלולאה המרכזית. מכאן: הירשמו ל-webhook כדי שהמערכת שלכם תשמע על invoice.issued/payment.recorded בלי לתשאל, או עיינו ברפרנס המלא של Billing לתשלומים, דוחות חשבון ומדרגות תשלום.