In den Beschreibungen der JavaDoc werden, um die Verständlichkeit und die Lesbarkeit zu erleichtern, im Text jeweils die männlichen Formulierungen (Patient, Arzt, ...) verwendet.
Die Formulierungen gelten gleichermaßen für alle Personen.
Einsatz der Vertragspartnersoftware:
Überblick über die Komponenten für die Vertragspartnersoftware
Die Abfrage der URLs zu den einzelnen Services erfolgt mittels des Servicemanagers.
Für die Abfrage der Services ist der Servicemanager unter folgender URL abrufbar:
- PROD-Instanz (Produktivumgebung):
- https://services.ecard.sozialversicherung.at/servicemanager/1
- VPSWH (Vertragspartnersoftware-Hersteller-Umgebung):
- https://services-a.ecard-test.sozialversicherung.at/servicemanager/1
Hinweis: Zusätzlich zu den verfügbaren SOAP-Services werden auch Informationen über die verfügbaren REST-Services retourniert.
Zu Beginn empfehlen wir die Implementierung folgender Services:
- REST-Service
- CRS
- Kartenleser (GINO)
- SOAP-Service
- BASE
- AUTH
- FDAS
Funktionalität zur Abfrage der verfügbaren angeschlossenen Kartenlesegeräte GINO.
Die Schnittstelle dient u.a. zum Auslesen von Kartendaten, dem Erstellen von Signaturtoken (cardToken) und der Kartenleserüberwachung.
Der Lesezugriff wird durch das REST-Service GINO ausgelöst: Swagger Doku Kartenleser.
Funktionalität für das Message-, Vertrags- und Berechtigungshandling und die Ordinationsübersiedlung.
Funktionalität um einen Dialog aufzubauen und zu beenden.
Abfrage-Funktionalität für dynamische Werte aus dem Regelwerk.
Anzeigetexte aus Regelwerksabfragen (z.B. Behandlungsfälle (KSE), Rückdatierungsgründe (eAUM),... ) sind unverändert anzuzeigen.
Es wird zwecks Vereinheitlichung und leichterer Bedienbarkeit empfohlen, dieselben Begriffe in der VPSW zu verwenden.
Folgende Funktionalitäten sind durch die VPSW selbst mittels der angebotenen REST-Schnittstelle zu verwalten:
- Karten-Handling (Lesen, Setzen/Ãndern von PIN/PUK)
- Kartenleserüberwachung
Voraussetzungen für die Vertragspartnersoftware:
Die Vertragspartnersoftware muss einen SOAP-Client verwenden, der mittels HTTPS-Protokoll auf einer definierten URL synchrone Funktionsaufrufe im SOAP-Format durchführt.
Die zu verwendende URL wird vom Servicemanager zurückgeliefert.
Das Ergebnis wird über eine HTTPS-Response zurückgeliefert.
Die Verarbeitung eingehender Requests mit dem selben Dialog erfolgt im e-card-System serialisiert.
D.h. der Request wird verarbeitet und eine entsprechende Response retourniert. Erst nach Retournierung der Response erfolgt die Verarbeitung eines weiteren Requests. Wird ein Request vor Erhalt der Response des vorangegangenen Requests geschickt, muss dieser warten bis der vorherige Funktionsaufruf vollständig abgearbeitet und eine entsprechende Response geliefert wurde. Bei vielen parallelen Requests mit dem selben Dialog (bzw. mit der selben DialogID) besteht daher die Gefahr von langen Wartezeiten bzw. von Timeouts.
Zusätzlich besteht seitens e-card Systems die Möglichkeit die Anzahl gleichzeitiger Requests von einem Vertragspartner zu begrenzen, wenn festgestellt wird, dass zu viele Requests auf einmal übermittelt werden. In diesem Fall wird die Fehlermeldung ZS-10041 (Fehlerkonstante ServiceException.INTERNAL_ERROR) retourniert.
Als SOAP-Programmiermodell wird RPC verwendet. Die SOAP-Nachrichten werden im Format Document/Literal (wrapped) übertragen. Asynchrone Benachrichtigungen vom Ordinationsclient zur Vertragspartnersoftware werden nicht unterstützt.
In den WSDL-Files werden eigens definierte Datentypen verwendet (Complex Types), die sich aus einfachen Datentypen (Integer, String, ...) zusammensetzen. Diese Datentypen können als Rückgabewerte der aufgerufenen Funktionen, als Parameter bzw. in Form von Fehlermeldungen (Exceptions) auftreten.
Abhängig vom verwendeten SOAP-Toolkit kann ein so genanntes Type-Mapping notwendig sein. Dazu müssen die WSDL-Datentypen mit den entsprechenden Implementierungsklassen der Zielsprache verknüpft werden.
Request-Timeouts:
Es empfiehlt sich, Funktionsaufrufe in der VPSW mittels Timeout-Steuerung zu überwachen. Die angebotenen Funktionen werden bezüglich ihrer Laufzeit in drei Gruppen unterteilt:
|
|
|
|
|
|
|
|
In der nachfolgenden Tabelle sind die empfohlenen Timeout-Werte je Laufzeitgruppe beschrieben.
| Laufzeitgruppe | EmpfohlerTimeout-Wert |
|---|---|
|
|
|
|
|
|
In der technischen Schnittstellenbeschreibung (JavaDoc) ist für angebotene Funktionen die Zugehörigkeit zur entsprechenden Laufzeitgruppe und damit der empfohlene Timeout-Wert beschrieben.
Besteht aus Implementierungsgründen nicht die Möglichkeit die Timeout-Steuerung pro Funktionsaufruf zu parametrieren, so ist allgemein der Timeout-Wert der Laufzeitgruppe Lang zu setzen.
Für die Kommunikation mit dem Kartenleser über REST ist ein entsprechender REST-Client notwendig.
Request-Wiederholung (Replay)
Aus diesem Grund gibt es die Möglichkeit, den selben Request nochmals zu senden.
Wurde der erste Versuch bereits am Server verarbeitet, wird die ursprüngliche Antwort zurückgeschickt, ohne den Request ein zweites Mal zu verarbeiten.
Um einen Request eindeutig identifizieren zu können, muss bei jedem Senden ein und des selben Requests die selbe TransactionId im Message-Header des Requests gesetzt sein.
TransaktionsId: <soap:TransactionId>Platzhalter</soap:TransactionId>
Hinweis: In der technischen Schnittstellenbeschreibung (JavaDoc) ist bei Funktionen, welche die Replay-Funktionalität implementieren, der Hinweis "Replayability: [Ja|Nein]." vermerkt.
Die TransactionId ist von der VPSW zu generieren und hat folgende Anforderungen:
- Darf weder mit null noch mit einem Leerstring versorgt sein
- Darf nicht länger als 100 Zeichen sein
- Muss eindeutig sein (GUID - Globally-Unique-Identifier, siehe auch Wikipedia - GUID, z.B. per java.util.UUID)
- Bei der Wiederholung eines Requests muss die TransactionId bei jedem Versuch ident sein
Bis zur verpflichtenden Angabe gelten folgende Bedingungen:
- Die TransactionId ist optional anzugeben - eine Nichtangabe führt nicht zum Fehler.
- Die Angabe der TransactionId kann mittels "ForceConfirmation" im SOAP-Header getestet werden.
Wird ForceConfirmation im Header angegeben, wird die angegebene TransactionId in der Response retourniert.
Beispiel Request:
<soapenv:Header>Beispiel Response:
<soap:ForceConfirmation/>
<soap:TransactionId>1234567</soap:TransactionId>
</soapenv:Header>
<soap:Confirmation xmlns:soap="http://soap.base.client.chipkarte.at">
<TransactionId>1234567</TransactionId>
</soap:Confirmation>
- Wird die TransactionId nicht angegeben, wird die Exception DialogExceptionConstants.INVALID_TRANSACTION_ID retourniert.
- Die Prüfung mittels "ForceConfirmation"-Header ist nicht mehr möglich.
- Die Retournierung der TransactionId als Confirmation im Response wird nicht mehr unterstützt.
Patientendaten:
Ist nur eine Schreibweise vorhanden, werden nur Namensfelder ohne "Druck-Prefix" befüllt. Ist zusätzlich noch eine weitere Schreibweise vorhanden, werden zusätzlich die "Druck"-Felder befüllt.
Bezüglich der einzelnen Erweiterungen in den Personendatenobjekten ist die JavaDoc-Beschreibung der einzelnen Services zu beachten.
Wichtiger Hinweis:
Nicht jedes Service bietet aufgrund fachlicher oder technischer Gegebenheiten (bei jeder Funktion) eine doppelte Namenslieferung an.
Beispiele:
Bei Abfragen der historischen Ansprüche mittels VDAS werden Daten aus einem Drittsystem geliefert – ohne Doppellieferung der Namensdaten bei abgeleiteten Ansprüchen.
Technische Details:
Kodierung:
SOAP-Requests müssen UTF-8 kodiert gesendet werden.
Request Größe:
Um das e-card System vor unerwünschter Belastung zu schützen, werden Requests, die größer als 1,5 MB sind, abgewiesen. In diesem Fall wird an der Schnittstelle der HTTP Fehler 413 (unerlaubte Requestgröße) zurückgemeldet. Diese Fehlermeldung ist keine SOAP-Response.
Kennzeichnung optionaler Parameter im WSDL:
Ein 'nillable = "true"' bedeutet, dass das Feld in den SOAP-Responses/-Requests nicht unbedingt befüllt sein muss – es kann leer bleiben.
Ein 'minOccurs="0"' bedeutet, dass das Feld in den SOAP-Responses/-Requests nicht unbedingt enthalten sein muss – es kann als Ganzes nicht angegeben werden.
Sind keine Angaben vorhanden, gelten die default-Werte 'minOccurs="1"' und 'nillable="false"'.
Fehlermeldungen:
Fehlermeldungen werden in Form von Fehlercodes geliefert. Zusätzlich werden eine Client-Fehlernummer und ein Text (inkl. Client-Fehlernummer) geliefert. In der technischen Schnittstellenbeschreibung (JavaDoc) sind für jede angebotene Funktion die Fehlercodes und die möglichen Fehlernummern aufgelistet. Es wird empfohlen, den Text (inkl. Fehlernummer) auch als Fehlertext in der VPSW zu verwenden. Dadurch wird die Fehleranalyse vereinfacht.
Protokoll:
HTTPS / SOAP / REST
Sicherheit der Schnittstelle:
Für die Kommunikation mit dem e-card System wird SSL mit serverseitiger
Authentifizierung mit RSA / 2048 Bit Verschlüsselung verwendet.
Die technische Grundlage für die verschlüsselte HTTPS-Kommunikation mit dem e-card System bilden Zertifikate, die
im Betriebssystem bzw. Webbrowser des Vertragspartners eingebunden (importiert) werden müssen.
Die Zertifikate stehen auf folgender Seite zum Download bereit: https://www.chipkarte.at/zertifikate
Achtung: Für die Kommunikation in der VSPWH-Umgebung gelten die
"Test"-Zertifikate und für die Kommunikation in
der Produktiv-Umgebung die "Prod"-Zertifikate.
Attachments:
Für die Übertragung von Attachments (sowohl im Request, als auch in der Response) wird MTOM (Message
Transmission Optimization Machanism) verwendet.
Für Funktionen mit der Angabe- oder Rückgabemöglichkeit eines Attachments ist dies entsprechend im
jeweiligen Service-WSDL angeführt.
Beispiel für die Darstellung im WSDL beim Upload:
<xs:element name="param2" type="tns:objectType" minOccurs="0" />
<xs:element name="param3" type="xs:string" minOccurs="0" />
<xs:element xmlns:ns2="http://www.w3.org/2005/05/xmlmime" name="attachment" type="xs:base64Binary" ns2:expectedContentTypes="application/octet-stream" minOccurs="0" />
Bei Angabe eines Attachments über SOAP mittels MTOM muss auf die Referenzangabe der 'cid' innerhalb des
XOP-Elements geachtet werden.
In Abhängigkeit des verwendeten Frameworks wird die Befüllung der Referenz auf die 'cid' automatisch bei
Angabe des Attachments gesetzt oder ist durch die VPSW selbst zu versorgen.
Wichtig ist hierbei, dass die 'cid'-Referenz mit der Content-ID des angehängten Attachments
übereinstimmt.
Bei den Services ABS, REZ und eKOS (eBS) werden Attachments bis zu einer Größe von 3MB (3245728 Byte / 3,095 MByte)
unterstützt. Dabei gilt die Summe aller Anlagen innerhalb des zu übergebenden ZIP-Archivs im entpackten
Zustand.
Bis zu einer Größe von insgesamt 3.19 MB wird bei Überschreiten der erlaubten Maximalgröße
der Request mit einer fachlichen Fehlermeldung abgebrochen. Ab einer erkannten Größe über 3.2 MB
wird kein fachlicher Fehler mehr retourniert, sondern
ein SocketError (SocketException: Connection reset). Es wird als Response der HTTP Statuscode 400 zurückgegeben.
Bsp.:
<soap:attachment><inc:Include href="cid:externGesetzteCid"
xmlns:inc="http://www.w3.org/2004/08/xop/include"/></soap:attachment>
.....
.....
.....
Content-ID: <externGesetzteCid>
Beispiel für die Darstellung im WSDL beim Download:
Die 'cid' (und somit auch die Content-ID) des Attachments werden durch das e-card System gesetzt. Diese ID wird dabei
bei jedem Request neu erzeugt und ist nicht in der VPSW zu speichern.
Bsp.:
<xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:internGesetzteCid"/>
.....
.....
.....
Content-ID: <internGesetzteCid>