openapi: 3.0.1
info:
  title: DVDV2 öffentliche API
  description: |-
    Öffentliche, lesende API für das DVDV.
    In diesem Dokument sind die öffentlichen Directory-Schnittstellen des DVDV2-Kernsystems dokumentiert.
    Es richtet sich also an erstens an Fachverfahrens-Entwickler, die diese Schnittstellen direkt aufrufen wollen, statt eine der DVDV-Bibliotheken zu verwenden,
    und zweitens an Entwickler, die die Schnittstellen des DVDV2-Kernsystems nachbilden wollen.

    Die URL, unter der Sie die u.a. Endpunkte erreichen, ergibt sich aus der URL Ihres DVDV-Betreibers, gefolgt vom sogenannten 'entryPath', gefolgt vom jeweiligen Funktionsnamen.
    Für den entryPath gibt es dabei folgende Werte: 

    (1) intern/directory (für rechenzentrumsinternen, unauthentifizierten Zugriff)

    (2) extern/standaloneauth/directory (für die Standalone-Authentifzierung, also mit einem vom DVDV-Server ausgestellten Token), und 

    (3) extern/bundesmasterauth/directory (für die Authentifizierung am IAM des Bundesmaster-Betreibers.).

    Damit ergibt sich z.B. https://ihr-dvdv-betreiber/dvdv2-backend/extern/standaloneauth/directory/findauthoritydescription

    Eine Sonderrolle spielt der Endpunkt extern/standaloneauth/token (siehe Methode createToken).
    Diesen benötigen Sie zum Erzeugen eines Tokens im Falle der Standalone-Authentifzierung.

    Wenn Sie diese Schnittstelle direkt aufrufen (ohne eine DVDV-Bibliothek), denken Sie daran, das vom Server bereitgestellte TLS-Zertifikat auf Gültigkeit und Vertrauenswürdigkeit des Herausgebers zu prüfen.
  contact:
    name: Dataport AöR
    url: 'https://www.dataport.de/'
    email: dvdv-development@dataport.de
  license:
    name: EUPL 1.2
    url: 'https://eupl.eu/1.2/de/'
  version: 2.9.0
paths:
  /extern/standaloneauth/token:
    post:
      summary: Liefert ein Access-Token
      description: |-
        Erzeugt ein Access-Token, mit dem der Aufrufer sich in nachfolgenden, fachlichen Requests authentifizieren kann.
        Diese Variante der Authentifizierung heißt 'Standalone-Authentifizierung'.
        Die Funktionsweise ist fast konform zu einem Spezialfall des OpenIdConnect-Standards:
        Die Request-Parameter und die Struktur der Response sind konform zum OpenIdConnect-Standard.
        Der Aufrufer fügt das in dieser Response enthalten Token in den nachfolgenden fachlichen Requests in den Standard-HTTP-Header 'Authorization' ein, 
        aber (und das ist die einzige Abweichung vom OpenIdConnect-Standard), mit dem Schlüssel 'EmbeddedBearer' anstelle von 'Bearer'.
      operationId: createToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: 'Der Wert sollte lauten: ''client_credentials'''
                client_assertion_type:
                  type: string
                  description: 'Der Wert sollte lauten: ''urn:ietf:params:oauth:client-assertion-type:jwt-bearer'''
                client_assertion:
                  type: string
                  description: 'Das RS256-signierte JWT-Token. Dieses JWT-Token muss ein subject der Form ''fp:<Zertifikatsfingerprint>'' haben für ein Client-Zertifikat im DVDV.'
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/AccessToken'
              examples:
                Tagesgültiges Token:
                  description: Tagesgültiges Token
                  value:
                    accessToken: eyJhbGciO..fC7CGKIZA
                    expiresIn: 86400
                    refreshExpiresIn: 0
                    tokenType: Bearer
                    notBeforePolicy: 0
                    scope: email profile dvdv2-kernsystem-application-client-scope
        '401':
          description: Kein passendes Client-Zertifikat
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Kein passendes Client-Zertifikat:
                  description: Kein passendes Client-Zertifikat
                  value:
                    type: problems/type/AUTHENTICATION
                    title: Fehler bei der Standalone-Authentifizierung
                    status: 401
                    detail: Kein passendes Client-Zertifikat gefunden für fingerprint 0d...dd5
                    instance: problems/instance/StandaloneAuthentication
  '/{entryPath}/batch/findOrganizationsByServiceElement':
    post:
      summary: findOrganizationsByServiceElement (batch-Variante)
      description: batch-Variante von findOrganizationsByServiceElement
      operationId: batchFindOrganizationsByServiceElement
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      requestBody:
        description: 'Anfrageparameter, nur ''serviceElementType'', ''parameterType'' und ''Value'' müssen gefüllt sein'
        content:
          application/json; charset=utf-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OrganizationDescription'
  '/{entryPath}/batch/findServiceSpecificationUrisByCategory':
    post:
      summary: findServiceSpecificationUrisByCategory (batch-Variante)
      description: batch-Variante von findServiceSpecificationUrisByCategory
      operationId: batchFindServiceSpecificationUrisByCategory
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      requestBody:
        description: 'Anfrageparameter, nur ''category'' muss gefüllt sein'
        content:
          application/json; charset=utf-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Request'
  '/{entryPath}/batch/findauthoritydescription':
    post:
      summary: findauthoritydescription (batch-Variante)
      description: batch-Variante von findauthoritydescription
      operationId: batchFindAuthorityDescription
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      requestBody:
        description: 'Anfrageparameter, nur ''category'' und ''organizationKey'' müssen gefüllt sein'
        content:
          application/json; charset=utf-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OrganizationDescription'
  '/{entryPath}/batch/findcategories':
    post:
      summary: findcategories (batch-Variante)
      description: batch-Variante von findCategories
      operationId: batchFindCategories
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      requestBody:
        description: 'Anfrageparameter, nur ''fingerPrint'' und ''organizationKey'' müssen gefüllt sein'
        content:
          application/json; charset=utf-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  type: string
  '/{entryPath}/batch/findservicedescription':
    post:
      summary: findservicedescription (batch-Variante)
      description: batch-Variante von findservicedescription
      operationId: batchFindServiceDescription
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      requestBody:
        description: 'Anfrageparameter, nur ''organizationKey'' und ''serviceSpecificationUri'' müssen gefüllt sein'
        content:
          application/json; charset=utf-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Service'
  '/{entryPath}/batch/verifycategory':
    post:
      summary: verifycategory (batch-Variante)
      description: batch-Variante von verifyCategory
      operationId: batchVerifyCategory
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      requestBody:
        description: 'Anfrageparameter, nur ''fingerPrint'' und ''category'' müssen gefüllt sein'
        content:
          application/json; charset=utf-8:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VerificationResult'
  '/{entryPath}/categories':
    get:
      summary: categories
      description: Liefert den Baum aller im DVDV verzeichneten Kategorien.
      operationId: findAllCategories
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SummaryServiceElementDTO'
        '401':
          description: 'Nicht authentifiziert. Es ist eine Authentifizierung notwendig, um diese Aktion auszuführen.'
  '/{entryPath}/findCertificateByFingerprint':
    get:
      summary: 'findCertificateByFingerprint: Ermittlung des Zertifikats'
      description: Ermittelt das Zertifikat mit dem angegebenen Fingerprint. Vom DirectoryRequestDTO muss dementsprechend nur das Feld 'FingerPrint' gefüllt sein.
      operationId: findCertificateByFingerprint
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: JSON-String mit dem Feld 'fingerPrint'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Certificate'
        '404':
          description: Kein oder mehr als ein Zertifikat gefunden.
  '/{entryPath}/findOrganizationsByServiceElement':
    get:
      summary: 'findOrganizationsByServiceElement: Query mit Dienstelementeigenschaften'
      description: 'Findet die Organisationen, die ein Dienstelement haben, das auf die in den Parametern angegebene Query passt.'
      operationId: findOrganizationsByServiceElement
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: 'JSON-String mit Feldern ''serviceElementType'', ''parameterType'' und ''parameterValue'''
          required: true
          schema:
            type: string
          example: '{"serviceElementType":"OSCI_ADDRESSEE","parameterType":"CIPHER_CERTIFICATE","parameterValue":"80157bbb3934cb651fb4df94a98773fba0b02b03"}'
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OrganizationDescription'
        '400':
          description: Es wurden ungültige Anfrageparameter übermittelt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Nicht-wohlgeformtes JSON:
                  description: Nicht-wohlgeformtes JSON
                  value:
                    type: problems/type/INPUT_VALIDATION
                    title: Invalide Eingabe
                    status: 400
                    detail: 'JSON-Verarbeitungsfehler: Fehler bei JSON-Konvertierung für URL-Query-Parameter request_json=''{Nonsense-Eingabe'''
                    instance: problems/instance/RequestJsonProcessing
                Falsche Parameter:
                  description: Falsche Parameter
                  value:
                    type: problems/type/INPUT_VALIDATION
                    title: Invalide Eingabe
                    status: 400
                    detail: 'JSON-Verarbeitungsfehler: Fehler bei JSON-Konvertierung für URL-Query-Parameter request_json=''{"serviceElementType":"Irrtum","parameterType":"Hier ist ein","parameterValue":"Fehler im Request"}'''
                    instance: problems/instance/RequestJsonProcessing
  '/{entryPath}/findServiceSpecificationUrisByCategory':
    get:
      summary: findServiceSpecificationUrisByCategory
      description: 'Liefert alle Dienstbeschreibungs-URIs, die von Organisationen der angegebenen Kategorie angeboten werden dürfen.'
      operationId: findServiceSpecificationUrisByCategory
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: JSON-String mit dem Feld 'category'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceBase'
        '401':
          description: 'Nicht authentifiziert. Es ist eine Authentifizierung notwendig, um diese Aktion auszuführen.'
  '/{entryPath}/findauthoritydescription':
    get:
      summary: 'findauthoritydescription: Organisationsermittlung'
      description: 'Entspricht der Schnittstelle ''FindAuthorityDescription'' des Altsystems DVDV 1. Wird benutzt von den DVDV-Bibliotheks-Funktionen findOrganizationDescription und findAuthorityDescription. Die Schnittstelle liefert zu einem gegebenen Organisationsschlüssel und der zugeordneten Organisationskategorie die Beschreibung der Organisation und des zugehörigen Organisation-Stellvertreters, sofern vorhanden. Vom DirectoryRequestDto müssen dementsprechend nur die Felder ''category'' und ''organizationKey'' gefüllt sein.'
      operationId: findAuthorityDescription
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: JSON-String mit Feldern 'category' und 'organizationKey'
          required: true
          schema:
            type: string
          example: '{"category":"Meldebehörde","organizationKey":"ags:01999001"}'
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/OrganizationDescription'
        '400':
          description: Es wurden ungültige Anfrageparameter übermittelt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Nicht-wohlgeformtes JSON:
                  description: Nicht-wohlgeformtes JSON
                  value:
                    type: problems/type/INPUT_VALIDATION
                    title: Invalide Eingabe
                    status: 400
                    detail: 'JSON-Verarbeitungsfehler: Fehler bei JSON-Konvertierung für URL-Query-Parameter request_json=''{Nonsense-Eingabe'''
                    instance: problems/instance/RequestJsonProcessing
                Fehlende Kategorie-Angabe:
                  description: Fehlende Kategorie-Angabe
                  value:
                    type: problems/type/SERVICE_VALIDATION
                    title: Invalider Request
                    status: 400
                    detail: Parameter 'category' fehlt
                    instance: problems/instance/RestValidation
        '404':
          description: Organisation konnte nicht gefunden werden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Kein Treffer:
                  description: Kein Treffer
                  value:
                    type: problems/type/ENTITY_NOT_FOUND
                    title: Entität nicht gefunden
                    status: 404
                    detail: '5009: Keine Organisation mit Kategorie "Meldebehörde" und Organisationsschlüssel "ags:irrtum" gefunden'
                    instance: problems/instance/DirectoryEntityNotFound
  '/{entryPath}/findauthoritydescriptions':
    get:
      summary: 'findauthoritydescriptions: Organisationsermittlung ohne Kategorie'
      description: 'Wie findauthoritydescription, nur ohne Angabe einer Kategorie. Dadurch kann es mehrere Treffer geben, das ist aber vergleichsweise selten. Vom DirectoryRequestDto muss dementsprechend nur das Feld ''organizationKey'' gefüllt sein.'
      operationId: findAuthorityDescriptions
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: JSON-String mit Feld 'organizationKey'
          required: true
          schema:
            type: string
          example: '{"organizationKey":"ags:01999001"}'
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationDescription'
        '400':
          description: Es wurden ungültige Anfrageparameter übermittelt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Nicht-wohlgeformtes JSON:
                  description: Nicht-wohlgeformtes JSON
                  value:
                    type: problems/type/INPUT_VALIDATION
                    title: Invalide Eingabe
                    status: 400
                    detail: 'JSON-Verarbeitungsfehler: Fehler bei JSON-Konvertierung für URL-Query-Parameter request_json=''{Nonsense-Eingabe'''
                    instance: problems/instance/RequestJsonProcessing
  '/{entryPath}/findcategories':
    get:
      summary: 'findcategories: Kategorienermittlung'
      description: 'Wird benutzt von der DVDV-Bibliotheks-Funktion findCategories. Ermittelt diejenigen Kategorien (typischerweise genau eine), zu denen es eine Organisation mit dem gegebenen Client-Zertfifikat und Organisationsschlüssel gibt. Dabei handelt es sich um die Blätter des Kategorienbaumes, z.B. ''Meldebörde'', ''Passbehörde'', ''StA'''
      operationId: findCategories
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: JSON-String mit Feldern 'fingerPrint' und 'organizationKey'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Es wurden ungültige Anfrageparameter übermittelt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Nicht-wohlgeformtes JSON:
                  description: Nicht-wohlgeformtes JSON
                  value:
                    type: problems/type/INPUT_VALIDATION
                    title: Invalide Eingabe
                    status: 400
                    detail: 'JSON-Verarbeitungsfehler: Fehler bei JSON-Konvertierung für URL-Query-Parameter request_json=''{Nonsense-Eingabe'''
                    instance: problems/instance/RequestJsonProcessing
                Fehlende Organisationsschlüssel-Angabe:
                  description: Fehlende Organisationsschlüssel-Angabe
                  value:
                    type: problems/type/SERVICE_VALIDATION
                    title: Invalider Request
                    status: 400
                    detail: Parameter 'organizationKey' fehlt
                    instance: problems/instance/RestValidation
  '/{entryPath}/findservicedescription':
    get:
      summary: 'findservicedescription: Ermittlung eines gültigen Diensts'
      description: Entspricht der Schnittstelle 'FindServiceDescription' des Altsystems DVDV 1. Wird benutzt von der DVDV-Bibliotheks-Funktion findServiceDescription. Die Schnittstelle liefert zu einem gegebenen Organisationsschlüssel und einer Dienstbeschreibungs-URI die Beschreibung des aktuell gültigen Dienstes mit allen Verbindungsparametern. Vom DirectoryRequestDto müssen dementsprechend nur die Felder 'organizationKey' und 'serviceSpecificationUri' gefüllt sein.
      operationId: findServiceDescription
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: JSON-String mit Feldern 'organizationKey' und 'serviceSpecificationUri'
          required: true
          schema:
            type: string
          example: '{"organizationKey":"ags:01999001","serviceSpecificationUri":"http://www.osci.de/xauslaender1100/xauslaender1100ABHABH.wsdl"}'
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Es wurden ungültige Anfrageparameter übermittelt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Nicht-wohlgeformtes JSON:
                  description: Nicht-wohlgeformtes JSON
                  value:
                    type: problems/type/INPUT_VALIDATION
                    title: Invalide Eingabe
                    status: 400
                    detail: 'JSON-Verarbeitungsfehler: Fehler bei JSON-Konvertierung für URL-Query-Parameter request_json=''{Nonsense-Eingabe'''
                    instance: problems/instance/RequestJsonProcessing
        '404':
          description: Kein gültiger passender Dienst gefunden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Kein Treffer:
                  description: Kein Treffer
                  value:
                    type: problems/type/ENTITY_NOT_FOUND
                    title: Entität nicht gefunden
                    status: 404
                    detail: '5005: Kein Dienst zum Organisationsschlüssel ''ags:gibsnich'' und URI http://www.osci.de/xinneres/rueckweisung/3/xinneresrueckweisungv3.wsdl.'
                    instance: problems/instance/DirectoryEntityNotFound
  '/{entryPath}/intermediaries':
    get:
      summary: intermediaries
      description: Liefert eine Liste aller im DVDV verzeichneten Intermediäre.
      operationId: findByType
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SummaryServiceElementDTO'
        '401':
          description: 'Nicht authentifiziert. Es ist eine Authentifizierung notwendig, um diese Aktion auszuführen.'
  '/{entryPath}/verifycategory':
    get:
      summary: 'verifycategory: Kategorienüberprüfung'
      description: 'Entspricht der Schnittstelle ''VerifyCategory'' des Altsystems DVDV 1. Wird benutzt von der DVDV-Bibliotheks-Funktion verifyCategory. Die Schnittstelle liefert zu einem gegebenen Zertifikat-Fingerprint und der zugeordneten Organisationskategorie ein Prüfergebnis ''true'' oder ''false''. Das Ergebnis ist genau dann ''true'', wenn es eine Organisation mit der angegebenen Organisationskategorie gibt, für die das übermittelte Zertifikat als Client-Zertifikat hinterlegt ist. Vom DirectoryRequestDto müssen dementsprechend nur die Felder ''fingerPrint'' und ''category'' gefüllt sein.'
      operationId: verifyCategory
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
        - name: request_json
          in: query
          description: JSON-String mit Feldern 'fingerPrint' und 'category'
          required: true
          schema:
            type: string
          example: '{"fingerPrint":"11:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:22","category":"Behörde"}'
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '400':
          description: Es wurden ungültige Anfrageparameter übermittelt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Nicht-wohlgeformtes JSON:
                  description: Nicht-wohlgeformtes JSON
                  value:
                    type: problems/type/INPUT_VALIDATION
                    title: Invalide Eingabe
                    status: 400
                    detail: 'JSON-Verarbeitungsfehler: Fehler bei JSON-Konvertierung für URL-Query-Parameter request_json=''{Nonsense-Eingabe'''
                    instance: problems/instance/RequestJsonProcessing
                Fehlende Kategorie-Angabe:
                  description: Fehlende Kategorie-Angabe
                  value:
                    type: problems/type/SERVICE_VALIDATION
                    title: Invalider Request
                    status: 400
                    detail: Parameter 'category' fehlt
                    instance: problems/instance/RestValidation
  '/{entryPath}/version':
    get:
      summary: getServiceVersion
      description: 'Gibt die Version der Software des DVDV2-Servers als JSON zurück. Keys: version, buildnunmber, schemaversion'
      operationId: getServiceVersion
      parameters:
        - name: entryPath
          in: path
          description: URI-Präfix inkl. Authentifizierungsvariante
          required: true
          schema:
            type: string
            enum:
              - intern/directory
              - extern/bundesmasterauth/directory
              - extern/standaloneauth/directory
      responses:
        '200':
          description: Aktion erfolgreich ausgeführt
          content:
            application/json; charset=utf-8:
              schema:
                type: string
        '401':
          description: 'Nicht authentifiziert. Es ist eine Authentifizierung notwendig, um diese Aktion auszuführen.'
components:
  schemas:
    AccessToken:
      type: object
      properties:
        access_token:
          type: string
          description: 'Das eigentliche Token, das der Aufrufer in nachfolgenden Requests im Authorization-Header im Schlüssel ''EmbeddedBearer'' benutzen sollte.'
        expires_in:
          type: integer
          description: Zeit bis zum  Verfall in Sekunden.
          format: int64
        id_token:
          type: string
        not-before-policy:
          type: integer
          format: int32
        refresh_expires_in:
          type: integer
          description: |-
            Zeit bis zum Verfall des Refresh-Tokens in Sekunden
            Hinweis: Token-Refresh wird zurzeit nicht unterstützt und ist auch nicht sinnvoll.
          format: int64
        refresh_token:
          type: string
          description: 'Hinweis: Token-Refresh wird zurzeit nicht unterstützt und ist auch nicht sinnvoll.'
        scope:
          type: string
        session_state:
          type: string
        token_type:
          type: string
      description: Access-Token gemäß OpenIdConnect-Standard.
    Certificate:
      type: object
      properties:
        algorithm:
          maxLength: 255
          minLength: 3
          type: string
          description: Verschlüsselungsalgorithmus
          example: SHA256withRSA
        content:
          type: string
          description: Zertifikatdatei als Base64-enkodierter String
        emailSubject:
          maxLength: 255
          minLength: 3
          type: string
          description: E-Mail Inhaber
        fingerprint:
          maxLength: 40
          minLength: 40
          type: string
          description: Fingerprint
          format: hexadezimal
          example: 0272c56c9742a62501329a3aa78974f1605c92a2
        nameIssuer:
          maxLength: 255
          type: string
          description: Name des Ausstellers
        nameSubject:
          maxLength: 255
          type: string
          description: Name des Inhabers
        organizationIssuer:
          maxLength: 255
          type: string
          description: Organization des Ausstellers
        organizationSubject:
          maxLength: 255
          type: string
          description: Organization des Inhabers
        ouIssuer:
          maxLength: 255
          type: string
          description: Ou-Issuer
        ouSubject:
          maxLength: 255
          type: string
          description: Ou-Subject
        serial:
          maxLength: 49
          type: string
          description: Seriennummer (Dezimaldarstellung)
          format: dezimal
        serialHex:
          maxLength: 40
          type: string
          description: Seriennummer (Hexadezimaldarstellung)
          format: hexadezimal
        validFrom:
          maxLength: 27
          minLength: 24
          type: string
          description: Gültigkeitszeitraum (Start)
          format: 'Datum (im Format ISO-8601, d.h.yyyy-MM-dd''T''HH:mm:ss.SSS''Z'')'
        validTo:
          maxLength: 27
          minLength: 24
          type: string
          description: Gültigkeitszeitraum (Ende)
          format: 'Datum (im Format ISO-8601, d.h.yyyy-MM-dd''T''HH:mm:ss.SSS''Z'')'
        x509KeyUsage:
          maximum: 32767
          minimum: 0
          type: integer
          description: '16-Bit Bitmap für KeyUsage gemäß X.509-Standard, siehe https://tools.ietf.org/html/rfc5280#page-29, oder null, falls das Zertifikat die KeyUsage-Extension nicht benutzt'
          format: int32
      description: Repräsentation eines Zertifikates
    Organization:
      required:
        - Technische Datenbank-ID
        - category
        - nameDe
        - organizationKeys
      type: object
      properties:
        Technische Datenbank-ID:
          maximum: 9223372036854776000
          minimum: 0
          type: integer
          format: int64
        category:
          maxLength: 255
          type: string
          description: Name der Behördenkategorie
        clientCertificates:
          type: array
          description: Liste der Client-Zertifikate
          items:
            $ref: '#/components/schemas/Certificate'
        descriptionDe:
          type: string
          description: deutsche Beschreibung
        descriptionEn:
          type: string
          description: englische Beschreibung
        dvdv1Id:
          maxLength: 255
          type: string
          description: DVDV1-ID
        locationStateId:
          maximum: 16
          minimum: 1
          type: integer
          description: Länderschlüssel
          format: int64
        nameDe:
          maxLength: 255
          type: string
          description: deutscher Name
        nameEn:
          type: string
          description: englischer Name
        organizationKeys:
          minLength: 1
          type: array
          description: Liste der Behördenschlüssel
          items:
            minLength: 1
            type: string
            description: Liste der Behördenschlüssel
        postalAddress:
          maxLength: 255
          type: string
          description: Anschrift
        services:
          type: array
          description: Liste der Dienste/Dienstbeschreibungen (ohne Dienstelemente)
          items:
            $ref: '#/components/schemas/ServiceBase'
        validFrom:
          type: string
          description: Gültigkeitszeitraum (Start)
        validTo:
          type: string
          description: Gültigkeitszeitraum (Ende)
      description: Repräsentation einer Organisation im DVDV2-Umfeld.
    OrganizationDescription:
      type: object
      properties:
        organization:
          $ref: '#/components/schemas/Organization'
        representatives:
          type: array
          description: Beschreibungsobjekt der Behördenstellvertreter
          items:
            $ref: '#/components/schemas/Organization'
      description: Beschreibung einer Organisation mit den zugehörigen Organisationsstellvertreter.
    Problem:
      type: object
      properties:
        detail:
          type: string
          description: 'Nutzerlesbare, detallierte Beschreibung des Problems.'
        instance:
          type: string
          description: 'Relative URI-Referenz, die das spezifische Auftreten dieses Problems identifiziert. Änderungen hieran gelten als "non-breaking change".'
          format: URI reference
        status:
          type: integer
          description: 'HTTP status code (https://datatracker.ietf.org/doc/html/rfc7231#section-6) vom DVDV-Server.'
          format: int32
        title:
          type: string
          description: 'Kurze, nutzerlesbare Beschreibung des Problemtyps.'
        type:
          type: string
          description: 'Relative URI-Referenz, die den Problemtyp bestimmt. Änderungen hieran gelten als "breaking change", daher eignet sich der Rückgabewert zum Switchen.'
          format: URI reference
    Request:
      type: object
      properties:
        category:
          maxLength: 255
          type: string
          description: Eindeutige Behördenkategoriebezeichnung
          example: Meldebehörde
        customServiceElementType:
          type: string
          description: Name des konfigurierbaren Typs der Dienstbeschreibung (falls serviceElementType fehlt)
        fingerPrint:
          maxLength: 40
          minLength: 40
          type: string
          description: Zertifikat-Fingerprint
          example: 0272c56c9742a62501329a3aa78974f1605c92a2
        organizationKey:
          maxLength: 255
          minLength: 6
          type: string
          description: Behördenschlüsselname
          example: 'ags:05009999'
        parameterType:
          type: string
          description: Typ des Anfrageparameters
          enum:
            - CIPHER_CERTIFICATE
            - SIGNATURE_CERTIFICATE
            - URI
        parameterValue:
          type: string
          description: Wert des Anfrageparameters. Die Bedeutung hängt ab von parameterType.
        serviceElementType:
          type: string
          description: Typ der Dienstbeschreibung
          enum:
            - OSCI_INTERMEDIARY
            - OSCI_ADDRESSEE
            - CIPHER_CERTIFICATE
            - SIGNATURE_CERTIFICATE
            - WEBSERVER
            - TEXT
        serviceSpecificationUri:
          maxLength: 1000
          minLength: 9
          type: string
          description: Name der Dienstbeschreibungs-URI
      description: Generisches Requestobjekt für verschiedene Anfragen an die Directory/Legacy-Schnittstelle
    Service:
      required:
        - Technische Datenbank-ID
        - serviceDescriptionName
        - serviceSpecificationDocument
        - serviceSpecificationType
        - serviceSpecificationUri
      type: object
      properties:
        Technische Datenbank-ID:
          maximum: 9223372036854776000
          minimum: 0
          type: integer
          format: int64
        descriptionDe:
          maxLength: 255
          type: string
          description: deutsche Beschreibung
        descriptionEn:
          maxLength: 255
          type: string
          description: englische Beschreibung
        dvdv1Uuid:
          maxLength: 255
          type: string
          description: DVDV1-UUID
        locationStateId:
          maximum: 16
          minimum: 1
          type: integer
          description: Länderschlüssel
          format: int64
        nameDe:
          maxLength: 255
          type: string
          description: deutscher Name
        nameEn:
          maxLength: 255
          type: string
          description: englischer Name
        organizationNameDe:
          maxLength: 255
          type: string
          description: deutscher Name der zugeordneten Organisation
        organizationNameEn:
          maxLength: 255
          type: string
          description: englischer Name der zugeordneten Organisation
        serviceDescriptionName:
          maxLength: 255
          type: string
          description: Name der zugehörigen Dienstbeschreibung
        serviceElements:
          type: array
          items:
            $ref: '#/components/schemas/ServiceElementInfo'
        serviceSpecificationDocument:
          maxLength: 65535
          type: string
          description: Dienstbeschreibung als WSDL
        serviceSpecificationType:
          type: string
          description: Dienstbeschreibungs-Typ
          enum:
            - WSDL_OSCI
            - MANUAL
        serviceSpecificationUri:
          maxLength: 1000
          type: string
          description: Dienstbeschreibungs-URI
        validFrom:
          maxLength: 27
          minLength: 24
          type: string
          description: Gültigkeitszeitraum (Start)
          format: 'Datum (im Format ISO-8601, d.h.yyyy-MM-dd''T''HH:mm:ss.SSS''Z'')'
        validTo:
          maxLength: 27
          minLength: 24
          type: string
          description: Gültigkeitszeitraum (Ende)
          format: 'Datum (im Format ISO-8601, d.h.yyyy-MM-dd''T''HH:mm:ss.SSS''Z'')'
      description: Dienst im DVDV2-Umfeld.
    ServiceBase:
      required:
        - Technische Datenbank-ID
        - serviceDescriptionName
        - serviceSpecificationType
        - serviceSpecificationUri
      type: object
      properties:
        Technische Datenbank-ID:
          maximum: 9223372036854776000
          minimum: 0
          type: integer
          format: int64
        descriptionDe:
          maxLength: 255
          type: string
          description: deutsche Beschreibung
        descriptionEn:
          maxLength: 255
          type: string
          description: englische Beschreibung
        dvdv1Uuid:
          maxLength: 255
          type: string
          description: DVDV1-UUID
        nameDe:
          maxLength: 255
          type: string
          description: deutscher Name
        nameEn:
          maxLength: 255
          type: string
          description: englischer Name
        serviceDescriptionName:
          maxLength: 255
          type: string
          description: Name der zugehörigen Dienstbeschreibung
        serviceSpecificationType:
          type: string
          description: Dienstbeschreibungs-Typ
          enum:
            - WSDL_OSCI
            - MANUAL
        serviceSpecificationUri:
          maxLength: 1000
          type: string
          description: Dienstbeschreibungs-URI
        validFrom:
          maxLength: 27
          minLength: 24
          type: string
          description: Gültigkeitszeitraum (Start)
          format: 'Datum (im Format ISO-8601, d.h.yyyy-MM-dd''T''HH:mm:ss.SSS''Z'')'
        validTo:
          maxLength: 27
          minLength: 24
          type: string
          description: Gültigkeitszeitraum (Ende)
          format: 'Datum (im Format ISO-8601, d.h.yyyy-MM-dd''T''HH:mm:ss.SSS''Z'')'
      description: 'Basisbeschreibung eines Dienstes im DVDV2-Umfeld, mit Kompatibilität zu DVDV1.'
    ServiceElementInfo:
      required:
        - providerId
        - serviceElementId
      type: object
      properties:
        cipherCertificate:
          $ref: '#/components/schemas/Certificate'
        customServiceElementType:
          type: string
          description: Erweiterter Typ der zugehörigen Dienstelementbeschreibung (installationsspezifisch anpassbar
        providerId:
          maximum: 9223372036854776000
          minimum: 0
          type: integer
          description: Technische ID des Providers
          format: int64
        providerNameDe:
          maxLength: 255
          type: string
          description: Deutsche Bezeichnung des Providers
        providerNameEn:
          maxLength: 255
          type: string
          description: Englische Bezeichnung des Providers
        required:
          type: boolean
          description: 'Flag, ob das Dienstelement erforderlich ist'
        serviceElementDescription:
          maxLength: 255
          type: string
          description: Beschreibung des Dienstelements
        serviceElementDescriptionName:
          maxLength: 255
          type: string
          description: Name der zugehörigen Dienstelementbeschreibung
        serviceElementId:
          maximum: 9223372036854776000
          minimum: 0
          type: integer
          description: Technische ID des Dienstelements
          format: int64
        serviceElementName:
          maxLength: 255
          type: string
          description: Name des Dienstelements
        serviceElementText:
          maxLength: 255
          type: string
          description: Beschreibungstext des Dienstelements
        serviceElementType:
          type: string
          description: Typ der zugehörigen Dienstelementbeschreibung
          enum:
            - OSCI_INTERMEDIARY
            - OSCI_ADDRESSEE
            - CIPHER_CERTIFICATE
            - SIGNATURE_CERTIFICATE
            - WEBSERVER
            - TEXT
        serviceElementUri:
          maxLength: 1000
          type: string
          description: URI des Dienstelements
        signatureCertificate:
          $ref: '#/components/schemas/Certificate'
      description: Information über ein Dienstelement.
    SummaryServiceElementDTO:
      required:
        - Technische Datenbank-ID
      type: object
      properties:
        Technische Datenbank-ID:
          maximum: 9223372036854776000
          minimum: 0
          type: integer
          format: int64
        orgaProvAddress:
          type: string
        orgaProvId:
          type: integer
          format: int64
        orgaProvName:
          type: string
        provider:
          type: boolean
        selDescription:
          type: string
        selName:
          type: string
        uri:
          type: string
    VerificationResult:
      required:
        - verifyCategory
      type: object
      properties:
        verifyCategory:
          type: boolean
      description: Ergebnis einer Kategorienüberprüfung
