Skip to content

Latest commit

 

History

History
966 lines (840 loc) · 29.2 KB

KIM_API.adoc

File metadata and controls

966 lines (840 loc) · 29.2 KB
Raw

Clientsystem

Beginnend mit der KIM Version 1.5 werden weitere Funktionalitäten im Clientmodul bereitgestellt, die im folgenden Kapitel näher beschrieben werden. Darüber hinaus kann ab dieser Version das Clientmodul optional in das Primärsystem integriert werden. Zur Sicherstellung der Interoperabilität zwischen den Clientmodulen und den Fachdiensten wird eine Schnittstelle (I_AccountManager_Service) durch die gematik am Account Manager normativ festgelegt. Diese wird durch das Administrationsmodul aufgerufen und ermöglicht die Konfiguration der Nutzer-Accounts.

1. Änderungen im Clientmodul ab KIM 1.5

1.1. Optionale Integration in das Clientsystem

Ab der KIM Version 1.5 ist es möglich das Clientmodul in ein Clientsystem zu integrieren. Ein seperates Clientmodul ist in diesem Fall nicht mehr notwendig. Zur Sicherstellung einer spezifikationskonformen Umsetzung der Intergration in das Clientsystem wird durch die gematik ein entsprechender Prokttypsteckbrief (gemProdT_iCM_KIM) bereitgestellt.

1.2. Umgang mit E-Mail-Kategorien

Für die automatisierte Auswertung der KIM-Mails auf Seiten des Empfängers werden die KIM-Mails mit einer KIM-Dienstkennung markiert (z. B. bei der eAU). Hierfür wird die Dienstkennung als Bestandteil in den äußeren Header (X-KIM-Dienstkennung) der KIM-Mail übernommen. Die Benennung der zu verwendenden Dienstkennungen erfolgt durch den Mail-Client. Wurde durch den Mail-Client keine Dienstkennung gesetzt, dann wird durch das Clientmodul eine Default-Dienstkennung eingetragen. Die Anpassungen sind in [gemSpec_CM_KOMLE#3.6] und [gemSMIME_KOMLE#2.1.1.1] spezifiziert.

Eine Übersicht über alle Dienstkennungen kann hier eingesehen werden: Dienstkennungen

1.3. Umgang mit Anwendungskennzeichen (ab KIM 1.5.3)

Für die geziehlte Auswahl einer KIM E-Mail-Adresse können die im TI VZD (LDAP) hinterlegten Adressen mit einem Anwendungskennzeichen versehen werden. So kann z. B. sichergestellt werden, dass eine gesendete Nachricht an diese KIM E-Mail-Adresse durch den Empfänger verarbeitet werden kann. Es können für eine KIM E-Mail-Adresse mehrere Anwendungskennzeichen hinterlegt werden.
Neben den auf eine explizite Anwendung bezogenen Anwendungskennzeichen wird ein Standard Anwendungskennzeichen konfiguriert. Dieses ermöglicht es, den Empfang von Nachrichten sicherzustellen, auch wenn kein passendes Anwendungskennzeichen gefunden wurde. Jeder Fachdiensteintrag (FAD) innerhalb eines Verzeichnisdiensteintrages (mit TelematikID) MUSS eine KIM E-Mail-Adresse mit einem Standard Anwendungskennzeichen besitzen. Wird eine KIM E-Mail-Adresse, die das Standard Anwendungskennzeichen zugewiesen hat, gelöscht, dann MUSS sichergestellt werden, dass eine Zuweisung für eine andere KIM E-Mail-Adresse im selben FAD eine Neuvergabe erfolgt. Das vor Ort befindliche KIM Clientmodul (Administrations-Modul) stellt die dafür notwendige Oberfläche bereit.

1.4. Umgang mit großen Anhängen

E-Mails mit einer Gesamtgröße bis zu 15 MiB werden entsprechend den Festlegungen im KIM 1.0 behandelt. Übersteigt die Größe einer E-Mail die 15 MiB Grenze, wird die gesamte Client-Mail, durch das Clientmodul des Senders verschlüsselt, auf dem KIM-Attachment-Service (KAS) des Fachdiensts des Absenders abgelegt. Das Clientmodul ersetzt den Body der originalen Mail mit der KIM-Attachment Datenstruktur ([gemSpec_CM_KOMLE#Tabelle 2]) und versendet diese nach der weiteren Verarbeitung durch das Clientmodul als KIM Nachricht an den Fachdienst. Das KIM-Clientmodul des Empfängers erkennt den link in der KIM-Attachment Datenstruktur, lädt die E-Mail-Daten vom KAS des Absenders und entschlüsselt sie. Die damit wieder hergestellte originale Client-Mail wird dem Mail-Client des Empfängers zugestellt. Der Umgang mit großen Anhängen ist in [gemSpec_CM_KOMLE#3.2] spezifiziert. Die vom KAS dazu bereitgestellte Schnittstelle wird im folgenden genauer beschrieben.

1.4.1. I_Attachment_Service

Über die Schnittstelle I_Attachment_Service stellt der KAS dem Clientmodul die logischen Operationen add_Attachment(), und read_Attachment() zum Hoch- und Herunterladen von verschlüsselten E-Mail-Daten sowie die Operation delete_Maildata für das Löschen der E-Mail-Daten, unmittelbar nach dem Hochladen, zur Verfügung. Im folgenden Kapitel wird der Aufruf der Operationen beschrieben.

add_Maildata()

Mit Hilfe der Opertion add_Maildata() werden die verschlüsselten E-Mail-Daten unter einem neu erzeugten Freigabe-Link auf dem KAS für einen begrenzten Empfängerkreis abgelegt. Hierfür werden in der Operation zusammen mit den E-Mail-Daten die berechtigten Empfänger, die Message-ID der dazugehörenden KIM-Nachricht und das Ablaufdatum der abgelegten E-Mail-Daten übergeben.

Beispiel einer HTTP Nachricht

URI

Method

POST

Header

 
HTTP-Version: "HTTP/1.1"
Content-Type: "multipart/form-data"
Authorization: "Basic Z2VtYXRpazpraW0="

Body

 
messageID: "bde36ec8-9710-47bc-9ea3-bf0425078e33@example"
recipients: "user1@example.kim.telematik", "user2@example.kim.telematik"
expires: "Mon, 15 Aug 22 15:52:01 +0000"
attachment: "{…file content…}"

messageID - Message-ID der zugehörigen KIM E-Mail
recipients - E-Mail Adressen der Empfänger
expires - Ablaufdatum der E-Mail-Daten
attachment - verschlüsselte E-Mail-Daten die auf dem KAS abgelegt werden sollen

Beispielabfrage:

curl -X 'POST' \
'https://kas.hrst1.kim.telematik/attachments/v2.3/attachment/' \
-H 'accept: application/json' \
-H 'Content-Type: multipart/form-data' \
-F 'messageID=bde36ec8-9710-47bc-9ea3-bf0425078e33@example' \
-F 'recipients=user1@example.kim.telematik, user2@example.kim.telematik' \
-F 'expires=Mon, 15 Aug 22 15:52:01 +0000' \
-F 'attachment={…file content…}'

Beispielantwort

Code: 201
Body:
{
  "sharedLink":"https://kas.hrst1.kim.telematik/attachments/v2.3/attachment/b2deea19-c37f-4ef0-a95f-d4e8b5817824"
}

HTTP-Status Codes:

Status Bedeutung

201

Created
Die E-Mail-Daten wurden erfolgreich unter dem angegebenen Freigabelink hinzugefügt.

400

Bad Request
Fehler in den Eingangsdaten, Beschreibung des Fehlers erfolgt in dem Fehlertext

401

Unauthorized
Authentifizierung fehlgeschlagen.

413

Payload Too Large
Die maximal zulässige Dokumentengröße wurde überschritten.

500

Internal Server Error

507

Insufficient Storage
Nicht genügend Speicherplatz vorhanden.
read_Maildata()

Die Opertion read_Maildata() gibt den unter einem Freigabelink verschlüsselten E-Mail-Daten zurück. Beim Aufruf der Operation muss die E-Mail-Adresse des Empfängers übergeben werden.

Beispiel einer HTTP Nachricht

URI

https://kas.hersteller.kim.telematik/attachments/v2.3/attachment/{attachmentId}
attachmentId - Freigabelink, unter dem die E-Mail-Daten gespeichert wurden

Method

GET

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "application/octet-stream"
 recipient: "user1@example.kim.telematik"

recipient - E-Mail Adresse des Empfängers

Body

keine Parameter

Beispielabfrage:

curl -X 'GET' \
'https://kas.hrst1.kim.telematik/attachments/v2.3/attachment/b2deea19-c37f-4ef0-a95f-d4e8b5817824' \
-H 'accept: application/octet-stream' \
-H 'recipient: user1@example.kim.telematik'

Beispielantwort

Code: 200
Body:
{
  "…file content…"
}

HTTP-Status Codes:

Status Bedeutung

200

OK
E-Mail-Daten wurden erfolgreich heruntergeladen.

404

Not Found
E-Mail-Daten wurden unter dem angegebenen Link nicht gefunden.

429

Too many Requests
E-Mail-Daten zu oft heruntergeladen.

500

Internal Server Error
delete_Maildata()

Mit Hilfe der Opertion delete_Maildata() kann ein Clientmodul die auf dem KAS abgelegten E-Mail Daten, im Falle des fehlerhaften Versands der dazugehörenden KIM-Nachricht, wieder löschen.

Beispiel einer HTTP Nachricht

URI

https://kas.hrst1.kim.telematik/attachments/v2.3/attachment/{attachmentId}
attachmentId - Freigabelink, unter dem die E-Mail-Daten gespeichert wurden

Method

DELETE

Header

 
HTTP-Version: "HTTP/1.1"
Content-Type: "multipart/form-data"
Authorization: "Basic Z2VtYXRpazpraW0="

Body

keine Parameter

Beispielabfrage:

curl -X 'DELETE' \
'https://kas.hrst1.kim.telematik/attachments/v2.3/attachment/b2deea19-c37f-4ef0-a95f-d4e8b5817824' \
-H 'accept: application/octet-stream' \

Beispielantwort

Code: 200

HTTP-Status Codes:

Status Bedeutung

200

OK
Daten wurden gelöscht

400

Bad Request
Fehler in den Eingangsdaten, Beschreibung des Fehlers erfolgt in dem Fehlertext

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

no Ressource
Ressource unter dem angegebenen Link nicht gefunden

500

Internal Server Error

1.4.2. I_AccountLimit_Service

Über die Schnittstelle I_AccountLimit_Service stellt der Account Manager dem Clientmodul die logische Operationen getLimits() zur Abfrage von technisch konfigurierbaren Parametern eines Nutzer-Accounts zur Verfügung.

getLimits()

Mit dem Aufruf der Operation getLimits() durch das Clientmodul erhält es alle technisch konfigurierbaren Parameter zu einem Nutzer-Account. Bei den Parametern handelt es sich um eine vom Anbieter definierte Größenbeschränkung einer KIM-E-Mail (maxMailSize), die vom Nutzer eingestellte Gültigkeitsdauer für E-Mail-Daten (dataTimeToLive)und die Angabe des Speichervolumens für den Nutzer-Account (quota, remainQuota). Das Ergebnis der Operation kann vom Clientmodul für 24 Stunden zwischengespeichert werden.

Der Parameter maxMailSize gibt die maximal mögliche Größe einer KIM-E-Mail inklusive aller Anhänge (Base64-kodiert), die der KAS akzeptiert, zurück. Mit diesem Wert prüft das Clientmodul die Einhaltung der maximalen Mailgröße (die vom Fachdienst-Anbieter definiert wird) für zu sendende Mails. Dieser Wert wird auf dem Fachdienst definiert.

Beispiel einer HTTP Nachricht

URI

Method

GET

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "application/json"
 Authorization: "Basic Z2VtYXRpazpraW0="

Body

keine Parameter

Beispielabfrage:

curl -X 'GET' \
  'https://account-manager.hrst1.kim.telematik/AccountLimit/v1.0/limit' \
  -H 'accept: application/json'

Beispielantwort

Code: 200
Body:
{
  "dataTimeToLive": 90,
  "maxMailSize": 734003200,
  "kasMailSizeThreshold": 15728640;
  "quota": 160000000000,
  "remainQuota": 112000000000
}

HTTP-Status Codes:

Status Bedeutung

200

OK

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

Not Found
Mail Account nicht vorhanden content:.

500

Internal Server Error

2. Administrationsmodul

2.1. I_AccountManager_Service

Über die Schnittstelle I_AccountManager_Service stellt der Account Manager des KIM-Fachdientes dem Administrationsmodul die logischen Operationen registerAccount(), deregisterAccount(), revokeDeregistration(), setAccount(), getAccount(), createCert(), getOTP(), setTID(), getOutOfOffice() und updateOutOfOffice() zur Verfügung. Im folgenden Kapitel wird der Aufruf der Operationen beschrieben.

2.1.1. registerAccount()

Mittels der Operation registerAccount() wird die Registrierung eines KIM-Teilnehmers am KIM-Fachdienst durchgeführt.

Beispiel einer HTTP Nachricht

URI

Method

POST

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "*/*"
 Content-Type: "application/json"
 iniPassword: "hrst01"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

 
{
  "referenceID": "0123456789",
  "username": "user@example.kim.telematik",
  "password": "new_password",
  "kimVersion": "1.5"
  "appTags": "<Anwendungskennzeichen>"
}

referenceID - Referenz eines KIM-Teilnehmers
username - E-Mail Adresse eines KIM-Teilnehmers
password - Neues Passwort festlegen
kimVersion - Die vom Clientmodul eingesetzte KIM-Version
appTags - Die vom KIM-Teilnehmers unterstützte/n Anwendung/en

Beispielaufruf:

curl -X 'POST' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account' \
  -H 'accept: */*' \
  -H 'iniPassword: old_password' \
  -H 'Content-Type: application/json' \
  -d '{
  "referenceID": "0123456789",
  "username": "user@example.kim.telematik",
  "password": "new_password",
  "kimVersion": "1.5"
  "appTags": "eAU"
  }'

Beispielantwort:

Code: 204

HTTP-Status Codes:

Status Bedeutung

204

No Content
Account erfolgreich registriert.

400

Bad Request
Fehler in den Eingangsdaten, Beschreibung des Fehlers erfolgt in dem Fehlertext.

401

Unauthorized
Authentifizierung fehlgeschlagen.

409

Conflict
Konflikt mit einem bereits bestehenden Account mit identischer E-Mail-Adresse.

420

Policy Not Fulfilled
Username oder Passwort entsprechen nicht den Regeln.

422

Unprocessable Entity
Die KIM-Version wird nicht unterstützt bzw. ist unbekannt.

500

Internal Server Error

502

Bad Gateway - VZD nicht erreichbar bzw. liefert Fehler

2.1.2. deregisterAccount()

Mittels der Operation deregisterAccount() wird die Deregistrierung eines KIM-Teilnehmers am KIM-Fachdienst durchgeführt.

Beispiel einer HTTP Nachricht

URI

Method

DELETE

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "*/*"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

keine Parameter

Beispielabfrage:

curl -X 'DELETE' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik' \
  -H 'accept: */*' \
  -H 'password: password'

Beispielantwort:

Code: 204

HTTP-Status Codes:

Status Bedeutung

204

No Content
Account erfolgreich deregistriert.

400

Bad Request
Fehler in den Eingangsdaten, Beschreibung des Fehlers erfolgt in dem Fehlertext.

401

Unauthorized
Authentifizierung fehlgeschlagen.

500

Internal Server Error

502

Bad Gateway - VZD nicht erreichbar bzw. liefert Fehler

2.1.3. revokeDeregistration()

Mittels der Operation revokeDeregistration() wird die Deregistrierung eines KIM-Teilnehmers am KIM-Fachdienst zurückgenommen. Der zugehörige Nutzeraccount wird wieder vollständig aktiviert.

Beispiel einer HTTP Nachricht

URI

Method

PUT

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "*/*"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

keine Parameter

Beispielabfrage:

curl -X 'POST' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik' \
  -H 'accept: */*' \
  -H 'password: password'

Beispielantwort:

Code: 204

HTTP-Status Codes:

Status Bedeutung

204

No Content
Deregistrierung erfolgreich zurückgenommen.

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

Unauthorized
Mail Account nicht vorhanden.

500

Internal Server Error

502

Bad Gateway - VZD nicht erreichbar bzw. liefert Fehler

2.1.4. setAccount()

Die Operation setAccount() ermöglicht die Verwaltung eines Accounts eines KIM-Teilnehmers.

Beispiel einer HTTP Nachricht

URI

Method

PUT

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "*/*"
 Content-Type: "application/json"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

 
{
  "referenceID": "0123456789",
  "username": "user@example.kim.telematik",
  "password": "password",
  "kimVersion": "1.5",
  "appTags": "<Anwendungskennzeichen>"
  "dataTimeToLive": 90
}

referenceID - Referenz eines KIM-Teilnehmers
username - E-Mail Adresse eines KIM-Teilnehmers
password - Neues Passwort festlegen
kimVersion - Die vom Clientmodul eingesetzte KIM-Version
appTags - Die vom KIM-Teilnehmers unterstützte/n Anwendung/en
dataTimeToLive - Speicherdauer in Tagen von Mails und Anhängen auf dem Fachdienst

Beispielabfrage:

curl -X 'PUT' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik' \
  -H 'accept: */*' \
  -H 'password: password' \
  -H 'Content-Type: application/json' \
  -d '{
  "referenceID": "0123456789",
  "username": "user@example.kim.telematik",
  "password": "password",
  "kimVersion": "1.5",
  "appTags": "eAU",
  "dataTimeToLive": 90
}'

Beispielantwort:

Code: 204

HTTP-Status Codes:

Status Bedeutung

204

No Content
Änderung des Accounts erfolgreich durchgeführt.

400

Bad Request
Fehler in den Eingangsdaten, Beschreibung des Fehlers erfolgt in dem Fehlertext.

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

Not Found
E-Mail Account nicht vorhanden.

420

Policy Not Fulfilled
Neues Passwort entspricht nicht den Regeln.

422

Unprocessable Entity
Die KIM-Version wird nicht unterstützt bzw. ist unbekannt.

500

Internal Server Error

502

Bad Gateway - VZD nicht erreichbar bzw. liefert Fehler

2.1.5. getAccount()

Die Operation getAccount() liefert Informationen zum Account eines KIM-Teilnehmers.

Beispiel einer HTTP Nachricht

URI

Method

GET

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "application/json"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

keine Parameter

Beispielabfrage:

curl -X 'GET' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik' \
  -H 'accept: application/json' \
  -H 'password: password'

Beispielantwort:

Code: 200
Body:
{
  "username": "user@example.kim.telematik",
  "kimVersion": "1.5",
  "regStat": "registered",
  "deregDate": 1616588543,
  "maxMailSize": 734003200,
  "appTags": "eAU",
  "dataTimeToLive": 90
}

HTTP-Status Codes:

Status Bedeutung

200

OK
Anzeige des Accounts.

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

Not Found
E-Mail Account nicht vorhanden.

500

Internal Server Error

502

Bad Gateway - VZD nicht erreichbar bzw. liefert Fehler

2.1.6. createCert()

Die Operation createCert() erzeugt und liefert ein TLS-Auth Zertifikat in einem PKCS#12 Container.

Beispiel einer HTTP Nachricht

URI

Method

POST

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "application/json"
 Content-Type: "application/json"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

 
{
  "commonName": "Praxis Mustermann",
  "certPassword": "password"
}

commonName - Clientmodul Name
certPassword - Passwort für die PKCS#12-Datei

Beispielabfrage:

curl -X 'POST' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik/cert' \
  -H 'accept: application/json' \
  -H 'password: password' \
  -H 'Content-Type: application/json' \
  -d '{
  "commonName": "Praxis Mustermann",
  "certPassword": "password"
}'

Beispielantwort:

Code: 201
Body:
{
  "file": "…file content…"
}

HTTP-Status Codes:

Status Bedeutung

201

Created
Zertifikat wird zurückgegeben.

401

Unauthorized
Authentifizierung fehlgeschlagen.

500

Internal Server Error

2.1.7. getOTP()

Die Operation getOTP() erzeugt und liefert ein One Time Passwort.

Beispiel einer HTTP Nachricht

URI

Method

GET

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "application/json"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

keine Parameter

Beispielabfrage:

curl -X 'GET' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik/OTP' \
  -H 'accept: application/json' \
  -H 'password: password'

Beispielantwort:

Code: 200
Body:
{
  "OTP": "sufglwahföqwklfnwqkalfnesaöjfjdg...jsdnvbruifqwijkvwurizrtqoiwfhbfe8"
}

HTTP-Status Codes:

Status Bedeutung

200

OK
OTP erfolgreich erzeugt.

401

Unauthorized
Authentifizierung fehlgeschlagen.

500

Internal Server Error

2.1.8. setTID()

Die Operation setTIP() entfernt die E-Mail Adresse vom bisherigen VZD Eintrag und trägt diese für den aktuellen VZD Eintrag (der den Authentisierungsdaten dieser Operation setTID entspricht) ein. Die Authentisierung erfolgt mit der neuen Smarcard des Nutzers.

Beispiel einer HTTP Nachricht

URI

Method

GET

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "*/*"
 password: "password"
 OTP: "sufglwahföqwklfnwqkalfnesaöjfjdg...jsdnvbruifqwijkvwurizrtqoiwfhbfe8"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

keine Parameter

Beispielabfrage:

curl -X 'PUT' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik/telematikID' \
  -H 'accept: */*' \
  -H 'password: password' \
  -H 'OTP: sufglwahföqwklfnwqkalfnesaöjfjdg...jsdnvbruifqwijkvwurizrtqoiwfhbfe8'

Beispielantwort:

Code: 204

HTTP-Status Codes:

Status Bedeutung

204

No Content
Änderung der TelematikID erfolgreich.

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

Not Found
E-Mail Account nicht vorhanden.

408

Request Timeout
Gültigkeitsdauer des One Time Passworts ist abgelaufen.

500

Internal Server Error

502

Bad Gateway - VZD nicht erreichbar bzw. liefert Fehler

2.1.9. getOutOfOffice()

Die Operation getOutOfOffice() liefert Informationen zu eingestellten Abwesenheitsnotizen eines KIM-Teilnehmers.

Beispiel einer HTTP Nachricht

URI

Method

GET

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "application/json"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

keine Parameter

Antwort

 
{
  "startDate": "2021-07-28T00:00:00.000Z",
  "endDate": "2021-08-01T00:00:00Z",
  "message": "Sehr geehrte Damen und Herren...",
  "active": "true"
}

startDate - Ab diesem Zeitpunkt wird die Abwesenheitsnotiz gesendet (RFC3339 Section 5.6)
endDate - Bis zu diesem Zeitpunkt wird die Abwesenheitsnotiz gesendet (RFC3339 Section 5.6)
message - Inhalt der Abwesenheitsnotiz
active - Aktivieren bzw. deaktiviert der Abwesenheitsnotiz

Beispielabfrage:

curl -X 'GET' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik/outofoffice' \
  -H 'accept: application/json' \
  -H 'password: password'

Beispielantwort:

Code: 200
Body:
{
  "startDate": "2021-07-28T00:00:00.000Z",
  "endDate": "2021-08-01T00:00:00Z",
  "message": "Sehr geehrte Damen und Herren...",
  "active": true
}

HTTP-Status Codes:

Status Bedeutung

200

OK
Lesen der Abwesenheitsnotiz erfolgreich.

400

Bad Request
Fehler in den Eingangsdaten, Beschreibung des Fehlers erfolgt in dem Fehlertext

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

Not Found
E-Mail Account nicht vorhanden.

500

Internal Server Error

2.1.10. UpdateOutOfOffice()

Die Operation UpdateOutOfOffice() ermöglicht das Einstellen einer Abwesenheitsnotiz eines KIM-Teilnehmers.

Beispiel einer HTTP Nachricht

URI

Method

PUT

Header

 
 HTTP-Version: "HTTP/1.1"
 accept: "*/*"
 Content-Type: "application/json"
 password: "password"
 Authorization: "Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ"

Body

 
{
  "startDate": "2021-07-28T00:00:00.000Z",
  "endDate": "2021-08-01T00:00:00Z",
  "message": "Sehr geehrte Damen und Herren...",
  "active": "true"
}

startDate - Ab diesem Zeitpunkt wird die Abwesenheitsnotiz gesendet (RFC3339 Section 5.6)
endDate - Bis zu diesem Zeitpunkt wird die Abwesenheitsnotiz gesendet (RFC3339 Section 5.6)
message - Inhalt der Abwesenheitsnotiz
active - Aktivieren bzw. deaktiviert der Abwesenheitsnotiz

Beispielabfrage:

curl -X 'PUT' \
  'https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.3/account/user@example.kim.telematik/outofoffice' \
  -H 'accept: */*' \
  -H 'password: password' \
  -H 'Content-Type: application/json' \
  -d '{
  "startDate": "2021-07-28T00:00:00Z",
  "endDate": "2021-08-01T00:00:00.000Z",
  "message": "Sehr geehrte Damen und Herren...",
  "active": true
}'

Beispielantwort:

Code: 204

HTTP-Status Codes:

Status Bedeutung

204

No Content
Änderung der Abwesenheitsnotiz erfolgreich.

400

Bad Request
Fehler in den Eingangsdaten, Beschreibung des Fehlers erfolgt in dem Fehlertext.

401

Unauthorized
Authentifizierung fehlgeschlagen.

404

Not Found
E-Mail Account nicht vorhanden.

500

Internal Server Error