Карта API

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

• Базовый префикс: /api/v2/competitions.
• Public endpoints возвращают только published/public данные.
• Write endpoints требуют authenticated actor или service scope.
• Submission, checking, publication и document endpoints принимают Idempotency-Key.
• Результаты и работы проверяют actor context: self, family, teacher, organization, venue, checker, admin.
• Teacher endpoints работают в преподавательском режиме и требуют выбранную организацию; organization/venue actions являются подслоями этого режима.
• Learning Workspace / Learning Group передаются как external refs; competitions не отдаёт API «мой canonical список учеников».
• Public storefront endpoints могут возвращать ссылки на LMS-разбор/тренажёр, но тренировочная попытка не создаёт competition submission.
• Participant launch endpoints открывают LMS activity runtime или temporary compatible adapter; raw answers не принимаются competitions API, если execution LMS-owned.
• Official data package для ГИР собирается через identity-owned protected attributes; competitions API возвращает readiness/status/ref, но не сырой СНИЛС, дату рождения ребёнка или родительские контакты.

Public

Endpoint	Метод	Permission	Назначение
/events	GET	public	опубликованные мероприятия
/events/{slug}	GET	public	мероприятие
/seasons/{seasonId}/venues	GET	public	опубликованные площадки списком
/seasons/{seasonId}/venues/map	GET	public	опубликованные площадки на карте
/seasons/{seasonId}/public-results	GET	public after publication	публичные результаты
/seasons/{seasonId}/training-links	GET	public/published	ссылки на LMS-разбор и тренажёр
/documents/verify/{code}	GET	public	проверка документа

Admin event/season/tour

Endpoint	Метод	Permission	Назначение
/admin/events	GET/POST	competitions.events.read/manage	мероприятия
/admin/events/{eventId}	GET/PATCH	competitions.events.read/manage	карточка
/admin/seasons	GET/POST	competitions.seasons.read/manage	сезоны
/admin/seasons/{seasonId}/status	PATCH	competitions.seasons.manage	статус сезона
/admin/tours	GET/POST	competitions.tours.read/manage	туры
/admin/tours/{tourId}/status	PATCH	competitions.tours.manage	статус тура
/admin/tracks	GET/POST	competitions.tracks.manage	зачёты

Registration and participants

Endpoint	Метод	Permission	Назначение
/seasons/{seasonId}/pre-registrations	POST	authenticated	предварительная регистрация
/registrations/{registrationId}/complete	PATCH	owner/family/teacher	дозаполнение второго шага
/seasons/{seasonId}/registrations	POST	authenticated	финальная индивидуальная/родительская/teacher registration
/teacher/organizations	GET	identity-backed	организации, доступные в преподавательском режиме
/teacher/organizations/{organizationId}/learning-groups	GET	Learning Workspace scope	Learning Groups выбранной организации
/teacher/competition-groups	GET/POST	competitions.groups.manage	season snapshot/projection выбранной Learning Group
/teacher/competition-groups/{groupId}/registrations	POST	competitions.registrations.manage.assigned	зарегистрировать группу или выбранных учеников
/teacher/competition-groups/{groupId}/helpers	POST/DELETE	competitions.group_helpers.manage	помощники с урезанными правами
/registrations/{registrationId}/official-data-status	GET	owner/family/teacher/admin scoped	готовность official data package
/registrations/{registrationId}/official-data-collection	POST	owner/family/teacher/admin scoped	создать identity collection session или parent invite
/admin/registrations	GET	competitions.registrations.read	заявки
/admin/registrations/{id}/status	PATCH	competitions.registrations.manage	решение
/participants/{participantId}/claim-access	POST	authenticated	claim access
/admin/access-claims/{id}/status	PATCH	competitions.access_claims.manage	рассмотреть claim

Teacher conduct and materials

Endpoint	Метод	Permission	Назначение
/teacher/conduct-applications	GET/POST	teacher mode selected organization	список или подача заявки на проведение тура
/teacher/conduct-applications/{id}	GET/PATCH	owner teacher/admin scoped	карточка или редактирование draft/needs_changes
/teacher/conduct-applications/{id}/complete	POST	owner teacher/admin scoped	завершить проведение
/admin/conduct-applications	GET	competitions.conduct_applications.read	административный список заявок
/admin/conduct-applications/{id}/approve	POST	competitions.conduct_applications.manage	одобрить заявку
/admin/conduct-applications/{id}/reject	POST	competitions.conduct_applications.manage	отклонить заявку
/teacher/seasons/{seasonId}/materials	GET	teacher mode selected organization	материалы сезона для преподавателя
/teacher/tours/{tourId}/materials	GET	teacher mode selected organization	материалы тура для преподавателя
/admin/materials	POST	competitions.materials.manage	добавить материал преподавателя
/admin/materials/{id}	PATCH	competitions.materials.manage	обновить материал преподавателя
/admin/materials/{id}/publish	POST	competitions.materials.manage	опубликовать материал преподавателя

Venues and organizations

Endpoint	Метод	Permission	Назначение
/venues/applications	POST	teacher venue layer	заявка площадки
/venues/applications/{id}	PATCH	teacher venue layer	дозаполнение заявки площадки
/admin/venues	GET/POST	competitions.venues.manage	площадки
/admin/venues/applications/{id}/status	PATCH	competitions.venues.manage	решение по заявке площадки
/venues/{venueId}/capacity	PATCH	teacher venue layer/systematika admin	изменить вместимость с проверкой текущих участников
/participants/{participantId}/venue-selection	POST/PATCH	self/family/teacher mode/systematika admin	выбор или смена площадки
/admin/venues/{venueId}/assignments	POST	competitions.venues.manage	назначение участников
/venue/me/participants	GET	competitions.venue.read	списки площадки

Activity runtime and delivery

Endpoint	Метод	Permission	Назначение
/admin/tour-activity-bindings	GET/POST	competitions.content.manage	связать тур/класс с LMS activity или temporary adapter
/admin/tour-activity-bindings/{id}/lock	POST	competitions.content.manage	lock activity structure
/tours/{tourId}/submissions	POST	participant/teacher mode	создать/получить LMS activity attempt и competition-facing ref
/teacher/tours/{tourId}/group-submissions	POST	teacher/helper scoped	отправить ответы по ученикам группы через LMS activity или adapter
/submissions/{submissionId}	GET	scoped read	competition-facing work/status refs
/submissions/{submissionId}/files	POST	owner/teacher/venue	загрузить файл в LMS/adapter/storage policy
/tours/{tourId}/bulk-files	POST	teacher mode/venue layer/systematika admin	MVP-загрузка файлов/zip/изображений без обязательной привязки к ученику
/photo-reports	POST	teacher/venue layer	отправить фотоотчёт
/photo-reports/{id}/status	PATCH	systematika admin	подтвердить/не подтвердить с комментарием
/admin/submissions/{id}/lock	POST	competitions.submissions.manage	lock

Checking, results, publications, documents

Endpoint	Метод	Permission	Назначение
/checker/submissions	GET	competitions.check.read	очередь проверки
/checker/submissions/{id}/check	POST	competitions.check.manage	проверка
/admin/results/calculate	POST	competitions.results.manage	расчёт
/admin/results/{id}/finalize	POST	competitions.results.manage	финализация
/admin/results/{id}/withhold	POST	competitions.results.manage	удержать результат от публикации
/appeals	POST	self/family/teacher mode scoped	MVP-апелляция результата
/admin/appeals/{id}/decision	POST	competitions.appeals.manage	решение по апелляции
/admin/arbitration-cases	POST	competitions.arbitration.manage	кейс подозрительной работы
/admin/arbitration-cases/{id}/decision	POST	competitions.arbitration.manage	решение арбитража
/admin/publications	GET/POST	competitions.publications.manage	публикации
/admin/documents/generate	POST	competitions.documents.manage	генерация

External teachers

Endpoint	Метод	Permission	Назначение
/external-teachers/profile	POST	competitions.external_teachers.manage.own	создать или обновить профиль внешнего преподавателя
/external-teachers/profile/verify	POST	competitions.external_teachers.manage.own	отправить подтверждение роли
/external-teachers/students	POST	competitions.participants.manage.assigned	добавить связь с учеником/participant
/external-teachers/students/{participantId}	DELETE	competitions.participants.manage.assigned	отозвать связь
/external-teachers/results	GET	competitions.results.read.assigned	результаты доступных учеников

Error codes

Код	HTTP	Когда
competitions.season.not_open	409	регистрация закрыта
competitions.registration.duplicate	409	повторная регистрация
competitions.payment.required	402	требуется оплата/entitlement
competitions.participant.access_denied	403	нет связи с участником
competitions.tour.not_open	409	тур не открыт
competitions.activity_binding.not_locked	409	activity binding не зафиксирован перед запуском тура
competitions.activity_runtime.unavailable	503	LMS activity runtime или temporary adapter недоступен
competitions.submission.locked	409	работа заблокирована
competitions.registration.details_required	409	регистрация требует дозаполнения
competitions.registration.duplicate_hold	409	регистрация удержана до решения по дублю
competitions.official_data.incomplete	409	official data package требуется, но не готов
competitions.official_data.raw_fields_forbidden	422	raw official fields переданы в competitions вместо identity collection flow
competitions.learning_group.not_accessible	403	нет доступа к Learning Group в выбранной организации
competitions.venue.capacity_below_assignments	409	вместимость ниже текущих назначений
competitions.conduct_application.not_editable	409	заявку на проведение нельзя редактировать в текущем статусе
competitions.material.not_available	403	материал закрыт по visibility или времени доступности
competitions.appeal.not_arbitration	422	апелляция не может использоваться для арбитража подозрительной работы
competitions.results.not_finalized	409	нельзя публиковать
competitions.result.withheld	409	результат удержан от публикации
competitions.document.not_generatable	409	нет finalized award