Kartenleser

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).

Inhalt

Versionierung

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

Alle Requests, die Daten im JSON-Format transportieren, müssen folgenden HTTP-Header besitzen:
Content-Type: application/json

Authentifizierung

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.

Fehlerbehandlung

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

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.

Slots

Folgende Slots stehen für den Zugriff zur Verfügung. Wobei der LanCCR nur den kontaktbehafteten Zugriff unterstützt und für den GINO der Satellit optional ist.
Es wird aber nur eine Karte unterstützt, sind mehrere Karten in den abgefragten Slots vorhanden, wird mit einem Fehler abgebrochen.

Case-Sensitivity

Die Namen von Input-Parametern sind case-sensitiv, es ist bei der Erstellung der Requests also auf korrekte Groß-/Kleinschreibung zu achten.

Anbindung via JavaScript

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.

Hinweise zur Dokumentation

Beispiel: Um in der Swagger-HTML-Ansicht eines Service die Beschreibung des Requests zur "status"-Ressource angezeigt zu bekommen, sind folgende Mausklicks notwendig:

  1. Klick auf die Ressource "POST /status"
  2. dadurch wird u.a. der Bereich "Request Body" aufgeklappt: dort Klick auf das Tab "Model" (neben "Example Value")
  3. Teile dieser so aufgeklappten Parameterbeschreibung sind weiterhin eingeklappt (erkennbar an einem dezenten Pfeil ">") und können durch Mausklick auf diese Pfeile ausgeklappt werden

Analoge Schritte sind zum Ausklappen der Response-Beschreibung notwendig.