Сабақтар API-і — кез келген күнге сабақтарды алу

Сабақтар API-і: GET /api/schedules/lessons/{datesrange} — кестелеріңіздегі нақты күнге бекітілген сабақтарды алуға арналған әмбебап қол жеткізу нүктесі: кез келген күн немесе күндер жиыны, қажетті нысандар бойынша сүзілген, астарындағы құрылымдармен немесе оларсыз, қатыспаулар мен алмастырулармен, сағаттармен немесе тордың жай уақыт аралықтарымен. Бұл — интеграциялардың көбінің бастапқы нүктесі.

Omniscol-дан тыс бір нәрсе не болып жатқанын және қашан екенін білуі керек болғанда, осы қол жеткізу нүктесіне сұрау жіберіледі:

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 мәндерімен, тұрақты уақыт аралықтарынан тыс) period орнына start/end мәндерін қамтиды.
• 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://your-school.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-ды сыртқы негізгі дереккөзбен үйлесімді ұстау үшін.

SIS / 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 (әдепкі мән) бар пәндерді сыртқы идентификатор, код немесе атау бойынша сәйкестендіреді. Бұл — пәндерді түнде жіберудің қол жеткізу нүктесі.