# 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 Version 17 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 Dialog-ID) besitzt. Die Ermittlung erfolgt hierbei mittels der beim Dialogaufbau angegebenen Ordination-ID und Tätigkeitsbereich-ID.
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, für das Service relevante Parameterwerte des e-card-Regelwerks dynamisch mindestens einmal pro Dialog mit den angebotenen Methoden zu ermitteln.
Allgemeine Abfragefunktionen (für Parameter, die in mehreren Services Verwendung finden) sind im Service FDAS enthalten.

## Servicemanager Der direkt erreichbare (zentrale) Servicemanager ist 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!

## Online-/Offline-Status

Ob eine Verbindung für ein bestimmtes Service zum e-card System 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:
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.

# Funktionalität des BASE Service

## Benachrichtigungsmechanismus

Mit diesem Mechanismus können Nachrichten vom e-card System übertragen werden.
Über ein Flag, das periodisch abgefragt werden kann, wird signalisiert, dass eine neue Nachricht vorliegt. Neue Nachrichten können vom e-card System abgefragt werden.
Das Messaging-System dient u.a. zur Benachrichtigung über asynchron im e-card System 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 bestimmter Parameter des angemeldeten Dialogs:
Nachrichten KSE: in Abhängigkeit der beim Dialogaufbau verwendeten taetigkeitsBereichId.
Nachrichten ABS und eBS (eKOS): 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 kann bzw. hat.

### mittels Push-Mechanismus

Die Nachrichtenzustellung erfolgt dialoggebunden.
Die Information über neue Nachrichten wird mit jedem Request zum e-card System 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 dialoggebunden.
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 davon, 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.
Andernfalls 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 sich 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ünglichen und die neuen Ordinationsdaten werden im Zuge des Dialogaufbaus retourniert.
Vor Abschluss der Übersiedlung sollten eventuell offene Geschäftsfälle abgeschlossen werden, da es ansonsten vorkommen kann, dass der Zugriff auf bestimmte Daten verloren geht. 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.