البدء السريع

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

قبل أن تبدأ

ستحتاج إلى 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 يحدّدان ما يُحصَّل من هذا الطالب مقابل هذه المجموعة (يمكن لجدول رسوم أن يحسب هذا نيابة عنك؛ انظر الفوترة).

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 مع سجلّ واحد لكل طالب في القائمة. إعادة إرسال حضور نفس الحصّة لاحقًا يحدّثه في مكانه — العملية غير تراكمية (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"
      }
    ]
  }'

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"

هذه هي الحلقة الأساسية. من هنا: اشترك في ويب هوك ليسمع نظامك بأحداث invoice.issued/payment.recorded دون استطلاع دوري، أو تصفّح مرجع الفوترة الكامل للمدفوعات والكشوف وجداول الرسوم.