5.1 Allgemeines

Der MCDMS WebService stellt eine REST-basierte HTTPS-Schnittstelle zum Austausch von Dateien bereit.

Alle Endpunkte verwenden das HTTP-Protokoll und liefern standardisierte HTTP-Statuscodes zurück.

Die Schnittstelle ist plattformunabhängig und kann von jeder Programmiersprache verwendet werden, die HTTPS-Anfragen unterstützt.

5.2 Basis-URL

Alle API-Endpunkte beginnen mit der Basisadresse des WebService.

Beispiel

https://server.meineklinik.de:5001/api/v1

5.3 Authentifizierung

Jede Anfrage muss einen gültigen API-Key enthalten.

Der API-Key wird im HTTP-Header übertragen.

Header	Pflicht	Beschreibung
X-API-KEY	✔	API-Key zur Authentifizierung

Fehlt dieser Header oder ist der Schlüssel ungültig, antwortet der WebService mit HTTP 401 (Unauthorized).

5.4 Standard-Header

Je nach Endpunkt werden zusätzlich folgende Header verwendet.

Header	Pflicht	Beschreibung
X-API-KEY	✔	API-Key
X-IK	✔	IK der Einrichtung
X-Dateiname	abhängig vom Endpunkt	Name der Datei

5.5 Übersicht der Endpunkte

Methode	Endpunkt	Beschreibung
POST	/api/v1/nachrichten	Datei hochladen
GET	/api/v1/nachrichten	Datei herunterladen
GET	/api/v1/nachrichten/liste	Dateiliste abrufen
DELETE	/api/v1/nachrichten	Datei löschen
GET	/api/v1/status	Statusinformationen

5.6 Datei hochladen

Lädt eine Datei in das Eingangsverzeichnis der angegebenen IK.

Request

Eigenschaft	Wert
Methode	POST
URL	/api/v1/nachrichten

Header

Header	Pflicht	Beispiel
X-API-KEY	✔	8B0A…
X-IK	✔	260820558
X-Dateiname	✔	Auftrag.xml

Body

Der Request Body enthält ausschließlich den Dateiinhalt.

Erfolgreiche Antwort

HTTP/1.1 200 OK

Beispiel mit curl

curl -X POST ^
  "https://server:5001/api/v1/nachrichten" ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  -H "X-Dateiname: Auftrag.xml" ^
  --data-binary "@Auftrag.xml"

Beispiel mit PowerShell

Invoke-WebRequest `
    -Uri "https://server:5001/api/v1/nachrichten" `
    -Method POST `
    -Headers @{
        "X-API-KEY"="123456789"
        "X-IK"="260820558"
        "X-Dateiname"="Auftrag.xml"
    } `
    -InFile "Auftrag.xml"

Beispiel VB.NET

Dim client As New WebClient

client.Headers.Add("X-API-KEY", apiKey)
client.Headers.Add("X-IK", "260820558")
client.Headers.Add("X-Dateiname", "Auftrag.xml")

client.UploadFile(url, "POST", "Auftrag.xml")

Beispiel C#

using var client = new HttpClient();

client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);
client.DefaultRequestHeaders.Add("X-IK", "260820558");
client.DefaultRequestHeaders.Add("X-Dateiname", "Auftrag.xml");

var bytes = await File.ReadAllBytesAsync("Auftrag.xml");

await client.PostAsync(
    url,
    new ByteArrayContent(bytes));

5.7 Datei herunterladen

Lädt eine Datei aus dem Ausgangsverzeichnis herunter.

Request

Eigenschaft	Wert
Methode	GET
URL	/api/v1/nachrichten

Header

Header	Pflicht
X-API-KEY	✔
X-IK	✔
X-Dateiname	✔

curl

curl ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  -H "X-Dateiname: Ergebnis.xml" ^
  -o Ergebnis.xml ^
  "https://server:5001/api/v1/nachrichten"

PowerShell

Invoke-WebRequest `
    -Uri "https://server:5001/api/v1/nachrichten" `
    -OutFile Ergebnis.xml `
    -Headers @{
        "X-API-KEY"="123456789"
        "X-IK"="260820558"
        "X-Dateiname"="Ergebnis.xml"
    }

VB.NET

Dim client As New WebClient

client.Headers.Add("X-API-KEY", apiKey)
client.Headers.Add("X-IK", "260820558")
client.Headers.Add("X-Dateiname", "Ergebnis.xml")

client.DownloadFile(url, "Ergebnis.xml")

5.8 Dateiliste abrufen

Liefert alle verfügbaren Dateien einer IK.

Request

Eigenschaft	Wert
Methode	GET
URL	/api/v1/nachrichten/liste

curl

curl ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  "https://server:5001/api/v1/nachrichten/liste"

Beispielantwort

[
  {
    "dateiname":"Auftrag.xml",
    "groesse":24581,
    "erstelltAm":"2026-07-24T08:31:44"
  },
  {
    "dateiname":"Befund.pdf",
    "groesse":482331,
    "erstelltAm":"2026-07-24T09:12:18"
  }
]

5.9 Datei löschen

Löscht eine Datei aus dem Ausgangsverzeichnis.

Request

Eigenschaft	Wert
Methode	DELETE
URL	/api/v1/nachrichten

curl

curl -X DELETE ^
  -H "X-API-KEY: 123456789" ^
  -H "X-IK: 260820558" ^
  -H "X-Dateiname: Ergebnis.xml" ^
  "https://server:5001/api/v1/nachrichten"

Erfolgreiche Antwort

HTTP/1.1 200 OK

5.10 Status-Endpunkt

Dient zur Überwachung und Funktionsprüfung des WebService.

Request

Eigenschaft	Wert
Methode	GET
URL	/api/v1/status

curl

curl https://server:5001/api/v1/status

Antwort

{
    "status":"OK",
    "version":"1.0.0",
    "serverTime":"2026-07-24T10:18:42",
    "uptime":"12.03:44:18"
}

5.11 HTTP-Statuscodes

Code	Bedeutung	Ursache
200	OK	Anfrage erfolgreich
400	Bad Request	Ungültige Header oder Parameter
401	Unauthorized	API-Key fehlt oder ist ungültig
403	Forbidden	IK nicht freigegeben
404	Not Found	Datei nicht gefunden
409	Conflict	Datei existiert bereits
413	Payload Too Large	Datei zu groß
500	Internal Server Error	Interner Fehler

5.12 Typischer Kommunikationsablauf

Client
   │
   │ HTTPS
   ▼
API-Key prüfen
   │
   ▼
IK prüfen
   │
   ▼
Datei speichern
   │
   ▼
Meta-Datei erzeugen
   │
   ▼
HTTP 200 OK

5.13 Test der REST-API

Nach der Installation empfiehlt sich folgender Funktionstest:

Schritt	Erwartetes Ergebnis
Status-Endpunkt aufrufen	HTTP 200
Testdatei hochladen	Datei im Eingangsordner vorhanden
Dateiliste abrufen	Testdatei wird angezeigt
Datei herunterladen	Inhalt identisch mit Original
Datei löschen	Datei wurde entfernt

Damit ist sichergestellt, dass

• der Windows-Dienst läuft,
• die HTTPS-Kommunikation funktioniert,
• der API-Key korrekt konfiguriert wurde,
• die IK freigegeben ist,
• die Dateiverzeichnisse erreichbar sind,
• Schreib- und Leseberechtigungen korrekt gesetzt wurden.