# Vertragspartner-Software SOAP Schnittstelle 25a

Die Vertragspartnersoftware-Schnittstelle stellt diverse Service-Endpoints zur Verfügung.

See: Description

Service-Manager
Package | Description
--- | ---
at.chipkarte.client.servicemanager.soap | Interface und Klassen des Servicemanagers.
at.chipkarte.client.servicemanager.soap.constants | Dieses Package enthält Konstanten für den Service-Manager.

Basis-Service (BASE)
Package | Description
--- | ---
at.chipkarte.client.base.soap | Interface und Klassen des Basis-Service (BASE).
at.chipkarte.client.base.soap.constants | Dieses Package enthält die Konstanten für das Basis-Service (BASE).
at.chipkarte.client.base.soap.exceptions | Dieses Package enthält die Exceptions für das Basis-Service (BASE).

Authentifizierungsservice (AUTH)
Package | Description
--- | ---
at.chipkarte.client.auth.soap | Interface und Klassen des Authentifizierungsservice (AUTH).

Freies Datenabfrageservice (FDAS)
Package | Description
--- | ---
at.chipkarte.client.fdas.soap | Interface und Klassen des freien Datenabfrageservice (FDAS).
at.chipkarte.client.fdas.soap.constants | Dieses Package enthält die Konstanten für das Freie Datenabfrageservice (FDAS).
at.chipkarte.client.fdas.soap.exceptions | Dieses Package enthält die Exceptions für das Freie Datenabfrageservice (FDAS).

Arzneimittelbewilligungsservice (ABS)
Package | Description
--- | ---
at.chipkarte.client.abs.soap | Interface und Klassen des Arzneimittelbewilligungsservice (ABS).
at.chipkarte.client.abs.soap.constants | Dieses Package enthält die Konstanten für das Arzneimittelbewilligungsservice (ABS).
at.chipkarte.client.abs.soap.exceptions | Dieses Package enthält die Exceptions für das Arzneimittelbewilligungsservice (ABS).

Konsultationsverwaltung (KSE)
Package | Description
--- | ---
at.chipkarte.client.kse.soap | Interface und Klassen der Konsultationsverwaltung (KSE).
at.chipkarte.client.kse.soap.constants | Dieses Package enthält die Konstanten für die Konsultationsverwaltung (KSE).
at.chipkarte.client.kse.soap.exceptions | Dieses Package enthält die Exceptions für die Konsultationsverwaltung (KSE).

Sozialversicherungsnummernabfrageservice (SAS)
Package | Description
--- | ---
at.chipkarte.client.sas.soap | Interface und Klassen des Sozialversicherungsnummern-Abfrage-Service (SAS).
at.chipkarte.client.sas.soap.constants | Dieses Package enthält die Konstanten für das Sozialversicherungsnummernabfrageservice (SAS).
at.chipkarte.client.sas.soap.exceptions | Dieses Package enthält die Exceptions für das Sozialversicherungsnummernabfrageservice (SAS).

Versichertendatenabfrageservice (VDAS)
Package | Description
--- | ---
at.chipkarte.client.vdas.soap | Interface und Klassen des Versichertendatenabfrageservice (VDAS).
at.chipkarte.client.vdas.soap.constants | Dieses Package enthält die Konstanten für das Versichertendatenabfrageservice (VDAS).
at.chipkarte.client.vdas.soap.exceptions | Dieses Package enthält die Exceptions für das Versichertendatenabfrageservice (VDAS).

Arbeitsunfähigkeitsmeldungs-Service (AUM)
Package | Description
--- | ---
at.chipkarte.client.aum.soap | Interface und Klassen des elektronischen Arbeitsunfähigkeitsmeldungsservice (AUM).
at.chipkarte.client.aum.soap.constants | Dieses Package enthält die Konstanten für das elektronische Arbeitsunfähigkeitsmeldungsservice (AUM).
at.chipkarte.client.aum.soap.exceptions | Dieses Package enthält die Exceptions für das elektronische Arbeitsunfähigkeitsmeldungsservice (AUM).

Datenabfrageservice (DAS)
Package | Description
--- | ---
at.chipkarte.client.das.soap | Interface und Klassen des Datenabfrageservice (DAS).
at.chipkarte.client.das.soap.constants | Dieses Package enthält die Konstanten für das Datenabfrageservice (DAS).
at.chipkarte.client.das.soap.exceptions | Dieses Package enthält die Exceptions für das Datenabfrageservice (FDAS).

Dokumentationsblattannahme-Service (DBAS)
Package | Description
--- | ---
at.chipkarte.client.dbas.soap | Interface und Klassen des Dokumentationsblattannahme-Service (DBAS).
at.chipkarte.client.dbas.soap.constants | Dieses Package enthält die Konstanten für das Dokumentationsblattannahme-Service (DBAS).
at.chipkarte.client.dbas.soap.exceptions | Dieses Package enthält die Exceptions für das Dokumentationsblattannahme-Service (DBAS).

Präoperative Befundung (PROP)
Package | Description
--- | ---
at.chipkarte.client.prop.soap | Interface und Klassen der Präoperativen Befundung (PROP).
at.chipkarte.client.prop.soap.constants | Dieses Package enthält die Konstanten für die Präoperative Befundung (PROP).
at.chipkarte.client.prop.soap.exceptions | Dieses Package enthält die Exceptions für die Präoperative Befundung (PROP).

Testszenarienverwaltung (TSV)
Package | Description
--- | ---
at.chipkarte.client.tsv.soap | Interface und Klassen der Testszenarienverwaltung (TSV).
at.chipkarte.client.tsv.soap.constants | Dieses Package enthält die Konstanten für die Testszenarienverwaltung (TSV).
at.chipkarte.client.tsv.soap.exceptions | Dieses Package enthält die Exceptions für die Testszenarienverwaltung (TSV).

Brustkrebs-Früherkennung (BKF)
Package | Description
--- | ---
at.chipkarte.client.bkf.soap | Interface und Klassen zur Brustkrebs-Früherkennung (BKF).
at.chipkarte.client.bkf.soap.constants | Dieses Package enthält die Konstanten für das Brustkrebs-Früherkennungs-Service (BKF).
at.chipkarte.client.bkf.soap.exceptions | Dieses Package enthält die Exceptions für das Brustkrebs-Früherkennungs-Service (BKF).

Disease Management Programm (DMP)
Package | Description
--- | ---
at.chipkarte.client.dmp.soap | Interface und Klassen des Disease Management Programm (DMP).
at.chipkarte.client.dmp.soap.constants | Dieses Package enthält die Konstanten für das Disease Management Programm (DMP).
at.chipkarte.client.dmp.soap.exceptions | Dieses Package enthält die Exceptions für das Disease Management Programm (DMP).

Security Token Service (STS)
Package | Description
--- | ---
at.chipkarte.client.sts.soap | Interface und Klassen des Security Token Service (STS)
at.chipkarte.client.sts.soap.constants | Dieses Package enthält die Konstanten für das Security Token Service (STS).
at.chipkarte.client.sts.soap.exceptions | Dieses Package enthält die Exceptions für das Security Token Service (STS).

Elektronisches Bewilligungs- und Antragsservice (EBS)
Package | Description
--- | ---
at.chipkarte.client.ebs.soap | Interface und Klassen des elektronischen Kommunikationsservice (eKOS).
at.chipkarte.client.ebs.soap.constants | Dieses Package enthält die Konstanten des elektronischen Kommunikationsservice (eBS).
at.chipkarte.client.ebs.soap.exceptions | Dieses Package enthält die Exceptions des elektronischen Kommunikationsservice (eBS).

e-card-Adapter für ELGA (ELGAAD)
Package | Description
--- | ---
at.chipkarte.client.elgaad.soap | Interface und Klassen des ELGA Adapters (ELGAAD).
at.chipkarte.client.elgaad.soap.constants | Dieses Package enthält die Konstanten für den ELGA Adapter (ELGAAD).
at.chipkarte.client.elgaad.soap.exceptions | Dieses Package enthält die Exceptions für den ELGA Adapter (ELGAAD).

Formularübermittlungsservice (FUS)
Package | Description
--- | ---
at.chipkarte.client.fus.soap | Interface und Klassen des Formularübermittlungsservice (FUS).
at.chipkarte.client.fus.soap.constants | Dieses Package enthält die Konstanten für das Fus-Service (FUS).
at.chipkarte.client.fus.soap.exceptions | Dieses Package enthält die Exceptions für das Fus-Service (FUS).

e-Rezept-Service (REZ)
Package | Description
--- | ---
at.chipkarte.client.rez.soap | Interface und Klassen des e-Rezept Service (REZ).
at.chipkarte.client.rez.soap.constants | Dieses Package enthält die Konstanten des REZ-Services.
at.chipkarte.client.rez.soap.exceptions | Dieses Package enthält die Exceptions des REZ-Services.

Mutterschutzhilfe-Service (MUHI)
Package | Description
--- | ---
at.chipkarte.client.muhi.soap | Interface und Klassen des Mutterschaftshilfeservice (MUHI).
at.chipkarte.client.muhi.soap.constants | Dieses Package enthält die Konstanten für das Mutterschutzhilfe-Service (MUHI).
at.chipkarte.client.muhi.soap.exceptions | Dieses Package enthält die Exceptions für das Mutterschutzhilfe-Service (MUHI).

Die Vertragspartnersoftware-Schnittstelle stellt diverse Service-Endpoints zur Verfügung.
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:

Ausgewählte Funktionen des e-card Systems werden für die Vertragspartner-Software über ein SOAP- bzw. REST-Interface zur Verfügung gestellt. Die zur Verfügung gestellten Funktionen sowie Ein- und Ausgangsparameter der SOAP-Services werden jeweils durch WSDL-Files spezifiziert.
Überblick über die Komponenten für die Vertragspartnersoftware
Das e-card System stellt mehrere Services (SOAP/REST) zur Verfügung.
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

Für jedes verfügbare Service werden Informationen zum Servicenamen, der Version sowie die jeweilige Endpoint-URL retourniert. Bei den vom Servicemanager retournierten URLs handelt es sich um absolute Adressangaben.
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

CRS (Card Reader Service):
Funktionalität zur Abfrage der verfügbaren angeschlossenen Kartenlesegeräte GINO.
Kartenleser (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.
BASE:
Funktionalität für das Message-, Vertrags- und Berechtigungshandling und die Ordinationsübersiedlung.
AUTH:
Funktionalität um einen Dialog aufzubauen und zu beenden.
FDAS:
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:

Voraussetzung für die clientseitige SOAP-Unterstützung ist ein TCP/IP-Stack sowie eine Bibliothek zur SSL-Verschlüsselung.
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:

Mittel | ...... | Funktionen mit Server-Kommunikation kurzer Laufzeit
Lang | ...... | Funktionen mit Server-Kommunikation langer Laufzeit

In der nachfolgenden Tabelle sind die empfohlenen Timeout-Werte je Laufzeitgruppe beschrieben.

Laufzeitgruppe | EmpfohlerTimeout-Wert
--- | ---
Mittel | >= 60 s
Lang | >= 1500 s

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)

Erfolgt keine Rückmeldung an die VPSW, kann es passieren, dass dem Benutzer nicht bekannt ist, wie weit der Request gekommen ist.
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

Die Verwendung der TransactionId ist aktuell noch optional. Wir empfehlen, die TransactionId bei jedem Aufruf zu versorgen, da die Angabe zukünftig verpflichtend ist.
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>
  <soap:ForceConfirmation/>
  <soap:TransactionId>1234567</soap:TransactionId>
  </soapenv:Header>
  Beispiel Response:
  <soap:Confirmation xmlns:soap="http://soap.base.client.chipkarte.at">
  <TransactionId>1234567</TransactionId>
  </soap:Confirmation>

Ab der verpflichtenden Angabe gelten folgende Bedingungen:

- 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:

Sofern für einen Patienten im e-card System mehr als eine Schreibweise des Namens vorhanden ist, werden alle Namensdaten retourniert.
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:complexType name=" functionXYZ">
<xs:sequence>
<xs:element name="param1" type="xs:string" minOccurs="0" />
<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" />
</xs:sequence>
</xs:complexType>

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:

<xs:complexType name="functionXYZ">
<xs:sequence>
<xs:element name="return" type="xs:base64Binary" xmime:expectedContentTypes="application/octet-stream" minOccurs="0" />
</xs:sequence>
</xs:complexType>

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>