API map LMS

Зачем нужно

Документ описывает публичную карту API LMS: какие endpoints нужны, кто ими пользуется и какие permissions применяются. Подробные DTO описаны в api-contracts.md.

Общие правила API

• Базовый префикс: /api/v2/lms.
• Все write-команды принимают Idempotency-Key.
• Все списки поддерживают pagination.
• Все ответы с приватными учебными данными фильтруются по identity context.
• Teacher-facing endpoints принимают выбранный organizationId из actor context и валидируют его через identity membership.
• Ошибки возвращаются в едином формате ApiError.
• Внешние webhook endpoints отделяются от пользовательского API.

Course catalog inside LMS

Endpoint	Метод	Permission	Назначение
/courses	GET	lms.courses.read	список LMS-курсов, доступных actor
/courses	POST	lms.courses.manage	создать course
/courses/{courseId}	GET	lms.courses.read	карточка course
/courses/{courseId}	PATCH	lms.courses.manage	изменить metadata course
/courses/{courseId}/archive	POST	lms.courses.archive	архивировать course
/courses/{courseId}/versions	GET	lms.courses.read	версии course
/courses/{courseId}/versions	POST	lms.courses.manage	создать draft version

Course versions and content tree

Endpoint	Метод	Permission	Назначение
/course-versions/{versionId}	GET	lms.courses.read	metadata версии
/course-versions/{versionId}/submit-review	POST	lms.courses.manage	отправить draft на review
/course-versions/{versionId}/publish	POST	lms.courses.publish	опубликовать version
/course-versions/{versionId}/retire	POST	lms.courses.publish	вывести version из новых enrollments
/course-versions/{versionId}/tree	GET	lms.content.read	дерево курса
/course-versions/{versionId}/nodes	POST	lms.content.manage	создать node
/nodes/{nodeId}	GET	lms.content.read	node с blocks
/nodes/{nodeId}	PATCH	lms.content.manage	изменить draft node
/nodes/{nodeId}/move	POST	lms.content.manage	переместить node
/nodes/{nodeId}/content-blocks	POST	lms.content.manage	создать block
/content-blocks/{blockId}	PATCH	lms.content.manage	изменить block
/content-blocks/{blockId}	DELETE	lms.content.manage	удалить draft block

Write-операции над content запрещены для published version.

Enrollment and access

Endpoint	Метод	Permission	Назначение
/enrollments	GET	lms.enrollments.read	поиск enrollments
/enrollments	POST	lms.enrollments.manage	ручное зачисление
/enrollments/{enrollmentId}	GET	owner, family, teacher, lms.enrollments.read	карточка enrollment
/enrollments/{enrollmentId}/activate	POST	lms.enrollments.manage	активировать
/enrollments/{enrollmentId}/pause	POST	lms.enrollments.manage	поставить на паузу
/enrollments/{enrollmentId}/resume	POST	lms.enrollments.manage	возобновить
/enrollments/{enrollmentId}/revoke	POST	lms.enrollments.manage	отозвать доступ
/enrollments/{enrollmentId}/complete	POST	system, lms.enrollments.manage	завершить курс

Student API

Endpoint	Метод	Permission	Назначение
/me/enrollments	GET	authenticated	мои курсы
/me/enrollments/{enrollmentId}	GET	owner	мой enrollment
/me/enrollments/{enrollmentId}/tree	GET	owner	дерево курса с progress
/me/enrollments/{enrollmentId}/lessons/{nodeId}	GET	owner + active enrollment	урок
/me/enrollments/{enrollmentId}/lessons/{nodeId}/open	POST	owner + active enrollment	зафиксировать открытие
/me/enrollments/{enrollmentId}/progress	GET	owner	progress курса
/me/enrollments/{enrollmentId}/timeline	GET	owner	история учебных событий

Parent API

Endpoint	Метод	Permission	Назначение
/family/student-profiles/{studentProfileId}/enrollments	GET	family context	курсы ребёнка
/family/student-profiles/{studentProfileId}/enrollments/{enrollmentId}/progress	GET	family context	progress ребёнка
/family/student-profiles/{studentProfileId}/workbooks/{workbookId}	GET	family context	просмотр тетради
/family/student-profiles/{studentProfileId}/chats/{threadId}	GET	family context	просмотр учебного чата, если разрешено

Attempts, submissions and feedback

Endpoint	Метод	Permission	Назначение
/attempts	POST	owner + active enrollment	начать попытку
/attempts/{attemptId}	GET	owner, family, teacher	попытка
/attempts/{attemptId}/submit	POST	owner	отправить ответ
/attempts/{attemptId}/cancel	POST	owner, lms.attempts.manage	отменить started attempt
/submissions	POST	owner	создать submission
/submissions/{submissionId}	GET	owner, family, assigned teacher	работа
/submissions/{submissionId}/submit	POST	owner	отправить работу
/submissions/{submissionId}/reopen	POST	assigned teacher, lms.feedback.write	открыть доработку
/submissions/{submissionId}/feedback	POST	assigned teacher, lms.feedback.write	добавить feedback
/feedback/{feedbackId}	PATCH	author, lms.feedback.manage	исправить feedback

Teacher API

Endpoint	Метод	Permission	Назначение
/teacher/assignments	GET	lms.teacher.read	назначенные области
/teacher/students	GET	lms.teacher.read	ученики в области преподавателя
/teacher/review-queue	GET	lms.feedback.write	работы на проверку
/teacher/enrollments/{enrollmentId}/progress	GET	assigned teacher	progress ученика
/teacher/submissions/{submissionId}/feedback	POST	assigned teacher	проверка работы
/teacher/notes	POST	assigned teacher	внутренняя заметка, если включено

Learning Workspace

Endpoint	Метод	Permission	Назначение
/learning-workspace/groups	GET	lms.learning-groups.read	список “мои группы” в выбранной организации
/learning-workspace/groups	POST	lms.learning-groups.manage	создать Learning Group
/learning-workspace/groups/{groupId}	GET	workspace scope	карточка Learning Group
/learning-workspace/groups/{groupId}	PATCH	lms.learning-groups.manage	изменить название/описание
/learning-workspace/groups/{groupId}/archive	POST	lms.learning-groups.manage	архивировать группу
/learning-workspace/groups/{groupId}/participants	GET	workspace scope	участники группы
/learning-workspace/groups/{groupId}/participants	POST	lms.learning-group-participants.manage	добавить ученика по studentProfileId
/learning-workspace/groups/{groupId}/participants/{participantId}	PATCH	lms.learning-group-participants.manage	pause/remove participant
/learning-workspace/groups/{groupId}/invites	POST	lms.learning-group-invites.manage	отправить invite ученику/родителю через identity
/learning-workspace/invites/{inviteId}/cancel	POST	lms.learning-group-invites.manage	отменить invite
/learning-workspace/groups/{groupId}/assignments	GET	workspace scope	назначения группы
/learning-workspace/groups/{groupId}/assignments	POST	lms.learning-group-assignments.assign	назначить курс, урок, тренажёр, разбор или task-bank set
/learning-workspace/assignments/{assignmentId}/cancel	POST	lms.learning-group-assignments.assign	отменить назначение
/learning-workspace/groups/{groupId}/progress	GET	lms.progress.read + assigned teacher	progress участников по разрешённым enrollments

Learning Workspace endpoints не используют root /groups, чтобы не смешивать рабочие группы преподавателя с live delivery groups.

Workbooks

Endpoint	Метод	Permission	Назначение
/workbooks	GET	owner, family, assigned teacher	список тетрадей
/workbooks/{workbookId}	GET	owner, family, assigned teacher	тетрадь
/workbooks/{workbookId}/revisions	GET	owner, family, assigned teacher	история версий тетради
/workbooks/{workbookId}/revisions	POST	owner	сохранить revision
/workbooks/{workbookId}/submit	POST	owner	отправить тетрадь
/workbooks/{workbookId}/comments	POST	assigned teacher	комментарий
/workbooks/{workbookId}/attachments	POST	owner, assigned teacher	вложение

Projects

Endpoint	Метод	Permission	Назначение
/projects	GET	owner, family, assigned teacher	список проектов
/projects/{projectId}	GET	owner, family, assigned teacher	проект
/projects/{projectId}/milestones/{milestoneId}/submit	POST	owner	сдать milestone
/projects/{projectId}/milestones/{milestoneId}/feedback	POST	assigned teacher	feedback по milestone
/projects/{projectId}/artifacts	POST	owner	приложить artifact

Booking and calendar

Endpoint	Метод	Permission	Назначение
/roadmap/programs	GET/POST	lms.roadmap.read/manage	roadmap programs
/roadmap/programs/{programId}	GET/PATCH	lms.roadmap.read/manage	карточка roadmap program и draft metadata
/roadmap/programs/{programId}/projection	GET	lms.roadmap.projection.read	projection roadmap с фильтрами audience, layer, format, track, availability, scheduledState, sort
/roadmap/topics	GET/POST	lms.roadmap.read/manage	roadmap topics
/me/roadmap/{programId}	GET	owner	student projection roadmap с progress, gaps и next step
/family/student-profiles/{studentProfileId}/roadmap/{programId}	GET	family context	roadmap ребёнка
/teacher/students/{studentProfileId}/roadmap/{programId}	GET	assigned teacher	roadmap ученика в teacher scope
/roadmap/topics/{topicId}/completion	POST	lms.roadmap.completion.manage	создать completion по rule или manual override
/roadmap/topics/{topicId}/completion/recalculate	POST	lms.roadmap.completion.recalculate	пересчитать completion по evidence
/roadmap/programs/{programId}/publish	POST	lms.roadmap.publish	опубликовать roadmap
/groups	GET/POST	lms.sessions.read/manage	live delivery groups для расписания, не Learning Groups
/sessions	GET/POST	lms.sessions.read/manage	live sessions
/sessions/{sessionId}/attendance	GET/POST	lms.attendance.write	attendance
/sessions/{sessionId}/topics	POST	lms.sessions.manage	связать session с roadmap topic
/booking/slots	GET	authenticated	доступные слоты
/booking/slots	POST	lms.booking.manage	создать учебный слот
/booking/slots/{slotId}/hold	POST	owner, family	временно удержать место
/booking/slots/{slotId}/book	POST	owner, family	записаться
/bookings/{bookingId}/cancel	POST	owner, family, lms.booking.manage	отменить запись
/bookings/{bookingId}/move	POST	owner, family, lms.booking.manage	перенести запись

Chat

Endpoint	Метод	Permission	Назначение
/chats	GET	participant, family, assigned teacher	список учебных чатов
/chats	POST	lms.chat.manage	создать thread
/chats/{threadId}	GET	participant, family, assigned teacher	thread
/chats/{threadId}/messages	GET	participant	сообщения
/chats/{threadId}/messages	POST	participant + lms.chat.write	отправить сообщение
/chats/{threadId}/read	POST	participant	отметить прочтение
/chats/{threadId}/close	POST	assigned teacher, lms.chat.moderate	закрыть thread

Public storefront read

Endpoint	Метод	Permission	Назначение
/public/roadmap/{programRef}	GET	public	публичная проекция roadmap для SSR/cache storefront
/public/programs	GET	public	опубликованные публичные программы
/public/facts	GET	public	публичные учебные факты без PII

Admin and operations

Endpoint	Метод	Permission	Назначение
/admin/imports	POST	lms.admin	запустить импорт
/admin/imports/{importId}	GET	lms.admin	статус импорта
/admin/progress/recalculate	POST	lms.admin	пересчитать progress
/admin/audit	GET	lms.audit.read	audit events
/admin/external-sync-records	GET	lms.admin	sync records

Webhooks and service API

Endpoint	Метод	Caller	Назначение
/webhooks/crm/entitlements	POST	CRM	открыть, паузить или отозвать enrollment
/webhooks/crm/entitlement-consumption	POST	CRM	подтвердить или отклонить consumption
/webhooks/task-bank/check-results	POST	task-bank	принять результат проверки
/webhooks/identity/family-changed	POST	identity	инвалидировать family access cache
/webhooks/external-lms/progress	POST	sync service	импортировать progress

Webhook endpoints должны проверять signature, timestamp, replay window и idempotency.

Стандартные ошибки

Code	HTTP	Когда
lms.access.denied	403	actor не имеет доступа к учебному объекту
lms.enrollment.inactive	403	enrollment не active
lms.state.invalid_transition	409	запрещённый переход
lms.version.immutable	409	попытка изменить published version
lms.revision.stale	409	optimistic lock conflict
lms.reference.broken	422	невалидная ссылка на task-bank или storage
lms.booking.capacity_exceeded	409	слот уже занят
lms.learning_group.not_scope	403	группа не входит в выбранный teacher/organization context
lms.learning_group.progress_denied	403	есть доступ к группе, но нет прав на progress