VKU/PGS Schnittstelle für Fremdsysteme

Transkript

1 VKU/PGS Schnittstelle für Fremdsysteme Schnittstellenbeschreibung Version 1.7 Autor Letzte Änderung Status Produktiv T F Fürst-Franz-Josef-Strasse 5 FL-9490 Vaduz info@kyberna.com

2 Dokumentenhistorie Version Datum Kommentar Grundversion «getcourse» hinzugefügt Mehr Informationen über den Kurs Zur Kursgruppe anmelden Löschen von Fahrlehrern und -schülern ID der Adresse anzeigen «getperson» hinzugefügt Überprüfung der Kursgruppen erweitert Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 2 von 29

3 Inhaltsverzeichnis 1 Einleitung Schnittstellenbeschreibung Allgemeines Umgebung Rückgabewerte Authentifizierung getversion getinstructors putinstructor deleteinstructor getpersons getperson putperson deleteperson getcoursegroups getcourse getcourseaddresses getcoursekinds putcoursegroup deletecoursegroup putpersoncourse putpersoncoursegroup deletepersoncourse putinstructorcourse putinstructorcoursegroup deleteinstructorcourse putconfirmation deleteconfirmation getconfirmation Codebeispiel in PHP GET PUT Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 3 von 29

4 1 Einleitung Die stellt für Drittanbieter eine Schnittstelle zu SARI VKU/PGS zur Verfügung. Die Schnittstelle steht als REST Web Service zur Verfügung. Am Ende dieses Dokumentes befindet sich noch zwei Code-Beispiele, die den der Schnittstelle in PHP demonstrieren. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 4 von 29

5 2 Schnittstellenbeschreibung 2.1 Allgemeines Umgebung Für SARI VKU/PGS gibt es eine Abnahme- und eine Produktionsumgebung. Zu Testzwecken soll die Abnahmeumgebung verwendet werden. In diesem Dokument muss bei den -URLs für die verschiedenen n der Platzhalter VKU_HOST_URL durch den korrekten Hostnamen der Umgebung ersetzt werden. Die URL für die Abnahmeumgebung lautet sari-vku-test.ky2help.com, die der Produktionsumgebung Der erfolgt in jedem Fall über HTTPS Rückgabewerte Die Schnittstelle liefert alle Ergebnisse als JSON-Objekt zurück. Das JSON-Objekt besteht aus zwei Einträgen: dem Ergebnis (result) und dem Status (status): "result": [], Im result-eintrag befinden sich die Daten, die aus dem System ausgelesen werden. Im status-eintrag steht jeweils eine Erfolgs- oder eine Fehlermeldung. Bei einer erfolgreichen Abfrage wird ein OK übergeben. Falls die Abfrage jedoch schiefläuft, wird eine entsprechende Fehlermeldung übergeben und der result-eintrag wird auf leer gesetzt. Die werden in den einzelnen n genauer beschrieben. Falls ein interner Serverfehler auftritt, lautet der status-eintrag INTERNAL_SERVER_ERROR. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 5 von 29

6 2.1.3 Authentifizierung Die nachfolgenden Schnittstellenmethoden können nur von authentifizierten Benutzern aufgerufen werden. Die Authentifizierung erfolgt mittels OAuth. Für den der einzelnen n muss ein Token im HTTP-Header beim übergeben werden. d&username=username&password=password client_id client_secret username passwort Identifikationsschlüssel für die Schnittstelle Passwort für die Schnittstelle Benutzername der Fahrschule Passwort des Benutzers Alle werden von der KYBERNA ausgestellt. GET "access_token": "ACCESS_TOKEN", "expires_in": 3600, "token_type": "bearer", "scope": "user", "refresh_token": "REFRESH_TOKEN" Beispielaufruf username&password=password Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 6 von 29

7 2.2 getversion Diese dient als Prüfung der Erreichbarkeit zwischen dem Client und dem Server. Zum Testen kann eine Zeichenkette übergeben, welche dann von der Schnittstelle zurückgeliefert werden soll. text Zeichenkette, die zurückgeliefert werden soll GET "result": "Hello_World", Beispielaufruf getinstructors Diese liefert alle Fahrlehrer der Fahrschule zurück. Das enthält nebst den Personendaten auch die Berechtigungen für die Bereiche, sowie den Status der Freigabe. GET "result": [ "faberid": " ", // Ausweisnummer "firstname": "Max", // Vorname "lastname": "Mustermann", // Nachname "birthdate": " ", // Geburtsdatum "sections": "vku": true, "pgs": false, "state": 0 // Bereiche // Freigabe-Status,... // weitere Fahrlehrer ], Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 7 von 29

8 2.4 putinstructor Mit dieser lässt sich ein Fahrlehrer zur Organisation hinzufügen. faberid birthdate Ausweisnummer des Fahrlehrers Geburtsdatum des Fahrlehrers Das Datum muss im Format JJJJ-MM-TT (Beispiel: ) übergeben werden. PUT INSTURCTOR_ALREADY_ADDED INSTRUCTOR_NOT_ENABLED MISMATCH_BIRTHDATE_FABERID Der Fahrlehrer wurde bereits zur Kursorganisation hinzugefügt. Der Fahrlehrer wurde noch nicht freigeschalten. Der Fahrlehrer wurde gefunden. Allerdings stimmt das übergebene Geburtsdatum nicht mit dem Geburtsdatum in den Personendaten überein. 2.5 deleteinstructor Mit dieser lässt sich ein Fahrlehrer aus der Organisation löschen. faberid Ausweisnummer des Fahrlehrers DELETE INSTRUCTOR_NOT_FOUND INSTRUCTOR_IN_COURSE Es wurde kein Fahrlehrer mit der übergebenen Ausweisnummer gefunden. Der Fahrlehrer befindet sich noch in Kursen. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 8 von 29

9 2.6 getpersons Diese liefert alle Fahrschüler der Fahrschule zurück. Bei dieser Abfrage muss der Bereich mitangegeben werden. Für den VKU-Bereich werden alle Fahrschüler angezeigt. Im PGS-Bereich sind nur Fahrschüler mit einer Kategorie A und/oder A1 ersichtlich. Die Schnittstelle liefert nebst den Personendaten zusätzlich die Kategoriedaten, sowie das Ablaufdatum mit. section Name des Bereiches: VKU oder PGS GET "result": [ "faberid": " ", // Ausweisnummer "firstname": "Max", // Vorname "lastname": "Mustermann", // Nachname "birthdate": " ", // Geburtsdatum "expirationdate": " ", // Ablaufdatum der aktuellen Kategorie "category": [ // Kategorien "A", "A1" ],... // weitere Fahrschüler ], SECTION_NOT_FOUND Bereich nicht gefunden Beispielaufruf Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 9 von 29

10 2.7 getperson Diese liefert die Informationen eines Fahrschülers zurück. Zu den Informationen gehören die Personendaten, Kursdaten sowie die Kategorien. faberid Ausweisnummer des Fahrschülers GET "result": "faberid": " ", "firstname": "Max", "lastname": "Mustermann", "birthdate": " ", "address": [ "address": "Bahnhofstrasse 1", "zip": 9470, "city": "Buchs SG" ], "courses": "VKU": [ "type": "VKU Teil 1", "date": " ", "completed": false, "courseexternalid": "1000", "coursegroupexternalid": "5000" ], "categories": [ "A", "A1" ], // FABER-ID // Vorname // Nachname // Geburtsdatum // Adresse der Person // Adresse // Postleitzahl // Ort // Kurse der Person // Kurse sind nach Bereich getrennt // Kursteil // Kursdatum // Kurs bestätigt (boolean oder Datum) // Externe ID des Kurses // Externe ID der Kursgruppe // Kategorien PERSON_NOT_FOUND Es wurde kein Fahrschüler mit der übergebenen Ausweisnummer gefunden werden. PERSON_NOT_IN_ORGANISATION Der Fahrschüler befindet sich nicht in dieser Organisation. Beispielaufruf Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 10 von 29

11 2.8 putperson Mit dieser lässt sich ein Fahrschüler zur Organisation hinzufügen. faberid birthdate Ausweisnummer des Fahrschülers Geburtsdatum des Fahrschülers Das Datum muss im Format JJJJ-MM-TT (Beispiel: ) übergeben werden. PUT PERSON_NOT_FOUND MISMATCH_BIRTHDATE_FABERID Es wurde kein Fahrschüler mit der übergebenen Ausweisnummer gefunden werden. Der Fahrschüler wurde gefunden. Allerdings stimmt das übergebene Geburtsdatum nicht mit dem Geburtsdatum in den Personendaten überein. 2.9 deleteperson Mit dieser lässt sich ein Fahrschüler aus der Organisation löschen. faberid Ausweisnummer des Fahrschülers DELETE PERSON_NOT_FOUND Es wurde kein Fahrschüler mit der übergebenen Ausweisnummer gefunden. PERSON_NOT_IN_ORGANISATION Der Fahrschüler befindet sich nicht in dieser Organisation. PERSON_ALREADY_CONFIRMED Der Fahrschüler hat bereits an Kursen teilgenommen. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 11 von 29

12 2.10 getcoursegroups Diese liefert alle Kursgruppen und die dazugehörenden Kurse der Fahrschule zurück. Bei dieser Abfrage muss der Bereich mitangegeben werden. Standardmässig werden nur Kursgruppen in der Zukunft zurückgeliefert. Falls man einen Überblick über alle Kursgruppen haben möchte, muss man die URL mit /all am Ende erweitern. section Name des Bereiches: VKU oder PGS GET "result": [ "name": "Kursgruppe", "externalid": "9000", "date": " :00", "courses": [ "externalid": 1, "name": "VKU Teil 1", "date": " :30", "level": "1", "enabled": true, "address": "id": 1, // Name der Kursgruppe // ID (Fremdsystem) der Kursgruppe // Datum der Kursgruppe // ID (Fremdsystem) des Teilkurses // Name des Teilkurses // Datum des Teilkurses // Kursteil // Kurs aktiviert // ID des Kursortes "name": "Bahnhofgeb\u00e4ude", // Name des Kursortes "address": "Bahnhofstrasse 1", // Adresse "zip": 9470, // Postleitzahl "city": "Buchs SG" // Ort, "freeplaces": 12 // Anzahl freier Plätze,... // weitere Kursteile ],... // weitere Kursgruppen ], SECTION_NOT_FOUND Bereich nicht gefunden Beispielaufruf Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 12 von 29

13 2.11 getcourse Diese liefert die Kursinformationen mit den zugewiesenen Teilnehmern und Fahrlehrern zurück. id ID (Fremdsystem) des Kurses GET "result": "name": "PGS Teil 1", // Name des Kurses "coursegroupexternalid": "9000", // ID (Fremdsystem) der Kursgruppe "date": " :00", // Datum des Kurses "enabled": true, // Kurs aktiviert "maxplaces": 5, // Anzahl freier Plätze "address": "id": 1, // ID des Kursortes "name": "Bahnhofgeb\u00e4ude", // Name des Kursortes "address": "Bahnhofstrasse 1", // Adresse "zip": 9470, // Postleitzahl "city": "Buchs SG" // Ort, "members": [ // Teilnehmer "faberid": " ", // Ausweisnummer "firstname": "Max", // Vorname "lastname": "Mustermann" // Nachname "confirmed": " " // Bestätigungsdatum, ansonsten leer "address": "address": "Hauptstrasse 1", // Adresse des Teilnehmers "zip": 9470, // Postleitzahl des Teilnehmers "city": "Buchs SG" // Ort des Teilnehmers,,... // weitere Teilnehmer ], "instructors": [ // Fahrlehrer "faberid": " ", // Ausweisnummer "firstname": "Max", // Vorname "lastname": "Mustermann" // Nachname,... // weitere Fahrlehrer ], COURSE_NOT_FOUND Kurs nicht gefunden Beispielaufruf Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 13 von 29

14 2.12 getcourseaddresses Diese liefert alle Kursorte der Fahrschule zurück. GET "result": [ "id": 1, "name": "Bahnhofgeb\u00e4ude", "address": "Bahnhofstrasse 1", "zip": 9470, // ID des Kursortes // Name des Kursortes // Adresse // Postleitzahl "city": "Buchs SG" // Ort,... // weitere Kursorte ], Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 14 von 29

15 2.13 getcoursekinds Diese liefert alle Kursarten der Fahrschule zurück. Die Kursarten werden nach dem Bereich getrennt. section Name des Bereiches: VKU oder PGS GET "result": [ "id": 1, "name": "Kurs Mo-Do", "coursekindtypes": [ "name": "Teil 1", "day": "1", // ID der Kursart // Name der Kursart // Name des Kursteils // Tag des Kursteils 1 (Mo), 7 (So) // Uhrzeit "time": "18:30",... // weitere Kursteile ],... // weitere Kursarten ], SECTION_NOT_FOUND Bereich nicht gefunden Beispielaufruf Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 15 von 29

16 2.14 putcoursegroup Mit dieser lässt sich eine Kursgruppe mit den dazugehörenden Kursen erstellen. Es müssen in jedem Fall vier Kursteile übermittelt werden. Zur Identifizierung muss ein Fremdschlüssel übergeben werden. Am Ende dieses Dokumentes befindet sich ein Beispiel der Implementierung dieser. externalid section name date address courses ID (Fremdsystem) der Kursgruppe Name des Bereiches: VKU oder PGS Name der Kursgruppe Datum der Kursgruppe Das Datum muss im Format JJJJ-MM-TT hh:mm (Beispiel: :00) übergeben werden. ID des Kursortes Im Array-Eintrag muss der Kursteil definiert werden. Es gibt für den VKU- Bereich folgende Teile: 1, 2, 3 und 4. Für den PGS-Bereich gibt es die Kursteile 1, 2, 2a und 3. [ "externalid": "course_1", // ID (Fremdsystem) des Kurses "part": 1, // Kursteil "enabled": 1, // Aktivierungs-Status "address": 1, // ID des Kursortes "date": " :00" // Datum und Uhrzeit,... // weitere Kursteile ] PUT SECTION_NOT_FOUND NOT_ENOUGH_COURSES ADDRESS_NOT_FOUND COURSEKIND_NOT_FOUND COURSETYPE_NOT_FOUND COURSE_SAME_DATE EXTERNALID_EXISTS Bereich nicht gefunden Es wurden nicht vier Kurse übergeben. Die Adresse mit der übergebenen ID wurde nicht gefunden. Die Kursart mit der übergebenen ID wurde nicht gefunden. Der Kurstyp wurde nicht gefunden. Die Kurse finden am gleichen Datum statt. Die ID des Fremdsystems ist bereits vergeben. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 16 von 29

17 Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 17 von 29

18 2.15 deletecoursegroup Mit dieser lässt sich eine Kursgruppe inklusive den dazugehörenden Kursen löschen. Das Löschen der Kursgruppe funktioniert nur, falls keine Fahrlehrer oder Fahrschüler im Kurs eingeschrieben sind. externalid ID (Fremdsystem) der Kursgruppe DELETE "result": [], COURSEGROUP_NOT_FOUND NO_PERMISSION PERSON_INSTRUCTOR_IN_COURSE Die Kursgruppe mit der übergebenen ID wurde nicht gefunden. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Die Kursgruppe kann nicht gelöscht werden, da Teilnehmer und/oder Fahrlehrer in diesem Kurs eingeschrieben sind. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 18 von 29

19 2.16 putpersoncourse Mit dieser kann man ein Fahrschüler zu einem Kurs hinzufügen. Die Schnittstelle prüft davor, ob alle Bedingungen für die Kursteilnahme erfüllt sind. Zur Verifizierung des Fahrschülers muss in dieser noch das Geburtsdatum übergeben werden. externalid faberid birthdate ID (Fremdsystem) des Kurses Ausweisnummer des Fahrschülers Geburtsdatum des Fahrschülers Das Datum muss im Format JJJJ-MM-TT (Beispiel: ) übergeben werden. PUT "result": [], PERSON_NOT_FOUND MISMATCH_BIRTHDATE_FABERID COURSE_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION PERSON_ALREADY_ADDED COURSE_TOOMUCH_MEMBERS COURSE_NOT_SAME_DATE COURSE_PERSON_DEADLINE_VIOLATED Diese Meldung erscheint, falls kein Fahrschüler zu der übergegebenen Ausweisnummer gefunden wurde oder der Fahrschüler keinen Lernfahrausweis verfügt und somit den Kurs nicht besuchen kann. Der Fahrschüler wurde gefunden. Allerdings stimmt das übergebene Geburtsdatum nicht mit dem Geburtsdatum in den Personendaten überein. Der Kurs mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrschüler wurde bereits zu diesem Kurs zugewiesen. Der Kurs ist ausgebucht. Der Fahrschüler nimmt zum gleichen Zeitpunkt bereits an einem anderen Kurs teil. Der Fahrschüler hat zum Zeitpunkt des Kurses keinen gültigen Ausweis. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 19 von 29

20 2.17 putpersoncoursegroup Mit dieser kann man ein Fahrschüler zu einer Kursgruppe hinzufügen. Die Schnittstelle prüft davor, ob alle Bedingungen für die Kursteilnahme erfüllt sind. Falls die Überprüfungen bei einer Kurszuweisung fehlschlagen, wird der Fahrschüler zu keinem Kurs zugewiesen. Zur Verifizierung des Fahrschülers muss in dieser noch das Geburtsdatum übergeben werden. externalid faberid birthdate ID (Fremdsystem) der Kursgruppe Ausweisnummer des Fahrschülers Geburtsdatum des Fahrschülers Das Datum muss im Format JJJJ-MM-TT (Beispiel: ) übergeben werden. PUT "result": [], PERSON_NOT_FOUND MISMATCH_BIRTHDATE_FABERID COURSEGROUP_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION PERSON_ALREADY_ADDED COURSE_TOOMUCH_MEMBERS COURSE_NOT_SAME_DATE COURSE_PERSON_DEADLINE_VIOLATED Diese Meldung erscheint, falls kein Fahrschüler zu der übergegebenen Ausweisnummer gefunden wurde oder der Fahrschüler keinen Lernfahrausweis verfügt und somit den Kurs nicht besuchen kann. Der Fahrschüler wurde gefunden. Allerdings stimmt das übergebene Geburtsdatum nicht mit dem Geburtsdatum in den Personendaten überein. Die Kursgruppe mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrschüler wurde bereits zu diesem Kurs zugewiesen. Der Kurs ist ausgebucht. Der Fahrschüler nimmt zum gleichen Zeitpunkt bereits an einem anderen Kurs teil. Der Fahrschüler hat zum Zeitpunkt des Kurses keinen gültigen Ausweis. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 20 von 29

21 2.18 deletepersoncourse Mit dieser lässt sich ein Fahrschüler aus einem Kurs löschen. Das Löschen funktioniert nur, sofern der Fahrschüler noch nicht bestätigt wurde. externalid faberid ID (Fremdsystem) des Kurses Ausweisnummer des Fahrschülers DELETE "result": [], Fehlermeldung PERSON_NOT_FOUND COURSE_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION COURSEMEMBER_NOT_FOUND Diese Meldung erscheint, falls kein Fahrschüler zu der übergegebenen Ausweisnummer gefunden wird. Der Kurs mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrschüler ist nicht in diesem Kurs eingeschrieben. COURSEMEMBER_ALREADY_CONFIRMED Der Fahrschüler hat bereits eine Bestätigung dieses Kurses. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 21 von 29

22 2.19 putinstructorcourse Mit dieser lässt sich ein Fahrlehrer zu einem Kurs zuweisen. Zur Verifizierung des Fahrlehrers muss in dieser noch das Geburtsdatum übergeben werden. externalid faberid birthdate ID (Fremdsystem) des Kurses Ausweisnummer des Fahrlehrers Geburtsdatum des Fahrlehrers Das Datum muss im Format JJJJ-MM-TT (Beispiel: ) übergeben werden. PUT "result": [], PERSON_NOT_FOUND MISMATCH_BIRTHDATE_FABERID COURSE_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION INSTRUCTOR_ALREADY_ADDED INSTRUCTOR_NOTVALID ALREADY_BOOKED ALREADY_STARTED Diese Meldung erscheint, falls kein Fahrlehrer zu der übergegebenen Ausweisnummer gefunden wurde. Der Fahrlehrer wurde gefunden, allerdings stimmt das übergebene Geburtsdatum nicht mit dem Geburtsdatum in den Personendaten überein. Der Kurs mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrlehrer wurde bereits zu diesem Kurs zugewiesen. Der Fahrlehrer hat zum Zeitpunkt des Kurses keine Erlaubnis. Der Fahrlehrer befindet sich zum Zeitpunkt des Kurses bereits in einem Kurs. Der Kurs hat bereits stattgefunden. INSTRUCTOR_NOSECTIONPERMISSION Der Fahrlehrer hat keine Berechtigung für den Bereich. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 22 von 29

23 2.20 putinstructorcoursegroup Mit dieser lässt sich ein Fahrlehrer zu einer Kursgruppe zuweisen. Falls die Überprüfungen bei einer Kurszuweisung fehlschlagen, wird der Fahrlehrer zu keinem Kurs zugewiesen. Zur Verifizierung des Fahrlehrers muss in dieser noch das Geburtsdatum übergeben werden. externalid faberid birthdate ID (Fremdsystem) der Kursgruppe Ausweisnummer des Fahrlehrers Geburtsdatum des Fahrlehrers Das Datum muss im Format JJJJ-MM-TT (Beispiel: ) übergeben werden. PUT "result": [], PERSON_NOT_FOUND MISMATCH_BIRTHDATE_FABERID COURSEGROUP_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION INSTRUCTOR_ALREADY_ADDED INSTRUCTOR_NOTVALID ALREADY_BOOKED ALREADY_STARTED Diese Meldung erscheint, falls kein Fahrlehrer zu der übergegebenen Ausweisnummer gefunden wurde. Der Fahrlehrer wurde gefunden, allerdings stimmt das übergebene Geburtsdatum nicht mit dem Geburtsdatum in den Personendaten überein. Die Kursgruppe mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrlehrer wurde bereits zu diesem Kurs zugewiesen. Der Fahrlehrer hat zum Zeitpunkt des Kurses keine Erlaubnis. Der Fahrlehrer befindet sich zum Zeitpunkt des Kurses bereits in einem Kurs. Der Kurs hat bereits stattgefunden. INSTRUCTOR_NOSECTIONPERMISSION Der Fahrlehrer hat keine Berechtigung für den Bereich. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 23 von 29

24 2.21 deleteinstructorcourse Mit dieser lässt sich ein Fahrlehrer aus einem Kurs löschen. Das Löschen funktioniert nur, sofern der Kurs noch nicht durchgeführt wurde. externalid faberid ID (Fremdsystem) des Kurses Ausweisnummer des Fahrlehrers DELETE "result": [], Fehlermeldung PERSON_NOT_FOUND COURSE_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION COURSEINSTRUCTOR_NOT_FOUND COURSE_ALREADY_DONE Diese Meldung erscheint, falls kein Fahrlehrer zu der übergegebenen Ausweisnummer gefunden wurde. Der Kurs mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrlehrer ist nicht in diesem Kurs eingeschrieben. Der Kurs hat bereits stattgefunden. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 24 von 29

25 2.22 putconfirmation Mit dieser kann man die Kursteilnahme eines Fahrschülers bestätigen. externalid faberid ID (Fremdsystem) des Kurses Ausweisnummer des Fahrschülers PUT "result": [], Fehlermeldung PERSON_NOT_FOUND COURSE_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION COURSEMEMBER_NOT_FOUND Diese Meldung erscheint, falls kein Fahrschüler zu der übergegebenen Ausweisnummer gefunden wird. Der Kurs mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrschüler ist nicht in diesem Kurs eingeschrieben. COURSEMEMBER_ALREADY_CONFIRMED Der Fahrschüler wurde bereits bestätigt. CONFIRMATION_FAILED Der Fahrschüler konnte nicht bestätigt werden. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 25 von 29

26 2.23 deleteconfirmation Mit dieser kann man die Kursbestätigung eines Fahrschülers löschen. externalid faberid ID (Fremdsystem) des Kurses Ausweisnummer des Fahrschülers DELETE "result": [], Fehlermeldung PERSON_NOT_FOUND COURSE_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION COURSEMEMBER_NOT_FOUND COURSEMEMBER_NOT_CONFIRMED UNDO_CONFIRMATION_FAILED Diese Meldung erscheint, falls kein Fahrschüler zu der übergegebenen Ausweisnummer gefunden wird. Der Kurs mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrschüler ist nicht in diesem Kurs eingeschrieben. Der Fahrschüler wurde nicht bestätigt. Die Bestätigung konnte nicht zurückgezogen werden, da die Frist abgelaufen ist. Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 26 von 29

27 2.24 getconfirmation Diese liefert das PDF der Kursbestätigung eines Fahrschülers als Base64-Zeichenkette zurück. externalid faberid ID (Fremdsystem) des Kurses Ausweisnummer des Fahrschülers DELETE "result": "BASE64-ZEICHENKETTE", Fehlermeldung PERSON_NOT_FOUND COURSE_NOT_FOUND COURSE_NOT_ALLOWED_OR_ENABLED NO_PERMISSION COURSEMEMBER_NOT_FOUND COURSEMEMBER_NOT_CONFIRMED Diese Meldung erscheint, falls kein Fahrschüler zu der übergegebenen Ausweisnummer gefunden wird. Der Kurs mit der übergebenen ID wurde nicht gefunden. Der Kurs ist nicht freigegeben oder aktiviert. Der Schnittstellenbenutzer hat keine Berechtigung für diese Fahrschule. Der Fahrschüler ist nicht in diesem Kurs eingeschrieben. Der Fahrschüler wurde noch nicht bestätigt. Beispielaufruf Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 27 von 29

28 3 Codebeispiel in PHP In den nachfolgenden Abschnitten werden Beispiele gezeigt, wie man die Schnittstelle über PHP aufrufen kann. Dabei wird jeweils ein der GET- und der PUT- gezeigt. Die Platzhalter VKU_HOST_URL, CLIENT_ID, CLIENT_SECRET, USERNAME, PASSWORD müssen mit den richtigen Daten ersetzt werden, damit die Beispiele funktionieren. 3.1 GET- <?php $curlaccesstoken = curl_init(); curl_setopt($curlaccesstoken, CURLOPT_RETURNTRANSFER, true); curl_setopt($curlaccesstoken, CURLOPT_FOLLOWLOCATION, true); curl_setopt($curlaccesstoken, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curlaccesstoken, CURLOPT_URL, ' pe=password&username=username&password=password'); $tokenpage = json_decode(curl_exec($curlaccesstoken)); curl_close($curlaccesstoken); if (empty($tokenpage->access_token)) exit('fehler: Token-Generierung fehlgeschlagen'); $curlapirequest = curl_init(); curl_setopt($curlapirequest, CURLOPT_RETURNTRANSFER, true); curl_setopt($curlapirequest, CURLOPT_FOLLOWLOCATION, true); curl_setopt($curlapirequest, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curlapirequest, CURLOPT_HTTPHEADER, ['Authorization: Bearer '. $tokenpage- >access_token]); curl_setopt($curlapirequest, CURLOPT_URL, ' $instructors = json_decode(curl_exec($curlapirequest)); curl_close($curlapirequest); print_r($instructors); Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 28 von 29

29 3.2 PUT- <?php $curlaccesstoken = curl_init(); curl_setopt($curlaccesstoken, CURLOPT_RETURNTRANSFER, true); curl_setopt($curlaccesstoken, CURLOPT_FOLLOWLOCATION, true); curl_setopt($curlaccesstoken, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curlaccesstoken, CURLOPT_URL, ' username=username&password=password'); $tokenpage = json_decode(curl_exec($curlaccesstoken)); curl_close($curlaccesstoken); if (empty($tokenpage->access_token)) exit('fehler: Token-Generierung fehlgeschlagen'); $curlapirequest = curl_init(); curl_setopt($curlapirequest, CURLOPT_RETURNTRANSFER, true); curl_setopt($curlapirequest, CURLOPT_FOLLOWLOCATION, true); curl_setopt($curlapirequest, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curlapirequest, CURLOPT_HTTPHEADER, ['Authorization: Bearer '. $tokenpage->access_token]); curl_setopt($curlapirequest, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($curlapirequest, CURLOPT_POSTFIELDS, http_build_query([ 'externalid' => 'cg_1', 'section' => 'VKU', 'name' => 'Kursgruppe', 'date' => ' :00', 'address' => 1, 'courses' => [ [ 'externalid' => 'course_1', 'part' => 1, 'enabled' => 1, 'address' => 1, 'date' => ' :00' ], [ 'externalid' => 'course_2', 'part' => 2, 'enabled' => 1, 'address' => 1, 'date' => ' :00' ], [ 'externalid' => 'course_3', 'part' => 3, 'enabled' => 1, 'address' => 1, 'date' => ' :00' ], [ 'externalid' => 'course_4', 'part' => 4, 'enabled' => 1, 'address' => 1, 'date' => ' :00' ] ] ])); curl_setopt($curlapirequest, CURLOPT_URL, ' $result = json_decode(curl_exec($curlapirequest)); curl_close($curlapirequest); print_r($result); Schnittstelle zu SARI VKU/PGS für Fremdsysteme Version 1.7 / Seite 29 von 29