Référence — emploi du temps

Lire les cours, déposer un emploi du temps, annuler un cours. Ces routes s'appellent avec une clé d'intégration : voir Conventions. Toutes sont sous /api/institutions/:institutionId, où :institutionId est l'identifiant de l'établissement de la clé, rendu par GET /api/me.

L'objet Cours

{
  "id": "9214f192-5c1e-4a0e-9b6e-1c2d3e4f5a6b",
  "roomId": "0b6a1f4e-2c3d-4e5f-8a9b-7c6d5e4f3a2b",
  "roomShortId": "ABCD2345",
  "roomName": "Salle 204",
  "occurrenceId": null,
  "groupId": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a9f",
  "groupName": "BTS SIO 1",
  "audiences": [],
  "teacherId": null,
  "title": "Mathématiques",
  "startsAt": "2026-10-14T08:00:00.000Z",
  "endsAt": "2026-10-14T10:00:00.000Z",
  "opensAt": "2026-10-14T07:50:00.000Z",
  "closesAt": "2026-10-14T10:15:00.000Z",
  "status": "scheduled",
  "lastActiveAt": null,
  "externalRef": "ENT-12345"

}

Statuts

Le statut suit les connexions et un balayage qui passe toutes les 15 minutes. Un cours auquel personne ne s'est connecté peut donc rester scheduled jusqu'à ce que ce balayage le passe held, au plus tard 15 minutes après closesAt.

Fenêtre d'accès

La salle s'ouvre avant le début du cours et se ferme après sa fin. Les deux marges dépendent du type de la salle ; elles ne se fixent pas dans un dépôt.

Une salle créée par un dépôt est toujours de type class.

GET /api/institutions/:institutionId/lessons

Les cours d'une période. Exige schedule.read — la portée schedule:read.

La période ne peut pas dépasser 400 jours, et to ne peut pas précéder from. Un cours est rendu s'il chevauche la période : sa fin est postérieure ou égale à from, et son début antérieur ou égal à to. Tous les statuts sont rendus, cours annulés compris.

Réponse 200 :

{
  "lessons": [ { "id": "9214f192-…", "status": "scheduled", "…": "…" } ],
  "from": "2026-10-12T00:00:00.000Z",
  "to": "2026-10-19T00:00:00.000Z"

}

PUT /api/institutions/:institutionId/lessons

Dépose un emploi du temps. Exige schedule.write — la portée schedule:write.

Le dépôt est rejouable : chaque cours est reconnu par votre ref, et un même corps envoyé deux fois ne change rien. Un cours absent du dépôt n'est PAS annulé.

Corps de la requête

{
  "sessions": [
    {
      "ref": "ENT-12345",
      "room": { "ref": "salle-204", "name": "Salle 204" },
      "group": { "ref": "bts-sio-1", "name": "BTS SIO 1" },
      "title": "Mathématiques",
      "startsAt": "2026-10-14T08:00:00Z",
      "durationMinutes": 120,
      "cancelled": false
    }
  ]

}

Chaque entrée de sessions :

Traitement

1. Chaque entrée est lue et vérifiée seule. Une entrée fautive est refusée, les autres continuent.
2. Le dépôt est confronté à lui-même : deux entrées de même ref, ou deux cours non annulés qui se chevauchent dans la même salle, sont refusés TOUS LES DEUX. Deux créneaux qui se touchent — fin de l'un égale au début de l'autre — ne se chevauchent pas. Une entrée dont room.centre ou group.centre ne désigne aucun centre de l'établissement est refusée.
3. Les salles et les classes sont cherchées par leur ref. Celles qui n'existent pas sont créées, sauf en essai à blanc : une salle de type class et de capacité 80, nommée room.name, ou room.ref à défaut ; une classe nommée group.name, ou group.ref à défaut. Chacune reçoit le centre donné par le dépôt, s'il y en a un.
4. Chaque entrée restante est appliquée. Une entrée cancelled: true annule le cours s'il existe. Sinon, le cours est refusé si un AUTRE cours non annulé occupe déjà la salle sur ce créneau ; il est laissé tel quel si rien n'a changé ; il est déplacé s'il existe ; il est créé sinon.

Règles qui en découlent :

• Un cours held ne se déplace plus : l'entrée est refusée.
• Le plafond de simultanéité de votre offre n'est vérifié qu'à la création d'un cours, pas à son déplacement.
• Un cours cancelled ne se rétablit pas par un dépôt : l'entrée est rapportée updated, mais le cours reste annulé.
• En essai à blanc, un cours dont la salle n'existe pas encore est rapporté created sans que l'occupation de la salle puisse être vérifiée.
• Une annulation par cette route n'émet pas l'événement session.cancelled.

Réponse

201 si le dépôt est appliqué, 200 si c'est un essai à blanc — dans les deux cas même si des entrées sont refusées.

{
  "dryRun": false,
  "read": 3,
  "created": 1,
  "updated": 1,
  "unchanged": 0,
  "cancelled": 0,
  "rejected": 1,
  "roomsCreated": 1,
  "groupsCreated": 0,
  "lines": [
    { "ref": "ENT-12345", "outcome": "created", "sessionId": "9214f192-…" },
    { "ref": "ENT-12346", "outcome": "updated", "sessionId": "7a1b2c3d-…" },
    {
      "ref": "ENT-12347",
      "outcome": "rejected",
      "sessionId": null,
      "reason": "salle « salle-204 » déjà occupée de 2026-10-14T08:00:00.000Z à 2026-10-14T10:00:00.000Z"
    }
  ]

}

Chaque ligne du rapport :

Causes de refus d'une entrée

Erreurs de la requête entière

DELETE /api/institutions/:institutionId/lessons/by-ref/:ref

Annule un cours déposé, par votre ref. Exige schedule.write — la portée schedule:write.

Réponse 200 :

{ "ref": "ENT-12345", "outcome": "cancelled", "sessionId": "9214f192-5c1e-4a0e-9b6e-1c2d3e4f5a6b" 
}

L'annulation libère la place que le cours retenait dans le plafond de simultanéité. Elle n'émet pas l'événement session.cancelled.

Les autres routes des cours

La même clé atteint aussi, selon ses portées, GET …/lessons/:lessonId (un cours), GET …/lessons/conflicts (les chevauchements d'une période) et les écritures à l'unité : poser un cours, une série, désigner l'enseignant, diffuser à d'autres classes, annuler par DELETE …/lessons/:lessonId. Cette dernière annulation, elle, émet session.cancelled. Chaque route, et ce qu'elle exige, est dans Conventions.