billing

Billing

Fee schedules, invoices, invoice lines, payments, and statements.

27 نقاط النهاية

GET /api/v1/billing/summary

Billing dashboard summary: outstanding, collected this month, overdue, by status.

يتطلّب المصادقةالصلاحيةinvoices.read

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/billing/summary" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
currencyمطلوب
string3–3 chars
outstandingمطلوب
Money—
collectedThisMonthمطلوب
Money—
overdueCountمطلوب
integer0–9007199254740991
overdueTotalمطلوب
Money—
byStatusمطلوب
object—
json
{
  "currency": "USD",
  "outstanding": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "collectedThisMonth": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "overdueCount": 0,
  "overdueTotal": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "byStatus": {
    "draft": 0,
    "issued": 0,
    "partially_paid": 0,
    "paid": 0,
    "overdue": 0,
    "void": 0
  }
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/fee-schedules

List fee schedules (cursor-paginated).

يتطلّب المصادقةالصلاحيةinvoices.read

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
cursor
querystring—
limit
queryinteger1–100 · default: 25
kind
queryenum: "per_group" | "per_course" | "one_off" | "registration"—
isActive
queryboolean—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/fee-schedules" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
dataمطلوب
array<object>—
nextCursorمطلوب
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "name": "Algebra I",
      "kind": "per_group",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "recurrence": "once",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
      "dueDay": 1,
      "isActive": true,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/fee-schedules

Create a fee schedule.

يتطلّب المصادقةالصلاحيةinvoices.write

محتوى الطلب

الاسمالنوعالقيود
nameمطلوب
string1–150 chars
kindمطلوب
enum: "per_group" | "per_course" | "one_off" | "registration"—
amountMinorمطلوب
integer0–9007199254740991
currencyمطلوب
enum: "ILS" | "USD" | "EUR"—
recurrenceمطلوب
enum: "once" | "monthly" | "per_term"—
courseId
string (uuid)—
groupId
string (uuid)—
dueDay
integer1–31
isActive
booleandefault: true

مثال

json
{
  "name": "Algebra I",
  "kind": "per_group",
  "amountMinor": 12000,
  "currency": "ILS",
  "recurrence": "once",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "dueDay": 1,
  "isActive": true
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/fee-schedules" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Algebra I",
    "kind": "per_group",
    "amountMinor": 12000,
    "currency": "ILS",
    "recurrence": "once",
    "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
    "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
    "dueDay": 1,
    "isActive": true
  }'

الاستجابات

201
الاسمالنوعالقيود
idمطلوب
string (uuid)—
nameمطلوب
string—
kindمطلوب
enum: "per_group" | "per_course" | "one_off" | "registration"—
amountمطلوب
Money—
recurrenceمطلوب
enum: "once" | "monthly" | "per_term"—
courseIdمطلوب
string (uuid) | null—
groupIdمطلوب
string (uuid) | null—
dueDayمطلوب
integer | null1–31
isActiveمطلوب
boolean—
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "name": "Algebra I",
  "kind": "per_group",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "recurrence": "once",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "dueDay": 1,
  "isActive": true,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

DELETE /api/v1/fee-schedules/{id}

Delete a fee schedule. Refused (409) if any invoice line still references it.

يتطلّب المصادقةالصلاحيةinvoices.write

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X DELETE "https://your-institute.example/api/v1/fee-schedules/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200The fee schedule was deleted.
الاسمالنوعالقيود
okمطلوب
enum: true—
json
{
  "ok": true
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/fee-schedules/{id}

Get a fee schedule by id.

يتطلّب المصادقةالصلاحيةinvoices.read

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/fee-schedules/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
nameمطلوب
string—
kindمطلوب
enum: "per_group" | "per_course" | "one_off" | "registration"—
amountمطلوب
Money—
recurrenceمطلوب
enum: "once" | "monthly" | "per_term"—
courseIdمطلوب
string (uuid) | null—
groupIdمطلوب
string (uuid) | null—
dueDayمطلوب
integer | null1–31
isActiveمطلوب
boolean—
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "name": "Algebra I",
  "kind": "per_group",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "recurrence": "once",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "dueDay": 1,
  "isActive": true,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

PATCH /api/v1/fee-schedules/{id}

Update a fee schedule.

يتطلّب المصادقةالصلاحيةinvoices.write

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
name
string1–150 chars
kind
enum: "per_group" | "per_course" | "one_off" | "registration"—
amountMinor
integer0–9007199254740991
currency
enum: "ILS" | "USD" | "EUR"—
recurrence
enum: "once" | "monthly" | "per_term"—
courseId
string (uuid)—
groupId
string (uuid)—
dueDay
integer1–31
isActive
booleandefault: true

مثال

json
{
  "name": "Algebra I",
  "kind": "per_group",
  "amountMinor": 12000,
  "currency": "ILS",
  "recurrence": "once",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "dueDay": 1,
  "isActive": true
}

مثال بأمر curl

curl
curl -X PATCH "https://your-institute.example/api/v1/fee-schedules/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Algebra I",
    "kind": "per_group",
    "amountMinor": 12000,
    "currency": "ILS",
    "recurrence": "once",
    "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
    "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
    "dueDay": 1,
    "isActive": true
  }'

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
nameمطلوب
string—
kindمطلوب
enum: "per_group" | "per_course" | "one_off" | "registration"—
amountمطلوب
Money—
recurrenceمطلوب
enum: "once" | "monthly" | "per_term"—
courseIdمطلوب
string (uuid) | null—
groupIdمطلوب
string (uuid) | null—
dueDayمطلوب
integer | null1–31
isActiveمطلوب
boolean—
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "name": "Algebra I",
  "kind": "per_group",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "recurrence": "once",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "dueDay": 1,
  "isActive": true,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/fee-schedules/{id}/generate

Batch-generate this period's invoices for a "monthly" fee schedule — one per actively-enrolled student, skipping anyone already invoiced for the period. `dryRun: true` previews counts only.

يتطلّب المصادقةالصلاحيةinvoices.write

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
periodمطلوب
string—
dryRunمطلوب
boolean—

مثال

json
{
  "period": "string",
  "dryRun": true
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/fee-schedules/37386ae0-3738-7738-8386-37386ae03738/generate" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "period": "string",
    "dryRun": true
  }'

الاستجابات

200
الاسمالنوعالقيود
periodمطلوب
string—
periodStartمطلوب
string (date)—
periodEndمطلوب
string (date)—
dueDateمطلوب
string (date)—
dryRunمطلوب
boolean—
eligibleStudentCountمطلوب
integer0–9007199254740991
alreadyInvoicedCountمطلوب
integer0–9007199254740991
createdInvoiceIdsمطلوب
array<string (uuid)>—
json
{
  "period": "string",
  "periodStart": "2026-03-02",
  "periodEnd": "2026-03-02",
  "dueDate": "2026-03-02",
  "dryRun": true,
  "eligibleStudentCount": 0,
  "alreadyInvoicedCount": 0,
  "createdInvoiceIds": [
    "9bebdb24-9beb-7beb-8ebd-9bebdb249beb"
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/invoices

List invoices (filters: status, studentId, guardianId, overdue, due date range; cursor-paginated).

يتطلّب المصادقةالصلاحيةinvoices.read

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
cursor
querystring—
limit
queryinteger1–100 · default: 25
status
queryenum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—
studentId
querystring (uuid)—
guardianId
querystring (uuid)—
overdue
queryboolean—
dueDateFrom
querystring (date)—
dueDateTo
querystring (date)—
sortBy
queryenum: "dueDate" | "total"default: "dueDate"
sortDir
queryenum: "asc" | "desc"default: "asc"

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/invoices" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
dataمطلوب
array<object>—
nextCursorمطلوب
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "branchId": "390b8975-390b-790b-80b8-390b8975390b",
      "number": "string",
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
      "status": "draft",
      "issueDate": "2026-03-02",
      "dueDate": "2026-03-02",
      "subtotal": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "discount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "tax": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paid": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "currency": "USD",
      "notes": "Prefers afternoon sessions.",
      "version": -9007199254740991,
      "voidedAt": "2026-03-02T09:00:00.000Z",
      "voidReason": "string",
      "pendingPaymentProofCount": 0,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices

Create a draft invoice. Totals are always recomputed server-side from `lines`.

يتطلّب المصادقةالصلاحيةinvoices.write

محتوى الطلب

الاسمالنوعالقيود
branchIdمطلوب
string (uuid)—
studentIdمطلوب
string (uuid)—
payerGuardianId
string (uuid)—
issueDateمطلوب
string (date)—
dueDateمطلوب
string (date)—
currencyمطلوب
enum: "ILS" | "USD" | "EUR"—
discountMinor
integer0–9007199254740991 · default: 0
taxMinor
integer0–9007199254740991 · default: 0
notes
string | string—
linesمطلوب
array<object>—

مثال

json
{
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "currency": "ILS",
  "discountMinor": 0,
  "taxMinor": 0,
  "notes": "Prefers afternoon sessions.",
  "lines": [
    {
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unitMinor": 0,
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "string",
      "periodEnd": "string"
    }
  ]
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "branchId": "390b8975-390b-790b-80b8-390b8975390b",
    "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
    "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
    "issueDate": "2026-03-02",
    "dueDate": "2026-03-02",
    "currency": "ILS",
    "discountMinor": 0,
    "taxMinor": 0,
    "notes": "Prefers afternoon sessions.",
    "lines": [
      {
        "description": "A short, human-readable description.",
        "quantity": 1,
        "unitMinor": 0,
        "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
        "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
        "periodStart": "string",
        "periodEnd": "string"
      }
    ]
  }'

الاستجابات

201
الاسمالنوعالقيود
idمطلوب
string (uuid)—
branchIdمطلوب
string (uuid)—
numberمطلوب
string≥1 chars
studentIdمطلوب
string (uuid)—
payerGuardianIdمطلوب
string (uuid) | null—
statusمطلوب
enum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—
issueDateمطلوب
string (date)—
dueDateمطلوب
string (date)—
subtotalمطلوب
Money—
discountمطلوب
Money—
taxمطلوب
Money—
totalمطلوب
Money—
paidمطلوب
Money—
currencyمطلوب
string3–3 chars
notesمطلوب
string | null1–2000 chars
versionمطلوب
integer-9007199254740991–9007199254740991
voidedAtمطلوب
string (date-time) | null—
voidReasonمطلوب
string | null1–500 chars
pendingPaymentProofCountمطلوب
integer0–9007199254740991
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
linesمطلوب
array<object>—
paymentsمطلوب
array<object>—
paymentProofsمطلوب
array<object>—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "number": "string",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "status": "draft",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "subtotal": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "discount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "tax": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "total": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paid": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "currency": "USD",
  "notes": "Prefers afternoon sessions.",
  "version": -9007199254740991,
  "voidedAt": "2026-03-02T09:00:00.000Z",
  "voidReason": "string",
  "pendingPaymentProofCount": 0,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "lines": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "2026-03-02",
      "periodEnd": "2026-03-02"
    }
  ],
  "payments": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "method": "cash",
      "provider": "manual",
      "providerRef": "string",
      "receivedAt": "2026-03-02T09:00:00.000Z",
      "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
      "note": "string",
      "reversedAt": "2026-03-02T09:00:00.000Z",
      "reversalReason": "string",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "paymentProofs": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/invoices/{id}

Get an invoice, with its lines and payments.

يتطلّب المصادقةالصلاحيةinvoices.read

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
branchIdمطلوب
string (uuid)—
numberمطلوب
string≥1 chars
studentIdمطلوب
string (uuid)—
payerGuardianIdمطلوب
string (uuid) | null—
statusمطلوب
enum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—
issueDateمطلوب
string (date)—
dueDateمطلوب
string (date)—
subtotalمطلوب
Money—
discountمطلوب
Money—
taxمطلوب
Money—
totalمطلوب
Money—
paidمطلوب
Money—
currencyمطلوب
string3–3 chars
notesمطلوب
string | null1–2000 chars
versionمطلوب
integer-9007199254740991–9007199254740991
voidedAtمطلوب
string (date-time) | null—
voidReasonمطلوب
string | null1–500 chars
pendingPaymentProofCountمطلوب
integer0–9007199254740991
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
linesمطلوب
array<object>—
paymentsمطلوب
array<object>—
paymentProofsمطلوب
array<object>—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "number": "string",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "status": "draft",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "subtotal": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "discount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "tax": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "total": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paid": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "currency": "USD",
  "notes": "Prefers afternoon sessions.",
  "version": -9007199254740991,
  "voidedAt": "2026-03-02T09:00:00.000Z",
  "voidReason": "string",
  "pendingPaymentProofCount": 0,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "lines": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "2026-03-02",
      "periodEnd": "2026-03-02"
    }
  ],
  "payments": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "method": "cash",
      "provider": "manual",
      "providerRef": "string",
      "receivedAt": "2026-03-02T09:00:00.000Z",
      "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
      "note": "string",
      "reversedAt": "2026-03-02T09:00:00.000Z",
      "reversalReason": "string",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "paymentProofs": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

PATCH /api/v1/invoices/{id}

Update a draft invoice (draft only). Replaces `lines` entirely. Requires the current `version`.

يتطلّب المصادقةالصلاحيةinvoices.write

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
versionمطلوب
integer1–9007199254740991
branchId
string (uuid)—
payerGuardianId
string (uuid)—
issueDate
string (date)—
dueDate
string (date)—
currency
enum: "ILS" | "USD" | "EUR"—
discountMinor
integer0–9007199254740991
notes
enum: "" | string | null—
linesمطلوب
array<object>—

مثال

json
{
  "version": 1,
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "currency": "ILS",
  "discountMinor": 0,
  "notes": "",
  "lines": [
    {
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unitMinor": 0,
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "2026-03-02",
      "periodEnd": "2026-03-02"
    }
  ]
}

مثال بأمر curl

curl
curl -X PATCH "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "version": 1,
    "branchId": "390b8975-390b-790b-80b8-390b8975390b",
    "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
    "issueDate": "2026-03-02",
    "dueDate": "2026-03-02",
    "currency": "ILS",
    "discountMinor": 0,
    "notes": "",
    "lines": [
      {
        "description": "A short, human-readable description.",
        "quantity": 1,
        "unitMinor": 0,
        "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
        "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
        "periodStart": "2026-03-02",
        "periodEnd": "2026-03-02"
      }
    ]
  }'

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
branchIdمطلوب
string (uuid)—
numberمطلوب
string≥1 chars
studentIdمطلوب
string (uuid)—
payerGuardianIdمطلوب
string (uuid) | null—
statusمطلوب
enum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—
issueDateمطلوب
string (date)—
dueDateمطلوب
string (date)—
subtotalمطلوب
Money—
discountمطلوب
Money—
taxمطلوب
Money—
totalمطلوب
Money—
paidمطلوب
Money—
currencyمطلوب
string3–3 chars
notesمطلوب
string | null1–2000 chars
versionمطلوب
integer-9007199254740991–9007199254740991
voidedAtمطلوب
string (date-time) | null—
voidReasonمطلوب
string | null1–500 chars
pendingPaymentProofCountمطلوب
integer0–9007199254740991
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
linesمطلوب
array<object>—
paymentsمطلوب
array<object>—
paymentProofsمطلوب
array<object>—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "number": "string",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "status": "draft",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "subtotal": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "discount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "tax": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "total": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paid": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "currency": "USD",
  "notes": "Prefers afternoon sessions.",
  "version": -9007199254740991,
  "voidedAt": "2026-03-02T09:00:00.000Z",
  "voidReason": "string",
  "pendingPaymentProofCount": 0,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "lines": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "2026-03-02",
      "periodEnd": "2026-03-02"
    }
  ],
  "payments": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "method": "cash",
      "provider": "manual",
      "providerRef": "string",
      "receivedAt": "2026-03-02T09:00:00.000Z",
      "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
      "note": "string",
      "reversedAt": "2026-03-02T09:00:00.000Z",
      "reversalReason": "string",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "paymentProofs": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices/{id}/issue

Issue a draft invoice: allocates its number, sets issue/due dates, and emits `invoice.issued`.

يتطلّب المصادقةالصلاحيةinvoices.write

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/issue" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
branchIdمطلوب
string (uuid)—
numberمطلوب
string≥1 chars
studentIdمطلوب
string (uuid)—
payerGuardianIdمطلوب
string (uuid) | null—
statusمطلوب
enum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—
issueDateمطلوب
string (date)—
dueDateمطلوب
string (date)—
subtotalمطلوب
Money—
discountمطلوب
Money—
taxمطلوب
Money—
totalمطلوب
Money—
paidمطلوب
Money—
currencyمطلوب
string3–3 chars
notesمطلوب
string | null1–2000 chars
versionمطلوب
integer-9007199254740991–9007199254740991
voidedAtمطلوب
string (date-time) | null—
voidReasonمطلوب
string | null1–500 chars
pendingPaymentProofCountمطلوب
integer0–9007199254740991
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
linesمطلوب
array<object>—
paymentsمطلوب
array<object>—
paymentProofsمطلوب
array<object>—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "number": "string",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "status": "draft",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "subtotal": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "discount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "tax": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "total": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paid": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "currency": "USD",
  "notes": "Prefers afternoon sessions.",
  "version": -9007199254740991,
  "voidedAt": "2026-03-02T09:00:00.000Z",
  "voidReason": "string",
  "pendingPaymentProofCount": 0,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "lines": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "2026-03-02",
      "periodEnd": "2026-03-02"
    }
  ],
  "payments": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "method": "cash",
      "provider": "manual",
      "providerRef": "string",
      "receivedAt": "2026-03-02T09:00:00.000Z",
      "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
      "note": "string",
      "reversedAt": "2026-03-02T09:00:00.000Z",
      "reversalReason": "string",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "paymentProofs": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/invoices/{id}/payment-proofs

List every payment proof attached to an invoice, with its review status.

يتطلّب المصادقةالصلاحيةpayments.read

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/payment-proofs" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
dataمطلوب
array<object>—
nextCursorمطلوب
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices/{id}/payment-proofs/{proofId}/confirm

Confirm a payment proof: records the payment (proof's own amount/date) against the invoice and marks the proof confirmed. Emits `payment.recorded` and `billing.payment_proof.reviewed`.

يتطلّب المصادقةالصلاحيةpayments.record

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—
proofIdمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
method
enum: "cash" | "bank_transfer" | "card" | "other"default: "bank_transfer"
providerRef
string | string—

مثال

json
{
  "method": "bank_transfer",
  "providerRef": "string"
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/payment-proofs/1a6553ac-1a65-7a65-8655-1a6553ac1a65/confirm" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "method": "bank_transfer",
    "providerRef": "string"
  }'

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
invoiceIdمطلوب
string (uuid)—
fileIdمطلوب
string (uuid)—
submittedByUserIdمطلوب
string (uuid)—
submittedByNameمطلوب
string | null≥1 chars
amountمطلوب
Money—
paidOnمطلوب
string (date)—
noteمطلوب
string | null1–500 chars
statusمطلوب
enum: "submitted" | "confirmed" | "rejected"—
reviewedByUserIdمطلوب
string (uuid) | null—
reviewedByNameمطلوب
string | null≥1 chars
reviewedAtمطلوب
string (date-time) | null—
reviewNoteمطلوب
string | null1–500 chars
paymentIdمطلوب
string (uuid) | null—
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
  "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
  "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
  "submittedByName": "string",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paidOn": "2026-03-02",
  "note": "string",
  "status": "submitted",
  "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
  "reviewedByName": "string",
  "reviewedAt": "2026-03-02T09:00:00.000Z",
  "reviewNote": "string",
  "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices/{id}/payment-proofs/{proofId}/reject

Reject a payment proof with a review note. Emits `billing.payment_proof.reviewed`.

يتطلّب المصادقةالصلاحيةpayments.record

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—
proofIdمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
reviewNoteمطلوب
string1–500 chars

مثال

json
{
  "reviewNote": "string"
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/payment-proofs/1a6553ac-1a65-7a65-8655-1a6553ac1a65/reject" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "reviewNote": "string"
  }'

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
invoiceIdمطلوب
string (uuid)—
fileIdمطلوب
string (uuid)—
submittedByUserIdمطلوب
string (uuid)—
submittedByNameمطلوب
string | null≥1 chars
amountمطلوب
Money—
paidOnمطلوب
string (date)—
noteمطلوب
string | null1–500 chars
statusمطلوب
enum: "submitted" | "confirmed" | "rejected"—
reviewedByUserIdمطلوب
string (uuid) | null—
reviewedByNameمطلوب
string | null≥1 chars
reviewedAtمطلوب
string (date-time) | null—
reviewNoteمطلوب
string | null1–500 chars
paymentIdمطلوب
string (uuid) | null—
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
  "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
  "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
  "submittedByName": "string",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paidOn": "2026-03-02",
  "note": "string",
  "status": "submitted",
  "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
  "reviewedByName": "string",
  "reviewedAt": "2026-03-02T09:00:00.000Z",
  "reviewNote": "string",
  "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/invoices/{id}/payments

List every payment recorded against an invoice.

يتطلّب المصادقةالصلاحيةpayments.read

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/payments" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
dataمطلوب
array<object>—
nextCursorمطلوب
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "method": "cash",
      "provider": "manual",
      "providerRef": "string",
      "receivedAt": "2026-03-02T09:00:00.000Z",
      "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
      "note": "string",
      "reversedAt": "2026-03-02T09:00:00.000Z",
      "reversalReason": "string",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices/{id}/payments

Record a payment against an invoice. Emits `payment.recorded`.

يتطلّب المصادقةالصلاحيةpayments.record

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
amountMinorمطلوب
integer1–9007199254740991
currencyمطلوب
enum: "ILS" | "USD" | "EUR"—
methodمطلوب
enum: "cash" | "bank_transfer" | "card" | "other"—
provider
enum: "manual" | "stripe" | "tranzila" | "other"default: "manual"
providerRef
string | string—
receivedAt
string | string (date-time)—
note
string | string—

مثال

json
{
  "amountMinor": 12000,
  "currency": "ILS",
  "method": "cash",
  "provider": "manual",
  "providerRef": "string",
  "receivedAt": "string",
  "note": "string"
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/payments" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amountMinor": 12000,
    "currency": "ILS",
    "method": "cash",
    "provider": "manual",
    "providerRef": "string",
    "receivedAt": "string",
    "note": "string"
  }'

الاستجابات

201
الاسمالنوعالقيود
idمطلوب
string (uuid)—
invoiceIdمطلوب
string (uuid)—
amountمطلوب
Money—
methodمطلوب
enum: "cash" | "bank_transfer" | "card" | "other"—
providerمطلوب
enum: "manual" | "stripe" | "tranzila" | "other"—
providerRefمطلوب
string | null≥1 chars
receivedAtمطلوب
string (date-time)—
receivedByUserIdمطلوب
string (uuid)—
noteمطلوب
string | null1–1000 chars
reversedAtمطلوب
string (date-time) | null—
reversalReasonمطلوب
string | null1–500 chars
createdAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "method": "cash",
  "provider": "manual",
  "providerRef": "string",
  "receivedAt": "2026-03-02T09:00:00.000Z",
  "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
  "note": "string",
  "reversedAt": "2026-03-02T09:00:00.000Z",
  "reversalReason": "string",
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices/{id}/remind

Send a payment reminder (the `invoice.overdue` template) to the invoice's payer/guardians. Idempotent per invoice per UTC day — a second call the same day reports `alreadyRemindedToday` instead of re-sending.

يتطلّب المصادقةالصلاحيةinvoices.write

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/remind" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
invoiceIdمطلوب
string (uuid)—
alreadyRemindedTodayمطلوب
boolean—
sentAtمطلوب
string (date-time)—
json
{
  "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
  "alreadyRemindedToday": true,
  "sentAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices/{id}/void

Void an invoice. Refused (409) if it has any active (non-reversed) payments.

يتطلّب المصادقةالصلاحيةinvoices.write

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
reasonمطلوب
string1–500 chars

مثال

json
{
  "reason": "Requested by guardian."
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices/37386ae0-3738-7738-8386-37386ae03738/void" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "reason": "Requested by guardian."
  }'

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
branchIdمطلوب
string (uuid)—
numberمطلوب
string≥1 chars
studentIdمطلوب
string (uuid)—
payerGuardianIdمطلوب
string (uuid) | null—
statusمطلوب
enum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—
issueDateمطلوب
string (date)—
dueDateمطلوب
string (date)—
subtotalمطلوب
Money—
discountمطلوب
Money—
taxمطلوب
Money—
totalمطلوب
Money—
paidمطلوب
Money—
currencyمطلوب
string3–3 chars
notesمطلوب
string | null1–2000 chars
versionمطلوب
integer-9007199254740991–9007199254740991
voidedAtمطلوب
string (date-time) | null—
voidReasonمطلوب
string | null1–500 chars
pendingPaymentProofCountمطلوب
integer0–9007199254740991
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
linesمطلوب
array<object>—
paymentsمطلوب
array<object>—
paymentProofsمطلوب
array<object>—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "number": "string",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "status": "draft",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "subtotal": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "discount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "tax": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "total": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paid": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "currency": "USD",
  "notes": "Prefers afternoon sessions.",
  "version": -9007199254740991,
  "voidedAt": "2026-03-02T09:00:00.000Z",
  "voidReason": "string",
  "pendingPaymentProofCount": 0,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "lines": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "2026-03-02",
      "periodEnd": "2026-03-02"
    }
  ],
  "payments": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "method": "cash",
      "provider": "manual",
      "providerRef": "string",
      "receivedAt": "2026-03-02T09:00:00.000Z",
      "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
      "note": "string",
      "reversedAt": "2026-03-02T09:00:00.000Z",
      "reversalReason": "string",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "paymentProofs": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/invoices/remind-overdue

Bulk-send a payment reminder to every `overdue` invoice not already reminded today (idempotent per invoice per UTC day).

يتطلّب المصادقةالصلاحيةinvoices.write

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/invoices/remind-overdue" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
totalOverdueمطلوب
integer0–9007199254740991
remindedمطلوب
integer0–9007199254740991
alreadyRemindedTodayمطلوب
integer0–9007199254740991
json
{
  "totalOverdue": 0,
  "reminded": 0,
  "alreadyRemindedToday": 0
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/me/invoices

My own invoices (student: own; guardian: invoices they pay, or their children’s). Cursor-paginated; filterable by `studentId` and `status`.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
cursor
querystring—
limit
queryinteger1–100 · default: 25
studentId
querystring (uuid)—
status
queryenum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/me/invoices" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
dataمطلوب
array<object>—
nextCursorمطلوب
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "branchId": "390b8975-390b-790b-80b8-390b8975390b",
      "number": "string",
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
      "status": "draft",
      "issueDate": "2026-03-02",
      "dueDate": "2026-03-02",
      "subtotal": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "discount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "tax": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paid": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "currency": "USD",
      "notes": "Prefers afternoon sessions.",
      "version": -9007199254740991,
      "voidedAt": "2026-03-02T09:00:00.000Z",
      "voidReason": "string",
      "pendingPaymentProofCount": 0,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/me/invoices/{id}

One of my own invoices, with its lines, payments and payment proofs.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/me/invoices/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
branchIdمطلوب
string (uuid)—
numberمطلوب
string≥1 chars
studentIdمطلوب
string (uuid)—
payerGuardianIdمطلوب
string (uuid) | null—
statusمطلوب
enum: "draft" | "issued" | "partially_paid" | "paid" | "overdue" | "void"—
issueDateمطلوب
string (date)—
dueDateمطلوب
string (date)—
subtotalمطلوب
Money—
discountمطلوب
Money—
taxمطلوب
Money—
totalمطلوب
Money—
paidمطلوب
Money—
currencyمطلوب
string3–3 chars
notesمطلوب
string | null1–2000 chars
versionمطلوب
integer-9007199254740991–9007199254740991
voidedAtمطلوب
string (date-time) | null—
voidReasonمطلوب
string | null1–500 chars
pendingPaymentProofCountمطلوب
integer0–9007199254740991
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
linesمطلوب
array<object>—
paymentsمطلوب
array<object>—
paymentProofsمطلوب
array<object>—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "number": "string",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "payerGuardianId": "4e92fac4-4e92-7e92-892f-4e92fac44e92",
  "status": "draft",
  "issueDate": "2026-03-02",
  "dueDate": "2026-03-02",
  "subtotal": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "discount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "tax": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "total": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paid": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "currency": "USD",
  "notes": "Prefers afternoon sessions.",
  "version": -9007199254740991,
  "voidedAt": "2026-03-02T09:00:00.000Z",
  "voidReason": "string",
  "pendingPaymentProofCount": 0,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "lines": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "description": "A short, human-readable description.",
      "quantity": 1,
      "unit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "total": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "enrollmentId": "c8bc7863-c8bc-78bc-8bc7-c8bc7863c8bc",
      "feeScheduleId": "3cfbbfe7-3cfb-7cfb-8fbb-3cfbbfe73cfb",
      "periodStart": "2026-03-02",
      "periodEnd": "2026-03-02"
    }
  ],
  "payments": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "method": "cash",
      "provider": "manual",
      "providerRef": "string",
      "receivedAt": "2026-03-02T09:00:00.000Z",
      "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
      "note": "string",
      "reversedAt": "2026-03-02T09:00:00.000Z",
      "reversalReason": "string",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "paymentProofs": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/me/invoices/{id}/payment-proofs

My own payment proofs attached to one of my own invoices, with their review status.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/me/invoices/37386ae0-3738-7738-8386-37386ae03738/payment-proofs" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
dataمطلوب
array<object>—
nextCursorمطلوب
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
      "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
      "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
      "submittedByName": "string",
      "amount": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "paidOn": "2026-03-02",
      "note": "string",
      "status": "submitted",
      "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
      "reviewedByName": "string",
      "reviewedAt": "2026-03-02T09:00:00.000Z",
      "reviewNote": "string",
      "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/me/invoices/{id}/payment-proofs

Attach a payment proof (photo + amount + date + note) to one of my own invoices, for a secretary to confirm.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
fileIdمطلوب
string (uuid)—
amountMinorمطلوب
integer1–9007199254740991
currencyمطلوب
enum: "ILS" | "USD" | "EUR"—
paidOnمطلوب
string (date)—
note
string | string—

مثال

json
{
  "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
  "amountMinor": 12000,
  "currency": "ILS",
  "paidOn": "2026-03-02",
  "note": "string"
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/me/invoices/37386ae0-3738-7738-8386-37386ae03738/payment-proofs" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
    "amountMinor": 12000,
    "currency": "ILS",
    "paidOn": "2026-03-02",
    "note": "string"
  }'

الاستجابات

201
الاسمالنوعالقيود
idمطلوب
string (uuid)—
invoiceIdمطلوب
string (uuid)—
fileIdمطلوب
string (uuid)—
submittedByUserIdمطلوب
string (uuid)—
submittedByNameمطلوب
string | null≥1 chars
amountمطلوب
Money—
paidOnمطلوب
string (date)—
noteمطلوب
string | null1–500 chars
statusمطلوب
enum: "submitted" | "confirmed" | "rejected"—
reviewedByUserIdمطلوب
string (uuid) | null—
reviewedByNameمطلوب
string | null≥1 chars
reviewedAtمطلوب
string (date-time) | null—
reviewNoteمطلوب
string | null1–500 chars
paymentIdمطلوب
string (uuid) | null—
createdAtمطلوب
string (date-time)—
updatedAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
  "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
  "submittedByUserId": "0a0c2905-0a0c-7a0c-80c2-0a0c29050a0c",
  "submittedByName": "string",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "paidOn": "2026-03-02",
  "note": "string",
  "status": "submitted",
  "reviewedByUserId": "8cf14e2f-8cf1-7cf1-8f14-8cf14e2f8cf1",
  "reviewedByName": "string",
  "reviewedAt": "2026-03-02T09:00:00.000Z",
  "reviewNote": "string",
  "paymentId": "ed1da17f-ed1d-7d1d-81da-ed1da17fed1d",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/me/statement

My own (or one linked child’s) statement: invoices and payments, chronological, with a running balance.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
studentId
querystring (uuid)—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/me/statement" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
studentIdمطلوب
string (uuid)—
currencyمطلوب
string3–3 chars
entriesمطلوب
array<object>—
balanceمطلوب
Money—
json
{
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "currency": "USD",
  "entries": [
    {
      "type": "invoice",
      "date": "2026-03-02T09:00:00.000Z",
      "referenceId": "6b25c837-6b25-7b25-825c-6b25c8376b25",
      "description": "A short, human-readable description.",
      "invoiceNumber": "string",
      "paymentMethod": "cash",
      "debit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "credit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "balance": {
        "amountMinor": 12000,
        "currency": "ILS"
      }
    }
  ],
  "balance": {
    "amountMinor": 12000,
    "currency": "ILS"
  }
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST /api/v1/payments/{id}/reverse

Reverse a recorded payment, recomputing its invoice’s paid amount/status.

يتطلّب المصادقةالصلاحيةpayments.record

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

محتوى الطلب

الاسمالنوعالقيود
reasonمطلوب
string1–500 chars

مثال

json
{
  "reason": "Requested by guardian."
}

مثال بأمر curl

curl
curl -X POST "https://your-institute.example/api/v1/payments/37386ae0-3738-7738-8386-37386ae03738/reverse" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "reason": "Requested by guardian."
  }'

الاستجابات

200
الاسمالنوعالقيود
idمطلوب
string (uuid)—
invoiceIdمطلوب
string (uuid)—
amountمطلوب
Money—
methodمطلوب
enum: "cash" | "bank_transfer" | "card" | "other"—
providerمطلوب
enum: "manual" | "stripe" | "tranzila" | "other"—
providerRefمطلوب
string | null≥1 chars
receivedAtمطلوب
string (date-time)—
receivedByUserIdمطلوب
string (uuid)—
noteمطلوب
string | null1–1000 chars
reversedAtمطلوب
string (date-time) | null—
reversalReasonمطلوب
string | null1–500 chars
createdAtمطلوب
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "invoiceId": "f3093e02-f309-7309-8093-f3093e02f309",
  "amount": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "method": "cash",
  "provider": "manual",
  "providerRef": "string",
  "receivedAt": "2026-03-02T09:00:00.000Z",
  "receivedByUserId": "56d35175-56d3-76d3-8d35-56d3517556d3",
  "note": "string",
  "reversedAt": "2026-03-02T09:00:00.000Z",
  "reversalReason": "string",
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET /api/v1/students/{id}/statement

A student’s invoices + payments, chronological, with a running balance.

يتطلّب المصادقةالصلاحيةinvoices.read

معطيات المسار والاستعلام

الاسمالموضعالنوعالقيود
idمطلوب
pathstring—

مثال بأمر curl

curl
curl -X GET "https://your-institute.example/api/v1/students/37386ae0-3738-7738-8386-37386ae03738/statement" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200
الاسمالنوعالقيود
studentIdمطلوب
string (uuid)—
currencyمطلوب
string3–3 chars
entriesمطلوب
array<object>—
balanceمطلوب
Money—
json
{
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "currency": "USD",
  "entries": [
    {
      "type": "invoice",
      "date": "2026-03-02T09:00:00.000Z",
      "referenceId": "6b25c837-6b25-7b25-825c-6b25c8376b25",
      "description": "A short, human-readable description.",
      "invoiceNumber": "string",
      "paymentMethod": "cash",
      "debit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "credit": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "balance": {
        "amountMinor": 12000,
        "currency": "ILS"
      }
    }
  ],
  "balance": {
    "amountMinor": 12000,
    "currency": "ILS"
  }
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.