Dieses Dokument beschreibt die Schnittstelle zur Bedienung des Kartenlesers (LAN-Chipcard-Reader, LanCCR). Konkret ist diese Schnittstelle für folgende Generationen des Kartenlesers relevant:
Folgende Versionen werden derzeit unterstützt:
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 entsprichen 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 (2x jährlich) eingebracht und führen zu einer Erhöhung der Schnittstellenversion um 1. Nach einer solchen Erhöhung wird die somit nicht mehr aktuelle Version jedenfalls eine 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 Signaturtokens können lediglich im Rahmen eines aufrechten Dialogs an das e-card-System übertragen werden und können somit dem entsprechenden Vertragspartner eindeutig zugeordnet 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 spezifischerer 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 LanCCRs beginnen die Detail-Fehlercodes mit dem Prefix "CA-", für Ginos mit dem Prefix "GN-"
Die Fehlercodes sind in den versionsspezifischen Spezifikationen aufgelistet.
Parallele Zugriffe sind gestattet, sollten jedoch zwecks Ressourcenschonung möglichst gering gehalten werden.
Beispiel für einen konkreten Anwendungsfall:
Sind mehrere Requests am LanCCR 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-sensitiv, es ist bei der Erstellung der Requests also auf korrekte GroÃ-/Kleinschreibung zu achten.
Die Datei cardreader.js enthält JavaScript-Code, der aus dem Browser heraus für die Kommunikation mit dem LanCCR-Adapter (bzw. zukünftig direkt mit dem GINO) 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 LanCCR-Adapter (bzw. GINO) 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 LanCCR-Adapter (bzw. GINO) gesendet.
Beispiel: Um in der Swagger-HTML-Ansicht eines Service die Beschreibung des Requests zur "status"-Ressource angezeigt zu bekommen, sind folgende Mausklicks notwendig:
Analoge Schritte sind zum Ausklappen der Response-Beschreibung notwendig.