gematik_schemes.vzd.DirectoryAdministration.yaml Maven / Gradle / Ivy
openapi: 3.0.1
info:
title: I_Directory_Administration
description: REST Schnittstelle zur Pflege der Verzeichniseinträge.
Über diese Schnittstelle können Verzeichniseinträge inklusive Zertifikaten erzeugt, aktualisiert und gelöscht werden. Die Administration von Fachdaten erfolgt über Schnittstelle I_Directory_Application_Maintenance und wird durch die Fachanwendungen durchgeführt. Lesender Zugriff auf die Fachdaten ist mit Operation getDirectoryEntries in vorliegender Schnittstelle möglich.
version: 1.5.0
# Änderungen in Version 1.5.0
# - Attribut "owner" in "holder" umbenannt ("owner" ist in LDAP vordefiniert und kann deshalb nicht für den vorgesehenen Zweck genutzt werden)
# Änderungen in Version 1.4.0
# - Operation read_Directory_Entry: Einschränkung auf 100 Suchergebnisse wieder eingeführt
# - Operation read_Directory_Entry_for_Sync: Für die Datensynchronisation der Herausgeber mit dem VZD wird diese Suchabfrage ohne Limitierung auf 100 Suchergebnisse ergänzt. Die parallele Ausführung dieser Operation wird vom Server aus Performancegründen eingeschränkt.
# - Attribut "usage" in Datenstruktur "userCertificate": "enum" im Format gestrichen.
#
# Änderungen in Version 1.3.0
# - Die direkte Suche von Verzeichniseinträgen (baseDirectoryEntry) mit dem
# Suchparameter telematikID wird unterstützt.
# o telematikID im baseDirectoryEntry hinzugefügt und in
# add_Directory_Entry, read_Directory_Entry und modify_Directory_Entry ergänzt
# - Paging Parameter entfernt (für eigene Verzeichniseinträge und Verzeichniseinträge
# ohne owner wird die Begrenzung auf 100 Suchergebnisse aufgehoben)
# - Operation read_Directory_Entry: Suchparameter telematikID-SubStr ergänzt
# - Operation read_Directory_Entry: Suchparameter telematikID-SubStr ergänzt
# - Datenmodell: "baseDirectoryEntry"
# o Ländercode "countryCode" ergänzt und in Operationen hinzugefügt
# o Änderungsdatum "changeDateTime" ergänzt
#
# Änderungen in Version 1.2.2
# Übernahme der Änderungen aus f_r313_hotfix_5 (version 1.1.2)
# - /DirectoryEntries
# get - Response Fehlercode 400 gestrichen.
# Bei mehr als 100 gefundenen Einträgen werden nur 100
# gefundenen Einträge zurückgegeben (Response 200), falls kein Paging genutzt wird.
# - /DirectoryEntries/Certificates
# get - Response Fehlercode 400 gestrichen.
# Bei mehr als 100 gefundenen Einträgen werden nur 100
# gefundenen Einträge zurückgegeben (Response 200).
#
# Änderungen in Version 1.2.1
# - /DirectoryEntries
# read_Directory_Entry:
# Suchparameter "baseEntryOnly" ergänzt
# Änderungen in Version 1.2.0
# - /DirectoryEntries
# read_Directory_Entry:
# Suchparameter "owner" ergänzt
# Paging Parameter ergänzt
# - searchControlValue für Paging der Suchergebnisse ergänzt
# - /DirectoryEntries/{uid}/baseDirectoryEntries:
# modify_Directory_Entry: Fehlerkode 422 ergänzt (ungültiger owner im Request Parameter)
# - /DirectoryEntries/{uid}/Certificates/{certificateEntryID}:
# put & delete - Operationen gestrichen
# - schemas:
# baseDirectoryEntry:
# Attribute "owner" und "maxKOMLEadr" mit Beschreibung der Auswirkungen auf die Operationen hinzugefügt
# Änderungen in Version 1.1.1
# - /DirectoryEntries/Certificates
# get - UID ist kein Pflichtparameter mehr um die Suche mit der TelematikID zu ermöglichen
# - Texte der HTTP Fehlercodes angepasst
externalDocs:
description: Schnittstelle zur Pflege der Verzeichniseinträge
url: http://www.gematik.de
servers:
- url: https://to.be.defined/
tags:
- name: DirectoryEntry Administration
description: Pflege der Verzeichniseinträge (Basiseinträge)
- name: Certificate Administration
description: Pflege der Zertifikatseinträge
- name: DirectoryEntry Synchronization
description: Synchronisation der Verzeichniseinträge (Basiseinträge) mit dem eigenen Datenbestand
paths:
/DirectoryEntries:
post:
tags:
- DirectoryEntry Administration
summary: Einen Eintrag zum Verzeichnisdienst hinzufügen
operationId: add_Directory_Entry
requestBody:
description: Datensatz für den neuen Eintrag. Die Attribute müssen wie folgt belegt sein
dn.* Leer/nicht vorhanden (wird vom Verzeichnisdienst belegt)
givenName Nicht vorhanden (wird vom Verzeichnisdienst belegt)
sn Nicht vorhanden (wird vom Verzeichnisdienst belegt)
cn Nicht vorhanden (wird vom Verzeichnisdienst belegt)
displayName Kann optional belegt werden.
streetAddress Kann optional belegt werden.
postalCode Kann optional belegt werden.
countryCode Kann optional belegt werden.
Falls nicht belegt, ergänzt der VZD den Code für Deutschland (Defaultwert).
localityName Kann optional belegt werden.
stateOrProvinceName Kann optional belegt werden.
title Kann optional belegt werden.
organization Kann optional belegt werden.
otherName Kann optional belegt werden.
telematikID Kann optional belegt werden.
Das ist die telematikID in den Basisdaten (baseDirectoryEntry).
Wird diese telematikID und userCertificate bzw. die telematikID in userCertificate angegeben, dann müssen diese telematikIDs übereinstimmen.
Bei unterschiedlichen telematikID wird die Operation mit Fehlercode 422 abgelehnt.
specialization Kann optional belegt werden.
domainID Kann optional belegt werden.
holder Kann optional belegt werden (falls nicht belegt, dann vom VZD aus dem ID_Token entnommen).
maxKOMLEadr Kann optional belegt werden.
personalEntry Nicht vorhanden (wird vom Verzeichnisdienst belegt)
dataFromAuthority Nicht vorhanden (wird vom Verzeichnisdienst belegt)
userCertificates Kann optional belegt werden.
dn.uid Leer/nicht vorhanden (wird vom Verzeichnisdienst belegt)
dn.dc Leer/nicht vorhanden (wird vom Verzeichnisdienst belegt)
dn.ou Leer/nicht vorhanden (wird vom Verzeichnisdienst belegt)
dn.cn Leer/nicht vorhanden (wird vom Verzeichnisdienst belegt)
telematikID Kann optional belegt werden.
Wird telematikID und userCertificate angegeben, dann muss diese telematikID mit der telematikID im userCertificate übereinstimmen.
Bei unterschiedlichen telematikID wird die Operation mit Fehlercode 422 abgelehnt.
entryType Nicht vorhanden (wird vom Verzeichnisdienst belegt)
professionOID Nicht vorhanden (wird vom Verzeichnisdienst belegt)
usage Kann optional belegt werden.
userCertificate Kann optional belegt werden (Format DER, Base64 kodiert)
description Kann optional belegt werden.
Entsprechend gemSpec_VZD wird ein Teil der Attribute durch den Verzeichnisdienst automatisch mit Werten aus dem Zertifikat gefüllt. Wenn in dieser Operation Attribute - für die dies erlaubt ist - mit einem Wert belegt werden, wird dieser Wert im Verzeichniseintrag gespeichert (auch wenn der Wert durch den Verzeichnisdienst aus dem Zertifikat entnommen werden kann).
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDirectoryEntry'
required: true
responses:
201:
description: Created
# Der Verzeichniseintrag wurde angelegt. Zurückgegeben wird der distinguishedName des erzeugten Eintrags.
content:
application/json:
schema:
$ref: '#/components/schemas/distinguishedName'
401:
description: Unauthorized
# Der WWW-Authenticate Header im Response muss auf OAuth gesetzt werden.
content: {}
403:
description: Forbidden
content: {}
405:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
422:
description: Unprocessable Entity
# Z.B. Wert aus dem Request Attribut "holder" nicht gültig
# Bei unterschiedlichen telematikIDs (Parameter telematikID und Wert im userCertificate) wird die Operation mit Fehlercode 422 abgelehnt.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
get:
tags:
- DirectoryEntry Administration
summary: Gesamten Verzeichniseintrag lesen
description: Liefert alle zum Filter passenden Verzeichniseinträge (maximal 100 Einträge). Die angegebenen Parameter werden mit logischen UND verknüpft.
operationId: read_Directory_Entry
parameters:
- name: uid
in: query
description: ID von dem Verzeichniseintrag (distinguishedName.uid)
schema:
type: string
- name: givenName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs givenName.
schema:
type: string
- name: sn
in: query
description: Erlaubt die Suche mit Hilfe des Attributs sn.
schema:
type: string
- name: cn
in: query
description: Erlaubt die Suche mit Hilfe des Attributs cn.
schema:
type: string
- name: displayName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs displayName.
schema:
type: string
- name: streetAddress
in: query
description: Erlaubt die Suche mit Hilfe des Attributs streetAddress.
schema:
type: string
- name: postalCode
in: query
description: Erlaubt die Suche mit Hilfe des Attributs postalCode.
schema:
type: string
- name: countryCode
in: query
description: Erlaubt die Suche mit Hilfe des Attributs countryCode.
schema:
type: string
- name: localityName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs localityName.
schema:
type: string
- name: stateOrProvinceName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs stateOrProvinceName.
schema:
type: string
- name: title
in: query
description: Erlaubt die Suche mit Hilfe des Attributs title.
schema:
type: string
- name: organization
in: query
description: Erlaubt die Suche mit Hilfe des Attributs organization.
schema:
type: string
- name: otherName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs otherName.
schema:
type: string
- name: telematikID
in: query
description: Erlaubt die Suche mit Hilfe des Attributs telematikID (die telematikID in den Basisdaten).
schema:
type: string
- name: telematikID-SubStr
in: query
description: Erlaubt die Suche nach einem Substring am Anfang der telematikID (die telematikID in den Basisdaten).
Entspricht der LDAP Filters Substring Assertion vom Typ "subInitial Component".
schema:
type: string
- name: specialization
in: query
description: Erlaubt die Suche mit Hilfe des Attributs specialization.
Der Verzeichniseintrag wird selektiert, wenn die angegebene domainID im Attribut domainID (array) des Verzeichniseintrags enthalten ist.
schema:
type: string
- name: domainID
in: query
description: Erlaubt die Suche mit Hilfe des Attributs domainID.
Der Verzeichniseintrag wird selektiert, wenn die angegebene domainID im Attribut domainID (array) des Verzeichniseintrags enthalten ist.
schema:
type: string
- name: holder
in: query
description: Erlaubt die Suche mit Hilfe des Attributs holder.
Der Verzeichniseintrag wird selektiert, wenn der angegebene holder im Attribut holder (array) des Verzeichniseintrags enthalten ist.
Wenn der Parameter mit dem eigenen Wert des Clients belegt wird, werden alle gefundenen Einträge zurückgegeben (maximal 100 Einträge).
Zur Suche nach Einträge ohne holder ist der Parameter mit dem einem leeren String "" zu belegen. Auch in diesem Fall werden alle gefundenen Einträge zurückgegeben (maximal 100 Einträge).
schema:
type: string
- name: personalEntry
in: query
description: Erlaubt die Suche mit Hilfe des Attributs personalEntry.
schema:
type: string
- name: dataFromAuthority
in: query
description: Erlaubt die Suche mit Hilfe des Attributs dataFromAuthority.
schema:
type: string
- name: baseEntryOnly
in: query
description: Mit baseEntryOnly = "true" wird nur der Basiseintrag (baseDirectoryEntry) im Response zurückgegeben. Falls nicht angegeben oder mit "false" belegt, wird der gesamte Verzeichniseintrag mit Zertifikaten und Fachdaten im Response zurückgegeben.
schema:
type: boolean
example: true
responses:
200:
description: OK
# Es werden alle zu dem Filter Parametern passenden Verzeichniseinträge - inklusive Zertifikaten und Fachdaten - zurückgegeben.
# Bei mehr als 100 gefundenen Einträgen nur 100 gefundenen Einträge zurückgegeben.
content:
application/json:
schema:
$ref: '#/components/schemas/DirectoryEntries'
401:
description: Unauthorized
# Der WWW-Authenticate Header im Response wird auf OAuth gesetzt.
content: {}
403:
description: Forbidden
content: {}
404:
description: Not Found
content: {}
/DirectoryEntriesSync:
get:
tags:
- DirectoryEntry Synchronization
summary: Synchronisation der Verzeichniseinträge zwischen VZD und Herausgeber
description: Liefert - analog zu read_Directory_Entry - alle zum Filter passenden Verzeichniseinträge. Im Unterschied zu read_Directory_Entry wird die Limitierung auf 100 Suchergebnisse aufgehoben. Die parallele Ausführung dieser Operation wird vom Server aus Performancegründen eingeschränkt.
Diese Operation soll nur genutzt werden, wenn mehr als 100 Suchergebnisse benötigt werden. Für alle anderen Suchanfragen soll Operation read_Directory_Entry genutzt werden.
operationId: read_Directory_Entry_for_Sync
parameters:
- name: uid
in: query
description: ID von dem Verzeichniseintrag (distinguishedName.uid)
schema:
type: string
- name: givenName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs givenName.
schema:
type: string
- name: sn
in: query
description: Erlaubt die Suche mit Hilfe des Attributs sn.
schema:
type: string
- name: cn
in: query
description: Erlaubt die Suche mit Hilfe des Attributs cn.
schema:
type: string
- name: displayName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs displayName.
schema:
type: string
- name: streetAddress
in: query
description: Erlaubt die Suche mit Hilfe des Attributs streetAddress.
schema:
type: string
- name: postalCode
in: query
description: Erlaubt die Suche mit Hilfe des Attributs postalCode.
schema:
type: string
- name: countryCode
in: query
description: Erlaubt die Suche mit Hilfe des Attributs countryCode.
schema:
type: string
- name: localityName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs localityName.
schema:
type: string
- name: stateOrProvinceName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs stateOrProvinceName.
schema:
type: string
- name: title
in: query
description: Erlaubt die Suche mit Hilfe des Attributs title.
schema:
type: string
- name: organization
in: query
description: Erlaubt die Suche mit Hilfe des Attributs organization.
schema:
type: string
- name: otherName
in: query
description: Erlaubt die Suche mit Hilfe des Attributs otherName.
schema:
type: string
- name: telematikID
in: query
description: Erlaubt die Suche mit Hilfe des Attributs telematikID (die telematikID in den Basisdaten).
schema:
type: string
- name: telematikID-SubStr
in: query
description: Erlaubt die Suche nach einem Substring am Anfang der telematikID (die telematikID in den Basisdaten).
Entspricht der LDAP Filters Substring Assertion vom Typ "subInitial Component".
schema:
type: string
- name: specialization
in: query
description: Erlaubt die Suche mit Hilfe des Attributs specialization.
Der Verzeichniseintrag wird selektiert, wenn die angegebene domainID im Attribut domainID (array) des Verzeichniseintrags enthalten ist.
schema:
type: string
- name: domainID
in: query
description: Erlaubt die Suche mit Hilfe des Attributs domainID.
Der Verzeichniseintrag wird selektiert, wenn die angegebene domainID im Attribut domainID (array) des Verzeichniseintrags enthalten ist.
schema:
type: string
- name: holder
in: query
description: Erlaubt die Suche mit Hilfe des Attributs holder.
Der Verzeichniseintrag wird selektiert, wenn der angegebene holder im Attribut holder (array) des Verzeichniseintrags enthalten ist.
Wenn der Parameter mit dem eigenen Wert des Clients belegt wird, werden alle gefundenen Einträge zurückgegeben (für eigene Einträge gilt das Limit von 100 Ergebnissen nicht).
Zur Suche nach Einträge ohne holder ist der Parameter mit dem einem leeren String "" zu belegen. Auch in diesem Fall werden alle gefundenen Einträge zurückgegeben (für Einträge ohne holder gilt das Limit von 100 Ergebnissen nicht).
schema:
type: string
- name: personalEntry
in: query
description: Erlaubt die Suche mit Hilfe des Attributs personalEntry.
schema:
type: string
- name: dataFromAuthority
in: query
description: Erlaubt die Suche mit Hilfe des Attributs dataFromAuthority.
schema:
type: string
- name: baseEntryOnly
in: query
description: Mit baseEntryOnly = "true" wird nur der Basiseintrag (baseDirectoryEntry) im Response zurückgegeben. Falls nicht angegeben oder mit "false" belegt, wird der gesamte Verzeichniseintrag mit Zertifikaten und Fachdaten im Response zurückgegeben.
schema:
type: boolean
example: true
responses:
200:
description: OK
# Es werden alle zu dem Filter Parametern passenden Verzeichniseinträge - inklusive Zertifikaten und Fachdaten - zurückgegeben.
# Bei mehr als 100 gefundenen Einträgen nur 100 gefundenen Einträge zurückgegeben.
# Wenn der Suchparameter "holder" mit dem eigenen Wert des Clients belegt wird, werden alle gefundenen Einträge zurückgegeben (für eigene Einträge gilt das Limit von 100 Ergebnissen nicht).
content:
application/json:
schema:
$ref: '#/components/schemas/DirectoryEntries'
401:
description: Unauthorized
# Der WWW-Authenticate Header im Response wird auf OAuth gesetzt.
content: {}
403:
description: Forbidden
content: {}
404:
description: Not Found
content: {}
503:
description: Service Unavailable
# Der Server schränkt die parallele Nutzung dieser Operation read_Directory_Entry_WL ein. Der Request kann nach einer angemessenen Zeitspanne wiederholt werden.
content: {}
/DirectoryEntries/{uid}/baseDirectoryEntries:
put:
tags:
- DirectoryEntry Administration
summary: Der Verzeichniseintrag (ohne Zertifikate und Fachdaten) wird mit den übergebenen Daten aktualisiert.
operationId: modify_Directory_Entry
parameters:
- name: uid
in: path
description: ID von dem Verzeichniseintrag
required: true
schema:
type: string
requestBody:
description: Datensatz für die Aktualisierung des Eintrags
Die Attribute müssen wie folgt belegt sein
dn.* Nicht vorhanden (Adressierung erfolgt über uid in Path).
givenName Nicht vorhanden.
sn Nicht vorhanden.
cn Nicht vorhanden.
displayName Kann optional belegt werden.
streetAddress Kann optional belegt werden.
postalCode Kann optional belegt werden.
countryCode Kann optional belegt werden.
localityName Kann optional belegt werden.
stateOrProvinceName Kann optional belegt werden.
title Kann optional belegt werden.
organization Kann optional belegt werden.
otherName Nicht vorhanden.
telematikID Kann optional belegt werden.
Das ist die telematikID in den Basisdaten (baseDirectoryEntry).
Sind Zertifikateseinträge (userCertificate) vorhanden, dann müssen die telematikIDs übereinstimmen.
Bei unterschiedlichen telematikID wird die Operation mit Fehlercode 422 abgelehnt.
specialization Kann optional belegt werden.
domainID Kann optional belegt werden.
holder Kann optional belegt werden.
maxKOMLEadr Kann optional belegt werden.
personalEntry Nicht vorhanden.
dataFromAuthority Nicht vorhanden
content:
application/json:
schema:
$ref: '#/components/schemas/baseDirectoryEntry'
required: true
responses:
200:
description: OK
# Der Verzeichniseintrag wurde aktualisiert.
content:
application/json:
schema:
$ref: '#/components/schemas/distinguishedName'
400:
description: Bad Request
# Invalid ID supplied
content: {}
401:
description: Unauthorized
# Der WWW-Authenticate Header im Response muss auf OAuth gesetzt werden.
content: {}
403:
description: Forbidden
content: {}
404:
description: Not Found
content: {}
405:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
422:
description: Unprocessable Entity
# Z.B. Wert aus dem Request Attribut "holder" nicht gültig
# Bei unterschiedlichen telematikIDs (Parameter telematikID und Wert im userCertificate) wird die Operation mit Fehlercode 422 abgelehnt.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/DirectoryEntries/{uid}:
delete:
tags:
- DirectoryEntry Administration
summary: Gesamten Verzeichniseintrag löschen
operationId: delete_Directory_Entry
parameters:
- name: uid
in: path
description: ID von dem zu löschenden Verzeichniseintrag
Gelöscht werden der Basis Verzeichniseintrag sowie alle dazugehörenden Zertifikate und Fachdaten.
required: true
schema:
type: string
responses:
200:
description: OK
content: {}
400:
description: Bad Request
# Invalid ID supplied
content: {}
401:
description: Unauthorized
# Der WWW-Authenticate Header im Response muss auf OAuth gesetzt werden.
content: {}
403:
description: Forbidden
content: {}
404:
description: Not Found
content: {}
/DirectoryEntries/{uid}/Certificates:
post:
tags:
- Certificate Administration
summary: Der Zertifikatseintrag wird im Verzeichnisdienst hinzugefügt und ist logisch über dn.uid mit dem übergeordneten Verzeichniseintrag verknüpft.
operationId: add_Directory_Entry_Certificate
parameters:
- name: uid
in: path
description: ID (dn.uid) vom übergeordneten Verzeichniseintrag
required: true
schema:
type: string
requestBody:
description: Datensatz für die Erzeugung des Eintrags
Die Attribute müssen wie folgt belegt sein
Attribut Wert
-------------------------------------------
dn.* Nicht vorhanden (Adressierung erfolgt über uid in Path)
telematikID Kann optional belegt werden.
Wird telematikID angegeben, dann muss diese telematikID mit der telematikID im userCertificate übereinstimmen.
Die telematikID muss mit der telematikID in den Basisdaten (baseDirectoryEntry) übereinstimmen (falls dort angegeben).
Falls die telematikID in den Basisdaten (baseDirectoryEntry) leer ist, muss sie auf den Wert aus dem Zertifikat bzw. dem hier angegebenen Wert gesetzt werden.
Bei unterschiedlichen telematikIDs wird die Operation mit Fehlercode 422 abgelehnt.
entryType Nicht vorhanden (wird vom Verzeichnisdienst belegt)
professionOID Nicht vorhanden (wird vom Verzeichnisdienst belegt)
usage Kann optional belegt werden
userCertificate Muss vorhanden sein
description Kann optional belegt werden
content:
application/json:
schema:
$ref: '#/components/schemas/userCertificate'
required: true
responses:
201:
description: Created
# Der Zertifikatseintrag wurde hinzugefügt. Zurückgegeben wird der distinguishedName des erzeugten Eintrags.
content:
application/json:
schema:
$ref: '#/components/schemas/distinguishedName'
401:
description: Unauthorized
# Der WWW-Authenticate Header im Response muss auf OAuth gesetzt werden.
content: {}
403:
description: Forbidden
content: {}
405:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
422:
description: Unprocessable Entity
# Bei unterschiedlichen telematikIDs (Parameter telematikID und Wert im userCertificate) wird die Operation mit Fehlercode 422 abgelehnt.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/DirectoryEntries/Certificates:
get:
tags:
- Certificate Administration
summary: Zertifikat lesen
description: Liefert alle Zertifikate, die dem Filter (siehe 'parameters') entsprechen.
operationId: read_Directory_Certificates
parameters:
- name: uid
in: query
description: ID vom übergeordneten Verzeichniseintrag
schema:
type: string
- name: certificateEntryID
in: query
description: ID von dem Zertifikat (dn.cn vom Zertifikatseintrag)
Wenn angegeben wird das adressierte (certificateEntryID) Zertifikat geliefert.
Wenn nicht angegeben werden alle Zertifikate des übergeordneten Verzeichniseintrags geliefert.
schema:
type: string
- name: entryType
in: query
description: Erlaubt die Suche mit Hilfe des Attributs entryType.
schema:
type: string
- name: telematikID
in: query
description: telematikID von dem Zertifikat
Erlaubt die Suche nach Zertifikatseinträgen einer telematikID.
schema:
type: string
- name: professionOID
in: query
description: Erlaubt die Suche mit Hilfe des Attributs professionOID.
Der Verzeichniseintrag wird selektiert, wenn die angegebene professionOID im Attribut professionOID (array) des Zertifikatseintrags enthalten ist.
schema:
type: string
- name: usage
in: query
description: Erlaubt die Suche mit Hilfe des Attributs usage.
Der Verzeichniseintrag wird selektiert, wenn die angegebene usage im Attribut usage (array) des Zertifikatseintrags enthalten ist.
schema:
type: string
responses:
200:
description: OK
# Es werden alle gefundenen Zertifikatseinträge zurückgegeben.
# Bei mehr als 100 gefundenen Einträgen nur 100 gefundenen Einträge zurückgegeben.
content:
application/json:
schema:
$ref: '#/components/schemas/userCertificates'
401:
description: Unauthorized
# Der WWW-Authenticate Header im Response muss auf OAuth gesetzt werden.
content: {}
403:
description: Forbidden
content: {}
404:
description: Not Found
# Certificate not found
content: {}
components:
schemas:
userCertificate:
description: Jeder Verzeichniseintrag muss mindestens ein Zertifikat enthalten.
required:
- dn
type: object
properties:
dn:
$ref: '#/components/schemas/distinguishedName'
entryType:
type: string
description: 'Eintragstyp Wird vom VZD anhand der in dem Zertifikat
enthaltenen OID (Extension Admission, Attribut ProfessionOID) und der
Spalte Eintragstyp in Tab_VZD_Mapping_Eintragstyp_und_ProfessionOID automatisch
eingetragen. Siehe auch [gemSpecOID]# Tab_PKI_402 und Tab_PKI_403'
readOnly: true
telematikID:
type: string
description: 'Wird beim Anlegen des Eintrags vom VZD aus dem Zertifikat übernommen (Feld registrationNumber der Extension Admission).
Falls der Basiseintrag (baseDirectoryEntry) ohne Zertifikat angelegt wird, kann in Operation add_Directory_Entry die telematikID angegeben werden.
Damit ist der Verzeichniseintrag bereits über die telematikID auffindbar.'
professionOID:
maxItems: 100
minItems: 0
type: array
readOnly: true
items:
type: string
description: 'Profession OID / Wird vom VZD anhand der in
den Zertifikaten enthaltenen OIDs (Extension Admission, Attribut ProfessionOID)
und dem Mapping in ab_VZD_Mapping_Eintragstyp_und_ProfessionOID automatisch
eingetragen. Siehe [gemSpecOID]# Tab_PKI_402 und Tab_PKI_403. / kann
mehrfach vorkommen (0..100)'
usage:
maxItems: 100
minItems: 0
type: array
description: 'Nutzungskennzeichnung kann pro Zertifikat mehrfach
vergeben werden. Vorgegebener Wertebereich [KOM-LE, ePA].
Obligatorisch für LEI und KTR mit vorgegebenem Wert usage=ePA'
items:
type: string
enum:
- KOM-LE
- ePA
userCertificate:
type: string
description: 'Zertifikat im DER Format. Base64 kodiert.
Die pflegende Stelle erhält das Zertifikat vom TSP oder falls das nicht möglich ist wird ein Ersatzverfahren abgestimmt.'
description:
type: string
description: Dieses Attribut ermöglicht das Zertifikat zu beschreiben, um
die Administration des VZD Eintrags zu vereinfachen.
userCertificates:
type: array
items:
$ref: '#/components/schemas/userCertificate'
Fachdaten:
required:
- dn
type: object
properties:
dn:
$ref: '#/components/schemas/distinguishedName'
FAD1:
maxItems: 50
minItems: 0
type: array
items:
$ref: '#/components/schemas/FAD1'
FAD1:
required:
- dn
type: object
properties:
dn:
$ref: '#/components/schemas/distinguishedName'
mail:
type: array
items:
type: string
description: 'E-Mail-Adresse'
readOnly: true
distinguishedName:
required:
- uid
readOnly: true
type: object
properties:
uid:
type: string
description: 'entryID: Name/ID, den den Eintrag eindeutig identifiziert. Hat für den Verzeichnisdienst_Eintrag, Certificate, KOM-LE_Fachdaten und FAD1 eines Verzeichniseintrags den gleichen Wert.'
dc:
type: array
items:
type: string
description: Domain Component
ou:
type: array
items:
type: string
description: Organizational Unit
cn:
type: string
description: Common Name
baseDirectoryEntry:
required:
- cn
- dn
type: object
properties:
dn:
$ref: '#/components/schemas/distinguishedName'
givenName:
type: string
description: 'HBA: Vorname, obligatorisch, wird aus dem Zertifikat
übernommen / SMC-B: nicht verwendet'
readOnly: true
example: Vorname
sn:
type: string
description: 'HBA: Name, obligatorisch, wird aus dem Zertifikat
übernommen / SMC-B: nicht verwendet'
readOnly: true
example: Nachname
cn:
type: string
description: 'HBA: Vorname und Nachname / SMC-B: Bezeichner:
Name Wird vom VZD aus dem Zertifikatsattribut commonName übernommen.'
readOnly: true
example: Vorname Nachname
displayName:
type: string
description: 'Anzeigename, kann geändert werden.
Dieses Attribut wird genutzt um den Namen der Organisation gegenüber dem Anwender darzustellen (Verwendung als Filter-Attribut um die Suche einzuschränken und bei der Darstellung des Ergebnisses).
Der Wert wird von der pflegenden Stelle festgelegt.
Konvention für HBA Einträge: Name, Vorname'
example: Name, Vorname
streetAddress:
type: string
description: 'Straße und Hausnummer
Der Wert wird von der pflegenden Stelle festgelegt'
example: Friedrichstraße 136
postalCode:
type: string
description: 'Postleitzahl
Der Wert wird von der pflegenden Stelle festgelegt'
example: 10117
countryCode:
type: string
maxLength: 2
description: 'Ländercode
Entsprechend ISO-3166-1 ALPHA-2'
# Falls das Attribut beim Anlegen des Datensatzes nicht beölegt wird, ergänzt der VZD den Code für Deutschland (Defaultwert).
example: DE
localityName:
type: string
description: 'Ort
Der Wert wird von der pflegenden Stelle festgelegt'
example: Berlin
stateOrProvinceName:
type: string
description: 'Bundesland
Der Wert wird von der pflegenden Stelle festgelegt'
example: Berlin
title:
type: string
description: 'HBA: Titel, optional / SMC-B: nicht verwendet'
organization:
type: string
example: 12345670
description: 'Organisation
Der Wert wird von der pflegenden Stelle festgelegt'
otherName:
type: string
description: 'Anderer Name.
Wird vom VZD aus dem Zertifikatsattribut otherName übernommen.'
telematikID:
type: string
description: 'Wird beim Anlegen des Eintrags vom VZD aus dem Zertifikat übernommen (Feld registrationNumber der Extension Admission).
Falls der Basiseintrag (baseDirectoryEntry) ohne Zertifikat angelegt wird, kann in Operation add_Directory_Entry die telematikID angegeben werden.
Damit ist der Verzeichniseintrag bereits über die telematikID im baseDirectoryEntry auffindbar. Diese telematikID muss mit der telematikID aus dem Zertifikatseintrag (userCertificate) übereinstimmen. Simmten die telematikIDs nicht überein, wird die Operation mit Fehlercode 422 abgelehnt'
specialization:
maxItems: 100
type: array
description: 'Fachgebiet
Der Wert wird von der pflegenden Stelle festgelegt'
items:
type: string
domainID:
maxItems: 100
type: array
description: 'Ärzte-> Betriebsstättennummer
Der Wert wird aus dem Zertifikat übernommen (Attribut organizationName)'
items:
type: string
example: 345678975
holder:
maxItems: 100
type: array
description: Identifiziert den Eigentümer dieses Verzeichniseintrags, der Änderungen an ihm vornehmen darf.
Hat keinen Einfluss auf Fachdaten und Zertifikatsdaten.
Beim Anlegen eines neuen Verzeichniseintrags (add_Directory_Entry)
- Ist im add_Directory_Entry Request das Attribut "holder" nicht vorhanden oder enthält keine Werte
o Wird vom VZD aus dem ID_TOKEN claim scope der Wert entnommen und als "holder" in dieses Attribut eingetragen.
- Ist im add_Directory_Entry Request das Attribut "holder" vorhanden und mit Inhalten gefüllt
o Übernimmt der VZD die Werte aus dem Request und trägt sie - nach Prüfung ihrer Gültigkeit - in den Verzeuichniseintrag ein.
Ist ein Wert aus dem Request nicht gültig, weist der VZD die Operation mit HTTP-Status-Code 422 ab.
Beim Ändern eines neuen Verzeichniseintrags (modify_Directory_Entry)
- Ist im modify_Directory_Entry Request das Attribut "holder" nicht vorhanden oder enthält keine Werte
o Die Werte im aktuellen "holder" Attribut des Verzeichniseintrags bleiben erhalten.
- Ist im add_Directory_Entry Request das Attribut "holder" vorhanden und mit Inhalten gefüllt
o Übernimmt der VZD die Werte aus dem Request und trägt sie - nach Prüfung ihrer Gültigkeit - in den Verzeuichniseintrag ein.
Ist ein Wert aus dem Request nicht gültig, weist der VZD die Operation mit HTTP-Status-Code 422 ab.
items:
type: string
example: KartenHerausgeberABC
maxKOMLEadr:
type: string
description: Maximale Anzahl von mail Adressen in den KOM-LE Fachdaten. Falls kein Wert eingetragen wurde, können beliebig viele mail Adressen in den KOM-LE Fachdaten eingetragen werden. Falls ein Wert eingetragen wurde, können maximal so viele mail Adressen in den KOM-LE Fachdaten eingetragen werden.
example: 1
personalEntry:
type: boolean
description: Wird vom VZD eingetragen / Wert == TRUE, wenn alle Zertifikate
den entryType 1 haben (Berufsgruppe), Wert == FALSE sonst
readOnly: true
example: true
dataFromAuthority:
type: boolean
description: Wird vom VZD eingetragen / Wert == TRUE, wenn der Verzeichnisdienst_Eintrag von dem Kartenherausgeber geschrieben wurde, Wert == FALSE sonst
readOnly: true
example: true
changeDateTime:
type: string
format: date-time
description: Der VZD setzt dieses Attribut bei jeder Schreiboperation für den Datensatz (Basisdaten) auf die aktuelle Zeit. Format entsprechend RFC 3339, section 5.6.
readOnly: true
example: "2017-07-21T17:32:28Z"
DirectoryEntry:
type: object
properties:
DirectoryEntryBase:
$ref: '#/components/schemas/baseDirectoryEntry'
userCertificates:
maxItems: 50
minItems: 0
type: array
items:
$ref: '#/components/schemas/userCertificate'
Fachdaten:
maxItems: 50
minItems: 0
type: array
items:
$ref: '#/components/schemas/Fachdaten'
CreateDirectoryEntry:
type: object
properties:
DirectoryEntryBase:
$ref: '#/components/schemas/baseDirectoryEntry'
userCertificates:
maxItems: 50
minItems: 0
type: array
items:
$ref: '#/components/schemas/userCertificate'
DirectoryEntries:
type: array
items:
$ref: '#/components/schemas/DirectoryEntry'
Error:
type: object
maxItems: 50
minItems: 0
properties:
attributeName:
description: Name des Attributs, in dem ein Fehler erkannt wurde
type: string
attributeError:
description: Beschreibung des erkannten Fehlers
type: string
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://to.be.defined/oauth/token
refreshUrl: https://to.be.defined/oauth/refreshToken
scopes:
VZD:DirectoryAdministration: I_Directory_Administration Client Scope
Als Clients dieser Schnittstelle sind nur Systeme der TI Kartenherausgeber und von ihnen beauftragte Organisationen (z.B. TSPs) zulässig.
Sie dürfen alle Operationen zur Administration der Verzeichniseinträge nutzen.
Das AccessToken enthält im "sub" claim den Identifier des Clients, der auf die Einträge zugreift. Dieser Identifier wird im Log abgelegt, welcher die Zugriffe über diese Schnittstelle protokolliert.
security:
- OAuth2:
- VZD:DirectoryAdministration © 2015 - 2025 Weber Informatics LLC | Privacy Policy