Schnittstellenbeschreibung zur Anbindung des Schulverwaltungsprogramms an app.schuelerausweis.de
Minimierter Verwaltungsaufwand
✅ Einmalige Einrichtung – Danach läuft der Prozess automatisch ✅ Kein manueller Datenabgleich mehr nötig ✅ Automatische Aktualisierung der Schülerausweise täglich
Fehlerreduktion und Datensicherheit
✅ Fehlerminimierung durch direkte Übernahme aus dem Schulverwaltungsprogramm ✅ Kein Risiko veralteter oder falscher Schülerdaten ✅ Sichere Übertragung über SSH (bevorzugt FTP alternativ)
Automatische Deaktivierung abgegangener Schüler*innen
✅ Schüler*innen, die nicht mehr in der Datei sind, werden automatisch deaktiviert ✅ Keine veralteten oder ungültigen Ausweise im System ✅ Abgelaufene Ausweise können nicht reaktiviert werden, sodass sichergestellt ist, dass nur aktive Schüler*innen gültige Ausweise haben
1. Einleitung
Diese Schnittstellenbeschreibung definiert die Anforderungen und das technische Vorgehen zur Anbindung eines Schulverwaltungsprogramms an das System app.schuelerausweis.de. Ziel ist die automatisierte Bereitstellung einer CSV-Datei, die von unserem System täglich importiert wird.
2. Datenbereitstellung
-
Format: CSV (UTF-8 ohne BOM, Trennzeichen ist ; (Semikolon) und die Benutzung dieses Zeichens (Semikolon) ist von allen anderen Felder ausgeschlossen. )
-
Zeilenumbruch:
LF(Unix-Standard) -
Dateiname: Muss konstant bleiben (z. B.
schuelerdaten.csv) -
Ablageort: Definierter SFTP-/SSH-Server der Schule
-
Zugriff: Unser System benötigt Lesezugriff auf das Verzeichnis der Datei
-
Import-Zyklus: Einmal täglich wird die Datei automatisch vom Server abgerufen und in unser System importiert
3. Regeln für die Datenverarbeitung
-
Leere Datei = kein Abgleich: Falls die Datei leer ist oder keine gültigen Datensätze enthält, findet kein Abgleich statt.
-
Alle aktiven Schüler*innen müssen enthalten sein: Schüler*innen, die nicht mehr in der Datei aufgeführt sind, werden automatisch deaktiviert.
-
In Apple Wallet können abgelaufene Ausweise nicht reaktiviert werden: Die betroffene Person muss sich einen neuen Ausweis erstellen.
-
Keine Änderungen an der Datenstruktur nach Einrichtung: Die Reihenfolge der Spalten darf nicht verändert werden.
-
Konstanter Dateiname: Die Datei muss immer denselben Namen haben. Änderungen am Dateinamen führen dazu, dass sie nicht importiert wird.
- Hinweis zur Spalte „Barcode“: Wenn an Ihrer Schule keine Barcodes verwendet werden, kann die Spalte leer bleiben.
Wenn an Ihrer Schule Barcodes verwendet werden, aber einzelnen Schüler*innen noch kein Barcode zugewiesen wurde, wird stattdessen automatisch der QR Verify Code auf dem Schülerausweis angezeigt. Barcodes können jederzeit nachträglich im AdminTool ergänzt oder bei einem späteren Daten-Update mitgeliefert werden.
3. Struktur der CSV-Datei (Feldmapping)
Die CSV-Datei muss exakt folgende Reihenfolge und Felder enthalten:
| Spalte | Datentyp/Format | Pflichtfeld | Beschreibung / Hinweise |
|---|---|---|---|
| Schulname | Fester Wert: Wird von uns bereitgestellt | ✅ | Bitte immer den Schulnamen "Musterschule" eintragen |
| Klasse | Freitext | ✅ | Klassenbezeichnung |
| Vorname | Freitext | ✅ | Vorname der Schüler*innen |
| Nachname | Freitext | ✅ | Nachname der Schüler*innen |
| Geb.Datum | YYYY-MM-DD |
✅ | Geburtsdatum |
| Kundennummer | Leer lassen | ✅ | Diese Spalte muss vorhanden sein und muss leer bleiben |
| Gültigkeit | YYYY-MM-DD |
✅ | Ablaufdatum des Ausweises |
| Barcode | Alphanumerisch (A-Z, a-z, 0-9) |
❌ | Die entsprechende Spalte muss in der CSV-Datei zwingend vorhanden sein. Falls nicht verwendet, leer lassen |
| Valide E-Mail-Adresse | ❌ |
Die entsprechende Spalte muss in der CSV-Datei zwingend vorhanden sein. Falls nicht verwendet, leer lassen. Alternativ – wenn Sie mit QR-Login-Karten arbeiten, Ihre Schule aber wünscht, dass die Schüler*innen ausschließlich ihre schulischen E-Mail-Adressen verwenden (z. B. zur einheitlichen Nutzung), dann übermitteln Sie uns diese bitte im Rahmen der Datenlieferung. So wird verhindert, dass private oder abweichende E-Mail-Adressen verwendet werden. |
|
| StudentID | Alphanumerisch + Sonderzeichen (keine Umlaute) | ✅ | Eindeutige Identifikationsnummer (nur einmalig für einen Schüler vergeben) aus dem Schulverwaltungsprogramm. |
| Adresse | Freitext | ❌ | Die entsprechende Spalte muss in der CSV-Datei zwingend vorhanden sein. Falls nicht verwendet, leer lassen. Eine Zeile in der die Strasse Hausnummer PLZ und Ort aufgeführt ist (z.B. Musterstrasse 9, 40699 Erkrath). In dem Feld Adresse kein Semikolon verwenden sondern Komma. |
4. Muster der CSV-Datei
Damit der Import reibungslos funktioniert, stellen wir Ihnen eine Musterdatei zur Verfügung.
Wichtig:
Bitte übernehmen Sie die Spaltenüberschriften exakt wie in der Musterdatei dargestellt – auch wenn einzelne Spalten (z. B. Adresse oder Barcode) bei Ihnen nicht befüllt werden. Diese müssen dennoch in der Datei vorhanden sein, können aber leer bleiben.
5. Technische Anforderungen
-
Protokoll: SSH (bevorzugt) oder SFTP
-
Dateiablage: Die CSV-Datei muss täglich an einem definierten Ort auf dem Schulserver gespeichert werden
-
Zugriffsrechte: Unser Server benötigt Lesezugriff auf das Verzeichnis
-
Zeichencodierung: UTF-8 (ohne BOM)
6. Implementierungsschritte
-
Die Schule richtet in ihrem Schulverwaltungsprogramm einen täglichen CSV-Export ein.
-
Die Datei wird automatisiert auf dem Schulserver gespeichert.
-
Unser System ruft die Datei täglich per SSH (alt. FTP) ab und importiert die Daten automatisch.
-
Regelmäßige Kontrolle der übermittelten Daten durch die Schule wird empfohlen.
Fragen / Kontakt zu uns:
Falls Ihre Schule eine andere Übertragungsmethode benötigt oder Fragen zur Einrichtung hat, kontaktieren Sie uns gerne.