English | Deutsch

Einführung

eauXchange ist ein eigenständiger Server für den Datenaustausch mit dem GKV-Kommunikationsserver. Er versendet und empfängt die Daten automatisch und zeitgesteuert, hält die Krankenkassendaten aktuell und verwaltet die öffentlichen Schlüssel der Kommunikationspartner.

Unterstützt werden zwei Verfahren, die getrennt lizenziert werden:

EAU (/eau)

elektronische Arbeitsunfähigkeitsbescheinigung.

Vorerkrankung / LFZ (/pre)

Vorerkrankungsanfragen für die Entgeltfortzahlung (Entgeltersatzleistungen).

Jede Installation liefert ihre eigene Dokumentation mit: Unter /help liegt die interaktive API-Referenz der laufenden Version, unter /changelog die Änderungen aller Versionen. Beides ist ohne Token erreichbar.

Lizenzierung

Die Lizenzdatei wird von der Javiis GmbH auf Anfrage erstellt. Dafür wird die Betriebsnummer (BNR) benötigt, für die die Lizenz ausgestellt wird – Test oder Produktion. Alle Anfragen werden anschließend für diese Betriebsnummern gestellt. (Im Testbetrieb wird die Test-Betriebsnummer verwendet.)

Die Lizenz bestimmt außerdem, welche Verfahren die Installation nutzen darf (EAU, Vorerkrankung oder beides). Aufrufe eines nicht lizenzierten Verfahrens werden abgewiesen.

Betrieb des Dienstes

eauXchange wird als Docker-Container ausgeliefert und speichert alle relevanten Informationen in einer PostgreSQL-Datenbank.

Folgende Dateien gehören in den Ordner config neben der docker-compose.yml:

  • application.yml – die Serverkonfiguration (siehe unten)

  • die Lizenzdatei der Javiis GmbH

  • Zertifikat und privater Schlüssel Ihrer Betriebsnummer (<bnr>.p7c / <bnr>.pkey), aus denen der Keystore gkv.p12 erzeugt wird

services:
  eauxchange:
    container_name: eauxchange_server
    image: www.eauxchange.de/eauxchange:latest
    ports:
      - "8085:8085"
    depends_on:
      - db
    environment:
      - SPRING_CONFIG_LOCATION=/opt/app/config/application.yml
      - DATABASE_CONNECTION=eauxchange_db
      - DATABASE_PORT=5432
    volumes:
      - ./config:/opt/app/config
  db:
    container_name: eauxchange_db
    image: postgres:14.12-bullseye
    restart: unless-stopped
    shm_size: 128mb
    environment:
      POSTGRES_DB: eauxchange
      POSTGRES_PASSWORD: <passwort>
      POSTGRES_USER: gkv_user
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
      - <EXTERNER_PFAD>:/var/lib/postgresql/data

Das Image liegt in der Registry www.eauxchange.de; die Zugangsdaten erhalten Sie zusammen mit der Lizenz. Das Datenbankschema wird beim Start automatisch angelegt und migriert.

Serverkonfiguration

Die Konfiguration steht in der application.yml im Ordner config. Die wichtigsten Einstellungen:

spring:
  datasource:
    username: gkv_user
    password: <passwort>
    url: jdbc:postgresql://eauxchange_db:5432/eauxchange

server:
  port: 8085

com:
  javiis:
    gkv:
      bnrTest: <Test-BNR>
      bnrProductive: <Produktiv-BNR>
      # true = es wird nichts an die Krankenkassen übertragen (Testbetrieb)
      dryRunning: true
      # false = Testzertifikat, true = Produktivzertifikat
      use_production_certificate: false
      product:
        manufacturer: <Firma>
        name: <Produktname>
        version: <Version>
        prodID: <Produktnummer>
        modID: <Modulnummer>
      contact:                       # technischer Ansprechpartner, geht mit jeder Anfrage mit
        name: Max Mustermann
        gender: M
        street: Musterstrasse
        streetNr: 74
        zip: 12345
        city: Berlin
        tel: 0123456789
        mail: kontakt@example.com
      keystore:
        test:
          path: /opt/app/config/test/gkv.p12
          password: <passwort>
          keyPassword: <passwort>
          alias: <BNR>
      receivePath: /opt/app/config/receive
      logSentFiles: true
      xmlLogPath: /opt/app/config/sent

Zeitpläne

Die Hintergrundjobs laufen nach Cron-Ausdrücken. Die Voreinstellungen passen in der Regel, überschreiben lässt sich jede davon:

Einstellung Vorgabe Aufgabe

com.javiis.gkv.send.request.cron

0 0 1 * * *

Versendet offene Anfragen an die Krankenkassen

com.javiis.gkv.status.request.cron

0 30 * * * *

Fragt beim GKV-Server neue Antworten ab und lädt sie herunter

com.javiis.gkv.eau.import.cron

0 35 * * * *

Importiert die heruntergeladenen Antwortdateien

com.javiis.gkv.sync.request.cron

0 45 * * * *

Ordnet Antworten ohne verwertbare Referenz ihrer Anfrage zu

com.javiis.gkv.certificate.expiry.cron

0 0 3 * * *

Prüft die Restlaufzeit der Kommunikationszertifikate
Statusabfragen dürfen nicht häufiger als alle 15 Minuten laufen (Vorgabe des GKV-Kommunikationsservers).

Benachrichtigungen

Mit com.javiis.gkv.mailSettings (host, port, sender, username, password, defaultRecipient) und com.javiis.gkv.sendEmailOnError: true werden Sie über Fehler in den Hintergrundjobs und über demnächst ablaufende Zertifikate informiert.

Anmeldung

Alle API-Aufrufe benötigen einen API-Token; nur die eingebaute Hilfe (/help, /api-docs) und die Release Notes (/changelog) sind frei zugänglich. Ein Token ist ein JWT, das für die Betriebsnummern gilt, für die es ausgestellt wurde, und ein Ablaufdatum trägt.

Den ersten Token erzeugen

  1. Beim allerersten Start legt der Server den Benutzer root an und schreibt dessen erzeugtes Passwort einmalig ins Log. Notieren Sie es; es wird nicht erneut angezeigt.

  2. Erstellen Sie mit diesem Benutzer einen API-Token (HTTP-Basic-Authentifizierung):

    curl -u root:<Passwort aus dem Log> \
     -X POST 'https://<host>/security/createAPIToken?expiryDate=2027-12-31T23:59:59&note=ERP' \
     -H 'Content-Type: application/json' \
     -d '["<BNR>"]'

  3. Verwenden Sie den zurückgegebenen Token bei jedem weiteren Aufruf:

    curl -X POST 'https://<host>/eau/getOpenEauResponses' \
     -H 'Authorization: Bearer <Token>'

Tokens lassen sich auflisten, deaktivieren, wieder aktivieren und löschen (/security/getTokens, /security/disableTokens, /security/enableTokens, /security/deleteTokens).

Eine Anfrage, deren Betriebsnummer nicht vom Token abgedeckt ist, wird mit HTTP 403 abgewiesen. Wenn eine neue Betriebsnummer dazukommt, stellen Sie einen neuen Token dafür aus – sonst bleiben diese Anfragen unversendet liegen.

Verwendung des Dienstes

Die vollständige Liste der Aufrufe und Datenstrukturen finden Sie in der eingebauten Hilfe Ihrer Installation unter /help. Sie dokumentiert genau die Version, die bei Ihnen läuft.

Eine eAU-Anfrage anlegen

In der eingebauten Hilfe: createEauRequests

Für eine eAU-Anfrage wird ein Objekt vom Typ EauRequest gesendet. Das Feld startDate bezeichnet den Beginn der Abwesenheit. Bleibt das Feld contactPerson leer, wird der zum Zeitpunkt der Erstellung hinterlegte Standard-Ansprechpartner verwendet. Die Antwort enthält pro gesendeter Anfrage einen Fehlercode (NONE, wenn die Anfrage erfolgreich eingeplant wurde).

operation::createEauRequests[snippets='http-request,http-response']

Eine eAU-Antwort abholen

In der eingebauten Hilfe: getOpenEauResponses

Offene eAU-Antworten holen Sie mit der Methode getOpenEauResponses ab. Zurückgegeben werden alle Antworten, die noch nicht als geprüft markiert sind.

operation::getOpenEauResponses[snippets='http-request,http-response']

Eine eAU-Antwort als erledigt markieren

In der eingebauten Hilfe: markEauResponsesAsChecked

Um Datenverlust zu vermeiden, müssen alle abgeholten eAU-Antworten anschließend als erledigt markiert werden. Das geschieht über die Methode markEauResponsesAsChecked.

operation::test-mark-eau-responses-as-checked[snippets='http-request,http-response']

Eine eAU-Anfrage stornieren

In der eingebauten Hilfe: stornoEauRequest

Mit stornoEauRequest brechen Sie eine eAU-Anfrage ab. Noch nicht übertragene Anfragen werden sofort verworfen, bereits versendete werden für die Stornierung im nächsten Abgleich vorgemerkt.

operation::stornoEauRequest[snippets='http-request,http-response']

Anfragen erneut senden

scheduleEauRequestsForResend stellt Anfragen erneut ein, etwa wenn eine Krankenkasse eine Wiederholung angefordert hat. scheduleEauRequestsForResendWithContactPerson macht dasselbe und ersetzt dabei den technischen Ansprechpartner – der richtige Aufruf, nachdem sich die Kontaktdaten geändert haben.

Anfragen und Antworten suchen

getOpenEauRequests liefert alles, was noch auf eine Antwort wartet. findEauRequestByCriteria und findEauResponseByCriteria suchen nach frei kombinierbaren Kriterien (Name, Versichertennummer, Zeitraum, Status). getEauRequest und getEauResponseFromRequestID holen einen einzelnen Datensatz.

Bleibt eine Anfrage offen, obwohl die Antwort bereits eingegangen ist, ordnet syncResponsesWithRequests offene Antworten ihren Anfragen zu. Dasselbe läuft automatisch (siehe Zeitpläne oben).

Sende- und Abholjob manuell ausführen

In der eingebauten Hilfe: manualexecuteRequestSending

Mit den Methoden manualExecuteRequestSending und manualExecuteStatusRequest unter /common stoßen Sie das Senden beziehungsweise Abholen von Hand an. Üblicherweise braucht man das zum Testen oder wenn eine Antwort vor dem nächsten geplanten Lauf benötigt wird.

operation::manualExecuteStatusRequest[snippets='http-request']

Vorerkrankungsanfragen (LFZ)

Setzt die Vorerkrankungs-Lizenz voraus. Der Ablauf entspricht dem EAU-Verfahren und nutzt die Endpunkte unter /pre.

  1. createPreexistingConditionInfoRequests plant die Anfragen ein. Doppelte Anfragen – gleiche Person, gleicher Zeitraum – werden sofort mit einer erklärenden Fehlermeldung abgewiesen, statt zweimal versendet zu werden.

  2. getOpenPreexistingConditionInfoRequests listet alles auf, was noch auf eine Antwort wartet.

  3. getOpenPreexistingConditionInfoResponses liefert die noch nicht als geprüft markierten Antworten. Der optionale Parameter limit begrenzt die Anzahl der Datensätze.

  4. markResponseAsChecked bestätigt die Verarbeitung, genau wie im EAU-Verfahren.

getPreexistingConditionInfoRequest, getPreexistingConditionInfoResponse und findPreexistingConditionInfoRequestsByAbAGDate holen einzelne Datensätze oder suchen nach dem Datum der Arbeitgeberanfrage.

Eine Antwort nachvollziehen

Zu jeder Anfrage stehen die von der Krankenkasse gelieferten Daten roh und aufbereitet zur Verfügung: getRawRequest, getRawResponse, getRawResponseByRequest, getRawErrorResponse sowie die entsprechenden getParsed…​-Methoden. Das ist der schnellste Weg, eine Ablehnung ohne Support-Anfrage zu klären – der Ablehnungsgrund der Krankenkasse ist Teil der Antwort.

Prüfdienst

Der Server prüft Betriebsnummern und Versichertennummern nach den üblichen Prüfregeln (/validation/companyBnr, /validation/insuranceNr). Mehr dazu: In der eingebauten Hilfe: validateInsuranceNr

Krankenkassen

Die Krankenkassendaten werden normalerweise automatisch abgeglichen. Sie können den Abgleich mit triggerInsuranceCompanyRefresh unter /insuranceCompany auch von Hand anstoßen. Dabei werden alle Krankenkassen, ihre öffentlichen Schlüssel und die Zuordnung zu ihren Datenannahmestellen aktualisiert. findInsuranceCompanyByBnr, findInsuranceCompanyByCriteria und getAllValidInsuranceCompanies lesen die Daten.

Hinweise für den Betrieb

Welche Version läuft?

/changelog zeigt die Version der Installation und die Änderungen aller Versionen; /changelog.json liefert dieselben Angaben maschinenlesbar.

Eine Antwortdatei ließ sich nicht importieren

Nicht verarbeitbare Dateien bleiben erhalten. reimportFailedResponses verarbeitet sie erneut, nachdem die Ursache behoben ist; manualTriggerResponseImports stößt den Import aller heruntergeladenen Dateien an.

Es wird nichts übertragen

Prüfen Sie dryRunning (im Produktivbetrieb false), die Auswahl des Zertifikats (use_production_certificate) und ob der API-Token die Betriebsnummer der Anfragen abdeckt.

Zertifikate

Die Restlaufzeit wird täglich geprüft. Mit konfigurierten Mail-Einstellungen kommt die Warnung früh genug, um das Zertifikat vor dem Stillstand der Übertragung zu tauschen.

Dateifolgenummer nachsehen

Dafür ist POST /dav/getCurrentDAVFileCounter da – der liest nur. Der zurückgegebene Wert ist die Nummer der zuletzt erzeugten Datei. Jede Datenannahmestelle führt je Verfahren einen eigenen Zähler: Der optionale Parameter procedure wählt ihn aus, EAA (Vorgabe) für die eAU und EEL für Vorerkrankungsanfragen. Das Modul des Verfahrens muss lizenziert sein – EAA setzt EAU voraus, EEL das Modul VORERKRANKUNG –, sonst antwortet der Server mit 403.

POST /dav/drawNextDAVFileCounter zieht die nächste Nummer und verbraucht sie. Die Nummer lässt sich nicht zurückgeben, und keine Ihrer Dateien trägt sie. Verwenden Sie den Aufruf nur in Wiederherstellungssituationen, niemals zum Nachsehen eines Wertes. Der ältere Pfad getCurrentFileCounterForBnr macht dasselbe und funktioniert weiter, ist aber als veraltet gekennzeichnet – sein Name klingt wie eine Abfrage, obwohl der Aufruf Daten ändert.