# Vertragspartner-Software SOAP Schnittstelle 24a

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 Service-Managers.
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).

GINA-Service (GINA)
Package | Description
--- | ---
at.chipkarte.client.gina.soap | Interface und Klassen des GINA-Service (GINA).

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 Sozialversicherungsnummernabfrageservice (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äoperative 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 (eBS).
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-Testszenarienverwaltung f�r ELGA (ELGATSV)
Package | Description
--- | ---
at.chipkarte.client.elgatsv.soap | Interface und Klassen der ELGA-Testszenarienverwaltung (ELGATSV).
at.chipkarte.client.elgatsv.soap.constants | Dieses Package enthält die Konstanten für die e-card-Testszenarienverwaltung für ELGA (ELGATSV).
at.chipkarte.client.elgatsv.soap.exceptions | Dieses Package enthält die Exceptions für die e-card-Testszenarienverwaltung für ELGA (ELGATSV).

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.

## Hinweis bzgl. der Verwendung bestimmter Begriffe:

Es erfolgte in den Fehlermeldungen und auf der GUI des e-card-Systems (eCS) ein Wording-Umstieg für folgende Begriffe:

Wording vorher | Wording nachher
--- | ---
SV-Person | Patient bzw. Proband (im VU-Bereich)
SVT SV-Träger Sozialversicherungsträger | KVT KV-Träger (bevorzugt) Krankenversicherungsträger
ASVG (im Bezug auf Ansprüche) | GKK/BKK
o-card Ordinationskarte | Admin-Karte
Pseudo-o-card | Pseudo-Admin-Karte
Ordinationskartennummer | Admin-Kartennummer
Ocard-ID | Admin-Karte-ID
Ordination | Standort
Ordinationsadresse | Standortadresse
Ordinationsnummer | Standortnummer
ONR | StNr
Ordinationsverlegung | Übersiedlung

Wichtig: Anzeigetexte aus Regelwerksabfragen (z.B. Behandlungsfälle (KSE), Rückdatierungsgründe (AUM),... ) sind unverändert anzuzeigen!
Es wird zwecks Vereinheitlichung und leichterer Bedienbarkeit empfohlen dieselben Begriffe in der Vertragspartnersoftware (VPSW) zu verwenden.
In den Beschreibungen der Javadoc werden, um die Verständlichkeit und die Lesbarkeit zu erleichtern, im Text jeweils die männlichen Formulierungen (Patient, Vertragspartner, Arzt, ...) verwendet.
Die Formulierungen gelten gleichermaßen für Frauen und Männer.

## Einsatz der Vertragspartnersoftware:

Ausgewählte Funktionen des e-card-Systems werden für die Vertragspartnersoftware ü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) für die Verwendung zur Verfügung.
Mit dem Projekt GINAaaS erfolgt eine Schrittweise Umstellung der Services auf reine Server Projekte.
D.h. es erfolgt eine Ablöse der GINA. Bestehende Services die bereits umgestellt wurden, sind sowohl über die GINA als auch über den Server verfügbar.
Die Abfrage der URLs zu den einzelnen Services erfolgt mittels des ServiceManagers.
Bei Verwendung des Servicemanagers über die GINA (<gina-adresse>) werden die auf der GINA bzw. dem GINA-Proxy verfügbaren Services retourniert.
Weitere Informationen über die Nutzung des GINA Proxys erhalten Sie auf Anfrage beim Partnersupport.
Für die Abfrage der zentralen Services ist der Servicemanager 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!
Hinweis: Zusätzlich zu den verfügbaren SOAP Services werden auch Informationen über die verfügbaren REST Services retourniert.
Für die Produktion gilt: Der "direkte" Aufruf über den Server ist aktuell nur bei Verwendung des GINA Proxys möglich.
In der VPSWH-Umgebung erfolgt ein direkter Zugriff auf die zentralisierten Services.
Man unterscheidet folgende vier Basis-Services:

- BASE
- AUTH
- FDAS
- GINA

BASE:
Funktionalität für die Serviceverfügbarkeitsabfrage, der Ordinationsübersiedlung, dem Message-, dem Vertrags- und dem Berechtigungshandling.
AUTH:
Funktionalität um einen Dialog aufzubauen und zu beenden.
FDAS:
Abfrage-Funktionalität für dynamische Werte aus dem Regelwerk.
GINA:
Funktionalität zur Verwaltung der GINA und der Kartenleser.
Hinweis: Mit Abschluss des Projektes GINAaaS (wenn alle Services auf reine Server-Sevices umgestellt sind), wird dieses Service nicht mehr benötigt werden (da dann die GINA nicht mehr benötigt wird). Genauere Informationen wie auf die Daten danach zugegriffen werden kann, werden zeitgerecht bereitgestellt werden.
Das GINA Service bietet die Möglichkeit der Kartenleserverwaltung (Abfrage der Kartenleser).
Der Zugriff auf den Kartenleser wird nicht über das GINA Service zur Verfügung gestellt (und auch nicht über ein anderes SOAP Service).
Für die Kommunikation mit dem LANCCR ist folgendes REST Service zu verwenden: Swagger Doku LANCCR.
Die Schnittstelle dient zum Auslesen von Kartendaten, dem Erstellen von Signaturtoken, der Kartenleserüerwachung (Ablöse von "getReaderStatusEvent()"), usw.
Die Kommunikation per REST erfolgt aktuell über die GINA. Mit einer späteren Release wird dies umgestellt, sodass die Kommunikation direkt mit dem Kartenleser erfolgt (neue Kartenlesergeneration - GINO).
Hinweis: Durch die spätere Umstellung der Kommuniktation direkt mit dem Kartenleser ändert sich nur die Aufruf-URL (Host).
Folgende Funktionalitäten sind durch die VPSW selbst mittels der angebotenen REST Schnittstelle selbst zu verwalten:

- Karten-Handling (Lesen, 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 für 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.
Der zu verwendende Port ist 443. Die zu verwendende URL wird vom Service-Manager zurückgeliefert.
Das Ergebnis wird über einen HTTPS-Response zurückgeliefert.
Die Verarbeitung einlangender Requests innerhalb eines Dialoges 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 wurde und eine entsprechende Response geliefert wurde. Bei vielen "gleichzeitigen" Requests innerhalb desselben Dialogs (mit derselben DialogID) besteht daher die Gefahr von langen Wartezeiten bzw. von Timeouts.
Zusätzlich besteht von Seiten des e-card Systems die Möglichkeit die Anzahl gleichzeitiger Requests von einem Vertragspartner zu begrenzen wenn festgestellt wird, das zuviele Request 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 (int, 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 auf der Clientseite, 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:
Um das Hängenbleiben der Vertragspartnersoftware aufgrund von Fehlersituationen bei der Durchführung von Funktionen zu verhindern, sollten die Funktionsaufrufe mittels Timeout-Steuerung überwacht werden. Die angebotenen Funktionen werden bezüglich ihrer Laufzeit in drei Gruppen unterteilt:

Kurz | ...... | Funktionen die nur lokal auf der GINA ausgeführt werden
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
--- | ---
Kurz | >= 15 s
Mittel | >= 60 s
Lang | >= 1500 s

In der technischen Schnittstellenbeschreibung (Javadoc) ist für angebotene Funktion 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 keiner Rückmeldung an die VPSWH, kann es passieren, dass dem Benutzer nicht bekannt ist wie weit der Request gekommen ist.
Aus diesem Grund gibt es die Möglichkeit denselben Request nochmals zu senden.
Ist der erste Versuch bereits am Server verarbeitet worden, wird einfach die Antwort zurückgeschickt, die eigentlich bereits für den ersten Request zurückkommen hätte sollen, ohne den Request ein zweites Mal zu verarbeiten.
Um dabei den Request eindeutig identifizieren zu können, muss beide Male dieselbe TransactionId im Message-Header des Request 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]." dokumentiert.
Die TransactionId ist von der Vertragspartnersoftware zu generieren und hat folgende Anforderungen:

- Für jeden neuen Request muss eine eigene TransactionId erzeugt werden
- Darf weder mit null noch mit einem Leerstring versorgt werden
- 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 mehr als einer Vertragspartnersoftware, muss jede Software ihre eigenen TransactionIds verwenden
- Bei der Wiederholung eines Request, muss die TransactionId bei jedem Versuch dieselbe sein

Die Verwendung der TransactionId ist aktuell (Stand R23b) noch optional. Es wird jedoch bereits jetzt empfohlen die TransactionId bei jedem Aufruf zu versorgen, da in einer späteren Release die Angabe verpflichtend werden wird.
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 im 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>
  Hinweis: Wird der Request Failover-fähig erzeugt, ist bereits jetzt im Response die Confirmation der TransaktionsId enthalten!

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 Ansprüche in die Vergangenheit mittels VDAS werden Daten aus einem Drittsystem geliefert – ohne Doppellieferung der Namensdaten bei abgeleiteten Ansprüchen.

## Exkurs - das e-card-System:

Das e-card-System unterteilt sich in ein Zentralsystem, das in einem Rechenzentrum läuft und (aktuell) den Ordinationsclients, die direkt beim Vertragspartner untergebracht sind. Der Ordinationsclient ist ein dedizierter Client (Hardware und Software) und ist die Schnittstelle zum Zentralsystem für die Endanwender beim Vertragspartner. Die Vertragspartnersoftware wird ebenfalls über den Ordinationsclient eingebunden.
Mit dem Projekt GINAaaS erfolgt eine Schrittweise Umstellung der Services auf reine Server Projekte. D.h. es erfolgt eine Ablöse der GINA. Services die bereits umgestellt wurden, sind sowohl über die GINA als auch über den Server verfügbar. Neue Services werden nur über den GINA Proxy aufrufbar sein. Für die Produktion gilt: Der "direkte" Aufruf über den Server ist aktuell nur bei Verwendung des GINA Proxys möglich. Weitere Informationen über die Nutzung des GINA Proxys erhalten Sie auf Anfrage beim Partnersupport. In der VPSWH-Umgebung erfolgt ein direkter Zugriff auf die zentralisierten Services.
Überblick über die Komponenten des Gesamtsystems

### Die allgemeinen Komponenten des Gesamtsystems:

Ordinationsclient / GINA
Mit dem Projekt GINAaaS erfolgt eine Schrittweise Umstellung der Services auf reine Zentralsystem Projekte. D.h. es ist eine Ablöse der GINA geplant.
Bestehende Services die bereits umgestellt wurden, sind sowohl über die GINA als auch über den Server verfügbar. Neue Services werden nur über den GINA Proxy aufrufbar sein. Für die Produktion gilt: Der "direkte" Aufruf über den Server ist aktuell nur bei Verwendung des GINA Proxys möglich. In der VPSWH-Umgebung erfolgt ein direkter Zugriff auf die zentralisierten Services.
Weitere Informationen über die Nutzung des GINA Proxys erhalten Sie auf Anfrage beim Partnersupport.
LANCCR
Diese Komponente ist für die Anbindung der Kartenleser verantwortlich und bietet Dienste zur Nutzung der Kartenfunktionen (z.B. Kartendaten lesen und Signaturerstellung) an. Der LANCCR kann mittels REST Service verwendet werden.
Clientverwaltung, Softwareverteilung, Fernwartung
Die Softwareverteilung ist ein Mechanismus am Ordinationsclient, der zu bestimmten Zeitpunkten die Aktualität der Software am Ordinationsclient prüft und falls erforderlich aktualisiert.
Die Clientverwaltung ist ein weiteres Subsystem des Zentralsystems. Insbesondere sind in diesem System alle erforderlichen Mechanismen zur Softwareverteilung (Updates) und deren Überwachung auf den Ordinationsclient zusammengefasst.
Mit Ablöse der GINA werden auch diese Mechanismen entfallen und bei Bedarf durch andere Mechanismen / Schnittstellen ersetzt.

## Technische Details:

Kodierung:

SOAP-Requests müssen UTF-8 kodiert gesendet werden.

Request Größe:

Um das eCS 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 kein SOAP-Response.

Kennzeichnung optionaler Parameter im WSDL:

Ein 'nillable = "true"' bedeutet, dass das Feld im SOAP-Response/-Request nicht unbedingt befüllt sein muss – es kann leer bleiben.

Ein 'minOccurs="0"' bedeutet, dass das Feld im SOAP-Response/-Request 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 Vertragspartnersoftware zu verwenden. Dadurch wird die Fehleranalyse vereinfacht.

Angabe der DialogId:

Bei Angabe der DialogId in einem SOAP-Request dürfen keine weiteren Attribute im dialogId-Tag enthalten sein.
D.h.: <dialogId>dialogId</dialogId>

Physikalische Schnittstelle:

Ethernet

Protokoll:

HTTPS / SOAP

Sicherheit der Schnittstelle:

Für die Verbindung über Ethernet zwischen Ordinationsclient und Vertragspartnersoftware wird SSL mit serverseitiger Authentifizierung mit RSA / 2048 Bit Verschlüsselung verwendet. Vor dem ersten Zugriff auf die Vertragspartnersoftware-Schnittstelle muss das Zertifikat für die Authentisierung des Ordinationsclients verteilt werden.
Der Ordinationsclient stellt folgende Zertifikate für die Vertragspartnersoftware zur Verfügung:

⇒ Root Zertifikat (im X.509 V3 Format)
• Produktiv
º http://<GINA-ADRESSE>/ecard/certificates/Zert_CA_Root_V02_Prod.cer
º http://<GINA-ADRESSE>/ecard/certificates/Zert_CA_Root_V02_Prod.pem
• Test (VPSWH)
º http://<GINA-ADRESSE>/ecard/certificates/Zert_CA_Root_V02_Test.cer
º http://<GINA-ADRESSE>/ecard/certificates/Zert_Ca_Root_V02_Test.pem
⇒ GINA CA Zertifikat (abgeleitet vom Root Zertifikat)
• Produktiv
º http://<GINA-ADRESSE>/ecard/certificates/Zert_CA_ECS_V02_Prod.cer
º http://<GINA-ADRESSE>/ecard/certificates/Zert_CA_ECS_V02_Prod.pem
• Test (VPSWH)
º http://<GINA-ADRESSE>/ecard/certificates/Zert_CA_ECS_V02_Test.cer
º http://<GINA-ADRESSE>/ecard/certificates/Zert_CA_ECS_V02_Test.pem

Beim Verbindungsaufbau der Vertragspartnersoftware zum Ordinationsclient wird eine SSL-Session initiiert. Dabei werden die erforderlichen Zertifikate (unter Verwendung des "GINA CA" Zertifikats, welches vom "Root" Zertifikat abgeleitet wurde) zum Ordinationsclient transferiert.
Für die Kommunikation unter HTTPS sind die oben angegebenen Zertifikate zu verwenden.
Achtung: Es ist zu beachten, daß für die Kommunikation in der VSPWH-Umgebung die "Test"-Zertifikate und für die Kommunikation in der Produktiv-Umgebung die "Prod"-Zertifikate zu verwenden sind!
Der Import des im Browser unter https://<GINA-ADRESSE>/ angebotenen Zertifikats in den Betriebssystem-Zertifikatsspeicher, ist nicht zu empfehlen.

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 bei 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 Vertragspartnersoftware selbst zu versorgen. Wichtig ist hierbei, dass die 'cid'-Referenz mit der Content-ID des angehängten Attachments übereinstimmt.
Bei den Services ABS und EBS werden Attachments bis zu einer Größe von 3MB (3245728 Byte / 3,095 MByte) unterstützt. Dabei gilt die Summe aller Anlagen innerhalt des zu übergebenden ZIP-Archivs im ungepackten Zustand. Bis zu einer Größe von gesamt 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).
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 bei 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 Attachment werden durch das e-card-System gesetzt. Diese ID wird dabei bei jedem Request neu erzeugt und ist nicht in der Vertragspartnersoftware zu speichern!
Bsp.:
<xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:internGesetzteCid"/>
.....
.....
.....
Content-ID: <internGesetzteCid>