Die API der Unterrichtsstunden — Unterrichtsstunden für ein beliebiges Datum abrufen

Die API der Unterrichtsstunden: GET /api/schedules/lessons/{datesrange} ist der Alleskönner-Endpunkt, um die tatsächlich datierten Unterrichtsstunden Ihrer Stundenpläne abzurufen — ein beliebiges Datum oder eine beliebige Datumsmenge, gefiltert auf die gewünschten Entitäten, mit oder ohne die zugrunde liegenden Strukturen, die Abwesenheiten und die Vertretungen, die Uhrzeiten oder die einfachen Rasterperioden. Es ist der Ausgangspunkt der meisten Integrationen.

Wenn etwas außerhalb von Omniscol wissen muss, was passiert und wann, ruft man diesen Endpunkt auf:

GET /api/schedules/lessons/{datesrange}

Er gibt die datierten Unterrichtsstunden Ihrer Stundenpläne zurück — jede Unterrichtsstunde auf ihrem tatsächlichen Datum platziert — für die angefragten Daten und Entitäten. Fast jede Integration (ein Intranet, ein ETL, ein Partnerwerkzeug) geht davon aus. Diese Seite geht die Hebel durch, die ihn zu einem einzigen Endpunkt für zahlreiche Verwendungen machen.

Unterrichtsstunden vs. Strukturen

Zwei Endpunkte, zwei Rollen:

• GET /api/schedules/lessons/{datesrange} — die Unterrichtsstunden: jede Unterrichtsstunde auf einem tatsächlichen Datum platziert, mit ihrem Fach, ihren Lehrkräften, ihrem Raum, ihrer Gruppe und ihrer Dauer. Das liest man, um zu wissen, wer wo und wann ist.
• GET /api/schedules/ — die Strukturen: die veröffentlichten Stundenpläne selbst (Klassen, Fächer, Standorte, das Raster). Zu lesen, wenn man das zugrunde liegende Modell statt der datierten Unterrichtsstunden braucht.

Man kann die Strukturen auch mit with_timetables=true in den Aufruf der Unterrichtsstunden einklappen (siehe weiter unten): Eine einzige Anfrage gibt dann beide zurück.

Die Daten wählen

{datesrange} wird in YYYYMMDD geschrieben und ist bewusst flexibel gehalten:

Die verstreute Form (durch Kommas getrennt) ist das, was aus einer Frage wie „diese drei Montage“ einen einzigen Aufruf macht.

Das anvisieren, was Sie brauchen

Ein filter schränkt die Anfrage auf die Entitäten ein, die zählen — dieselbe Filtergrammatik wie die Verfügbarkeits-Endpunkte (Erweiterte Abfragen):

• eine einfache Liste von Kennungen — {"classes":["3a","3b"]},
• ein Joker — {"teachers":"*"},
• eine einfache Feldübereinstimmung — {"classrooms":[{"site":"nord"}]},
• oder ein strukturiertes $where — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

Das Ergebnis wird nach Filtertyp, dann nach Entitätskennung gruppiert — zum Beispiel schedules.classes.3a.courses[], schedules.teachers.j-doe.courses[].

Zwei weitere Einstellungen rahmen die Extraktion ein, und eine letzte deckelt sie:

• timetables_restrict / timetables_exclude — Stundenplan-Kennungen begrenzen oder ausschließen (Zeichenkette, CSV oder Array).
• limit — die Anzahl der pro Filter zurückgegebenen Unterrichtsstunden deckeln.

Wie eine Unterrichtsstunde aussieht

Jeder Eintrag von courses[] ist eine platzierte Unterrichtsstunde:

{
  "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 ist das Datum der Unterrichtsstunde.
• position.period ist der Index der Unterrichtsstunde im Raster des Stundenplans — vorhanden für die auf dem Raster platzierten Unterrichtsstunden. Eine rasterfremde Unterrichtsstunde (mit ihren eigenen expliziten start/end, außerhalb der regulären Zeitfenster) trägt stattdessen start/end, ohne period.
• position.start / position.end (Uhrzeiten) begleiten immer eine rasterfremde Unterrichtsstunde und kommen zu den Rasterunterrichtsstunden hinzu, wenn Sie with_hours=true übergeben (vorberechnete Uhrzeiten). Zu aktivieren, wenn Ihr Zielsystem die Uhrzeiten statt des Rasterindex braucht.

Abwesenheiten, Annullierungen und Vertretungen

Standardmäßig konsolidiert der Endpunkt die Abwesenheiten: Eine abwesende Lehrkraft wird aus der Unterrichtsstunde entfernt, und eine Unterrichtsstunde ohne verbleibende Lehrkraft gilt als annulliert und wird verworfen. Mehrere Indikatoren ändern dies:

• without_absences — die Abwesenheiten vollständig ignorieren; das rohe geplante Raster zurückgeben.
• with_absences — die rohen Abwesenheiten des Zeitraums neben den Unterrichtsstunden hinzufügen.
• with_cancelcourses — die annullierten Unterrichtsstunden (alle Lehrkräfte abwesend) behalten, statt sie zu verwerfen.
• with_studentcancelcourses — nur die durch die Abwesenheit eines Schülers annullierten Unterrichtsstunden behalten.
• with_removedcourses — die entfernten Unterrichtsstunden zurückgeben (exklusiv mit with_cancelcourses).
• without_teacher_consolidation — die abwesenden Lehrkräfte in der teachers-Liste jeder Unterrichtsstunde behalten, statt sie zu entfernen.
• without_holidays — die Ferien nicht in den Bereich einfügen.

Wenn eine Vertretung für eine Abwesenheit bestimmt wurde, ersetzt sie standardmäßig einfach die abwesende Lehrkraft in der teachers-Liste der Unterrichtsstunde — die Substitution ist transparent, ohne zusätzliches Feld. Übergeben Sie with_cancelcourses oder without_teacher_consolidation, und die Unterrichtsstunde trägt zusätzlich einen substitutes-Block (die Kennung der Vertretung, den Abwesenheitsgrund und die Abwesenheit, die sie erzwungen hat), um in derselben Nutzlast zu sehen, wer ersetzt wurde und warum.

Strukturen und Verzeichnisse

Hängen Sie die nützlichen Referenzdaten im selben Aufruf an:

• with_timetables=true — die rohen Strukturen der Stundenpläne, die zur Berechnung der Unterrichtsstunden gedient haben (Klassen, Fächer, Raster, nach Kennung). Zu aktivieren, um die Kennungen aufzulösen; deaktiviert zu lassen für eine kompakte Antwort.
• with_entities=true — leichte Namen/Codes (und Personennamenfelder) der Entitäten des Ergebnisses.
• with_teachers / with_all_teachers — die auf den Unterrichtsstunden verwendeten Lehrkräfte oder alle Lehrkräfte des Stundenplans und des Verzeichnisses.
• with_students — die Schüler, mit ihren Platzierungen nach Datum.
• with_events=true — die rasterfremden Ereignisse (Konferenzen, Elternsprechtage …) im selben Bereich.

Ein nächtlicher ETL-Abzug

Eine Woche Unterrichtsstunden für alle Klassen, mit den Uhrzeiten, abrufen und in Ihr Informationssystem laden:

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"

Die Antwort gruppiert die Unterrichtsstunden unter schedules.classes.<id>.courses[]. Die Abwesenheiten sind bereits konsolidiert: Was Sie laden, spiegelt den tatsächlichen und aktuellen Stundenplan wider — fügen Sie with_absences=true hinzu, wenn Sie auch den Grund einer Änderung aufzeichnen möchten.

Nach Omniscol pushen

Die Integration funktioniert auch in die andere Richtung — um Omniscol an einer externen Quelle der Wahrheit ausgerichtet zu halten. Diese Endpunkte existieren ausschließlich für diese externe Synchronisierung; die Omniscol-Oberfläche ruft sie niemals selbst auf:

• POST /api/external/classes (os_external_classes_post) — bestehende Klassen aktualisieren (Name, Standort, Niveau, Raum, Stärke) aus einer nach Klassenkennung indizierten Nutzlast. Er aktualisiert die bekannten Klassen; er erstellt keine neuen. Setzen Sie ein Feld auf null, um es zu löschen (den Klassennamen ausgenommen — eine Klasse behält ihren Namen).
• POST /api/external/teachers (os_external_teachers_post) — Lehrkräfte nach Kennung einfügen oder aktualisieren, sowohl in den Stundenplänen als auch im Verzeichnis (wobei bei Bedarf der Benutzer mit der Rolle Lehrkraft und einem automatisch generierten Login erstellt wird). Die DELETE-Varianten entfernen eine Klasse oder eine Lehrkraft.
• POST /api/admin/subjects/custom (os_admin_subjects-custom_post) — einen Katalog benutzerdefinierter Fächer laden. Der Körper ist { "subjects": [ … ], "replace": false, "nodoubles": true }: standardmäßig inkrementell, replace: true für eine vollständige Aktualisierung, nodoubles: true, um die bestehenden Fächer nach externer Kennung, Code oder Name abzugleichen. Es ist der Endpunkt für einen nächtlichen Push von Fächern.

Es gibt auch einen speziellen, nur überschreibbaren Endpunkt, os_external_classes_get: Omniscol liefert dafür standardmäßig keine Implementierung, aber wenn ein Partner oder ein Anbieter ihn auf seinen eigenen Dienst zeigen lässt (über API-Anpassung), füllt sich der Bildschirm zur Klassenerstellung aus dieser geschlossenen Klassenliste vor, statt aus dem manuellen Formular. Ohne Überschreibung tut er einfach nichts.

Für eine SIS-/ERP-Softwarelösung (Aurion, Auriga …) bevorzugen Sie den dedizierten Konnektor gegenüber diesen rohen Endpunkten — siehe Synchronisierung mit externen Systemen.