L'API delle lezioni — recuperare le lezioni per qualsiasi data

L'API delle lezioni: GET /api/schedules/lessons/{datesrange} è l'endpoint tuttofare per recuperare le lezioni realmente datate dei Suoi orari — qualsiasi data o insieme di date, filtrato sulle entità volute, con o senza le strutture sottostanti, le assenze e le sostituzioni, gli orari o le semplici periodi di griglia. È il punto di partenza della maggior parte delle integrazioni.

Quando qualcosa fuori da Omniscol ha bisogno di sapere cosa succede, e quando, è questo l'endpoint da chiamare:

GET /api/schedules/lessons/{datesrange}

Restituisce le lezioni datate dei Suoi orari — ogni lezione posata sulla sua data reale — per le date e le entità richieste. Quasi ogni integrazione (un intranet, un ETL, uno strumento partner) parte da qui. Questa pagina percorre le leve che ne fanno un solo endpoint per numerosi usi.

Lezioni vs strutture

Due endpoint, due ruoli:

• GET /api/schedules/lessons/{datesrange} — le lezioni: ogni lezione posata su una data reale, con la sua materia, i suoi professori, la sua aula, il suo gruppo e la sua durata. È ciò che si legge per sapere chi è dove e quando.
• GET /api/schedules/ — le strutture: gli orari pubblicati stessi (classi, materie, sedi, la griglia). Da leggere quando si ha bisogno del modello sottostante piuttosto che delle lezioni datate.

Si possono anche ripiegare le strutture nella chiamata delle lezioni con with_timetables=true (vedi più sotto): una sola richiesta restituisce allora entrambe.

Scegliere le date

{datesrange} si scrive in YYYYMMDD e si vuole volutamente flessibile:

La forma sparsa (separata da virgole) è ciò che rende una domanda come «questi tre lunedì» una sola chiamata.

Mirare a ciò di cui ha bisogno

Un filter restringe la richiesta alle entità che contano — la stessa grammatica di filtro degli endpoint di disponibilità (Interrogazione avanzata):

• una semplice lista di identificativi — {"classes":["3a","3b"]},
• un jolly — {"teachers":"*"},
• una corrispondenza di campo semplice — {"classrooms":[{"site":"nord"}]},
• o un $where strutturato — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

Il risultato è raggruppato per tipo di filtro, poi per identificativo di entità — ad esempio schedules.classes.3a.courses[], schedules.teachers.j-doe.courses[].

Altri due regolaggi inquadrano l'estrazione, e un ultimo la limita:

• timetables_restrict / timetables_exclude — limitare o escludere degli identificativi di orario (stringa, CSV o array).
• limit — limitare il numero di lezioni restituite per filtro.

A cosa somiglia una lezione

Ogni voce di courses[] è una lezione posata:

{
  "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 è la data della lezione.
• position.period è l'indice della lezione sulla griglia dell'orario — presente per le lezioni posate sulla griglia. Una lezione fuori griglia (con i suoi propri start/end espliciti, fuori dagli slot regolari) porta start/end al suo posto, senza period.
• position.start / position.end (orari) accompagnano sempre una lezione fuori griglia, e si aggiungono alle lezioni di griglia quando passa with_hours=true (orari pre-calcolati). Da attivare quando il Suo sistema target ha bisogno delle ore d'orologio piuttosto che dell'indice di griglia.

Assenze, annullamenti e sostituzioni

Per impostazione predefinita, l'endpoint consolida le assenze: un professore assente è ritirato dalla lezione, e una lezione senza professore rimasto è considerata annullata e scartata. Diversi indicatori cambiano ciò:

• without_absences — ignorare completamente le assenze; restituire la griglia pianificata grezza.
• with_absences — aggiungere le assenze grezze del periodo accanto alle lezioni.
• with_cancelcourses — conservare le lezioni annullate (tutti gli professori assenti) invece di scartarle.
• with_studentcancelcourses — mantenere solo le lezioni annullate dall'assenza di un allievo.
• with_removedcourses — restituire le lezioni ritirate (esclusivo con with_cancelcourses).
• without_teacher_consolidation — mantenere i professori assenti nella lista teachers di ogni lezione invece di ritirarli.
• without_holidays — non iniettare le vacanze nell'intervallo.

Per impostazione predefinita, quando un sostituto è stato designato per un'assenza, esso sostituisce semplicemente il professore assente nella lista teachers della lezione — la sostituzione è trasparente, senza campo supplementare. Passi with_cancelcourses o without_teacher_consolidation e la lezione porta in più un blocco substitutes (l'identificativo del sostituto, il motivo di assenza e l'assenza che l'ha imposta), per vedere chi è stato sostituito e perché nello stesso payload.

Strutture e rubriche

Attacchi i dati di riferimento utili, nella stessa chiamata:

• with_timetables=true — le strutture grezze degli orari che sono servite a calcolare le lezioni (classi, materie, griglia, per identificativo). Da attivare per risolvere gli identificativi; da lasciare disattivato per una risposta compatta.
• with_entities=true — nome/codice leggero (e campi di nome di persona) delle entità del risultato.
• with_teachers / with_all_teachers — i professori utilizzati sulle lezioni, o tutti i professori dell'orario e della rubrica.
• with_students — gli allievi, con i loro posizionamenti per data.
• with_events=true — gli eventi fuori griglia (consigli, incontri genitori-professori…) sullo stesso intervallo.

Un tiraggio ETL notturno

Recuperare una settimana di lezioni per tutte le classi, con gli orari, e caricarla nel Suo sistema informativo:

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

La risposta raggruppa le lezioni sotto schedules.classes.<id>.courses[]. Le assenze sono già consolidate: ciò che carica riflette l'orario reale e aggiornato — aggiunga with_absences=true se vuole anche registrare la ragione di un cambiamento.

Spingere verso Omniscol

L'integrazione funziona anche nell'altro senso — per mantenere Omniscol allineato a una fonte di verità esterna. Questi endpoint esistono unicamente per questa sincronizzazione esterna; l'interfaccia Omniscol non li chiama mai da sé:

• POST /api/external/classes (os_external_classes_post) — aggiornare delle classi esistenti (nome, sede, livello, aula, effettivo) da un payload indicizzato per identificativo di classe. Aggiorna le classi conosciute; non ne crea di nuove. Metta un campo a null per cancellarlo (il nome della classe eccetto — una classe conserva il suo nome).
• POST /api/external/teachers (os_external_teachers_post) — inserire o aggiornare dei professori per identificativo, sia negli orari sia nella rubrica (creando l'utente con il ruolo professore e un login auto-generato all'occorrenza). Le varianti DELETE ritirano una classe o un professore.
• POST /api/admin/subjects/custom (os_admin_subjects-custom_post) — caricare un catalogo di materie personalizzate. Il corpo è { "subjects": [ … ], "replace": false, "nodoubles": true }: incrementale per impostazione predefinita, replace: true per un aggiornamento completo, nodoubles: true per riconciliare le materie esistenti per identificativo esterno, codice o nome. È l'endpoint di un push notturno di materie.

Esiste anche un endpoint speciale, solo sovrascrivibile, os_external_classes_get: Omniscol non ne fornisce alcuna implementazione predefinita, ma quando un partner o un fornitore lo punta verso il suo proprio servizio (via Personalizzazione dell'API), la schermata di creazione di classe si pre-compila da questa lista chiusa di classi invece che dal modulo manuale. Senza sovrascrittura, non fa semplicemente nulla.

Per un software gestionale SIS / ERP (Aurion, Auriga…), preferisca il connettore dedicato a questi endpoint grezzi — vedi Sincronizzazione con sistemi esterni.