Dieses Dokument beschreibt die Schnittstelle zur Bedienung des Kartenlesers. Konkret ist diese Schnittstelle für folgende Generationen des Kartenlesers relevant:
Folgende Versionen werden derzeit unterstützt:
Anmerkung zur Versionierung: Version 1 entfiel mit dem Abbau der Vorgänger-Kartenlesergeneration (LAN-CCR).
Die Schnittstelle basiert auf REST/JSON und kann daher u.a. auf einfache Weise von JavaScript-Clients verwendet werden (z.B. auch von reinen Web-Oberflächen).
Die Schnittstellenspezifikation entspricht dem OpenAPI-Standard und wurde mit Tools aus der Swagger-Suite erstellt. In der von Swagger bereitgestellten HTML-Ansicht sind per Default weite Teile der Dokumentation eingeklappt und müssen per Mausklick aufgeklappt werden (siehe Hinweise zur Dokumentation).
Jede Version ist vollumfänglich in einer Schnittstellenspezifikation beschrieben.
Die Version dieser Schnittstelle wird einerseits im "version"-Attribut festgehalten und andererseits in der angesprochenen URL eingebettet.
Abwärtskompatible Ãnderungen an der Schnittstelle (wie z.B. die Erweiterung um neue Ressourcen) führen nicht zu einer Erhöhung der Schnittstellenversion. Alle anderen Ãnderungen werden ausschlieÃlich im Rahmen einer e-card-Release eingebracht und führen zu einer Erhöhung der Schnittstellenversion. Nach einer solchen Erhöhung wird die somit nicht mehr aktuelle Version jedenfalls ein Release lang weiter zur Verfügung gestellt und spätestens mit der nächsten Schnittstellenhebung eingestellt. Es werden daher maximal zwei Versionen parallel angeboten.
Ãnderungen an der Schnittstelle werden im Changelog der jeweiligen Version festgehalten.
Content-Type: application/json;charset=utf-8
Die Verwendung dieser Schnittstelle bedarf keiner vorherigen Authentifizierung. Für den Dialogaufbau per o-card ist die Eingabe der PIN erforderlich. Mit e-card oder o-card erstellte Signaturtoken können lediglich im Rahmen eines aufrechten Dialogs an das e-card System übertragen werden.
Fehler werden über ein entsprechendes JSON-Objekt zurückgemeldet, das einen eindeutigen, für automatisierte Verarbeitung geeigneten Fehlercode enthält. Da auf diese Weise bereits entsprechende Granularität gewährleistet wird, wird zwecks Vereinfachung in Fehlerfällen stets der HTTP-Statuscode 500 retourniert (unabhängig davon, wo die Fehlerquelle tatsächlich liegt). Bei allgemeinen Fehlern während der Request-Verarbeitung (wie z.B. bei Requests an nicht bekannte Ressourcen) kann ggf. ein konkreterer HTTP-Statuscode retourniert werden, was jedoch nicht garantiert wird.
Da jederzeit (auch ohne Schnittstellenhebung) neue Fehlercodes hinzukommen können, sollte der Aufrufer ein entsprechendes "Catch-All" für nicht explizit behandelte Fehlercodes implementieren.
Zusätzlich zum Fehlercode werden auch ein Detail-Fehlercode sowie ein Fehlertext retourniert, die dem Benutzer angezeigt werden sollten. Diese Anzeige ist in jenen Fällen nicht notwendig, in denen die Software automatisiert auf Fehlersituationen reagieren kann.
Für GINO Kartenleser beginnen die Detail-Fehlercodes mit dem Prefix "GN-".
Die Fehlercodes sind in den versionsspezifischen Schnittstellenbeschreibung aufgelistet.
Parallele Zugriffe sind gestattet, sollten jedoch zwecks Ressourcenschonung möglichst gering gehalten werden.
Beispiel für einen konkreten Anwendungsfall:
Sind mehrere Requests am Kartenleser anhängig, die alle auf dieselbe Statusänderung reagieren, so erfolgt die Verarbeitung der einzelnen Requests transparent voneinander.
Die Namen von Input-Parametern sind case-sensitive; es ist bei der Erstellung der Requests auf korrekte GroÃ-/Kleinschreibung zu achten.
Die Datei cardreader.js enthält JavaScript-Code, der aus dem Browser für die Kommunikation mit dem Kartenleser verwendet werden kann.
Browser unterbinden aus Sicherheitsgründen per default JavaScript-Requests, die an einen anderen Host als den Quell-Host des JavaScript-Codes gerichtet sind. Aus diesem Grund ist es beim Einsatz einer Browser-basierten Software notwendig, den Quell-Host des Software-Anbieters explizit am Kartenleser freischalten zu lassen, wodurch solche CORS-Requests ("Cross Origin Resource Sharing") ermöglicht werden. Nehmen Sie zu diesem Zweck bitte Kontakt mit dem SVC Partnersupport auf (support@svc.co.at), unter Angabe des freizuschaltenden Host-Namens. Dieser Host-Name wird vom Browser im HTTP-Header "Origin" an den Kartenleser gesendet.
Beispiel: Um in der Swagger-HTML-Ansicht eines Service die Beschreibung des Requests zur "status"-Ressource anzuzeigen, sind folgende Klicks notwendig:
Zum Ausklappen der Response-Beschreibung sind analoge Schritte notwendig.