Vorarbeit: WebUntis-API

2026-08-24 12:14:36 +02:00
parent a30aab0fa5
commit 5841d96c5b
10 changed files with 1377 additions and 0 deletions
@@ -85,6 +85,54 @@ DWD-Ausfall liefert der Server den letzten erfolgreichen Stand. Für eine eigene
 `LehrerApp-Server/1.0 (+https://schule.example)`. Der Container benötigt ausgehenden HTTPS-Zugriff
 auf `nominatim.openstreetmap.org`, `www.dwd.de` und `opendata.dwd.de`.

+## WebUntis
+
+Die WebUntis-Zugangsdaten werden ausschließlich im API-Container konfiguriert und nie an den
+Desktop-Client ausgegeben:
+
+```dotenv
+WEBUNTIS_SCHOOL=meine-schule
+WEBUNTIS_HOST=meine-schule.webuntis.com
+WEBUNTIS_USER=technischer-benutzer
+WEBUNTIS_PASSWORD=geheimes-passwort
+WEBUNTIS_CLIENT=LehrerApp
+WEBUNTIS_SESSION_IDLE_MINUTES=10
+```
+
+`WEBUNTIS_HOST` kann entfallen, wenn der Host `<WEBUNTIS_SCHOOL>.webuntis.com` entspricht. Der
+technische Benutzer benötigt die jeweiligen WebUntis-Leserechte und darf für die alte JSON-RPC-
+Schnittstelle keine aktivierte Zwei-Faktor-Authentifizierung haben.
+
+Der API-Server meldet sich beim ersten Abruf an und verwendet diese Sitzung für weitere Abrufe.
+Erst wenn zehn Minuten lang kein WebUntis-Abruf mehr aktiv war, meldet er sich automatisch ab.
+`WEBUNTIS_SESSION_IDLE_MINUTES` kann bei Bedarf auf einen Wert zwischen 1 und 30 Minuten geändert
+werden.
+
+Alle Endpunkte benötigen dasselbe Bearer-Token wie die Sync-API und führen genau einen Abruf aus;
+sie speichern das Ergebnis nicht serverseitig:
+
+| Endpunkt | Zweck |
+| --- | --- |
+| `GET /api/webuntis/student-report?className=7a` | Schülerreport, optional nach Klasse gefiltert |
+| `GET /api/webuntis/schoolyears` | Schuljahre |
+| `GET /api/webuntis/classes?schoolyearId=123` | Klassen eines Schuljahres |
+| `GET /api/webuntis/teachers` | Lehrkräfte und WebUntis-IDs |
+| `GET /api/webuntis/holidays` | Ferienzeiträume |
+| `GET /api/webuntis/timegrid` | Stunden-/Zeitraster |
+| `GET /api/webuntis/substitutions?startDate=20260824&endDate=20260828` | Vertretungen im Zeitraum |
+| `GET /api/webuntis/timetable?elementType=teacher&elementId=42&startDate=20260824&endDate=20260828` | Stundenplan für Klasse, Lehrkraft, Fach, Raum oder Schüler |
+| `GET /api/webuntis/students/9001/absences?startDate=20260801&endDate=20270731` | Fehlzeiten eines Schülers; `9001` ist der `externKey` aus dem Schülerreport |
+| `GET /api/webuntis/students/17/class-register-entries?startDate=20260801&endDate=20270731` | Klassenbucheinträge eines Schülers; `17` ist dessen `untisId` |
+| `GET /api/webuntis/class-register/categories` | Kategorien der Klassenbucheinträge |
+| `GET /api/webuntis/class-register/category-groups` | Kategoriegruppen der Klassenbucheinträge |
+
+Datumsparameter verwenden das WebUntis-Format `yyyyMMdd`. Vertretungen sind auf 31 Tage und
+Stundenpläne auf 62 Tage pro Anfrage begrenzt, damit ein einzelner Client keine unkontrolliert
+großen WebUntis-Abfragen auslösen kann. Fehlzeiten und Klassenbucheinträge dürfen für einen
+kompletten Schuljahreszeitraum von bis zu 400 Tagen geladen werden. Diese Klassenbuchfunktionen
+sind nur verfügbar, wenn das Modul an der Schule aktiv ist und der technische Benutzer die
+benötigten Leserechte besitzt.
+
 ## Deployment über Dokploy

 Kein manuelles Bauen/Hochladen nötig – Dokploy zieht das Repo direkt per Git und baut das Image