API занятий — получение занятий на любую дату

API занятий: GET /api/schedules/lessons/{datesrange} — универсальная конечная точка для получения занятий ваших расписаний с реальными датами: на любую дату или набор дат, с фильтром по нужным сущностям, с базовыми структурами, отсутствиями и замещениями или без них, со временем начала и окончания или только с номерами слотов сетки. С неё начинается большинство интеграций.

Когда внешней системе нужно знать, что происходит и когда, она обращается к этой конечной точке:

GET /api/schedules/lessons/{datesrange}

Она возвращает занятия с датами из ваших расписаний — каждое занятие стоит на своей реальной дате — для запрошенных дат и сущностей. Почти любая интеграция (интранет, ETL, инструмент партнёра) начинается отсюда. На этой странице разобраны параметры, благодаря которым одна конечная точка подходит для множества задач.

Занятия и структуры

Две конечные точки, две роли:

• GET /api/schedules/lessons/{datesrange} — занятия: каждое занятие, поставленное на реальную дату, с дисциплиной, преподавателями, кабинетом, группой и продолжительностью. Её читают, чтобы узнать, кто где находится и когда.
• GET /api/schedules/ — структуры: сами опубликованные расписания (классы, дисциплины, площадки, сетка). Её читают, когда нужна базовая модель, а не занятия с датами.

Структуры можно также добавить в вызов занятий с помощью with_timetables=true (см. ниже): тогда один запрос возвращает и то, и другое.

Выбор дат

{datesrange} записывается в формате YYYYMMDD и намеренно допускает разные формы:

Разрозненная форма (через запятую) позволяет уложить вопрос вроде «эти три понедельника» в один вызов.

Выберите только то, что нужно

Параметр filter ограничивает запрос нужными сущностями — по той же грамматике фильтра, что и конечные точки доступности (Расширенные запросы):

• простой список идентификаторов — {"classes":["3a","3b"]},
• подстановочный знак — {"teachers":"*"},
• простое совпадение по полю — {"classrooms":[{"site":"nord"}]},
• или структурированный $where — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

Результат группируется по типу фильтра, затем по идентификатору сущности — например, schedules.classes.3a.lessons[], schedules.teachers.j-doe.lessons[].

Ещё два параметра задают рамки выборки, а один ограничивает её объём:

• timetables_restrict / timetables_exclude — оставить или исключить идентификаторы расписаний (строка, CSV или массив).
• limit — ограничить число занятий, возвращаемых на каждый фильтр.

Как выглядит занятие

Каждый элемент lessons[] — это поставленное занятие:

{
  "position": { "day": "2026-10-05", "period": 0, "start": "8:15", "end": "9:10" },
  "duration": 2,
  "subject": "maths",
  "teachers": ["j-doe"],
  "classroom": "nord:B12",
  "class": "3a",
  "schedid": "3"
}

• position.day — дата занятия.
• position.period — номер занятия на сетке расписания; он есть у занятий, поставленных на сетку. У занятия вне сетки (со своими явными start/end, не совпадающими с обычными слотами) вместо него указаны start/end, а period отсутствует.
• position.start / position.end (время) всегда сопровождают занятие вне сетки и добавляются к занятиям на сетке, если передать with_hours=true (заранее вычисленное время). Включайте этот параметр, когда целевой системе нужно время по часам, а не номер на сетке.

Отсутствия, отмены и замещения

По умолчанию конечная точка учитывает отсутствия: отсутствующий преподаватель исключается из занятия, а занятие, у которого не осталось преподавателей, считается отменённым и отбрасывается. Это меняют несколько параметров:

• without_absences — полностью игнорировать отсутствия; вернуть исходную запланированную сетку.
• with_absences — добавить к занятиям необработанные отсутствия за период.
• with_cancellessons — сохранить отменённые занятия (все преподаватели отсутствуют), а не отбрасывать их.
• with_studentcancellessons — оставить только занятия, отменённые из-за отсутствия ученика.
• with_removedlessons — вернуть снятые занятия (несовместим с with_cancellessons).
• without_teacher_consolidation — оставить отсутствующих преподавателей в списке teachers каждого занятия, а не исключать их.
• without_holidays — не подставлять каникулы в диапазон.

По умолчанию, если на время отсутствия назначен замещающий, он просто занимает место отсутствующего преподавателя в списке teachers занятия — замещение прозрачно, без дополнительных полей. Если передать with_cancellessons или without_teacher_consolidation, у занятия появляется ещё и блок substitutes (идентификатор замещающего, причина отсутствия и само отсутствие, из-за которого потребовалось замещение): так в одном ответе видно, кого заменили и почему.

Структуры и справочники

Нужные справочные данные можно присоединить в том же вызове:

• with_timetables=true — исходные структуры расписаний, по которым вычислены занятия (классы, дисциплины, сетка, по идентификатору). Включайте, чтобы расшифровать идентификаторы; для компактного ответа оставьте выключенным.
• with_entities=true — краткие название и код (и поля имени человека) сущностей из результата.
• with_teachers / with_all_teachers — преподаватели, участвующие в занятиях, или все преподаватели расписания и справочника.
• with_students — ученики с их распределением по датам.
• with_events=true — события вне сетки (педагогические советы, родительские собрания…) за тот же диапазон.

Ночной забор данных для ETL

Получить занятия за неделю по всем классам, со временем начала и окончания, и загрузить их в вашу информационную систему:

curl -G "https://votre-etablissement.omniscol.com/api/schedules/lessons/20261005-20261011" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classes":"*"}' \
  --data-urlencode "with_hours=true"

В ответе занятия сгруппированы в schedules.classes.<id>.lessons[]. Отсутствия уже учтены: загружаемые данные отражают реальное и актуальное расписание — добавьте with_absences=true, если хотите сохранять ещё и причину изменения.

Передача данных в Omniscol

Интеграция работает и в обратную сторону — чтобы Omniscol совпадал с внешним источником достоверных данных.

Для школьной информационной системы или ERP (Aurion, Auriga…) лучше использовать специальный коннектор, а не приведённые ниже низкоуровневые конечные точки — см. Синхронизация с внешними системами.

Классы и преподаватели

Эти конечные точки существуют только для синхронизации с внешней системой; сам интерфейс Omniscol их никогда не вызывает:

• POST /api/external/classes (os_external_classes_post) — обновить существующие классы (название, площадка, уровень, кабинет, численность) по данным, индексированным по идентификатору класса. Он обновляет известные классы, но новых не создаёт. Чтобы очистить поле, задайте ему значение null (кроме названия класса — у класса название остаётся всегда).
• POST /api/external/teachers (os_external_teachers_post) — добавить или обновить преподавателей по идентификатору, как в расписаниях, так и в справочнике (при необходимости создавая пользователя с ролью преподавателя и автоматически сформированным логином). Варианты DELETE удаляют класс или преподавателя.

Есть и особая конечная точка, которую можно только переопределить, os_external_classes_get: Omniscol не поставляет для неё реализации по умолчанию, но когда партнёр или поставщик направляет её на собственный сервис (через Настройка API), экран создания класса предварительно заполняется из этого закрытого списка классов вместо формы ручного ввода. Без переопределения она просто ничего не делает.

Собственные дисциплины

POST /api/admin/subjects/custom (os_admin_subjects-custom_post) загружает каталог собственных дисциплин или создаёт одну дисциплину. Интерфейс тоже пользуется ею. Тело запроса для каталога — { "subjects": [ … ], "replace": false, "duplicates_reuse": true }: по умолчанию данные добавляются, replace: true — полное обновление, duplicates_reuse: true (значение по умолчанию) — сопоставлять существующие дисциплины по внешнему идентификатору, коду или названию. Это конечная точка для ночной передачи дисциплин.