De lessen-API — de lessen ophalen voor elke willekeurige datum

De lessen-API: GET /api/schedules/lessons/{datesrange} is het endpoint dat alles kan om de daadwerkelijk gedateerde lessen uit uw roosters op te halen — welke datum of reeks datums dan ook, gefilterd op de gewenste entiteiten, met of zonder de onderliggende structuren, de afwezigheden en de vervangingen, de kloktijden of enkel de posities op het tijdrooster. Het is het startpunt van de meeste integraties.

Wanneer iets buiten Omniscol moet weten wat er gebeurt, en wanneer, is dit het endpoint dat wordt aangeroepen:

GET /api/schedules/lessons/{datesrange}

Het geeft de gedateerde lessen uit uw roosters terug — elke les geplaatst op haar werkelijke datum — voor de gevraagde datums en entiteiten. Bijna elke integratie (een intranet, een ETL, een partnertool) begint hier. Deze pagina loopt de parameters langs die er één endpoint van maken voor uiteenlopende toepassingen.

Lessen versus structuren

Twee endpoints, twee rollen:

• GET /api/schedules/lessons/{datesrange} — de lessen: elke les geplaatst op een werkelijke datum, met haar vak, docenten, lokaal, groep en duur. Dit is wat u leest om te weten wie waar is, en wanneer.
• GET /api/schedules/ — de structuren: de gepubliceerde roosters zelf (klassen, vakken, vestigingen, het tijdrooster). Te lezen wanneer u het onderliggende model nodig hebt in plaats van de gedateerde lessen.

U kunt de structuren ook in de aanroep van de lessen opnemen met with_timetables=true (zie verderop): één enkele aanvraag geeft dan beide terug.

De datums kiezen

{datesrange} wordt geschreven als YYYYMMDD en is bewust soepel opgezet:

Dankzij de losse vorm (gescheiden door komma's) wordt een vraag als “deze drie maandagen” één enkele aanroep.

Precies opvragen wat u nodig hebt

Een filter beperkt de aanvraag tot de entiteiten die ertoe doen — dezelfde filtergrammatica als bij de beschikbaarheids-endpoints (Geavanceerde queries):

• een eenvoudige lijst met identificaties — {"classes":["4a","4b"]},
• een jokerteken — {"teachers":"*"},
• een eenvoudige veldovereenkomst — {"classrooms":[{"site":"noord"}]},
• of een gestructureerde $where — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

Het resultaat is gegroepeerd per filtertype en daarna per entiteitsidentificatie — bijvoorbeeld schedules.classes.4a.lessons[], schedules.teachers.d-devries.lessons[].

Dezelfde array wordt tijdens een overgangsperiode nog steeds aangeboden onder haar oude naam courses[]: baseer uw integratie op lessons[].

Twee andere parameters bakenen de extractie af, en een laatste stelt er een plafond aan:

• timetables_restrict / timetables_exclude — roosteridentificaties beperken of uitsluiten (tekenreeks, CSV of array).
• limit — het aantal per filter teruggegeven lessen begrenzen.

Hoe een les eruitziet

Elk item in lessons[] is een geplaatste les:

{
  "position": { "day": "2026-10-05", "period": 0, "start": "8:15", "end": "9:10" },
  "duration": 2,
  "subject": "wiskunde",
  "teachers": ["d-devries"],
  "classroom": "noord:B12",
  "class": "4a",
  "schedid": "3"
}

• position.day is de datum van de les.
• position.period is de index van de les op het tijdrooster van het rooster — aanwezig bij lessen die op het tijdrooster staan. Een les buiten rooster (met eigen expliciete start/end, buiten de gewone tijdslots) draagt in plaats daarvan start/end, zonder period.
• position.start / position.end (kloktijden) horen altijd bij een les buiten rooster, en komen erbij op de lessen op het tijdrooster wanneer u with_hours=true meegeeft (vooraf berekende tijden). Zet dit aan wanneer uw doelsysteem de kloktijden nodig heeft in plaats van de index op het tijdrooster.

Afwezigheden, annuleringen en vervangingen

Standaard verwerkt het endpoint de afwezigheden: een afwezige docent wordt van de les gehaald, en een les zonder overgebleven docent geldt als geannuleerd en valt weg. Verschillende schakelaars veranderen dat:

• without_absences — de afwezigheden volledig negeren; het ruwe geplande rooster teruggeven.
• with_absences — de ruwe afwezigheden van de periode naast de lessen toevoegen.
• with_cancelcourses — de geannuleerde lessen (alle docenten afwezig) behouden in plaats van ze weg te laten.
• with_studentcancelcourses — alleen de lessen behouden die door de afwezigheid van een leerling geannuleerd zijn.
• with_removedcourses — de verwijderde lessen teruggeven (sluit with_cancelcourses uit).
• without_teacher_consolidation — de afwezige docenten in de lijst teachers van elke les behouden in plaats van ze eruit te halen.
• without_holidays — de vakanties niet in het bereik invoegen.

Wanneer er voor een afwezigheid een vervanger is aangewezen, neemt die standaard eenvoudigweg de plaats in van de afwezige docent in de lijst teachers van de les — de vervanging verloopt onzichtbaar, zonder extra veld. Geeft u with_cancelcourses of without_teacher_consolidation mee, dan draagt de les daarbovenop een blok substitutes (de identificatie van de vervanger, de reden van de afwezigheid en de afwezigheid die haar heeft opgelegd), zodat u in hetzelfde antwoord ziet wie vervangen is en waarom.

Structuren en referentielijsten

Voeg de nuttige referentiegegevens toe, in dezelfde aanroep:

• with_timetables=true — de ruwe structuren van de roosters die gebruikt zijn om de lessen te berekenen (klassen, vakken, tijdrooster, per identificatie). Zet dit aan om de identificaties te herleiden; laat het uit voor een compact antwoord.
• with_entities=true — lichte naam/code (en de naamvelden van personen) van de entiteiten in het resultaat.
• with_teachers / with_all_teachers — de docenten die op de lessen gebruikt worden, of alle docenten uit het rooster en de gebruikerslijst.
• with_students — de leerlingen, met hun plaatsingen per datum.
• with_events=true — de evenementen buiten rooster (rapportvergaderingen, ouderavonden…) binnen hetzelfde bereik.

Een nachtelijke ETL-extractie

Een week aan lessen ophalen voor alle klassen, met de kloktijden, en die laden in uw informatiesysteem:

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

Het antwoord groepeert de lessen onder schedules.classes.<id>.lessons[]. De afwezigheden zijn al verwerkt: wat u laadt, weerspiegelt het werkelijke, actuele rooster — voeg with_absences=true toe als u ook de reden van een wijziging wilt vastleggen.

Gegevens naar Omniscol sturen

De integratie werkt ook de andere kant op — om Omniscol in lijn te houden met een externe bron van waarheid. Deze endpoints bestaan uitsluitend voor die externe synchronisatie; de Omniscol-interface roept ze zelf nooit aan:

• POST /api/external/classes (os_external_classes_post) — bestaande klassen bijwerken (naam, vestiging, niveau, lokaal, aantal leerlingen) vanuit gegevens die op klasidentificatie zijn geïndexeerd. Het werkt de bekende klassen bij; het maakt er geen nieuwe aan. Zet een veld op null om het te wissen (behalve de naam van de klas — een klas behoudt haar naam).
• POST /api/external/teachers (os_external_teachers_post) — docenten invoegen of bijwerken op identificatie, zowel in de roosters als in de gebruikerslijst (waarbij de gebruiker zo nodig wordt aangemaakt met de rol docent en een automatisch gegenereerde login). De DELETE-varianten verwijderen een klas of een docent.
• POST /api/admin/subjects/custom (os_admin_subjects-custom_post) — een catalogus met aangepaste vakken laden. De body is { "subjects": [ … ], "replace": false, "nodoubles": true }: standaard incrementeel, replace: true voor een volledige verversing, nodoubles: true om bestaande vakken te matchen op externe identificatie, code of naam. Dit is het endpoint voor een nachtelijke push van vakken.

Er bestaat ook een bijzonder endpoint dat alleen als override werkt, os_external_classes_get: Omniscol levert er standaard geen enkele implementatie voor, maar zodra een partner of een leverancier het naar zijn eigen dienst laat wijzen (via API-aanpassingen), vult het scherm voor het aanmaken van een klas zich vooraf in vanuit die gesloten lijst met klassen in plaats van uit het handmatige formulier. Zonder override doet het eenvoudigweg niets.

Voor een SIS- of ERP-pakket (Aurion, Auriga…) verdient de speciale connector de voorkeur boven deze ruwe endpoints — zie Synchronisatie met externe systemen.