eauXchange Getting Started Guide

Introduction

eAUXchange is a dedicated server established for interaction with the GKVKomServer. It supports automatic and scheduled sending and receiving of eAUs, keeping insurance company information up to date and tracking public keys of communication partners.

Licensing

The license file is created by Javiis GmbH upon request. For this, the company number (BNR) (test or production) for which a license is issued is required. All eAU requests are then sent for this company number. (For test mode, the test company number is used)

Running the service

eAUXchange is also delivered as a Docker container. It uses a postgres database to store all relevant information Instructions to run this container are as follows.

First, create a docker-compose.yml file, then add the following files to the config folder:

<bnr>.license
<bnr>.p7c (certificate)
<bnr>.pkey (private key)
application.properties

version: '3.9'

services:
  eauxchange:
    container_name: eauxchange_server
    image: eauxchange:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
    volumes:
      - ./config:/opt/app/config
  db:
    container_name: eauxchange_db
    image: postgres:14.12-bullseye
    restart: unless-stopped
    shm_size: 128mb
    environment:
      POSTGRES_DB: gkvapi
      POSTGRES_PASSWORD: test1234
      POSTGRES_USER: gkv_user
    ports:
      - "5432:5432"
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
      - <EXTERNAL_PATH>:/var/lib/postgresql/data

In this configuration, the eAUXchange Docker container exposes port 8080 for accessing the application. The data directory on the host is mounted into the /data directory in the container. Similarly, the config directory on the host system is mounted into the /config directory inside the Docker container.

Server Configuration

To configure the server, you can make the following adjustments in the 'application.properties' file in the config folder.

Set the username and password according to the docker compose configuration
Set the sendInterval for eAU requests in Cron job notation.
Set the eauresponseInterval for querying for eAU responses in Cron job notation.
Set the testMode to enable the testmode (Requests will be sent to the evpt testserver: EVPT Testserver

Both sendInterval and eauresponseInterval must not be less than every 15 minutes (GKV restriction). Find an example of a gkv.properties file below.

spring.datasource.username=gkv_user
spring.datasource.password=test1234
com.javiis.gkv.sendInterval=0/15 * * * *
com.javiis.gkv.eauResponseInterval=0/15 * * * *
com.javiis.gkv.testMode=true

How to use the service

For a detailed list of API calls and schemas visit:

API Reference

Creating an eAU request

Detailed reference

To schedule an eAU request, an object of EauRequest type is sent. The startDate field refers to the point in time when the absence was taken. If the field contactPerson is empty, the default set contact person at creation time will be used. The response will be an errorCode per request sent (NONE) if request is scheduled successfully)

HTTP request

POST /eau/createEauRequests HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 511
Host: localhost:8080

[ {
  "lastname" : "Sauer",
  "firstname" : "Friedrich",
  "gender" : "M",
  "externalID" : "0152",
  "insuranceNumber" : "63250769S494",
  "companyIdentifier" : "99301347",
  "insuranceCompanyIdentifcationNumber" : "99300660",
  "startDate" : "2023-01-01",
  "contactPerson" : {
    "nameAnsprechpartner" : "Max Mustermann",
    "telefonAnsprechpartner" : "0123456789",
    "name1" : "Firma XYZ",
    "name3" : "Abteilung IT",
    "plz" : "12345",
    "ort" : "Musterstadt"
  },
  "birthday" : "2024-07-30"
} ]

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 42

[ "f042f3bd-95ee-480e-bc80-017203698c4e" ]

Retrieving an eAU response

Detailed reference

You can retrieve open eAU responses with the method getOpenEauResponses. All eAU requests that are not marked as checked are retrieved.

HTTP request

POST /eau/getOpenEauResponses HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3

[ ]

Marking an eAU response as finished

Detailed reference

In order to avoid data loss, all eAU responses must be marked as completed once they are retrieved from the server. This status update is achieved by invoking the markEauResponsesAsChecked method.

HTTP request

POST /eau/markEauResponsesAsChecked HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 40
Host: localhost:8080

["47413653-bf02-4583-838d-9871e0f105dd"]

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4

true

Schedule eAU cancellation

Detailed reference

You can abort an eAU request by invoking the stornoEauRequest method. eAU requests that have not yet been transmitted will be obliterated instantly, while requests that have already been dispatched will be queued for cancellation during the next synchronization process.

HTTP request

POST /eau/stornoEauRequest HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 38
Host: localhost:8080

"80a42f79-3c07-4c4d-a981-5371aa168fa5"

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4

true

Execute sending/retrieving job manually

Detailed reference

You have the option to initiate a manual send or retrieve task by invoking the methods: manualExecuteRequestSending and manualExecuteStatusRequest. Typically, these methods are utilized exclusively for testing purposes.

HTTP request

POST /eau/manualexecuteRequestSending HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

HTTP request

POST /eau/manualExecuteStatusRequest HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Use the validation service

The server provides methods for validation insurance company numbers and employee insurance numbers according to standard validation rules: More information: ValidationApi

Syncing available Insurance companies

The insurance company data is ordinarily synchronized automatically, however, you also have the opportunity to manually trigger this synchronization by calling the triggerInsuranceCompanyRefresh method. This action updates all insurance companies and their public keys, in addition to their associations with their respective DAVs.