# Package at.chipkarte.client.base.soap

Interface und Klassen des Basis-Service (BASE).

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  IBaseService | Dieses Service stellt die Basis-Funktionen zur Verfügung.

- Class Summary
  Class | Description
  --- | ---
  Anspruch | Enthält die Daten für einen eigenen Anspruch beziehungsweise für einen abgeleiteten Anspruch
  BaseProperty | Enthält Daten zu verschiedenen Codewerten, die an der Schnittstelle verwendet werden.
  ErsatzbelegInfo | Enthält Informationen zum e-card Ersatzbeleg.
  Message | Enthält den Inhalt einer Nachricht.
  MessagePollResult | Enthält die Daten zu den über den Poll-Mechanismus abgefragten Nachrichten.
  Property | Enthält Key und Value einer Property.
  SvPersonV2 | Enthält die Daten eines Patienten.
  SvtProperty | Enthält über `BaseProperty` hinausgehende Daten für einen Krankenversicherungsträger.
  VertragsDaten | Enthält Daten zum Vertrag eines Vertragspartners.

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

Interface und Klassen des Basis-Service (BASE). Enthält den SOAP Endpoint `IBaseService` sowie die dazu notwendigen Klassen.
Inhalt der BASE package-Beschreibung:

- Allgemein

- Rechte
- Dynamische Ermittlung von Parameterwerten des e-card-Regelwerks
- Servicemanager
- Online-/Offline-Status

- Funktionalität des BASE-Service

- Benachrichtigungsmechanismus

- mittels Poll-Mechanismus
- mittels Push-Mechanismus

- Verträge abfragen
- Übersiedlung eines Vertragspartners abschließen

# Allgemein

## Rechte

Vertragspartner können bestimmte Services nur dann nutzen, wenn sie dazu berechtigt sind. Mittels der Funktion getBerechtigungen() ist es möglich die jeweiligen Berechtigungen des Vertragspartners abzufragen. Es werden dabei jene Rechte abgefragt, die der Vertragspartner mit dem aufgebauten Dialog (spezifiziert über die DialogId) besitzt. Die Ermittlung erfolgt hierbei mittels der beim Dialogaufbau angegebenen OrdinationId und TaetigkeitsBereichId.
Jedes Service benötigt dabei bestimmte Rechte z.B. benötigt das SAS-Service das Recht SAS.CORE.
Die Information, welches Recht bzw. welche Rechte ein Service benötigt ist bei der jeweiligen Servicebeschreibung bzw. den jeweiligen Funktionsbeschreibungen (Vorbedingungen) in der Javadoc zu finden.
Die Vertragspartnersoftware bzw. der Vertragspartnersoftware-Hersteller ist dazu angehalten dem Vertragspartner nur dann Zugriff zu den jeweiligen Services zu gewähren, wenn die dazu benötigten Rechte vorhanden sind.

## Dynamische Ermittlung von Parameterwerten des e-card-Regelwerks
Es wird empfohlen, die für das Service relevanten Parameterwerte des e-card-Regelwerks dynamisch mit den an der Vertragspartnersoftware-Schnittstelle angebotenen Methoden zu ermitteln.
Allgemeine Abfragefunktionen (für Parameter die in mehreren Services Verwendung finden) sind im Service FDAS enthalten.

## Servicemanager Die Ermittlung der Services über den auf der GINA verfügbaren Servicemanager ist nur von kurze Zeit möglich. Die Ermittlung ist umzustellen auf den zentralen ServiceManager.
Der direkt erreichbare (zentrale) ServiceManager ist unter folgender URL abrufbar:

- Produktion:
  - https://services.ecard.sozialversicherung.at/servicemanager/1
- 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 der URL unter der das Service erreichbar ist retourniert. Bei den vom ServiceManager retournierten URLs handelt es sich um absolute Adressangabe!

## Online-/Offline-Status

Im laufenden Betrieb kann ein Offline-Zustand bzw. das Auftreten eines Verbindungsproblems dadurch identifiziert werden, dass auf einen Request keine Response erfolgt.
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, 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://services.ecard.sozialversicherung.at/<service-name>/<versionsnummer>/status
Ist der Server erreichbar, wird der Response HTTP 200 retourniert. Ist der Server nicht erreichbar (Offline), wird keine Response mehr retourniert.

# Funktionalität des BASE-Service

## Benachrichtigungsmechanismus

Mit diesem Mechanismus können Nachrichten vom e-card-Serversystem zum Ordinationsclient übertragen werden.
Über ein Flag, das periodisch abgefragt werden kann, wird signalisiert, dass eine neue Nachricht vorliegt. Die neuen Nachrichten können dann vom e-card-Serversystem abgefragt werden.
Das Messaging-System dient zur Benachrichtigung über asynchron am e-card-Server verarbeiteter fachlicher Funktionen.
Hinweis - Zustellung und Abholung von Nachrichten in Abhängigkeit des Dialogs:
Je nach Service erfolgt die Zustellung (push) bzw. die Abholung (poll) von Nachrichten in Abhängigkeit bestimmte Parameter des angemeldeten Dialogs:
Nachrichten KSE: in Abhängigkeit der beim Dialogaufbau verwendeten TaetigkeitsBereichId.
Nachrichten ABS und EBS: in Abhängigkeit der (beim Dialogaufbau) verwendeten Vertragspartnernummer.
D.h. bei mehreren Vertragspartnernummern bzw. mehreren Tätigkeitsbereichen müssen unter Umständen mehrere Dialoge zur Abfrage der Nachrichten verwendet werden. Die Daten können nur mit einem Dialog abgeholt werden, der auch die Nachricht empfangen hat bzw. kann.
Wird von der Vertragspartnersoftware ein Service unterstützt, welches den Benachrichtigungsmechanismus benötigt (KSE, ABS, EBS), ist das Messaging-System wie oben beschrieben einzusetzen.

### mittels Push-Mechanismus

Die Nachrichtenzustellung erfolgt Session-Orientiert.
Die Information über neue Nachrichten wird mit jedem Request zum e-card-Server aktualisiert und seitens Vertragspartnersoftware mit der Funktion hasUnreadMessages() abgefragt. Liegen neue Nachrichten vor, können diese mit der Funktion getMessages() abgeholt und entsprechend der Meldungskategorie weiterverarbeitet werden.

##### Szenario 4 - Asynchrone Nachrichtenabfrage mittels Push-Mechanismus:

### mittels Poll-Mechanismus

Die Nachrichtenzustellung erfolgt nicht Session-Orientiert.
Mittels der Funktion pollMessages() wird eine Anfrage nach Nachrichten gestartet. Dabei ist der Suchzeitpunkt anzugeben, ab dem neue Nachrichten geliefert werden sollen. Bei der ersten Abfrage sollte dieser Suchzeitpunkt in der Vergangenheit liegen.
Liegen Nachrichten vor, werden diese abgeholt. Zusätzlich wird der nächste Suchzeitpunkt, unabhängig ob Nachrichten vorliegen oder nicht übermittelt. Wird die Funktion pollMessages() immer mit dem zurückgelieferten Suchzeitraum aufgerufen, ergibt sich eine lückenlose und duplikatfreie Zustellung der Nachrichten (in Abhängigkeit der Dialogparameter - siehe auch Hinweis - Zustellung und Abholung von Nachrichten in Abhängigkeit des Dialogs).
Die Nachrichten können anhand der Meldungskategorie weiterverarbeitet werden.
Ergibt eine Anfrage, dass mehr Nachrichten vorliegen als aktuell zurückgeliefert werden können, kann die Funktion pollMessages() sofort nochmals aufgerufen werden.
Anderenfalls muss das Pollintervall berücksichtigt werden. Das Intervall selbst kann anhand der Funktion getMinMsgPollingIntervall() ermittelt werden.
Für eine ordentliche Zuordnung der Nachrichten zu einem Benutzer, muss die Vertragspartnersoftware bei Serviceabfragen (z.B. Bewilligungsanfrage aus ABS) die jeweilige ID, die als Ergebnis zurückgeliefert wird, intern zu dem ausführenden Benutzer merken. Diese IDs sind bei den durch pollMessages() abgefragten Nachrichten im Message-Datenfeld Data zu finden. Dadurch kann eine benutzerbezogene Zuordnung und Zustellung innerhalb der Vertragspartnersoftware stattfinden.

##### Szenario 4 - Asynchrone Nachrichtenabfrage mittels Poll-Mechanismus:

## Verträge abfragen

Mittels der Funktion getVertraege() können die gültigen Verträge des Vertragspartners abgefragt werden. Ein Vertrag ist dabei jeweils für eine bestimmte Ordination mit einem bestimmten Tätigkeitsbereich gültig.

## Übersiedlung eines Vertragspartners abschließen

Durch diese Funktion kann der Vertragspartner die Übersiedlung einer Ordinationsadresse abschließen. Die ursprüngliche und die neue Ordinationsadresse werden im Zuge des Dialogaufbaus bekanntgegeben.
Im Zuge der Übersiedlung sollten eventuell vorhandene Offlinedaten übertragen werden, da es ansonsten zu einem Datenverlust kommen kann. Mittels des Parameters forceUebersiedlung kann festgelegt werden, ob bei der Durchführung der Funktion geprüft werden soll, ob für die Ordination noch Offlinedaten vorhanden sind (in diesem Fall wird eine entsprechende Fehlermeldung retourniert).
Hinweis: Die Prüfung erfolgt in diesem Fall für die Ordination und den Tätigkeitsbereich des Dialogaufbaus. Werden also im Zuge der Übersiedlung der Ordination Offlinedaten festgestellt, müssen die Daten jeweils separat mittels eines eigenen Dialogs für jeden Tätigkeitsbereich der Ordination übertragen werden.