Hilfe zur Anbindung der perimed puls-Schnittstellen

REST API

Mit Hilfe der REST API können aus Ihrer eigenen KIS/PVS Anwendung heraus Patientenaufklärungsbögen mit Patientendaten versehen und heruntergeladen werden. Die heruntergeladenen Bögen stehen in Ihrer Anwendung als PDF zur Verfügung. Diese können mit einem passenden Programm (vgl. Acrobat Reader) angezeigt oder direkt gedruckt werden.

Die REST API ist für die Integration in bestehende (Intranet-) Anwendungen gedacht. Die Implementierung erfordert nicht zwingend eine Webanwendung bzw. einen Browser für den Zugriff auf das perimed Portal. Solange ein Internetzugriff (mit oder ohne Proxy) und ein passender HTTP-Client für die gewünschte Programmiersprache zur Verfügung stehen, können Sie die REST API in Ihr Produkt integrieren (Backend-Integration).
Natürlich kann die REST API auch per JavaScript/TypeScript direkt aus einer Webanwendung heraus verwendet werden (Frontend-Integration).

Unter einer REST API versteht man eine HTTP-Schnittstelle die von einem beliebigen Programm (mit Internetzugriff) angesprochen werden kann (vgl. https://de.wikipedia.org/wiki/Representational_State_Transfer).

Unsere REST API umfasst momentan folgende Funktionen:

• Eine Liste aller verfügbaren Bögen abfragen GET /api/v1/bogen
  
• Details zu einem Bogen abfragen GET /api/v1/bogen/{bogenId}
• Die meistgedruckten oder neuesten Bögen abfragen GET /api/v1/bogen/meistgedruckt
• Eine Liste aller Fachgebiete inklusive referenzierter Unterfachgebiete und Bögen abfragen GET /api/v1/fachgebiet
• Details zu einem Fachgebiet abfragen GET /api/v1/fachgebiet/{fachgebietId}
• Details zu Ihrem Account abfragen GET /api/v1/meinaccount
• Favoriten zu Ihrem Account verwalten (Abfragen, Hinzufügen, und Löschen) GET /api/v1/meinaccount/favorit
• Ihre Online-Druckhistorie abfragen GET /api/v1/meinkunde/druckhistorie
• Details zu einem Online-Druck abfragen GET /api/v1/meinkunde/druckhistorie/{druckJobId}
• Einen bestimmten Patientenaufklärungsbögen mit Patientendaten als PDF drucken POST /api/v1/onlinedruck/{bogenId}/drucken
• Patientendaten validieren (Pflichtfelder und Syntax) POST /api/v1/onlinedruck/validieren
• Bögen per Volltextsuche finden GET /api/v1/suche?query={Suchbegriff}

Swagger UI Dokumentation zu unserer REST API

Unsere REST API Schnittstellen sind mit Hilfe der OpenAPI Spezifikation v3 dokumentiert. Sie finden die Dokumentation inklusive einer Benutzeroberfläche zum Ausprobieren unter perimed Portal Swagger API Beschreibung.

In der Beschreibung der einzelnen Schnittstellen finden Sie die URLs, die benötigten Parameter, die Beschreibung der Request- und Response-Objekte, die Authentifizierungsmethoden und vieles mehr. Anhand der Try it out Beispiele können Sie direkt in der Oberfläche die verschiedenen Schnittstellen testen.

Mit Hilfe dieser Dokumentation können Sie mit etwas Programmieraufwand unsere REST API aus Ihrer Anwendung heraus aufrufen.

Generierung eines REST API Clients für Ihre Anwendung

Mit Hilfe des Swagger Editors (vgl. Swagger Editor zum Generieren eines API Clients) ist es möglich sich mit wenigen Handgriffen einen passenden Client zur OpenAPI Schnittstellenbeschreibung des perimed Portals generieren zu lassen. Dabei werden verschiedenste Programmiersprachen unterstützt - ein kleiner Auszug daraus:

• C#
• Java
• JavaScript
• TypeScript
• php
• python
• swift
• und viele mehr

Klicken Sie im Swagger Editor einfach oben rechts auf den Menüpunkt Generate Client und folgen Sie den Anweisungen der Anwendung. Nach der erfolgreichen Generierung eines passenden Clients integrieren Sie die erzeugten Artefakte in Ihre Anwendung.

Code-Beispiele für die Verwendung der REST API

Java-Code (ab JDK11) ohne JSON-Serializer (wie z.B. Jackson oder GSON)

package de.perimed.api.onlinedruck;

import org.junit.jupiter.api.Test;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import java.util.Base64;

/**
 * Implementierung als JUnit5 (Juniper) Test
 */
class OnlineDruckResourceIT {

    // ID: 612, BogenCode: "AnAa008De", Name: "Narkose und/oder Regionalanästhesie bei Erwachsenen und Jugendlichen"
    private static final int BOGEN_ID = 612;

    private static final String BENUTZERNAME = "Ihre perimed Benutzername";
    private static final String PASSWORT = "Ihr perimed Passwort";
    private static final String AUTHORIZATION_HEADER = "Basic " + Base64.getEncoder().encodeToString((BENUTZERNAME + ":" + PASSWORT).getBytes());

    @Test
    void validierenUndOnlineDruck() throws Exception {
        // einfaches JSON ohne wie Serializer-Libraries wie Jackson oder GSON
        String jsonBody = "{\"vorname\": \"$vorname\", \"nachname\": \"$nachname\", \"geburtsdatum\": \"$geburtsdatum\", \"anmerkungen\": \"$anmerkungen\" }"
                .replace("$vorname", "Max")
                .replace("$nachname", "Mustermann")
                .replace("$geburtsdatum", "1982-06-27")
                .replace("$anmerkungen", "Dies ist eine ärztliche Anmerkung zum Test\\n\\nNoch eine weitere Zeile nach einer Leerzeile");

        if (isValidOnlinedruck(jsonBody)) {
            byte[] pdfContent = onlinedruck(jsonBody, BOGEN_ID);

            Path outputFilePath = Files.createTempFile("AnAa008De_", ".pdf");
            Files.write(outputFilePath, pdfContent);

            System.out.printf("Bogen PDF [%s] erfolgreich gespeichert %n", outputFilePath);
        }
    }

    private boolean isValidOnlinedruck(String jsonBody) throws Exception {
        HttpRequest httpRequest = HttpRequest.newBuilder()
                .uri(new URI("https://www.perimed.de/portal/api/v1/onlinedruck/validieren"))
                .header("Authorization", AUTHORIZATION_HEADER)
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .timeout(Duration.of(5, ChronoUnit.SECONDS))
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();

        HttpResponse<String> httpResponse = HttpClient.newHttpClient()
                .send(httpRequest, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));

        System.out.printf("POST Request auf [%s] - Response: Status [%d] Body [%s]%n",
                httpRequest.uri(),
                httpResponse.statusCode(),
                httpResponse.body());

        return httpResponse.statusCode() == 200;
    }

    private byte[] onlinedruck(String jsonBody, int bogenId) throws Exception {
        HttpRequest httpRequest = HttpRequest.newBuilder()
                .uri(new URI(String.format("https://www.perimed.de/portal/api/v1/onlinedruck/%d/drucken", bogenId)))
                .header("Authorization", AUTHORIZATION_HEADER)
                .header("Content-Type", "application/json")
                .header("Accept", "application/pdf")
                .timeout(Duration.of(5, ChronoUnit.SECONDS))
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();

        HttpResponse<byte[]> httpResponse = HttpClient.newHttpClient()
                .send(httpRequest, HttpResponse.BodyHandlers.ofByteArray());

        System.out.printf("POST Request auf [%s] - Response: Status [%d]%n",
                httpRequest.uri(),
                httpResponse.statusCode());

        if (httpResponse.statusCode() != 200) {
            throw new RuntimeException(String.format("OnlineDruck lieferte Status [%d] zurück", httpResponse.statusCode()));
        }

        return httpResponse.body();
    }
}
        

bash script - validiert und druckt den gewünschten Bogen in eine temporäre Datei

#!/bin/bash

BENUTZERNAME="Ihr perimed Benutzername"
PASSWORT="Ihr perimed Passwort"

JSON_BODY='{"vorname": "Petra", "nachname": "Müller", "geburtsdatum": "1985-08-04"}'

VALID=$(curl -s -X 'POST' 'https://www.perimed.de/portal/api/v1/onlinedruck/validieren' \
    -H "Authorization: Basic $(echo -n ${BENUTZERNAME}:${PASSWORT} | base64)" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d "${JSON_BODY}" \
    -o /dev/null \
    -w "%{http_code}")

if [ "${VALID}" -eq "200" ]; then
  OUTPUT=$(mktemp --tmpdir --suffix=.pdf AnAa008De_XXXXXXX)

  curl -s -X 'POST' 'https://www.perimed.de/portal/api/v1/onlinedruck/612/drucken' \
      -H "Authorization: Basic $(echo -n ${BENUTZERNAME}:${PASSWORT} | base64)" \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/pdf' \
      -d "${JSON_BODY}" \
      -o "${OUTPUT}"

  echo "PDF wurde nach ${OUTPUT} geschrieben"
else
  echo "Fehler bei der Validierung - es kann kein Onlinedruck mit dem JSON durchgeführt werden"
fi
        

KIS-Schnittstelle

Die KIS Schnittstelle ist für Ihre bereits bestehenden Websysteme gedacht. Bei der Verwendung dieser Schnittstelle werden die gewünschten Patientendaten per HTTP POST an unser System übergeben. Anschließend wird unsere Anwendung im selben Browserfenster gestartet (per Redirect-URL als Antwort auf den HTTP POST). Anschließend kann ein beliebiger Patientenaufklärungsbogen aus dem Menü gewählt und mit den übergebenen Patientendaten bedruckt werden.
Nach dem erfolgreichen Herunterladen des Bogens als PDF ist das Zurückspringen in Ihre Anwendung zum aktuellen Zeitpunkt nicht möglich.

Für das Übertragen von Patientendaten aus Ihrer Webseite heraus, verwenden Sie folgenden JavaScript Code am Ende ihrer Seite vor dem </body> Tag.
Zum Abschicken der Daten inklusive Weiterleitung auf die perimed Portal-Seite verwenden Sie dann in Ihrem HTML-Code <button onclick="postPatientendaten()">Patientendaten übergeben</button>.

JavaScript Code Beispiel für die Integration der KIS Schnittstelle auf einer Webseite

<script>
    function postPatientendaten() {
        // Beispieldaten
        var daten = {
            login: 'Ihre Benutzername',
            passwort: 'Ihr Passwort',
            vorname: 'Max',
            nachname: 'Mustermann',
            geburtsdatum: '03.09.1985',
            krankenkasse: 'Techniker',
            kassenNummer: '4711',
            versichertenNummer: '815',
            status: 'Selbstverständlich',
            betriebsstaettenNummer: '1234',
            arztNummer: '4321',
            fallNummer: '1234567890',
            patientenNummer: '1010101010',
            behandlungsDatum: '09.05.2025',
            angehoeriger: 'Moritz',
            angehoerigerVerwandschaftsgrad: 'Bruder',
            angehoerigerTelefon: '0911-555555',
            angehoerigerEmail: 'moritz@mustermann.de',
            anmerkungen: 'Dies sind Test-Anmerkungen\nüber mehrere\nZeilen.'
        }

        var form = document.createElement('form');
        form.method = 'post';
        form.action = 'https://www.perimed.de/portal/patientendaten';

        for (var key in daten) {
            if (daten.hasOwnProperty(key)) {
                var hiddenField = document.createElement('input');
                hiddenField.type = 'hidden';
                hiddenField.name = key;
                hiddenField.value = daten[key];

                form.appendChild(hiddenField);
            }
        }

        document.body.appendChild(form);
        form.submit();
    }
</script>