Die Endpunkte von score-api, Anmeldung, Fehlercodes und Request-IDs.
score-api spricht JSON über HTTP. score-web nutzt dieselbe API serverseitig; für Fremdsysteme
ist eine eigene Route mit Token statt Cookie vorgesehen. Alles unter /v1/ verlangt eine
Sitzung, und jede Antwort enthält nur, was die Row-Level Security für die angemeldete Person
freigibt.
Betrieb
Methode
Pfad
Zweck
GET
/healthz
Prozess läuft
GET
/readyz
Prozess läuft und erreicht PostgreSQL
Anmeldung
Methode
Pfad
Zweck
GET
/auth/login?return_to=…&idp=…
Anmeldung starten; idp wählt den Identitätsanbieter vor
Zeugnisse der Klasse als Entwurf anlegen; art ist halbjahr (Standard), jahr, abitur oder abschluss
POST
/v1/klassen/{klasse}/sammeldruck
Druckauftrag für alle freigegebenen Zeugnisse der Klasse
GET
/v1/zeugnisse/{zeugnis}
ein Zeugnis mit Angaben, Noten und Status
PATCH
/v1/zeugnisse/{zeugnis}
Angaben ändern: Fehltage, davon unentschuldigt, Bemerkungen, Zeugnisdatum
POST
/v1/zeugnisse/{zeugnis}/versetzung
Versetzungsbeschluss; Abweichung vom Vorschlag der Regel-Engine nur mit Grund
POST
/v1/zeugnisse/{zeugnis}/status
Statuswechsel: Entwurf, in Prüfung, freigegeben, gedruckt, archiviert
POST
/v1/zeugnisse/{zeugnis}/korrektur
neue Fassung als Entwurf, mit Grund; die alte gilt als ersetzt
GET
/v1/zeugnisse/{zeugnis}/pdf
PDF; offene Zeugnisse als Vorschau mit Vermerk „Entwurf“
POST
/v1/zeugnisse/{zeugnis}/kenntnisnahme
Kenntnisnahme durch den Ausbildungsbetrieb eintragen (Berufsschule)
GET
/v1/jobs/{job}
Fortschritt eines Hintergrundauftrags wie des Sammeldrucks
Anlegen und bearbeiten dürfen Klassenleitung und Schulleitung, freigeben nur die Schulleitung.
Bei der Freigabe schreibt score den Datenstand, den Hash der Vorlage und den Hash der
Regelpakete fest; danach sind Inhalt und PDF unveränderlich. Lesen und PDF-Abruf werden
protokolliert.
Abitur
Methode
Pfad
Zweck
GET
/v1/klassen/{klasse}/abitur
Abiturakten der Tutorengruppe mit Status
POST
/v1/klassen/{klasse}/abitur
Akten für die Schüler der Gruppe anlegen
GET
/v1/abitur/{abitur}
eine Akte mit Studienbuch, Einbringung, Prüfungen und Ergebnis; bei jedem Lesen neu berechnet
PUT
/v1/abitur/{abitur}/wahl
Prüfungsfächer und Einbringung wählen; leer heißt Vorschlag der Regel-Engine
Vorbereiten dürfen Tutorin oder Tutor, zulassen, Prüfungsnoten erfassen und abschließen nur die
Schulleitung. Zulassen verlangt erfüllte Voraussetzungen, Abschließen alle Prüfungsnoten; nach
der Zulassung ist die Wahl festgeschrieben.
Berufsschulabschluss
Methode
Pfad
Zweck
GET
/v1/klassen/{klasse}/berufsabschluss
Abschlüsse der Klasse mit Status
POST
/v1/klassen/{klasse}/berufsabschluss
Abschlüsse für die Schüler der Klasse anlegen
GET
/v1/berufsabschluss/{berufsabschluss}
Jahresnoten, Vorschläge der Endnoten, Ausgleich, Abschlussnote, Prädikat, Vermerke
PUT
/v1/berufsabschluss/{berufsabschluss}
Endnoten (Abweichung vom Vorschlag mit Grund), Nachweise zu Kammerprüfung und Fremdsprache
POST
/v1/berufsabschluss/{berufsabschluss}/status
Beschluss der Klassenkonferenz eintragen; aufheben nur die Schulleitung
Rückmeldung, Reporting, Aufbewahrung
Methode
Pfad
Zweck
GET
/v1/einrichtungen/{kennung}/rueckmeldungen
Rückmeldungen an die Schulverwaltung mit Zustellstand
POST
/v1/rueckmeldungen/{rueckmeldung}/erneut
eine aufgegebene Rückmeldung erneut senden
GET
/v1/einrichtungen/{kennung}/reporting[?zeitraum=]
aggregierte Auswertung ohne Personenbezug
GET
/v1/einrichtungen/{kennung}/aufbewahrung
Bestand je Datenart mit Frist und Fälligkeit, Archivangebote, Löschnachweise; auch für Datenschutz/Revision
Rückmeldungen und Reporting stehen Schulleitung und Schuladmin zur Verfügung. Format und Verhalten beschreibt
Rückmeldung, Reporting, Export.
Fehler
Status
Bedeutung
401
keine gültige Sitzung
403
die Datenbank verweigert das Schreiben (fehlendes Recht, SQLSTATE 42501)
404
nicht vorhanden oder für die angemeldete Person nicht sichtbar
409
Notenschluss erreicht, Kurs gesperrt (SQLSTATE SC001); Zeugnis-Regel verletzt, etwa ein unerlaubter Statuswechsel oder eine Änderung nach der Freigabe (SQLSTATE SC003); Regel für Abitur (SC004) oder Berufsschulabschluss (SC005) verletzt; Bildungsgang der Klasse regelt kein Abitur bzw. keinen Berufsschulabschluss
422
Eingabe ungültig, etwa eine Note außerhalb der Notenskala des Pakets
Request-ID
Jede Anfrage bekommt eine Request-ID: aus dem Header X-Request-Id, wenn vorhanden, sonst neu
erzeugt. Sie steht im JSON-Log jeder Anfrage und in jedem Audit-Ereignis, das die Anfrage
auslöst.