# 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) 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-Service

- 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 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 Sie bei den Funktionsbeschreibungen (siehe "Tagesaktuelle Versichertendatenabfrage" bzw. "Stichtagsaktuelle Versichertendatenabfrage") bzw. in der Javadoc.
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 mit den an der Vertragspartnersoftware-Schnittstelle angebotenen Methoden ermittelt werden:

KVTs ermitteln | - | FDAS-Methode: getSVTs

### Online-/Offline-Status

Im laufenden Betrieb kann ein Offline-Zustand bzw. das Auftreten eines Verbindungsproblems in Abängigkeit der Kommunikationsart mit dem e-card System wie folgt identifiziert werden:

- die Kommunikation erfolgt direkt über die GINA:
  Die aufrufende Funktion retourniert eine entsprechende SOAP Exception (ServiceException.CONNECTION_ERROR).
- die Kommunikation erfolgt über den Proxy auf der GINA:
  Es wird als Response HTTP 503 retourniert.
- die Kommunikation erfolgt direkt mit dem Serversystem:
  Es erfolgt keine Response.

Ob eine Verbindung für ein bestimmtes Service zum e-card-Serversystem besteht, sollte im Normalbetrieb NICHT abgefragt werden! Die Abfrage sollte nur dann durchgeführt werden um festzustellen, ab wann das Service wieder online ist, wenn 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: Der Aufruf erfolgt mittels:
GET https://<gina-adresse>/<service-name>/<versionsnummer>/status
Ist der Server erreichbar, wird der Response HTTP 200 retourniert. Ist der Server nicht erreichbar (Offline) und der Request wird über die GINA geschickt (direkt über die GINA bzw. über den GINA Proxy), wird der Response HTTP 503 retourniert.
Hinweis: Erfolgt die Kommunikation mittels GINA Proxy wird im HTTP 503 Response zusätzlich der Text "Die GINA konnte keine Verbindung zum Serversystem herstellen." im Response-Body befüllt.
Erfolgt die Abfrage direkt auf das Serversystem (nach Entfall der GINA) wird im Offline-Fall keine Response mehr 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 SW-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 LANCCR angefordert werden.
Die Dokumentation des REST-Services zur Kommunikation mit dem Kartenleser ist zu finden unter: Swagger Doku LANCCR.
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 ausgestellte Cardtoken kann anschließend in den Funktionen der jeweiligen Services anstelle einer (gesteckten) Karte verwendet werden.
Das Stecken der Karte zum Ausführen der jeweiligen Servicefunktion ist nicht mehr notwendig.
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!
In VDAS gibt es folgende Funktionen mit der Mölichkeit ein CardToken zu verwenden:
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 (o-card Token oder SW-Zertifikat) muss zwingend die SV-Nummer des Patienten angegeben werden.
Wird ein Cardtoken und eine SV-Nummer Parameter 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 (bei e-card Cardtoken) erstellt wurde.

## Prinzipielle Erklärungen

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

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

### Benutzergruppen

VDAS wird zwei Benutzergruppen zur Verfügung gestellt:

- Vertragspartner aus dem Bereich der Krankenanstalten
- Vertragspartner aus dem Bereich der Gesundheitsdienstanbieter

Gesundheitsdienstanbieter
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.
Ausnahme: Krankentransporteinrichtungen (KTE) fallen zwar prinzipiell unter die Benutzergruppe der Gesundheitsdienstanbieter, erhalten allerdings ebenfalls das Recht VDAS.ANSPRUCH_HISTORISCH und sind somit berechtigt zur Nutzung der Funktion retrieveVersichertendatenPerStichtag() (äquivalent den Vertragspartnern aus dem Krankenanstaltenbereich).
Krankenanstaltenbereich
Diese Vertragspartner besitzen das Recht VDAS.CORE und VDAS.ANSPRUCH_HISTORISCH. Dies berechtigt zur Nutzung der Funktion getVersichertendaten() (siehe Tagesaktuelle Versichertendatenabfrage) bzw. 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 Software-Zertifikat des Vertragspartners.
Für die Verwendung eines Software-Zertifikats gilt:

- Der verwendete Dialog wurde mit einem Software-Zertifikat aufgebaut.
- Das für die Versichertendatenabfrage verwendete Software-Zertifikat ist ident mit dem des Dialogaufbaus.
- Die Verwendung ist äquivalent zum Dialogaufbau (d.h. die Signatur des Software-Zertifikats muss im Message-Header gesetzt werden).
- Soll trotz Verwendung eines Software-Zertifikats auf eine gesteckte e-card zugegriffen werden (und somit auch die Signierung mit dieser erfolgen), muss explizit ein Kartenleser gesetzt werden.
  Wird kein Kartenleser mit dem Request angegeben, wird auch nicht auf einen Kartenleser zugegriffen (auch wenn eventuell in der Abfrage zuvor ein Kartenleser verwendet und im Dialog gesetzt wurde).
  Wichtig: Wird ein Kartenleser explizit angegeben, wird eine gesteckte e-card erwartet. Sollte keine e-card gesteckt sein, erfolgt in diesem Fall die Retournierung einer Fehlermeldung. D.h.: Ist keine e-card gesteckt, sollte somit auch kein Kartenleser explizit angegeben 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.
Sofern das e-card-System sich im Status Online befindet, kann diese Anfrage immer durchgeführt werden (solange das entsprechende Recht vorhanden ist).
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-Service nicht erreichbar, wird die Fehlerkonstante VdasException.BACKENDSYSTEM_NOT_AVAILABLE ausgegeben.
Ist das KVKVVERM-Service 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 Server eine Fotoinformation retourniert, so ist der im Parameter enthaltene String dem Vertragspartner anzuzeigen!

# Funktionalität des VDAS-Service

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 den e-card-System-Daten 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 Software-Zertifikat aufgebaut wurde, dasselbe Software-Zertifikat zur Signierung des VDAS-Request verwendet werden. Die Schritte zur Signierung mit Software-Zertifikat sind im nachfolgenden Szenario rot markiert.
Fotoinformation:
Wird im Rückgabeobjekt VersichertendatenAbfrageErgebnis durch den e-card Server 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 vorgelegen ist 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 Software-Zertifikat aufgebaut, kann dasselbe Software-Zertifikat zur Signierung des VDAS-Request verwendet werden. Die Schritte zur Signierung mit Software-Zertifikat sind im nachfolgenden Szenario rot markiert.
Fotoinformation:
Wird im Rückgabeobjekt VersichertendatenAbfrageErgebnis durch den e-card Server der Parameter Fotoinformation versorgt, so ist der darin enthaltene String dem Vertragspartner anzuzeigen.

##### Szenario 5 - Stichtagsaktuelle Versichertendatenabfrage: