API lekcji — pobieranie lekcji dla dowolnej daty

API lekcji: GET /api/schedules/lessons/{datesrange} to uniwersalny punkt dostępu służący do pobierania rzeczywiście datowanych lekcji z planów lekcji — dowolna data albo dowolny zbiór dat, zawężone do żądanych jednostek, ze strukturami leżącymi u podstaw, nieobecnościami i zastępstwami albo bez nich, z godzinami zegarowymi albo po prostu z numerami pozycji na siatce godzin. To punkt wyjścia większości integracji.

Gdy coś poza Omniscolem potrzebuje wiedzieć, co się dzieje i kiedy, wywoływany jest właśnie ten punkt dostępu:

GET /api/schedules/lessons/{datesrange}

Zwraca datowane lekcje z planów lekcji — każdą lekcję umieszczoną na jej rzeczywistej dacie — dla żądanych dat i jednostek. Niemal każda integracja (intranet, ETL, narzędzie partnerskie) zaczyna się właśnie tutaj. Ta strona omawia dźwignie, które czynią z niego jeden punkt dostępu do wielu zastosowań.

Lekcje a struktury

Dwa punkty dostępu, dwie role:

• GET /api/schedules/lessons/{datesrange} — lekcje: każda lekcja umieszczona na rzeczywistej dacie, wraz z jej przedmiotem, nauczycielami, salą, grupą i czasem trwania. To właśnie czyta się, aby wiedzieć, kto jest gdzie i kiedy.
• GET /api/schedules/ — struktury: same opublikowane plany lekcji (klasy, przedmioty, lokalizacje, siatka godzin). Do czytania wtedy, gdy potrzebny jest model leżący u podstaw, a nie datowane lekcje.

Struktury można też zwinąć do wywołania lekcji za pomocą with_timetables=true (zob. poniżej): jedno żądanie zwraca wtedy jedno i drugie.

Wybór dat

{datesrange} zapisuje się w formacie YYYYMMDD i jest celowo elastyczny:

Forma rozproszona (rozdzielona przecinkami) sprawia, że pytanie w rodzaju „te trzy poniedziałki” staje się jednym wywołaniem.

Zawężenie do tego, co potrzebne

Parametr filter zawęża żądanie do jednostek, które się liczą — ta sama gramatyka filtra co w punktach dostępu zwracających dostępność (Zaawansowane zapytania):

• prosta lista identyfikatorów — {"classes":["3a","3b"]},
• znak wieloznaczny — {"teachers":"*"},
• proste dopasowanie pola — {"classrooms":[{"site":"centrum"}]},
• albo ustrukturyzowany $where — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

Wynik jest pogrupowany według typu filtra, a potem według identyfikatora jednostki — na przykład schedules.classes.3a.lessons[], schedules.teachers.a-kowalska.lessons[].

Dwa kolejne ustawienia zakreślają ramy pobierania, a ostatnie je ogranicza:

• timetables_restrict / timetables_exclude — ograniczenie lub wykluczenie identyfikatorów planu lekcji (łańcuch znaków, CSV albo tablica).
• limit — pułap liczby lekcji zwracanych dla każdego filtra.

Jak wygląda lekcja

Każdy wpis w lessons[] to umieszczona lekcja:

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

• position.day to data lekcji.
• position.period to numer pozycji lekcji na siatce godzin planu lekcji — obecny przy lekcjach umieszczonych na siatce. Lekcja poza siatką (z własnymi, jawnymi start/end, poza regularnymi przedziałami czasowymi) nosi w zamian start/end, bez period.
• position.start / position.end (godziny) towarzyszą zawsze lekcji poza siatką, a do lekcji na siatce dochodzą po przekazaniu with_hours=true (godziny wyliczone wcześniej). Do włączenia wtedy, gdy system docelowy potrzebuje godzin zegarowych, a nie numeru pozycji na siatce.

Nieobecności, odwołania i zastępstwa

Domyślnie punkt dostępu konsoliduje nieobecności: nieobecny nauczyciel zostaje usunięty z lekcji, a lekcja, na której nie został żaden nauczyciel, jest uznawana za odwołaną i pomijana. Kilka przełączników zmienia to zachowanie:

• without_absences — całkowite pominięcie nieobecności; zwrócenie planu lekcji w postaci surowej, tak jak został zaplanowany.
• with_absences — dodanie surowych nieobecności z danego okresu obok lekcji.
• with_cancellessons — zachowanie odwołanych lekcji (wszyscy nauczyciele nieobecni) zamiast ich pomijania.
• with_studentcancellessons — zachowanie wyłącznie lekcji odwołanych z powodu nieobecności ucznia.
• with_removedlessons — zwrócenie usuniętych lekcji (wyklucza się z with_cancellessons).
• without_teacher_consolidation — zachowanie nieobecnych nauczycieli na liście teachers każdej lekcji zamiast ich usuwania.
• without_holidays — niewstawianie dni wolnych w zakres.

Domyślnie, gdy do nieobecności wyznaczono zastępcę, zajmuje on po prostu miejsce nieobecnego nauczyciela na liście teachers lekcji — zastępstwo jest niewidoczne, bez dodatkowego pola. Po przekazaniu with_cancellessons albo without_teacher_consolidation lekcja nosi ponadto blok substitutes (identyfikator zastępcy, powód nieobecności oraz nieobecność, która je wymusiła), aby w tej samej odpowiedzi zobaczyć, kto został zastąpiony i dlaczego.

Struktury i spisy

Przydatne dane referencyjne można dołączyć w tym samym wywołaniu:

• with_timetables=true — surowe struktury planów lekcji, które posłużyły do wyliczenia lekcji (klasy, przedmioty, siatka godzin, według identyfikatora). Do włączenia, aby rozwiązać identyfikatory; do pozostawienia wyłączonym dla zwartej odpowiedzi.
• with_entities=true — nazwa i kod w wersji lekkiej (oraz pola imienia i nazwiska) jednostek z wyniku.
• with_teachers / with_all_teachers — nauczyciele występujący na lekcjach albo wszyscy nauczyciele z planu lekcji i ze spisu użytkowników.
• with_students — uczniowie wraz z ich przypisaniami według daty.
• with_events=true — wydarzenia poza siatką (posiedzenia rady pedagogicznej, zebrania z rodzicami…) w tym samym zakresie.

Nocne pobranie ETL

Pobranie tygodnia lekcji dla wszystkich klas, wraz z godzinami, i wczytanie go do własnego systemu informatycznego:

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

Odpowiedź grupuje lekcje pod schedules.classes.<id>.lessons[]. Nieobecności są już skonsolidowane: to, co zostaje wczytane, odzwierciedla rzeczywisty i aktualny plan lekcji — należy dodać with_absences=true, aby zapisać także powód zmiany.

Wysyłanie do Omniscol

Integracja działa też w drugą stronę — aby utrzymać Omniscol w zgodzie z zewnętrznym źródłem prawdy.

Dla oprogramowania SIS / ERP (Aurion, Auriga…) właściwym narzędziem jest dedykowany konektor, a nie surowe punkty dostępu poniżej — zob. Synchronizacja z systemami zewnętrznymi.

Klasy i nauczyciele

Te punkty dostępu istnieją wyłącznie na potrzeby synchronizacji z systemem zewnętrznym; interfejs Omniscol nigdy sam ich nie wywołuje:

• POST /api/external/classes (os_external_classes_post) — aktualizacja istniejących klas (nazwa, lokalizacja, poziom, sala, liczba uczniów) z danych indeksowanych identyfikatorem klasy. Aktualizuje klasy znane; nowych nie tworzy. Ustawienie pola na null je czyści (z wyjątkiem nazwy klasy — klasa zachowuje swoją nazwę).
• POST /api/external/teachers (os_external_teachers_post) — wstawienie lub aktualizacja nauczycieli według identyfikatora, zarówno w planach lekcji, jak i w spisie użytkowników (z utworzeniem w razie potrzeby użytkownika o roli nauczyciela i z automatycznie wygenerowanym loginem). Warianty DELETE usuwają klasę albo nauczyciela.

Istnieje też szczególny punkt dostępu, wyłącznie do nadpisania, os_external_classes_get: Omniscol nie dostarcza dla niego żadnej domyślnej implementacji, ale gdy partner albo dostawca skieruje go na własną usługę (przez Personalizacja API), ekran tworzenia klasy wypełnia się wstępnie z tej zamkniętej listy klas zamiast ręcznego formularza. Bez nadpisania po prostu nic nie robi.

Przedmioty niestandardowe

POST /api/admin/subjects/custom (os_admin_subjects-custom_post) wczytuje katalog przedmiotów niestandardowych albo tworzy jeden przedmiot. Korzysta z niego także interfejs. Treść żądania dla katalogu to { "subjects": [ … ], "replace": false, "duplicates_reuse": true }: domyślnie przyrostowo, replace: true dla pełnego odświeżenia, duplicates_reuse: true (wartość domyślna), aby dopasować istniejące przedmioty według identyfikatora zewnętrznego, kodu albo nazwy. To punkt dostępu nocnej wysyłki przedmiotów.