L'API des séances — récupérer les séances pour n'importe quelle date

L'API des séances : GET /api/schedules/lessons/{datesrange} est le point d'accès à tout faire pour récupérer les séances réellement datées de vos emplois du temps — n'importe quelle date ou ensemble de dates, filtré sur les entités voulues, avec ou sans les structures sous-jacentes, les absences et les remplacements, les horaires ou les simples périodes de grille. C'est le point de départ de la plupart des intégrations.

Quand quelque chose hors d'Omniscol a besoin de savoir ce qui se passe, et quand, c'est ce point d'accès qu'on appelle :

GET /api/schedules/lessons/{datesrange}

Il renvoie les séances datées de vos emplois du temps — chaque séance posée sur sa date réelle — pour les dates et les entités demandées. Presque toute intégration (un intranet, un ETL, un outil partenaire) part de là. Cette page parcourt les leviers qui en font un seul point d'accès pour de nombreux usages.

Séances vs structures

Deux points d'accès, deux rôles :

• GET /api/schedules/lessons/{datesrange} — les séances : chaque séance posée sur une date réelle, avec sa matière, ses enseignants, sa salle, son groupe et sa durée. C'est ce qu'on lit pour savoir qui est où et quand.
• GET /api/schedules/ — les structures : les emplois du temps publiés eux-mêmes (classes, matières, sites, la grille). À lire quand on a besoin du modèle sous-jacent plutôt que des séances datées.

On peut aussi replier les structures dans l'appel des séances avec with_timetables=true (voir plus bas) : une seule requête renvoie alors les deux.

Choisir les dates

{datesrange} s'écrit en YYYYMMDD et se veut volontairement souple :

La forme éparse (séparée par des virgules) est ce qui fait d'une question comme « ces trois lundis » un seul appel.

Cibler ce dont vous avez besoin

Un filter restreint la requête aux entités qui comptent — la même grammaire de filtre que les points d'accès de disponibilité (Requêtage avancé) :

• une simple liste d'identifiants — {"classes":["3a","3b"]},
• un joker — {"teachers":"*"},
• une correspondance de champ simple — {"classrooms":[{"site":"nord"}]},
• ou un $where structuré — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

Le résultat est groupé par type de filtre, puis par identifiant d'entité — par exemple schedules.classes.3a.courses[], schedules.teachers.j-doe.courses[].

Deux autres réglages cadrent l'extraction, et un dernier la plafonne :

• timetables_restrict / timetables_exclude — limiter ou exclure des identifiants d'emploi du temps (chaîne, CSV ou tableau).
• limit — plafonner le nombre de séances renvoyées par filtre.

À quoi ressemble une séance

Chaque entrée de courses[] est une séance posée :

{
  "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 est la date de la séance.
• position.period est l'indice de la séance sur la grille de l'emploi du temps — présent pour les séances posées sur la grille. Une séance hors-grille (avec ses propres start/end explicites, hors des créneaux réguliers) porte start/end à la place, sans period.
• position.start / position.end (horaires) accompagnent toujours une séance hors-grille, et s'ajoutent aux séances de grille quand vous passez with_hours=true (horaires pré-calculés). À activer quand votre système cible a besoin des heures d'horloge plutôt que de l'indice de grille.

Absences, annulations et remplacements

Par défaut, le point d'accès consolide les absences : un enseignant absent est retiré de la séance, et une séance sans enseignant restant est considérée comme annulée et écartée. Plusieurs indicateurs changent cela :

• without_absences — ignorer complètement les absences ; renvoyer la grille planifiée brute.
• with_absences — ajouter les absences brutes de la période à côté des séances.
• with_cancelcourses — conserver les séances annulées (tous les enseignants absents) au lieu de les écarter.
• with_studentcancelcourses — ne garder que les séances annulées par l'absence d'un élève.
• with_removedcourses — renvoyer les séances retirées (exclusif avec with_cancelcourses).
• without_teacher_consolidation — garder les enseignants absents dans la liste teachers de chaque séance au lieu de les retirer.
• without_holidays — ne pas injecter les vacances dans la plage.

Par défaut, lorsqu'un remplaçant a été désigné pour une absence, il remplace simplement l'enseignant absent dans la liste teachers de la séance — la substitution est transparente, sans champ supplémentaire. Passez with_cancelcourses ou without_teacher_consolidation et la séance porte en plus un bloc substitutes (l'identifiant du remplaçant, le motif d'absence et l'absence qui l'a imposé), pour voir qui a été remplacé et pourquoi dans la même charge utile.

Structures et annuaires

Attachez les données de référence utiles, dans le même appel :

• with_timetables=true — les structures brutes des emplois du temps ayant servi à calculer les séances (classes, matières, grille, par identifiant). À activer pour résoudre les identifiants ; à laisser désactivé pour une réponse compacte.
• with_entities=true — nom/code légers (et champs de nom de personne) des entités du résultat.
• with_teachers / with_all_teachers — les enseignants utilisés sur les séances, ou tous les enseignants de l'emploi du temps et de l'annuaire.
• with_students — les élèves, avec leurs placements par date.
• with_events=true — les événements hors grille (conseils, rencontres parents-professeurs…) sur la même plage.

Un tirage ETL nocturne

Récupérer une semaine de séances pour toutes les classes, avec les horaires, et la charger dans votre système d'information :

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"

La réponse groupe les séances sous schedules.classes.<id>.courses[]. Les absences sont déjà consolidées : ce que vous chargez reflète l'emploi du temps réel et à jour — ajoutez with_absences=true si vous voulez aussi enregistrer la raison d'un changement.

Pousser vers Omniscol

L'intégration fonctionne aussi dans l'autre sens — pour garder Omniscol aligné sur une source de vérité externe. Ces points d'accès existent uniquement pour cette synchronisation externe ; l'interface Omniscol ne les appelle jamais elle-même :

• POST /api/external/classes (os_external_classes_post) — mettre à jour des classes existantes (nom, site, niveau, salle, effectif) depuis une charge utile indexée par identifiant de classe. Il met à jour les classes connues ; il n'en crée pas de nouvelles. Mettez un champ à null pour l'effacer (le nom de la classe excepté — une classe garde son nom).
• POST /api/external/teachers (os_external_teachers_post) — insérer ou mettre à jour des enseignants par identifiant, à la fois dans les emplois du temps et dans l'annuaire (en créant l'utilisateur avec le rôle enseignant et un login auto-généré au besoin). Les variantes DELETE retirent une classe ou un enseignant.
• POST /api/admin/subjects/custom (os_admin_subjects-custom_post) — charger un catalogue de matières personnalisées. Le corps est { "subjects": [ … ], "replace": false, "nodoubles": true } : incrémental par défaut, replace: true pour un rafraîchissement complet, nodoubles: true pour rapprocher les matières existantes par identifiant externe, code ou nom. C'est le point d'accès d'un push nocturne de matières.

Il existe aussi un point d'accès spécial, uniquement surchargeable, os_external_classes_get : Omniscol n'en livre aucune implémentation par défaut, mais lorsqu'un partenaire ou un fournisseur le pointe vers son propre service (via Personnalisation d'API), l'écran de création de classe se pré-remplit depuis cette liste fermée de classes au lieu du formulaire manuel. Sans surcharge, il ne fait simplement rien.

Pour un progiciel SIS / ERP (Aurion, Auriga…), préférez le connecteur dédié à ces points d'accès bruts — voir Synchronisation avec des systèmes externes.