Skip navigation links

Vertragspartner-Software SOAP Schnittstelle Release

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 vorherWording nachher
SV-PersonPatient 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-cardPseudo-Admin-Karte
OrdinationskartennummerAdmin-Kartennummer
Ocard-IDAdmin-Karte-ID
OrdinationStandort
OrdinationsadresseStandortadresse
OrdinationsnummerStandortnummer
ONRStNr
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.

Technische Anbindung

Ü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.

LaufzeitgruppeEmpfohlerTimeout-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.

Gesamtsystem

Ü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>

Skip navigation links