# Package at.chipkarte.client.vdas.soap

Interface und Klassen des Versichertendatenabfrageservice (VDAS).

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  IVdasService | Dieses Service stellt die Funktionalitäten des Versichertendatenabfrageservice (VDAS) Version 16 zur Verfügung.

- Class Summary
  Class | Description
  --- | ---
  Anspruchsdaten | Enthält die Daten für einen eigenen Anspruch beziehungsweise für einen abgeleiteten Anspruch.
  VersichertendatenAbfrage | Enthält die Suchkriterien für eine Abfrage der tages-/stichtagsaktuellen Versichertendaten für einen Patienten.
  VersichertendatenAbfrageErgebnis | Enthält das Ergebnis einer positiv durchgeführten Versichertendatenabfrage.
  VersichertendatenAbfragePerStichtag | Enthält die Suchkriterien für eine Abfrage der stichtagsaktuellen Versichertendaten für einen Patienten.
  VersichertendatenSvPerson | Enthält die Daten zu einem Patienten.

## Package at.chipkarte.client.vdas.soap Description

Interface und Klassen des Versichertendatenabfrageservice (VDAS). Enthält den SOAP-Endpoint `IVdasService IVdasService` sowie die dazu notwendigen Klassen.
Inhalt der VDAS Package-Beschreibung:

- Allgemein

- Rechte
- Dynamische Ermittlung von Parameterwerten des e-card-Regelwerks
- Online-/Offline-Status
- SV-Nummer vs. e-card CardToken
- Prinzipielle Erklärungen

- Benutzergruppen
- Datenquellen für Anspruchsdaten
- Todesdatum

- Fotoinformation

- Funktionalität des VDAS

- Tagesaktuelle Versichertendatenabfrage
- Stichtagsaktuelle Versichertendatenabfrage

# Allgemein

## Rechte

Für die Funktionen des Versichertendatenabfrageservice benötigt der Vertragspartner für die Durchführung das Recht VDAS.CORE.
Wird eine Funktion, welche dieses Recht benötigt, ohne das entsprechende Recht aufgerufen, erhält man die Exception AccessException.MISSING_VDAS_CORE.
Für spezifische Funktionen im Krankenanstaltenbereich bzw. für Krankentransporteinrichtungen wird zusätzlich das Recht VDAS.ANSPRUCH_HISTORISCH benötigt.
Wird eine Funktion, welche dieses Recht benötigt, ohne das entsprechende Recht aufgerufen, erhält man die Exception AccessException.MISSING_VDAS_ANSPRUCH_HISTORISCH.
Genauere Informationen, welche Rechte bei den jeweiligen VDAS Funktionen benötigt werden, finden sich u.a. bei den Funktionsbeschreibungen (siehe "Tagesaktuelle Versichertendatenabfrage" bzw. "Stichtagsaktuelle Versichertendatenabfrage").
Mittels der Funktion getBerechtigungen() aus dem BASE Service ist es möglich, die Rechte des Vertragspartners abzufragen.

## Dynamische Ermittlung von Parameterwerten des e-card-Regelwerks

Für das Service relevante Parameterwerte des e-card-Regelwerks müssen dynamisch mindestens einmal pro Dialog mit den angebotenen Methoden ermittelt werden:

KVT ermitteln | - | FDAS-Methode: getSVTs

### Online-/Offline-Status

Ob eine Verbindung für ein bestimmtes Service zum e-card-Serversystem besteht, sollte im Normalbetrieb NICHT abgefragt werden! Die Abfrage sollte nur durchgeführt werden um festzustellen, ab wann das Service wieder online ist, sofern zuvor Verbindungsprobleme aufgetreten sind.
Die empfohlene Frequenz für die Abfragen liegt in diesem Fall bei > 1 Minute.
Die Abfrage ist über eine REST-Schnittstelle durchzuführen:
GET https://services.ecard.sozialversicherung.at/<service-name>/<versionsnummer>/status (PROD-Instanz) bzw. GET https://services-a.ecard-test.sozialversicherung.at/<service-name>/<versionsnummer>/status (VPSWH-Instanz)
Ist der Server erreichbar, wird die Response HTTP 200 retourniert. Im Offline-Fall wird keine Response retourniert.

## SV-Nummer vs. e-card CardToken

Bei den VDAS Funktionen unterscheidet man folgende unterschiedliche Eingabevarianten zur Identifikation des Patienten:

- SV-Nummer und/oder e-card CardToken
- SV-Nummer und o-card CardToken
- SV-Nummer und Software-Zertifikat

Das e-card CardToken (SV-Signaturtoken mit e-card), sowie das o-card CardToken (SV-Signaturtoken mit o-card) kann mittels REST-Schnittstelle vom GINO angefordert werden.
Die Dokumentation des REST-Services zur Kommunikation mit dem Kartenleser ist zu finden unter: Swagger Doku GINO.
Bei der Anmeldung des Patienten kann in Abhängigkeit davon, ob eine e-card vorhanden ist, ein e-card CardToken (SV-Signaturtoken mit e-card) oder ein o-card CardToken (SV-Signaturtoken mit Admin-Karte) ausgestellt werden.
Das CardToken kann je nach Service für eine bestimmte Dauer nach Ausstellung genutzt werden. In der Regel ist ein ausgestellter CardToken für 10 Stunden verwendbar.
Welcher CardToken vom jeweiligen Service unterstützt wird, ist bei den Services selbst definiert.
In VDAS wird sowohl das e-card CardToken, als auch ein o-card CardToken (mit SV-Signatur) unterstützt!
Folgende VDAS Funktionen können mit CardToken verwendet werden:
getVersichertenDaten() und retrieveVersichertendatenPerStichtag()
Bei diesen Funktion werden folgende Angabemöglichkeiten unterstützt:

- e-card CardToken
- e-card CardToken und SV-Nummer
- o-card CardToken und SV-Nummer
- SW-Zertifikat und SV-Nummer

Ein SV-Patient kann mittels SV-Nummer und/oder e-card CardToken angegeben werden. Ist kein e-card CardToken vorhanden (da keine e-card vorhanden ist), muss die Abfrage in Abhängigkeit des Dialogaufbaus entweder mit einem o-card CardToken oder mit SW-Zertifikat durchgeführt werden. In diesem Fall muss zwingend die SV-Nummer des Patienten angegeben werden.
Wird ein CardToken und eine SV-Nummer angegeben, muss die SV-Nummer zum Patienten gehören, für den das jeweilige CardToken erstellt wurde (SV-Signaturtoken) bzw. zur e-card, mit der das CardToken erstellt wurde.

## Prinzipielle Erklärungen

Die Funktionen des VDAS dienen der Ermittlung von Personendaten und Krankenversicherungsansprüchen von Patienten.
Bei jeder Versichertendatenabfrage wird signiert. Dazu kann verwendet werden:

- e-card
- o-card
- SW-Zertifikat (Krankenanstalt)

### Benutzergruppen

VDAS wird zwei Benutzergruppen zur Verfügung gestellt:

- Vertragspartner aus dem Bereich der Krankenanstalten und Krankentransporteinrichtungen
- Vertragspartner aus dem Bereich des Heilmittel- und Heilbehelfe-Bereichs, Apotheken, Therapeuten und Heime (Pfelgeheime, Genesungsheime, ...)

Heilmittel- und Heilbehelfe, Apotheken, Therapeuten und Heime (Pfelgeheime, Genesungsheime, ...)
In diesen Bereich fallen folgende Vertragspartner:

- Heilmittel- und Heilbehelfe - z.B. Hörgeräteakustiker, Optiker, Bandagisten ...
- Heime - z.B. Pflegeheim, Pensionistenheim, Kurheim, Genesungsheim, ...
- öffentliche Apotheken
- Therapeuten - z.B. Physiotherapeut, Logopäde, Psychotherapie, ...

Diese Vertragspartner haben nur das Recht VDAS.CORE. Dies berechtigt zur Nutzung der Funktion getVersichertendaten() (siehe Tagesaktuelle Versichertendatenabfrage). Die Signierung erfolgt entweder mit der e-card des Patienten oder mit der o-card des Vertragspartners.
Krankenanstalten und Krankentransporteinrichtungen
Diese Vertragspartner besitzen das Recht VDAS.CORE und VDAS.ANSPRUCH_HISTORISCH. Dies berechtigt zur Nutzung der Funktion getVersichertendaten() (siehe Tagesaktuelle Versichertendatenabfrage) und retrieveVersichertendatenPerStichtag() (siehe Stichtagsaktuelle Versichertendatenabfrage).
Die Signierung erfolgt entweder mit der e-card des Patienten oder (in Abhängigkeit des Dialogaufbaus) mit der o-card oder dem SW-Zertifikat des Vertragspartners.
Für die Verwendung eines SW-Zertifikats gilt:

- Der verwendete Dialog wurde mit einem SW-Zertifikat aufgebaut.
- Das für die Versichertendatenabfrage verwendete SW-Zertifikat ist ident mit dem des Dialogaufbaus.
- Die Verwendung ist äquivalent zum Dialogaufbau (d.h. die Signatur des SW-Zertifikats muss im Message-Header gesetzt werden).

### Datenquellen für Anspruchsdaten

Tagesaktuelle Anfragen
Es kann kein explizites Datum eingegeben werden. Die Suche erfolgt immer mit dem aktuellen Datum. Es werden die Daten des e-card Systems verwendet.
Stichtagsaktuelle Anfragen
Es muss für die Suche ein Datum eingegeben werden. Dieses Datum muss in der Vergangenheit liegen.
Die Suche erfolgt mit dem eingegebenen Datum unter Verwendung des Auskunftsservice KVKVKERM.
Diese Anfrage kann nur durchgeführt werden, wenn sowohl das e-card System, als auch das Auskunftsservice KVKVKERM erreichbar sind.
Ist das KVKVKERM nicht erreichbar, wird die Fehlerkonstante VdasException.BACKENDSYSTEM_NOT_AVAILABLE ausgegeben.
Ist das KVKVKERM zwar verfügbar, kann jedoch der Request nicht verarbeitet werden, wird die Fehlerkonstante VdasException.BACKENDSYSTEM_SYSTEM_ERROR ausgegeben.
Die Ermittlung der Personendaten des Patienten erfolgt immer aus den Daten des e-card Systems.

### Todesdatum

Wurde ein Patient vom zuständigen KV-Träger als tot gemeldet, wird diese Information zusätzlich in den Personendaten (Objekt versichertendatenSvPerson) übermittelt.
Man unterscheidet zwischen:

- bestätigter Todmeldung mit Todesdatum
- unbestätigter Todmeldung
- keine Todmeldung

bestätigte Todmeldung mit Todesdatum
Im Objekt versichertendatenSvPerson ist das Todesdatum mit einem Datumswert befüllt und der Parameter todesdatumBestaetigt mit "1" (= ja/true) belegt.
unbestätigte Todmeldung
Im Objekt VersichertendatenSvPerson ist das Todesdatum nicht befüllt und der Parameter todesdatumBestaetigt mit "0" (= nein/false) belegt.
keine Todmeldung
Im Objekt versichertendatenSvPerson sind sowohl das Todesdatum, als auch der Parameter todesdatumBestaetigt leer.
Achtung:
Wurde für einen Patienten ein Todesdatum gemeldet, werden nur dann Anspruchsdaten bei einer Abfrage retourniert, wenn das Abfragedatum vor dem Todesdatum liegt.
D.h. Anspruchsdaten können in diesem Fall nur mit einer stichtagsaktuellen (historischen) Abfrage erhoben werden, da bei einer tagesaktuellen Anfrage keine explizite Datumsangabe möglich ist, sondern automatisch das aktuelle Datum verwendet wird.
Liegt nur eine unbestätigte Todmeldung vor (d.h. Todesdatum ist nicht versorgt und todesdatumBestaetigt hat den Wert "0") werden zu den Personen- auch die Anspruchsdaten retourniert.

## Fotoinformation

Im Zuge folgender Funktionen ist die Übermittlung einer Fotoinformation möglich:

- Tagesaktuelle Versichertendatenabfrag - getVersichertenDaten()
- Stichtagsaktuelle Versichertendatenabfrage - retrieveVersichertendatenPerStichtag()

Wird in einer dieser Funktionen vom e-card System eine Fotoinformation retourniert, so ist der im Parameter enthaltene String dem Vertragspartner anzuzeigen.

# Funktionalität des VDAS

Es stehen folgende Funktionen zur Verfügung:

- Tagesaktuelle Versichertendatenabfrage
- Stichtagsaktuelle Versichertendatenabfrage

## Tagesaktuelle Versichertendatenabfrage:

Diese Funktion steht Vertragspartnern zur Verfügung, die das Recht VDAS.CORE besitzen.
Mittels der Funktion getVersichertenDaten() kann der Vertragspartner die gültigen Personendaten und den Anspruch bzw. die möglichen Ansprüche des Patienten auf Leistungen aus der Krankenversicherung aus dem e-card System ermitteln.
Wird ein Abfrageergebnis retourniert, d.h. es ist kein Fehler aufgetreten, ist darin immer das Objekt versichertendatenSvPerson versorgt (die Felder innerhalb des Objektes müssen nicht alle zwingend versorgt sein). Das Objekt anspruchsdaten wird in Abhängigkeit der internen Ermittlungslogik einmal, mehrmals oder gar nicht versorgt. Anspruchsdaten können nur retourniert werden, wenn zum Zeitpunkt der Überprüfung (also zum aktuellen Zeitpunkt) ein gültiger Krankenversicherungsanspruch vorliegt und für den Patienten kein (bestätigtes) Todesdatum angegeben ist.
Sofern das Objekt vdasMessageCodes versorgt ist, ist dieses auszuwerten. In den Codes finden sich die Informationen bzgl. des weiteren Vorgehens.
Beispiele:

- Das Ergebnis beinhaltet die Personendaten, keine Anspruchsdaten und den vdasMessageCode = 6. Dieser Message-Code besagt, dass der Patient keinen gültigen Anspruch besitzt. Eine nochmalige Abfrage zu diesem Patienten mit geänderten Eingangsdaten ist somit nicht zielführend.
- Das Ergebnis beinhaltet die Personendaten, keine Anspruchsdaten und den vdasMessageCode = 8 (nur möglich bei Nutzern mit alleinigem VDAS.CORE Recht, ohne VDAS.ANSPRUCH_HISTORISCH). Dieser Message-Code besagt, dass eine Mehrfachversicherung vorliegt und ein KVT erfasst werden muss. Eine nochmalige Anfrage zu dem Patienten mit angegebenem KVT kann somit zu einer Anspruchslieferung führen.

Diese Funktion kann auch durch Vertragspartner mit dem zusätzlichen Recht VDAS.ANSPRUCH_HISTORISCH verwendet werden (solange diese auch das Recht VDAS.CORE besitzen).
In diesem Falle kann, wenn der verwendete Dialog mittels SW-Zertifikat aufgebaut wurde, dasselbe SW-Zertifikat zur Signierung des VDAS Requests verwendet werden. Die Schritte zur Signierung mit SW-Zertifikat sind im nachfolgenden Szenario rot markiert.
Fotoinformation:
Wird im Rückgabeobjekt versichertendatenAbfrageErgebnis der Parameter fotoinformation versorgt, so ist der darin enthaltene String dem Vertragspartner anzuzeigen.

##### Szenario 5 - Tagesaktuelle Versichertendatenabfrage

## Stichtagsaktuelle Versichertendatenabfrage:

Diese Funktion steht Vertragspartnern zur Verfügung, die das Recht VDAS.ANSPRUCH_HISTORISCH zusätzlich zum Recht VDAS.CORE besitzen.
Mittels der Funktion retrieveVersichertendatenPerStichtag() kann der Vertragspartner die aktuellen Personendaten sowie den Anspruch bzw. die möglichen Ansprüche des Patienten auf Leistungen aus der Krankenversicherung für ein in der Vergangenheit liegendes Datum ermitteln.
Die Anspruchsdaten werden hierbei mit Hilfe des KVKVKERM-Auskunftsservice ermittelt.
Wird ein Abfrageergebnis retourniert, d.h. es ist kein Fehler aufgetreten, ist darin immer das Objekt versichertendatenSvPerson versorgt (die Felder innerhalb des Objektes müssen nicht alle zwingend versorgt sein). Das Objekt anspruchsdaten wird in Abhängigkeit der internen Ermittlungslogik einmal, mehrmals oder gar nicht versorgt.
Anspruchsdaten werden geliefert, wenn zum angegebenen Datum (also zum angegebenen Stichtag) ein gültiger Krankenversicherungsanspruch vorlag und das Stichtagsdatum vor einem eventuell angegebenen (bestätigten) Todesdatum liegt.
Eine Ermittlung der aktuellen Ansprüche (Stichtagsdatum = aktuelles Datum) ist mit dieser Funktion nicht möglich.
Sofern das Objekt vdasMessageCodes versorgt ist, ist dieses auszuwerten. In den Codes finden sich die Informationen bzgl. des weiteren Vorgehens.
Beispiele:

- Das Ergebnis beinhaltet die Personendaten, keine Anspruchsdaten und den vdasMessageCode = 6. Dieser Message-Code besagt, dass der Patient keinen gültigen Anspruch besitzt. Eine nochmalige Abfrage zu diesem Patienten mit geänderten Eingangsdaten ist somit nicht zielführend.
- Das Ergebnis beinhaltet die Personendaten, keine Anspruchsdaten und den vdasMessageCode = 5. Dieser Message-Code besagt, dass zu der angegebenen abgeleiteten SV-Nummer kein Anspruch bzw. kein gültiger Anspruch vorliegt. Eine nochmalige Anfrage zu diesen Patienten ohne bzw. mit geänderter abgeleiteter SV-Nummer kann somit zu einer Anspruchslieferung führen.

Wurde der verwendete Dialog mittels SW-Zertifikat aufgebaut, kann dasselbe SW-Zertifikat zur Signierung des VDAS Requests verwendet werden. Die Schritte zur Signierung mit SW-Zertifikat sind im nachfolgenden Szenario rot markiert.
Fotoinformation:
Wird im Rückgabeobjekt versichertendatenAbfrageErgebnis der Parameter fotoinformation versorgt, so ist der darin enthaltene String dem Vertragspartner anzuzeigen.

##### Szenario 5 - Stichtagsaktuelle Versichertendatenabfrage: