openapi: 3.0.0
info:
  title: FIT-Connect Routingdienst Api
  description: Diese Api dient dem Ermitteln der zuständigen Organisationseinheiten und deren Destination-ID
  version: 1.0.0
  contact:
    name: FITKO
  termsOfService: 'https://www.fitko.de/'
servers:
  - url: 'https://api.fit-connect-routing.example.org/'
    description: Example server
tags:
  - name: Routing
    description: Methoden zum ermitteln der Routinginformationen.
  - name: Area
    description: Methoden zum ermitteln von Gebieten.
paths:
  /routes:
    get:
      operationId: route
      tags:
        - Routing
      description: 'Ermittelt die notwendigen Routinginformationen anhand von Leikaschlüssel und einem Schlüssel eines Gebietobjektes (Bundesland, Landkreis, Kreisfreie Stadt, etc.). Es muss genau ein Parameter für das Gebiet gesetzt sein. Die Ermittlung der Routinginfomationen erfolgt nur für eindeutige Leika-Schlüssel sowie einen eindeutigen Gebietschlüssel.'
      parameters:
        - $ref: '#/components/parameters/leika-key'
        - $ref: '#/components/parameters/ags'
        - $ref: '#/components/parameters/ars'
        - $ref: '#/components/parameters/area-id'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResult'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          description: Bad Request. Das Format des Request ist nicht korrekt. Die Vorgaben der Eingangsparameter sind nicht erfüllt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '401':
          description: Unauthorized. Der Request ist nicht authorisiert.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '403':
          description: Forbidden. Der Request auf die Resource ist nicht erlaubt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '500':
          description: Internal Server Error. Es ist ein interner Fehler bei der Abarbeitung des Request aufgetreten.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
  /areas:
    get:
      operationId: area
      tags:
        - Area
      description: Ermittelt passende Gebiete anhand des übergebenenen Namen oder Postleitzahl. Es muss mindestens ein Suchparameter angegeben werden.
      parameters:
        - $ref: '#/components/parameters/area-searchexpression'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: successful operation
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/AreaResult'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          description: Bad Request. Das Format des Request ist nicht korrekt. Die Vorgaben der Eingangsparameter sind nicht erfüllt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '401':
          description: Unauthorized. Der Request ist nicht authorisiert.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '403':
          description: Forbidden. Der Request auf die Resource ist nicht erlaubt.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '500':
          description: Internal Server Error. Es ist ein interner Fehler bei der Abarbeitung des Request aufgetreten.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
components:
  schemas:
    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.
    RouteResult:
      title: Routinginformationen
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: Anzahl zurückgegebener Treffer
          maximum: 500
          minimum: 0
        offset:
          type: integer
          format: int32
          description: Startpunkt in der Gesamtanzahl der Suchtreffer
          minimum: 0
        totalCount:
          type: integer
          format: int32
          description: Gesamtanzahl der Suchtreffer
          minimum: 0
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
          description: Gefundene Routingergebnisse
          maxItems: 500
          minItems: 0
    Route:
      title: Routinginformation
      type: object
      description: Routingergebnis
      properties:
        destinationId:
          type: string
          format: uuid
          minLength: 32
          maxLength: 36
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        destinationParameters:
          $ref: '#/components/schemas/Destination'
          description: Technische Parameter wie z.B. Verschlüsselungszertifikate für die Antragsübermittlung
        destinationParametersSignature:
          description: Signatur der Technischen Parameter
          type: string
          pattern: '^[a-zA-Z0-9\-_]+?\.\.([a-zA-Z0-9\-_]+)?$'
          example: eyJ0eXAiOiJKT1NFIiwiYWxnIjoiUFM1MTIiLCJraWQiOiJlOWJjMDk3YS1jZTUxLTQwMzYtOTU2Mi1kMmFkZTg4MmRiMGQiLCJjdHkiOiJhcHBsaWNhdGlvbi9qb3NlIn0..g9xgjWf-_3JjMAFwPgBB4iXFrkrsRS-Ois3pxWWcFzdZuu_I8jH9Bd4FAQpf6nJwPtytJgoWYkm7gTCMwKiQH7JknXXrdYcnHRrlU2aT9thjaK5uYKYvuDfvklvQvKTYtfqowkMtk3pl91TfB1Pyxbprx6u5qut_pI-z2E7SC8gJ6V8u1rT1wDHOp-xrvMHUQiH7Ugmyb7Tg_Dc55AL0FrZ2wmurdPK46iAZBfIpzNJgUbqrlKvKQkwbs11Bc2qRzrFIG8yMyuN-qhGxibokMoq1U3FjlxtNgwWQJJOYlMiCbMibkINsmZ5mGZDS_Dra89TVMz0_rZagj-mxJ5-DlIE7E1LsvUKXYBHhPFoCJTGH1Lla7AEWtZ59HNSalMjvgcGWTgp-xTbqo8Ej6PwUM9j7_lNH1kT0iSvuCTYktVJEmovmpT0gB9c0AaGbQfiZFk8UUiBSAVFoD2B-0EP8CkEDAxsL0xlDdSAeK4Zrvg2nnck8NjdDQa68KfW4Fp32cfdkWYhGJ13xNG889P0aofCv7Joj4zxVEsPGfvqe6b78i8oZOe_Tn2lIVBwxZ6phtvEmZ8w_aS4zGSuYXoXx1DOjwatvCuH3rKicbQpJwEX3Bbcmv-NSgVZDae4dntgc89zbPbAg1zsqZDyHublVSK8m7i5CVLKiDvXdoWidNbY
        destinationName:
          type: string
          example: Einwohnermeldeamt
          description: Bezeichnung des Routingziels
        destinationLogo:
          type: string
          example: 'https://xxxxxxxx.xx'
          description: Url zum Logo der Organisationseinheit
    ApplicationSchema:
      title: Antragsschema
      description: 'Repräsentation eines Schemas, in dem die Fachdaten eines Antrags übermittelt werden.'
      type: object
      additionalProperties: false
      x-examples:
        XÖV-Schema:
          mimeType: application/xml
          schemaUri: 'urn:xoev-de:bmk:standard:xbau_2.2#baugenehmigung.antrag.0200'
        FIM-Fachdatenschema:
          mimeType: application/json
          schemaUrl: 'https://schema.fimportal.de/fim/fim.S00000147.00000147001002.json'
      properties:
        schemaUri:
          type: string
          format: uri
          description: Referenz-URI auf das Schemas (z.B. URN eines XML-Schema aus einem XÖV-Standard oder URL eines JSON-Schema aus dem FIM-Repository)
          maxLength: 200
        mimeType:
          type: string
          description: Gibt das zulässige Format (JSON oder XML) der Fachdaten an.
          maxLength: 50
          pattern: '^[-\w.]+/[-\w.]+$'
      required:
        - schemaUri
    Destination:
      title: Zustellpunkt
      description: Bildet die Struktur eines Zustellpunktes ab.
      type: object
      additionalProperties: false
      properties:
        submissionUrl:
          type: string
          format: uri
          description: Endpunkt für die Datenübergabe
          example: 'https://zustelldienst.example.org/destinations/3fa85f64-5717-4562-b3fc-2c963f66afa6'
        schemas:
          uniqueItems: true
          minItems: 1
          type: array
          description: Auflistung aller unterstützten Antragsschemata des Zustellpunktes.
          items:
            $ref: '#/components/schemas/ApplicationSchema'
        encryptionKid:
          type: string
          maxLength: 512
          description: 'Referenz auf den Public Key, der zur Verschlüsselung zu verwenden ist. Der referenzierte Public Key ist im Attribut `publicKeys` hinterlegt.'
        publicKeys:
          $ref: '#/components/schemas/JWKS'
      required:
        - host
        - schemas
        - encryptionKid
        - publicKeys
    JWK:
      title: JSON Web Key (JWK)
      type: object
      description: JSON Web Key - RFC 7517
      additionalProperties: false
      properties:
        kty:
          type: string
          description: Key Type
          enum:
            - EC
            - RSA
            - oct
            - OKP
        use:
          type: string
          description: Public Key Use
          enum:
            - sig
            - enc
        key_ops:
          type: array
          description: Key Operations
          uniqueItems: true
          items:
            type: string
            enum:
              - sign
              - verify
              - encrypt
              - decrypt
              - wrapKey
              - unwrapKey
              - deriveKey
              - deriveBits
        alg:
          type: string
          description: Algorithm
          enum:
            - PS512
            - RSA-OAEP-256
        kid:
          description: Key ID
          type: string
          maxLength: 512
        x5c:
          description: 'X.509 Certificate Chain. Die Reihenfolge der hinterlegten Zertifikate darf nicht verändert werden. Siehe https://datatracker.ietf.org/doc/html/rfc7517#section-4.7'
          type: array
          items:
            type: string
        e:
          type: string
          maxLength: 4096
        'n':
          type: string
          maxLength: 4096
      required:
        - kty
        - key_ops
        - kid
        - x5c
    JWKS:
      title: JSON Web Key Set (JWKS)
      description: 'JWKS nach 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'
    AreaResult:
      title: Ergebnis einer Gebietessuche.
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: Anzahl zurückgegebener Treffer
          maximum: 500
          minimum: 0
        offset:
          type: integer
          format: int32
          description: Startpunkt in der Gesamtanzahl der Suchtreffer
          minimum: 0
        totalCount:
          type: integer
          format: int32
          description: Gesamtanzahl der Suchtreffer
          minimum: 0
        areas:
          type: array
          items:
            $ref: '#/components/schemas/Area'
          minItems: 0
          maxItems: 500
          description: Aktuelle Suchtreffer
    Area:
      title: Gebiet
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id des Gebietes
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        name:
          type: string
          description: Name des Gebietes
          example: Halle (Saale)
        type:
          type: string
          description: Typ des Gebietes
          example: Kreisfreie Stadt
  parameters:
    ars:
      name: ars
      in: query
      description: 'Amtlicher Regionalschlüssel des Gebietes (https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/_FAQ/regionalschluessel.html)'
      required: false
      schema:
        type: string
        pattern: '^(\d{2}|\d{3}|\d{5}|\d{9}|\d{12})$'
    ags:
      name: ags
      in: query
      description: 'Amtlicher Gemeindeschlüssel des Ortes (https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/Glossar/amtlicher-gemeindeschluessel.html)'
      required: false
      schema:
        type: string
        pattern: '^(\d{2}|\d{3}|\d{5}|\d{8})$'
    leika-key:
      name: leika-key
      in: query
      description: Leikaschlüssel der Leistung
      required: true
      schema:
        type: string
        pattern: '^99\d{12}$'
    area-id:
      name: area-id
      in: query
      description: Id des Gebietes. Diese Id kann über die Resource /area ermittelt werden.
      required: false
      schema:
        type: string
        pattern: '^\d{1,}'
    area-searchexpression:
      name: area-searchexpression
      in: query
      description: 'Suchbegriffe für das zu suchenden Gebiet. Es können auch Postleitzahlen als Suchbegriffe verwendet werden. Es kann das Wildcard "\*" für die Suche verwendet werden. Zum Beispiel: "Mag\*" findet alle Gebiete die ein Wort beginend mit "Mag" im Namen (z.B. Magdeburg) enthalten.'
      required: true
      schema:
        type: array
        minItems: 1
        maxItems: 10
        items:
          type: string
          pattern: '^(\*?([^\*]{2,})\*?)*$'
      style: form
      explode: true
    offset:
      name: offset
      in: query
      description: Startposition der Teilmenge der Ergebnismenge. Standard ist 0.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 0
    limit:
      name: limit
      in: query
      description: Anzahl der Teilmenge der Ergebnismenge. Maximum ist 500. Standard ist 100.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 500
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
      description: Maximale Anzahl an Anfragen je Stunde.
    X-RateLimit-Remaining:
      schema:
        type: integer
      description: Verbleibende Anfragen im aktuellen Zeitfenster.
    X-RateLimit-Reset:
      schema:
        type: string
        format: date-time
      description: 'Der Zeitpunkt, in UTC-Zeit, an dem das aktuelle Zeitfenster abläuft und ein neues Zeitfenster beginnt.'
