openapi: 3.0.3
info:
  version: 1.2.0
  title: FIT-Connect Self-Service API
  description: Diese API dient dem Verwalten von Zustellpunkten.
  contact:
    name: FITKO
    url: https://docs.fitko.de/fit-connect/contact
  license:
    url: https://creativecommons.org/licenses/by-sa/4.0/
    name: Creative Commons Attribution Share Alike 4.0 (CC BY-SA 4.0)
  termsOfService: https://docs.fitko.de/fit-connect/docs/details/terms-of-use-testing/
servers:
  - url: https://portal.auth-testing.fit-connect.fitko.dev
    description: Testumgebung
  - url: https://portal.auth-prod.fit-connect.fitko.net
    description: Produktivumgebung
tags:
  - name: Zustellpunktverwaltung
    description: Endpunkte für die Verwaltung von Zustellpunkten.
  - name: Allgemein
    description: Endpunkte, die in keine andere Kategorie passen.
  - name: Fachlich
    description: Unter dieser Gruppe sind alle Endpunkte organisiert, die fachliche Informationen über die Instanz des Dienstes liefern.
externalDocs:
  description: FIT-Connect-Dokumentationsportal mit Dokumentation zur API-Nutzung
  url: https://docs.fitko.de/fit-connect
paths:
  /v1/delivery-services:
    get:
      operationId: get-delivery-services
      description: Liefert alle registrierten Zustelldienste als JWS
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  deliveryServicesSignature:
                    description: Eine Liste aller bei FIT-Connect registrierter Zustelldienste als JSON Web Signature
                    example: eyJraWQiOiJhZUJVaFFTOHVhSnZ0ek1jVHlpRUFOM0tXNG02NXVEbUwwWDFBQUlxZENFIiwidHlwIjoiSldUIiwiYWxnIjoiUFM1MTIifQ.eyJpc3MiOiJodHRwczpcL1wvcG9ydGFsLmF1dGgtdGVzdGluZy5maXQtY29ubmVjdC5maXRrby5kZXYiLCJkZWxpdmVyeVNlcnZpY2VzIjpbeyJzdWJtaXNzaW9uSG9zdCI6InN1Ym1pc3Npb24tYXBpLXRlc3RpbmcuZml0LWNvbm5lY3QuZml0a28uZGV2In1dLCJpYXQiOjE2NjQ1MzExOTgsImp0aSI6ImFlYWMxYmZmLWIzOTUtNDJhNC04ZThlLTM0Zjc0MzZmZDFmNyJ9.LOsfV1tgjj0cBAInUJdc4lI_DrhvGQYp29fK60iPwFWRuqBKdAFN5WrDspH2qKjx3z_NL7fKj_VieGq-tJEX5WmZhNbh5w7il-9bxeCN05rTamqwxYtSK-DWwtrYSMGZYwh63KYQS2TmS1oJQ3vICP_UpaBPxLK2hFZps5kfkfyAv8bSeOvT5NoLaswW-lpXONvDtEj2LNwzYyd4hVZe3vb7m_Braql48aFTFbdtsQtN2kPuY4qqD2CksOtQoFKvVidW4zJquZfQRUDfEdWW5vhDe1sIBAOoSiLjAEaYWMriFeq4tt-vIGyo0GKQbpni6AmzoINc35RYvCeZyjDF_Pmyw6ZeGOXTeB40XAcKRebCkdRYIDh12Y3iaRNNGftGfhI23KtntxaPMxsRis-ZRMRCVbLPk6KNJS_Fa_IPG3eluv5VVExdJjBhPUXwBdN2x4j2EWndzimXu-3pAPOWPy7BjsEx9PDBG0JXAAyqFUQTrJbfKI8mQwd2vkpT5nbqlvyrLwgnTTncl_b60az_4JncOjuCFsXHqMpwbU_UAgcBA3R2YItuiIwWivDjkwwgPoJScTFumotUEE4L8qFnaGgP9mplss4iErmxmVcxcvDFwhplHEGZPvKKO-BKajm84-1WjJeIakDBkF7BXAJgl_pSWN-69rzRzABT3JFWQTg
                    type: string
      tags:
        - Allgemein
  /v1/destinations:
    get:
      operationId: get-my-destinations
      summary: Eigene Zustellpunkte auflisten
      description: Mit diesem Request können alle selbst angelegten Zustellpunkte sowie deren Konfigurationen abgerufen werden.
      tags:
        - Zustellpunktverwaltung
      security:
        - OAuth2:
            - https://schema.fitko.de/fit-connect/oauth/scopes/manage-destinations
      responses:
        '200':
          description: OK
          headers:
            Cache-Control:
              $ref: '#/components/headers/cache-control-no-cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destination-simple-list'
              examples:
                Empty List:
                  $ref: '#/components/examples/destination-simple-list-empty'
                Several Destinations:
                  $ref: '#/components/examples/destination-simple-list'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
    post:
      operationId: create-destination
      summary: Zustellpunkt anlegen
      description: |
        Erstellung eines neuen Zustellpunktes mit entsprechender Konfiguration zum Empfang von Einreichungen. Eine detaillierte Beschreibung ist in der [Dokumentation](https://docs.fitko.de/fit-connect/docs/getting-started/receiving/destination-management) zu finden.
      tags:
        - Zustellpunktverwaltung
      security:
        - OAuth2:
            - https://schema.fitko.de/fit-connect/oauth/scopes/self-service-api/create:destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-destination'
            examples:
              Beispiel:
                $ref: '#/components/examples/create-destination'
      callbacks:
        NewSubmissions:
          $ref: '#/components/callbacks/new-submissions'
      responses:
        '201':
          description: Created
          headers:
            Cache-Control:
              $ref: '#/components/headers/cache-control-no-cache'
            Location:
              $ref: '#/components/headers/location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/created-destination'
              example:
                destinationId: 7881dba9-4055-4854-8b6d-11ea5b7f3047
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/destinations/{destinationId}:
    parameters:
      - $ref: '#/components/parameters/destinationId'
    get:
      operationId: get-destination-info
      summary: Zustellpunkt abfragen
      description: Ruft die Details eines Zustellpunktes ab.
      tags:
        - Zustellpunktverwaltung
      security:
        - OAuth2:
            - https://schema.fitko.de/fit-connect/oauth/scopes/manage-destinations
      responses:
        '200':
          description: OK
          headers:
            Cache-Control:
              $ref: '#/components/headers/cache-control-no-cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destination-private'
              examples:
                Beispiel:
                  $ref: '#/components/examples/destination-private'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
    put:
      operationId: update-destination
      summary: Zustellpunkt vollständig aktualisieren
      description: Ermöglicht es, einen Zustellpunkt vollständig zu aktualisieren.
      tags:
        - Zustellpunktverwaltung
      security:
        - OAuth2:
            - https://schema.fitko.de/fit-connect/oauth/scopes/manage-destinations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-destination'
            examples:
              Beispiel:
                $ref: '#/components/examples/update-destination'
      callbacks:
        NewSubmissions:
          $ref: '#/components/callbacks/new-submissions'
      responses:
        '200':
          description: OK
          headers:
            Cache-Control:
              $ref: '#/components/headers/cache-control-no-cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destination-private'
              examples:
                Beispiel:
                  $ref: '#/components/examples/destination-private'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
    patch:
      operationId: patch-destination
      summary: Zustellpunkt partiell aktualisieren
      description: |
        Ermöglicht es einen Zustellpunkt partiell zu aktualisieren. Ein Beispiel wäre die Änderung des Feldes `encryptionKid` bei Schlüssel-Rollover.
      tags:
        - Zustellpunktverwaltung
      security:
        - OAuth2:
            - https://schema.fitko.de/fit-connect/oauth/scopes/manage-destinations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patch-destination'
            examples:
              Patch Status:
                $ref: '#/components/examples/patch-destination-status'
              Patch Contact:
                $ref: '#/components/examples/patch-destination-contact'
      callbacks:
        NewSubmissions:
          $ref: '#/components/callbacks/new-submissions'
      responses:
        '200':
          description: OK
          headers:
            Cache-Control:
              $ref: '#/components/headers/cache-control-no-cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destination-private'
              examples:
                Beispiel:
                  $ref: '#/components/examples/destination-private'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
    delete:
      operationId: delete-destination
      summary: Zustellpunkt löschen
      description: Dieser Endpunkt ermöglicht es, einen Zustellpunkt zu löschen. Das Löschen ist jedoch nur möglich, wenn der Zustellpunkt nie im Status active war oder den Status decommissioned erreicht hat. Die Seite [Zustellpunkte löschen](https://docs.fitko.de/fit-connect/docs/receiving/destination-delete#destination_delete) fasst die Bedingungen für das Löschen zusammen.
      tags:
        - Zustellpunktverwaltung
      security:
        - OAuth2:
            - https://schema.fitko.de/fit-connect/oauth/scopes/manage-destinations
      responses:
        '204':
          description: Zustellpunkt erfolgreich gelöscht.
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/destinations/{destinationId}/keys:
    parameters:
      - $ref: '#/components/parameters/destinationId'
    post:
      operationId: add-destination-key
      summary: Fügt dem Zustellpunkt einen JWK hinzu.
      description: Um einem Zustellpunkt verschlüsselte Datensätze zu schicken benötigt man dessen öffentlichen Schlüssel. Diesen Schlüssel kann man als Verwalter eines Zustellpunktes über diesen Endpunkt setzen.
      tags:
        - Zustellpunktverwaltung
      security:
        - OAuth2:
            - https://schema.fitko.de/fit-connect/oauth/scopes/manage-destinations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/jwk'
            examples:
              Beispiel Signatur-Public-Key:
                $ref: '#/components/examples/jwk-verify'
              Beispiel Verschlüsselungs-Public-Key:
                $ref: '#/components/examples/jwk-wrapKey'
      responses:
        '201':
          description: Schlüssel hinzugefügt oder existiert bereits
          headers:
            Location:
              $ref: '#/components/headers/location'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/info:
    get:
      operationId: get-info
      summary: Rufe fachliche Serviceinformationen der Instanz ab
      description: Für Debugging oder Informationszwecke angebotener Endpunkt
      tags:
        - Fachlich
      responses:
        '200':
          description: OK
          headers:
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/access-control-allow-origin'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/info'
              examples:
                Beispiel:
                  $ref: '#/components/examples/info'
  /.well-known/jwks.json:
    get:
      operationId: get-ssp-jwks.json
      summary: Rufe die öffentlichen Schlüssel des Self-Service-Portals ab
      description: Vom Self-Service-Portal signierte Datensätze können mit einem dieser Schlüssel signiert werden.
      tags:
        - Allgemein
      responses:
        '200':
          description: OK
          headers:
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/access-control-allow-origin'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jwks'
              examples:
                Beispiel:
                  $ref: '#/components/examples/jwks-verify'
components:
  securitySchemes:
    OAuth2:
      description: Authentifizierungsmethode, um den Zugriff nach RFC8725 zu autorisieren
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth-testing.fit-connect.fitko.dev/token
          scopes:
            https://schema.fitko.de/fit-connect/oauth/scopes/self-service-api/create:destination: Erlaubt das Anlegen von Zustellpunkten
            https://schema.fitko.de/fit-connect/oauth/scopes/manage-destinations: Erlaubt das Verändern und Löschen eines Zustellpunktes
  headers:
    cache-control-no-cache:
      required: true
      description: Zustellpunkte dürfen aufgrund ihrer Schlüssel nicht gecached werden
      schema:
        type: string
        default: no-cache
        enum:
          - no-cache
    location:
      required: true
      description: Pfad zum Abrufen der erstellten Ressource
      schema:
        type: string
    access-control-allow-origin:
      required: true
      description: Erlaubt Anfragen von beliebigen Quellen
      schema:
        type: string
        default: '*'
        enum:
          - '*'
  schemas:
    destination-name:
      type: string
      minLength: 0
      maxLength: 128
      description: Name des Zustellpunktes
    destination-id:
      type: string
      format: uuid
      minLength: 32
      maxLength: 36
      description: Identifikator des Zustellpunktes im Format einer UUID
    destination-simple:
      title: Einfacher Zustellpunkt
      description: Einfache Repräsentation eines Zustellpunktes
      type: object
      required:
        - destinationId
      properties:
        name:
          $ref: '#/components/schemas/destination-name'
        destinationId:
          $ref: '#/components/schemas/destination-id'
    destination-simple-list:
      title: Liste selbst angelegter Zustellpunkte
      type: object
      required:
        - destinations
      properties:
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/destination-simple'
          description: Eine Auflistung aller selbst angelegten Zustellpunkte
          maxItems: 500
          minItems: 0
    error:
      title: Fehler
      type: object
      description: Der Inhalt von HTTP Responses bei Fehlern nach RFC7807.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          description: Eine URI-Referenz, die den Problemtyp identifiziert.
        title:
          type: string
          description: Eine kurze, von Menschen lesbare Zusammenfassung des Problems.
        status:
          type: integer
          description: Der HTTP-Statuscode der vom Ursprungsserver für dieses Auftreten des Problems generiert wurde.
          minimum: 100
          maximum: 599
        detail:
          type: string
          description: Eine von Menschen lesbare Erklärung speziell für dieses Auftreten des Problems.
        instance:
          type: string
          format: uri
          description: |
            Eine URI-Referenz, die das spezifische Auftreten des Problems identifiziert. Sie kann, muss aber nicht, weitere Informationen liefern, wenn sie dereferenziert wird.
    contact-information:
      title: Kontakt
      description: Angaben zum Ansprechpartner des Zustellpunktes
      type: object
      required:
        - legalName
        - address
        - phone
        - email
      properties:
        legalName:
          type: string
          description: Juristischer Name der verantwortlichen Organisation
          example: Max Mustermann
        address:
          type: string
          description: Adresse der verantwortlichen Organisation
        phone:
          type: string
          description: Telefonnummer der verantwortlichen Stelle
        email:
          type: string
          format: email
          description: E-Mail-Adresse der verantwortlichen Stelle (Funktionspostfach). Falls kein Funktionspostfach vorhanden ist, kann auch eine personalisierte Adresse des Supportverantwortlichen eingetragen werden.
          example: Max@Mustermann.de
        unit:
          type: string
          description: Verantwortliche Untereinheit (Abteilung, Referat, etc.) der Organisation. Kann zur Vereinfachung von Klärungsfragen angegeben werden.
    service-region:
      title: Region
      type: string
      description: Amtlicher Regionalschlüssel (ARS), vorangestellt mit 'DE'.
      minLength: 2
      maxLength: 14
      pattern: ^DE[0-9]{0,12}$
      example: DE094750156156
    submission-schema:
      title: Fachdatenschema
      description: Referenz auf ein Schema, das die Struktur der Fachdaten einer Einreichung beschreibt.
      type: object
      required:
        - mimeType
        - schemaUri
      properties:
        mimeType:
          type: string
          description: Mimetype (z.B. application/json oder application/xml) des referenzierten Schemas (z.B. XSD- oder JSON-Schema).
          enum:
            - application/json
            - application/xml
        schemaUri:
          type: string
          format: uri
          description: URI des Fachschemas. Wird hier eine URL verwendet, sollte das Schema unter der angegebenen URL abrufbar sein. Eine Verfügbarkeit des Schemas unter der angegebenen URL darf jedoch nicht vorausgesetzt werden.
    destination-service:
      title: Verwaltungsleistung
      description: Verwaltungsleistung, die eine Destination anbietet.
      type: object
      required:
        - identifier
        - regions
        - submissionSchemas
      properties:
        identifier:
          title: Leistungs-Identifikator
          description: |
            URN einer Leistung. Im Falle einer Leistung aus dem Leistungskatalog sollte hier `urn:de:fim:leika:leistung:` vorangestellt werden.
          type: string
          minLength: 7
          maxLength: 255
          pattern: ^urn:[a-z0-9][a-z0-9-]{0,31}:[a-z0-9()+,.:=@;$_!*'%/?#-]+$
          example: urn:de:fim:leika:leistung:99400048079000
        regions:
          description: Amtliche Regionalschlüssel (ARS) der Regionen in denen die Leistung angeboten wird. Vorangestellt mit 'DE'.
          uniqueItems: true
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/service-region'
        submissionSchemas:
          title: Unterstützte Fachschemata
          description: Auflistung aller unterstützten Fachschemata des Zustellpunktes.
          uniqueItems: true
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/submission-schema'
    create-callback:
      title: Objekt zur Konfiguration von Callbacks
      type: object
      required:
        - url
        - secret
      properties:
        url:
          title: Callback-URL
          description: Öffentlich erreichbare Callbackadresse, um Benachrichtigungen durch den Zustelldienst zu empfangen. Muss eine valide HTTPS-URL sein.
          type: string
          minLength: 9
          format: uri
          pattern: ^https://.+
          example: https://fachverfahren.beispielstadt.example.org/callbacks/fit-connect
        secret:
          title: Callback-Secret
          description: Callback-Secret zur Erzeugung des zur Absicherung eines Callback verwendeten HMACs. Das Callback-Secret kann über die API nur geschrieben, aber nicht abgerufen werden.
          type: string
          minLength: 32
          maxLength: 512
          example: insecure_unsafe_qHScgrg_kP-R31jHUwp3GkVkGJolvBchz65b74Lzue0
    jwk:
      title: JSON Web Key (JWK)
      type: object
      description: JSON Web Key - RFC 7517
      required:
        - kty
        - key_ops
        - alg
        - x5c
        - kid
        - 'n'
        - e
      properties:
        kty:
          type: string
          description: |
            Der Parameter "kty" (Schlüsseltyp) identifiziert die kryptografische Algorithmus Familie, die mit dem Schlüssel verwendet wird, z. B. "RSA" oder "EC". In FIT-Connect sind aktuell nur RSA-Schlüssel erlaubt.
          enum:
            - RSA
        key_ops:
          type: array
          description: |
            Der Parameter "key_ops" (Schlüsseloperationen) identifiziert die Operation(en) für die der Schlüssel verwendet werden soll. Die Bedeutung der Erlaubten Operationen sind:
              - `verify`: Digitale Signatur oder MAC überprüfen
              - `wrapKey`: Verschlüsselungsschlüssel
          items:
            type: string
            enum:
              - verify
              - wrapKey
        alg:
          type: string
          description: |
            Der Parameter "alg" (Algorithmus) identifiziert den Algorithmus, der für Verwendung mit dem Schlüssel vorgesehen ist. In FIT-Connect wird `PS512` für Signaturschlüssel und `RSA-OAEP-256` für Verschlüsselungsschlüssel genutzt.
          enum:
            - PS512
            - RSA-OAEP-256
        x5c:
          type: array
          description: |
            Der Parameter "x5c" (X.509 certificate chain) enthält eine Kette von einem oder mehreren PKIX-Zertifikaten [RFC5280]. Die Zertifikatskette wird als JSON-Array von Zertifikatswert-Strings dargestellt.
          minItems: 1
          items:
            type: string
        kid:
          type: string
          description: |
            Der Parameter "kid" (Schlüssel-Id) wird verwendet, um einen bestimmten Schlüssel zu finden. Dieser wird z. B. verwendet, um zwischen einer Reihe von Schlüsseln innerhalb eines JWK-Sets zu wählen während des Schlüssel-Rollover.
          minLength: 8
          maxLength: 64
        'n':
          type: string
          description: Modulus des Schlüssels. Die minimale Länge von 683 Zeichen repräsentiert eine Schlüssellange von mindestens 4096 Bit.
          minLength: 683
        e:
          type: string
          description: Öffentliche Exponent des Schlüssels
          enum:
            - AQAB
    supported-metadata-versions:
      title: Liste unterstützter Metadatenschemataversionen
      description: Eine Liste unterstützter Versionen des Metadatenschemas gemäß [Semantic Versioning](https://semver.org/).
      type: array
      uniqueItems: true
      minItems: 1
      items:
        type: string
        pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$
        example: 1.1.1
    create-destination:
      title: Struktur zum Erzeugen eines Zustellpunktes
      description: Notwendige Struktur, um einen Zustellpunkt anzulegen.
      type: object
      required:
        - name
        - contactInformation
        - services
        - encryptionKid
        - encryptionPublicKey
        - signingPublicKey
        - metadataVersions
      properties:
        name:
          $ref: '#/components/schemas/destination-name'
        contactInformation:
          $ref: '#/components/schemas/contact-information'
        services:
          title: Unterstützte Verwaltungsleistungen
          description: Auflistung aller unterstützten Verwaltungsleistungen des Zustellpunktes.
          type: array
          uniqueItems: true
          minItems: 1
          items:
            $ref: '#/components/schemas/destination-service'
        callback:
          $ref: '#/components/schemas/create-callback'
        encryptionKid:
          type: string
          maxLength: 64
          description: Identifikator des Schlüssels der Destination. Muss zur `kid` im Feld `encryptionPublicKey` passen.
        encryptionPublicKey:
          $ref: '#/components/schemas/jwk'
        signingPublicKey:
          $ref: '#/components/schemas/jwk'
        metadataVersions:
          $ref: '#/components/schemas/supported-metadata-versions'
    created-destination:
      title: Created Destination
      type: object
      description: The created destination
      required:
        - destinationId
      properties:
        destinationId:
          $ref: '#/components/schemas/destination-id'
    submission-id:
      type: string
      format: uuid
      minLength: 32
      maxLength: 36
      description: Identifikator der Einreichung im Format einer UUID
    case-id:
      type: string
      format: uuid
      minLength: 32
      maxLength: 36
      description: Vorgangsreferenz des Vorgangs, zu der die Einreichung gehört.
    submission-for-pickup:
      type: object
      title: Abholbereite Einreichungen
      description: Eine einzelne abholbereite Einreichung, abzurufen beim Zustellpunkt mit der angegebenen `destinationId`.
      required:
        - destinationId
        - submissionId
        - caseId
      properties:
        destinationId:
          $ref: '#/components/schemas/destination-id'
        submissionId:
          $ref: '#/components/schemas/submission-id'
        caseId:
          $ref: '#/components/schemas/case-id'
    callback-new-submissions:
      title: Callback
      description: Callback, der über abholbereite Einreichungen informiert.
      type: object
      properties:
        type:
          title: Art des Callbacks
          description: Es liegen neue Einreichungen vor
          type: string
          enum:
            - https://schema.fitko.de/fit-connect/submission-api/callbacks/new-submissions
        submissions:
          title: Liste abholbereiter Einreichungen
          description: Liste von Einreichungen, die zur Abholung bereitstehen
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/submission-for-pickup'
    destination-public:
      title: Zustellpunkt
      description: Repräsentation eines Zustellpunktes
      type: object
      required:
        - name
        - destinationId
        - encryptionKid
        - metadataVersions
        - services
        - status
      properties:
        destinationId:
          $ref: '#/components/schemas/destination-id'
        encryptionKid:
          type: string
          maxLength: 64
          description: Key-ID des Verschlüsselungsschlüssels der Destination. Zu finden in der Subressource `keys/<keyId>`.
        metadataVersions:
          $ref: '#/components/schemas/supported-metadata-versions'
        services:
          title: Unterstützte Verwaltungsleistungen
          description: Auflistung aller unterstützten Verwaltungsleistungen des Zustellpunktes.
          type: array
          uniqueItems: true
          minItems: 1
          items:
            $ref: '#/components/schemas/destination-service'
        status:
          type: string
          enum:
            - created
            - active
            - inactive
            - decommissioned
          description: Status des Zustellpunktes. Eine Beschreibung der Status finden Sie in den Detailinformationen unter [Zustellpunktverwaltung](https://docs.fitko.de/fit-connect/docs/details/destination-management).
    callback-url:
      title: Konfiguration des eingerichteten Callbacks
      type: object
      required:
        - url
      properties:
        url:
          title: Callback-URL
          description: Öffentlich erreichbare Callbackadresse, um Benachrichtigungen durch den Zustelldienst zu empfangen. Muss eine valide HTTPS-URL sein.
          type: string
          minLength: 9
          format: uri
          pattern: ^https://.+
    destination-private-parts:
      type: object
      required:
        - contactInformation
        - name
      properties:
        name:
          $ref: '#/components/schemas/destination-name'
        contactInformation:
          $ref: '#/components/schemas/contact-information'
        callback:
          $ref: '#/components/schemas/callback-url'
    destination-private:
      allOf:
        - $ref: '#/components/schemas/destination-public'
        - $ref: '#/components/schemas/destination-private-parts'
    update-destination:
      title: Aktualisierung eines Zustellpunktes
      description: Struktur mit Attributen, die aktualisiert werden sollen.
      type: object
      required:
        - name
        - status
        - contactInformation
        - services
        - encryptionKid
        - metadataVersions
      properties:
        name:
          $ref: '#/components/schemas/destination-name'
        status:
          type: string
          enum:
            - created
            - active
            - inactive
            - decommissioned
          description: Status des Zustellpunktes. Eine Beschreibung der Status finden Sie in den Detailinformationen unter [Zustellpunktverwaltung](https://docs.fitko.de/fit-connect/docs/details/destination-management).
        contactInformation:
          $ref: '#/components/schemas/contact-information'
        services:
          title: Unterstützte Verwaltungsleistungen
          description: Auflistung aller unterstützten Verwaltungsleistungen des Zustellpunktes.
          type: array
          uniqueItems: true
          minItems: 1
          items:
            $ref: '#/components/schemas/destination-service'
        callback:
          $ref: '#/components/schemas/create-callback'
        encryptionKid:
          type: string
          maxLength: 64
          description: Schlüssel-Id des Verschlüsselungsschlüssels des Zustellpunktes.
        metadataVersions:
          $ref: '#/components/schemas/supported-metadata-versions'
    patch-destination:
      title: Partielle Aktualisierung eines Zustellpunktes
      description: Struktur mit Attributen, die aktualisiert werden sollen. Eine Teilaktualisierung einzelner Datenfelder innherhalb der Attribute ist nicht möglich.
      type: object
      properties:
        name:
          $ref: '#/components/schemas/destination-name'
        status:
          type: string
          enum:
            - active
            - inactive
            - decommissioned
          description: Status des Zustellpunktes. Eine Beschreibung der Status finden Sie in den Detailinformationen unter [Zustellpunktverwaltung](https://docs.fitko.de/fit-connect/docs/details/destination-management).
        contactInformation:
          $ref: '#/components/schemas/contact-information'
        services:
          title: Unterstützte Verwaltungsleistungen
          description: Auflistung aller unterstützten Verwaltungsleistungen des Zustellpunktes.
          type: array
          uniqueItems: true
          minItems: 1
          items:
            $ref: '#/components/schemas/destination-service'
        callback:
          $ref: '#/components/schemas/create-callback'
        encryptionKid:
          type: string
          maxLength: 64
          description: Schlüssel-Id des Verschlüsselungsschlüssels des Zustellpunktes.
        metadataVersions:
          $ref: '#/components/schemas/supported-metadata-versions'
    version:
      title: Serviceversion
      type: object
      required:
        - major
        - minor
        - patch
      properties:
        major:
          type: integer
        minor:
          type: integer
        patch:
          type: integer
    info:
      title: Version der Self-Service API
      type: object
      required:
        - version
      properties:
        version:
          $ref: '#/components/schemas/version'
    jwks:
      title: JSON Web Key Set (JWKS)
      description: JWKS nach [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517#section-5)
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          uniqueItems: true
          minItems: 1
          items:
            $ref: '#/components/schemas/jwk'
  examples:
    destination-simple-list-empty:
      value:
        destinations: []
    destination-simple-list:
      value:
        destinations:
          - destinationId: de735e92-8ced-4298-a021-5f4aa124cc47
            name: Bürgeramt Berlin Mitte
          - destinationId: 2f59b8c6-3206-4734-aa21-a7b2a4d92f7a
            name: Stadtverwaltung Buxtehude
    create-destination:
      value:
        name: Bürgeramt Berlin
        contactInformation:
          legalName: Max
          address: Musterstr. 31, 10000 Berlin, Deutschland
          phone: '+49170123456789'
          email: max@mustermann.not
          unit: Department XYZ
        services:
          - identifier: urn:de:fim:leika:leistung:99010003001006
            submissionSchemas:
              - schemaUri: https://schema.fitko.de/fim/s00000121_1.0.0.schema.json
                mimeType: application/json
            regions:
              - DE094750156156
              - DE09330411
        callback:
          url: https://fachverfahren.beispielstadt.example.org/callbacks/fit-connect
          secret: insecure_unsafe_qHScgrg_kP-R31jHUwp3GkVkGJolvBchz65b74Lzue0
        encryptionKid: c66e4423-e28d-4a1f-911d-818f9ab60221
        encryptionPublicKey:
          kty: RSA
          key_ops:
            - wrapKey
          alg: RSA-OAEP-256
          x5c:
            - ...(base64 encoded cert)...
            - ...(base64 encoded intermediate cert)...
            - ...(base64 encoded root cert)...
          kid: c66e4423-e28d-4a1f-911d-818f9ab60221
          'n': hGALqq-nbAymF5MyZIXV9RY-pW4r39BrBnxryp6ukjdrGacVhwKtm-zqN9urUETAhjfQo7CsxuJ7de291In9uPIhXYSvZcTQXH930Gpkv1BeAsU9x5uP6EnfrgRZfODwpmw1HJmAOK6aJ_ARJV7iJ1a_AGSK5ZO1bsmUWhJk-V-tFbs3xTbsmOZxVfxJWC-0pDxmEljmoi4q8f-LtNzVPEIC3-T5LaGEYy0stCU-YkJ-uDKGUJh01fQWRYaG7gCRnoIT9BJNQWUE0kfRjrZ9nOqNHibs9CreliIhD6k0310DDT0JV6-Y55AgOCqWoYCw7Xn3_AACx1aJccaRojC7FqwI6FWx2d3HkAz6o4l1llfTkgELhYjpUdW-m7dfQTbZzVlZRrVWE8lzbza2GXv6IFi3RzEWNso6KJMo-kRJxG-ZCruVhTt6FIyiZk6HpWGH6AGR62Fku8O_GR6YaNchKSB4nkj76iSPGTasLeJi2Sjw7kVZxhiL6MN4bBTT9jAB_sYcSrd9H12-KGV9IwnW8JnO3derCI6gfdGTKOzHTS3z231fDcCsXtDD4tJHHIXsW7_ytDprkwBwl9OLBW1xAniOgAH8sqgX3SGOYFcbd6Zxx0zgSlRNMdj4qkswS7KhC9-vyCA2qBnRdowPd9_1H9CpuHAyo3-iMf3UaBsPj0s
          e: AQAB
        signingPublicKey:
          kty: RSA
          key_ops:
            - verify
          alg: PS512
          x5c:
            - ...(base64 encoded cert)...
            - ...(base64 encoded intermediate cert)...
            - ...(base64 encoded root cert)...
          kid: a11e4423-e28d-4a1f-911d-818f9ab64321
          'n': hGALqq-nbAymF5MyZIXV9RY-pW4r39BrBnxryp6ukjdrGacVhwKtm-zqN9urUETAhjfQo7CsxuJ7de291In9uPIhXYSvZcTQXH930Gpkv1BeAsU9x5uP6EnfrgRZfODwpmw1HJmAOK6aJ_ARJV7iJ1a_AGSK5ZO1bsmUWhJk-V-tFbs3xTbsmOZxVfxJWC-0pDxmEljmoi4q8f-LtNzVPEIC3-T5LaGEYy0stCU-YkJ-uDKGUJh01fQWRYaG7gCRnoIT9BJNQWUE0kfRjrZ9nOqNHibs9CreliIhD6k0310DDT0JV6-Y55AgOCqWoYCw7Xn3_AACx1aJccaRojC7FqwI6FWx2d3HkAz6o4l1llfTkgELhYjpUdW-m7dfQTbZzVlZRrVWE8lzbza2GXv6IFi3RzEWNso6KJMo-kRJxG-ZCruVhTt6FIyiZk6HpWGH6AGR62Fku8O_GR6YaNchKSB4nkj76iSPGTasLeJi2Sjw7kVZxhiL6MN4bBTT9jAB_sYcSrd9H12-KGV9IwnW8JnO3derCI6gfdGTKOzHTS3z231fDcCsXtDD4tJHHIXsW7_ytDprkwBwl9OLBW1xAniOgAH8sqgX3SGOYFcbd6Zxx0zgSlRNMdj4qkswS7KhC9-vyCA2qBnRdowPd9_1H9CpuHAyo3-iMf3UaBsPj0s
          e: AQAB
        replyChannel:
          deMail: null
        metadataVersions:
          - 1.0.1
          - 2.1.1
    destination-private:
      value:
        destinationId: 7881dba9-4055-4854-8b6d-11ea5b7f3047
        status: created
        services:
          - identifier: urn:de:fim:leika:leistung:99010003001006
            submissionSchemas:
              - schemaUri: https://schema.fitko.de/fim/s00000121_1.0.0.schema.json
                mimeType: application/json
            regions:
              - DE094750156156
              - DE09330411
        encryptionKid: c66e4423-e28d-4a1f-911d-818f9ab60221
        contactInformation:
          legalName: Max
          address: Musterstr. 31, 10000 Berlin, Deutschland
          phone: '+49170123456789'
          email: max@mustermann.not
          unit: Department XYZ
        callback:
          url: https://fachverfahren.beispielstadt.example.org/callbacks/fit-connect
        metadataVersions:
          - 1.0.1
          - 2.1.2
        name: Meine Destination
    update-destination:
      value:
        name: Bürgeramt Nord Nürnberg
        status: active
        contactInformation:
          legalName: Max
          address: Musterstr. 31, 10000 Berlin, Deutschland
          phone: '+49170123456789'
          email: max@mustermann.not
          unit: Department XYZ
        services:
          - identifier: urn:de:fim:leika:leistung:99010003001006
            submissionSchemas:
              - schemaUri: https://schema.fitko.de/fim/s00000121_1.0.0.schema.json
                mimeType: application/json
            regions:
              - DE094750156156
              - DE09330411
        callback:
          url: https://fachverfahren.beispielstadt.example.org/callbacks/fit-connect
          secret: insecure_unsafe_qHScgrg_kP-R31jHUwp3GkVkGJolvBchz65b74Lzue0
        encryptionKid: c66e4423-e28d-4a1f-911d-818f9ab60221
        metadataVersions:
          - 1.0.1
          - 2.1.2
    patch-destination-status:
      value:
        status: active
    patch-destination-contact:
      value:
        contactInformation:
          legalName: Max
          address: Musterstr. 31, 10000 Berlin, Deutschland
          phone: '+49170123456789'
          email: max@mustermann.not
          unit: Department XYZ
    jwk-verify:
      value:
        kty: RSA
        key_ops:
          - verify
        alg: PS512
        x5c:
          - ...(base64 encoded cert)...
          - ...(base64 encoded intermediate cert)...
          - ...(base64 encoded root cert)...
        kid: c66e4423-e28d-4a1f-911d-818f9ab60221
        'n': hGALqq-nbAymF5MyZIXV9RY-pW4r39BrBnxryp6ukjdrGacVhwKtm-zqN9urUETAhjfQo7CsxuJ7de291In9uPIhXYSvZcTQXH930Gpkv1BeAsU9x5uP6EnfrgRZfODwpmw1HJmAOK6aJ_ARJV7iJ1a_AGSK5ZO1bsmUWhJk-V-tFbs3xTbsmOZxVfxJWC-0pDxmEljmoi4q8f-LtNzVPEIC3-T5LaGEYy0stCU-YkJ-uDKGUJh01fQWRYaG7gCRnoIT9BJNQWUE0kfRjrZ9nOqNHibs9CreliIhD6k0310DDT0JV6-Y55AgOCqWoYCw7Xn3_AACx1aJccaRojC7FqwI6FWx2d3HkAz6o4l1llfTkgELhYjpUdW-m7dfQTbZzVlZRrVWE8lzbza2GXv6IFi3RzEWNso6KJMo-kRJxG-ZCruVhTt6FIyiZk6HpWGH6AGR62Fku8O_GR6YaNchKSB4nkj76iSPGTasLeJi2Sjw7kVZxhiL6MN4bBTT9jAB_sYcSrd9H12-KGV9IwnW8JnO3derCI6gfdGTKOzHTS3z231fDcCsXtDD4tJHHIXsW7_ytDprkwBwl9OLBW1xAniOgAH8sqgX3SGOYFcbd6Zxx0zgSlRNMdj4qkswS7KhC9-vyCA2qBnRdowPd9_1H9CpuHAyo3-iMf3UaBsPj0s
        e: AQAB
    jwk-wrapKey:
      value:
        kty: RSA
        key_ops:
          - wrapKey
        alg: RSA-OAEP-256
        x5c:
          - ...(base64 encoded cert)...
          - ...(base64 encoded intermediate cert)...
          - ...(base64 encoded root cert)...
        kid: c66e4423-e28d-4a1f-911d-818f9ab60221
        'n': hGALqq-nbAymF5MyZIXV9RY-pW4r39BrBnxryp6ukjdrGacVhwKtm-zqN9urUETAhjfQo7CsxuJ7de291In9uPIhXYSvZcTQXH930Gpkv1BeAsU9x5uP6EnfrgRZfODwpmw1HJmAOK6aJ_ARJV7iJ1a_AGSK5ZO1bsmUWhJk-V-tFbs3xTbsmOZxVfxJWC-0pDxmEljmoi4q8f-LtNzVPEIC3-T5LaGEYy0stCU-YkJ-uDKGUJh01fQWRYaG7gCRnoIT9BJNQWUE0kfRjrZ9nOqNHibs9CreliIhD6k0310DDT0JV6-Y55AgOCqWoYCw7Xn3_AACx1aJccaRojC7FqwI6FWx2d3HkAz6o4l1llfTkgELhYjpUdW-m7dfQTbZzVlZRrVWE8lzbza2GXv6IFi3RzEWNso6KJMo-kRJxG-ZCruVhTt6FIyiZk6HpWGH6AGR62Fku8O_GR6YaNchKSB4nkj76iSPGTasLeJi2Sjw7kVZxhiL6MN4bBTT9jAB_sYcSrd9H12-KGV9IwnW8JnO3derCI6gfdGTKOzHTS3z231fDcCsXtDD4tJHHIXsW7_ytDprkwBwl9OLBW1xAniOgAH8sqgX3SGOYFcbd6Zxx0zgSlRNMdj4qkswS7KhC9-vyCA2qBnRdowPd9_1H9CpuHAyo3-iMf3UaBsPj0s
        e: AQAB
    info:
      value:
        version:
          major: 1
          minor: 0
          patch: 1
    jwks-verify:
      value:
        keys:
          - kty: RSA
            key_ops:
              - verify
            alg: PS512
            x5c:
              - ...(base64 encoded cert)...
              - ...(base64 encoded intermediate cert)...
              - ...(base64 encoded root cert)...
            kid: c66e4423-e28d-4a1f-911d-818f9ab60221
            'n': hGALqq-nbAymF5MyZIXV9RY-pW4r39BrBnxryp6ukjdrGacVhwKtm-zqN9urUETAhjfQo7CsxuJ7de291In9uPIhXYSvZcTQXH930Gpkv1BeAsU9x5uP6EnfrgRZfODwpmw1HJmAOK6aJ_ARJV7iJ1a_AGSK5ZO1bsmUWhJk-V-tFbs3xTbsmOZxVfxJWC-0pDxmEljmoi4q8f-LtNzVPEIC3-T5LaGEYy0stCU-YkJ-uDKGUJh01fQWRYaG7gCRnoIT9BJNQWUE0kfRjrZ9nOqNHibs9CreliIhD6k0310DDT0JV6-Y55AgOCqWoYCw7Xn3_AACx1aJccaRojC7FqwI6FWx2d3HkAz6o4l1llfTkgELhYjpUdW-m7dfQTbZzVlZRrVWE8lzbza2GXv6IFi3RzEWNso6KJMo-kRJxG-ZCruVhTt6FIyiZk6HpWGH6AGR62Fku8O_GR6YaNchKSB4nkj76iSPGTasLeJi2Sjw7kVZxhiL6MN4bBTT9jAB_sYcSrd9H12-KGV9IwnW8JnO3derCI6gfdGTKOzHTS3z231fDcCsXtDD4tJHHIXsW7_ytDprkwBwl9OLBW1xAniOgAH8sqgX3SGOYFcbd6Zxx0zgSlRNMdj4qkswS7KhC9-vyCA2qBnRdowPd9_1H9CpuHAyo3-iMf3UaBsPj0s
            e: AQAB
  parameters:
    hmac-cb-authentication:
      in: header
      name: Callback-Authentication
      required: true
      description: Der Message Authentication Code des übertragenen Callbacks
      schema:
        type: string
    hmac-cb-timestamp:
      in: header
      name: Callback-Timestamp
      required: true
      description: Der Timestamp des Message Authentication Code.
      schema:
        type: integer
    destinationId:
      name: destinationId
      in: path
      description: Die UUID des Zustellpunktes
      required: true
      schema:
        $ref: '#/components/schemas/destination-id'
  callbacks:
    new-submissions:
      https://example.org/callback:
        post:
          summary: Callback für eine neue Einreichung
          description: |
            Bei neu eintreffenden Submissions wird ein Zustellpunkt mit Hilfe dieses Callbacks benachrichtigt. Voraussetzung ist die vorherige Konfiguration der [Callback-URL](https://docs.fitko.de/fit-connect/docs/receiving/destination#callback).
          parameters:
            - $ref: '#/components/parameters/hmac-cb-authentication'
            - $ref: '#/components/parameters/hmac-cb-timestamp'
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/callback-new-submissions'
          responses:
            '200':
              description: OK
