tours

Guided Tours

The caller's own progress through the in-app guided tours (started, finished, dismissed).

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

GET `/api/v1/me/tours`

Every guided tour the caller has started, finished or dismissed.

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

مثال بأمر curl

curl

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

الاستجابات

200

الاسم	النوع	القيود
toursمطلوب	array<object>	—

json

{
  "tours": [
    {
      "tourId": "first-login.owner",
      "status": "started",
      "lastStep": 0,
      "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? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

PUT `/api/v1/me/tours/{tourId}`

Saves the caller's own progress in one tour (also used to restart a finished or dismissed one).

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

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

الاسم	الموضع	النوع	القيود
tourIdمطلوب	path	string	—

محتوى الطلب

الاسم	النوع	القيود
statusمطلوب	enum: "started" \| "completed" \| "dismissed"	—
lastStepمطلوب	integer	0–49

مثال

json

{
  "status": "started",
  "lastStep": 0
}

مثال بأمر curl

curl

curl -X PUT "https://your-institute.example/api/v1/me/tours/1de6160e-1de6-7de6-8e61-1de6160e1de6" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "status": "started",
    "lastStep": 0
  }'

الاستجابات

200

الاسم	النوع	القيود
tourIdمطلوب	enum: "first-login.owner" \| "first-login.teacher" \| "first-login.student" \| "first-login.guardian" \| "task.add-student" \| "task.add-student-to-course" \| "task.invite-student" \| "task.course-video-quiz" \| "task.lesson-files" \| "task.take-attendance" \| "task.issue-invoice" \| "task.message-parents"	—
statusمطلوب	enum: "started" \| "completed" \| "dismissed"	—
lastStepمطلوب	integer	0–9007199254740991
updatedAtمطلوب	string (date-time)	—

json

{
  "tourId": "first-login.owner",
  "status": "started",
  "lastStep": 0,
  "updatedAt": "2026-03-02T09:00:00.000Z"
}