REST-API für die Schulsoftware
Basis-URL: https://<server>/api · Format: JSON (UTF-8) · Authentifizierung per Header X-API-Key: kv_…
(Schlüssel erzeugt ein Administrator unter „Administration“). Alternativ Authorization: Bearer kv_….
Mandanten: Jeder API-Schlüssel gehört zu genau einem Mandanten und liefert/ändert ausschließlich dessen Daten. Schlüssel werden vom Administrator des jeweiligen Mandanten erzeugt. Fremde IDs (Kurse, Kunden anderer Mandanten) werden wie nicht vorhanden behandelt.
Kunden
| Methode | Pfad | Beschreibung |
|---|---|---|
| GET | /customers | Liste. Filter: q, status, funding, course_id, course_number, ba_number, measure_number, updated_since (ISO-Datum, für inkrementellen Abgleich), limit (max. 500), offset |
| GET | /customers/{id} | Einzelner Kunde inkl. Kursdaten |
| POST | /customers | Anlegen (Pflicht: last_name, first_name). Interne Nummer wird vergeben. |
| PUT | /customers/{id} | Teil-Update (nur übergebene Felder) |
Felder: last_name first_name gender street house_number zip city email phone salutation birth_date status ba_number rv_number measure_number course_id funding funding_note notes account_holder iban bic bank_name payment_interval
Zusätzlich in Antworten lesbar (nicht schreibbar): internal_email (Interne E-Mail).
status: interessent | bewerber | aktiv | beendet | ausgeschieden · funding: bildungsgutschein | selbstzahler | sonstiges | rentenversicherung ·
payment_interval: einmalig | monatlich | quartalsweise | halbjaehrlich | jaehrlich · gender: m | w | d oder Freitext.
Kurse
| GET | /courses | Alle Kurse mit Teilnehmerzahl (participants) und Fehlzeiten-Summen aller Teilnehmer in Tagen: absence_excused, absence_unexcused, absence_sick (Krankheit), absence_other, absence_total. Zählweise per day_mode=calendar|school (Standard Kalendertage) |
| GET | /courses/{id} | Einzelner Kurs (inkl. Fehlzeiten-Summen, day_mode wie oben) |
| GET | /courses/{id}/participants | Teilnehmerliste des Kurses (inkl. internal_email) |
| POST | /courses | Anlegen: course_number, name, measure_number (optional), start_date, end_date (JJJJ-MM-TT) |
| PUT | /courses/{id} | Teil-Update |
Fehlzeiten
Fehlzeiten gehören zu einem Kunden und müssen im Zeitraum des zugeordneten Kurses liegen; sie dürfen sich für einen Kunden nicht überschneiden (409).
Zählweise per Parameter day_mode=calendar (Standard, Kalendertage inkl. Start-/Endtag) oder day_mode=school (Unterrichtstage: Mo–Fr ohne gesetzliche Feiertage in Berlin und ohne in der Verwaltung eingetragene schulfreie Tage). Das Feld days folgt day_mode; calendar_days und school_days werden immer mitgeliefert. day_mode gilt für alle GET-Endpunkte unten (Liste, Summen, Einzelabruf).
| Methode | Pfad | Beschreibung |
|---|---|---|
| GET | /absences | Liste über alle Kunden. Filter: customer_id, ba_number, course_id, course_number, type, from/to (JJJJ-MM-TT, überlappende Fehlzeiten), updated_since (ISO-Datum, für inkrementellen Abgleich), limit (max. 1000), offset |
| GET | /absences/summary | Summen je Kunde: entschuldigt, unentschuldigt, krankheit, sonstiges, gesamt (Tage). Gleiche Filter; from/to schneiden die Tage auf den Zeitraum zu |
| GET | /absences/{id} | Einzelne Fehlzeit |
| GET | /customers/{id}/absences | Fehlzeiten eines Kunden |
| POST | /customers/{id}/absences | Anlegen: date_from (Pflicht), date_to (optional, Standard = date_from), type (entschuldigt | unentschuldigt | krankheit | sonstiges; Anzeige: (E) entschuldigt, (UE) unentschuldigt, (K) Krankheit, (S) Sonstiges), note |
| PUT | /absences/{id} | Ändern (alle Felder wie beim Anlegen übergeben) |
| DELETE | /absences/{id} | Löschen (Antwort 204) |
Beispiele
curl -H "X-API-Key: kv_..." "https://server/api/customers?course_number=K-2026-01&status=aktiv"
curl -X POST -H "X-API-Key: kv_..." -H "Content-Type: application/json" \
-d '{"last_name":"Muster","first_name":"Max","status":"bewerber","ba_number":"123A456789"}' \
https://server/api/customers
curl -X POST -H "X-API-Key: kv_..." -H "Content-Type: application/json" \
-d '{"date_from":"2026-11-09","date_to":"2026-11-10","type":"entschuldigt","note":"Krank"}' \
https://server/api/customers/42/absences
curl -H "X-API-Key: kv_..." "https://server/api/absences/summary?course_number=K-2026-01"
Antworten & Fehler
Listen: {"total":n,"limit":50,"offset":0,"items":[…]}. Fehler: {"error":"Text"} mit Status 400 (Validierung), 401 (Schlüssel fehlt/ungültig), 403 (nicht erlaubt, z. B. Löschen), 404, 409 (doppelte Kursnummer).
Welche Funktionen ein Schlüssel nutzen darf, legt der Administrator je Schlüssel fest (Rechte customers.view/edit, courses.view/edit, absences.view/edit; Antwort 403 ohne Recht). Kontodaten (IBAN, BIC, Bank, Kontoinhaber) sind über API-Schlüssel nie sichtbar und nicht änderbar. Ein Schlüssel darf nur Kunden, Kurse und Fehlzeiten lesen/anlegen/ändern, Fehlzeiten zusätzlich löschen – Kunden und Kurse nicht löschbar, keine Dokumente, Verträge, Reports oder Administration.