openapi: 3.0.0
info:
  version: 1.0.0
  title: Buchhaltungs-API
  description: |
    Buchhaltungs-API für das Web-Anwendungen-Projekt
servers:
  - url: ../api/{apiVersion}
    variables:
      apiVersion:
        enum:
          - v1
        default: v1
        description: API-Version
paths:
  /accounts:
    get:
      tags:
        - Konten
      description: |
        Dieser Endpunkt liefert eine Liste aller Konten zurück.
      operationId: book.getAccounts
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountTree'
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Konten
      description: |
        Erstellt ein neues Konto.

        Die Kontonummer muss in Verbindung mit dem übergeordneten Konto eindeutig sein.
      operationId: book.createAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        204:
          description: OK
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        422:
          description: Nicht ausführbare Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{account}:
    get:
      tags:
        - Konten
      description: |
        Dieser Endpunkt liefert die Details eines Kontos sowie
        die Liste der Buchungen des Kontos.
      parameters:
        - name: account
          in: path
          description: |
            Qualifizierter Name des Kontos
          required: true
          schema:
            $ref: '#/components/schemas/AccountQualifiedName'
          style: simple
      operationId: book.getAccount
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDetails'
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Konto existiert nicht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Konten
      description: |
        Ändert die Kontodaten.

        Die Kontonummer muss in Verbindung mit dem übergeordneten Konto eindeutig sein.

        Der Kontotyp kann nur geändert werden, falls keine Buchungen mit dem Konto verknüpft sind.
      parameters:
        - name: account
          in: path
          description: |
            Qualifizierter Name des Kontos
          required: true
          schema:
            $ref: '#/components/schemas/AccountQualifiedName'
          style: simple
      operationId: book.updateAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        204:
          description: OK
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Konto existiert nicht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        422:
          description: Nicht ausführbare Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Konten
      description: |
        Löscht das Konto.

        Diese Anfrage kann nur ausgeführt werden, falls keine Buchungen oder Unterkonten mehr mit dem Konto verknüpft sind.
      parameters:
        - name: account
          in: path
          description: |
            Qualifizierter Name des Kontos
          required: true
          schema:
            $ref: '#/components/schemas/AccountQualifiedName'
          style: simple
      operationId: book.deleteAccount
      responses:
        204:
          description: OK
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Konto existiert nicht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        422:
          description: Nicht ausführbare Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions:
    get:
      tags:
        - Buchungen
      description: |
        Dieser Endpunkt liefert eine Liste aller Buchungen zurück.
      operationId: transaction.getTransactions
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionListItem'
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Buchungen
      description: |
        Erstellt eine neue Buchung.
      operationId: transaction.createTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/Identifier'
                required:
                  - id
                additionalProperties: false
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        422:
          description: Ungültige Transaktion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions/{id}:
    get:
      tags:
        - Buchungen
      description: |
        Zeigt die Details einer Buchung mit allen Konten und Beträgen an.
      parameters:
        - name: id
          in: path
          description: Buchungs-ID
          required: true
          schema:
            $ref: '#/components/schemas/Identifier'
          style: simple
      operationId: transaction.getTransaction
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Transaktion existiert nicht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Buchungen
      description: |
        Aktualisiert die Buchung.
      parameters:
        - name: id
          in: path
          description: Buchungs-ID
          required: true
          schema:
            $ref: '#/components/schemas/Identifier'
          style: simple
      operationId: transaction.updateTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
      responses:
        204:
          description: OK
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Transaktion existiert nicht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        422:
          description: Ungültige Transaktion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Buchungen
      description: |
        Löscht die Buchung aus allen Konten.
      parameters:
        - name: id
          in: path
          description: Buchungs-ID
          required: true
          schema:
            $ref: '#/components/schemas/Identifier'
          style: simple
      operationId: transaction.deleteTransaction
      responses:
        204:
          description: OK
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Transaktion existiert nicht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reset:
    post:
      tags:
        - Wartung
      description: |
        Dieser Endpunkt setzt den Datenbestand zurück.
      operationId: admin.doReset
      responses:
        204:
          description: OK
        400:
          description: Ungültige Anfrage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Unerwarteter Fehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Identifier:
      type: integer
      minimum: 1
      maximum: 99999999
      description: ID
      example: 1
    CurrencyAmount:
      type: number
      multipleOf: 0.01
      description: Geldbetrag in Euro
      example: 225.17
    CurrencyNonZeroAmount:
      description: Geldbetrag in Euro, der nicht Null ist
      oneOf:
        - type: number
          multipleOf: 0.01
          minimum: 0
          exclusiveMinimum: true
          description: Positiver Geldbetrag in Euro
          example: 25.17
        - type: number
          multipleOf: 0.01
          maximum: 0
          exclusiveMaximum: true
          description: Negativer Geldbetrag in Euro
          example: -93.11
    Account:
      type: object
      properties:
        number:
          $ref: '#/components/schemas/AccountNumber'
        name:
          $ref: '#/components/schemas/AccountName'
        description:
          $ref: '#/components/schemas/AccountDescription'
        type:
          $ref: '#/components/schemas/AccountType'
        parentAccount:
          $ref: '#/components/schemas/AccountQualifiedName'
      required:
        - number
        - name
        - type
      additionalProperties: false
    AccountTree:
      type: object
      properties:
        number:
          $ref: '#/components/schemas/AccountNumber'
        name:
          $ref: '#/components/schemas/AccountName'
        qualifiedName:
          $ref: '#/components/schemas/AccountQualifiedName'
        description:
          $ref: '#/components/schemas/AccountDescription'
        type:
          $ref: '#/components/schemas/AccountType'
        balance:
          $ref: '#/components/schemas/CurrencyAmount'
        localBalance:
          $ref: '#/components/schemas/CurrencyAmount'
        subaccounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountTree'
      required:
        - number
        - name
        - qualifiedName
        - type
        - balance
        - localBalance
        - subaccounts
      additionalProperties: false
    AccountDetails:
      type: object
      properties:
        number:
          $ref: '#/components/schemas/AccountNumber'
        name:
          $ref: '#/components/schemas/AccountName'
        qualifiedName:
          $ref: '#/components/schemas/AccountQualifiedName'
        description:
          $ref: '#/components/schemas/AccountDescription'
        type:
          $ref: '#/components/schemas/AccountType'
        balance:
          $ref: '#/components/schemas/CurrencyAmount'
        localBalance:
          $ref: '#/components/schemas/CurrencyAmount'
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Entry'
      required:
        - number
        - name
        - qualifiedName
        - type
        - balance
        - localBalance
        - entries
      additionalProperties: false
    AccountNumber:
      type: integer
      minimum: 1
      maximum: 99999999
      description: Kontonummer (wird insbesondere zur Sortierung genutzt)
      example: 1100
    AccountName:
      type: string
      minLength: 3
      maxLength: 32
      pattern: '^[a-zA-Z0-9äöüßÄÖÜẞ_ -]*$'
      description: Name des Kontos
      example: Aktiva
    AccountQualifiedName:
      type: string
      minLength: 3
      description: Name des Kontos mit übergeordneten Konten (qualifizierter Name)
      example: Aktiva:Barvermögen:Bargeld
    AccountDescription:
      type: string
      minLength: 3
      maxLength: 64
      description: Beschreibung des Kontos
      example: Girokonto bei der Musterbank eG
    AccountType:
      type: string
      enum:
        - default
        - meta
      description: Art des Kontos (nur Platzhalter für Unterkonten oder eigene Buchungen erlaubt)
      example: default
    Entry:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        postingDate:
          $ref: '#/components/schemas/EntryPostingDate'
        valueDate:
          $ref: '#/components/schemas/EntryValueDate'
        title:
          $ref: '#/components/schemas/EntryTitle'
        amount:
          $ref: '#/components/schemas/CurrencyNonZeroAmount'
        label:
          $ref: '#/components/schemas/EntryLabel'
        offsetAccounts:
          type: string
          description: Gegenkonto (ggf. mehrere bei mehrteiliger Buchung)
      required:
        - id
        - postingDate
        - valueDate
        - title
        - amount
        - offsetAccounts
      additionalProperties: false
    EntryPostingDate:
      type: string
      format: date
      description: Buchungsdatum
    EntryValueDate:
      type: string
      format: date
      description: Valuta (Wertstellungsdatum)
    EntryTitle:
      type: string
      minLength: 3
      maxLength: 64
      description: Buchungstitel
      example: Semesterbeitrag SoSe 2024
    EntryLabel:
      type: string
      minLength: 3
      maxLength: 64
      description: Buchungstitel des Kontos
    Transaction:
      type: object
      properties:
        postingDate:
          $ref: '#/components/schemas/EntryPostingDate'
        valueDate:
          $ref: '#/components/schemas/EntryValueDate'
        title:
          $ref: '#/components/schemas/EntryTitle'
        entries:
          type: array
          minItems: 2
          items:
            type: object
            properties:
              account:
                $ref: '#/components/schemas/AccountQualifiedName'
              amount:
                $ref: '#/components/schemas/CurrencyNonZeroAmount'
              label:
                $ref: '#/components/schemas/EntryLabel'
            required:
              - account
              - amount
            additionalProperties: false
      required:
        - postingDate
        - valueDate
        - title
        - entries
      additionalProperties: false
    TransactionListItem:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        postingDate:
          $ref: '#/components/schemas/EntryPostingDate'
        valueDate:
          $ref: '#/components/schemas/EntryValueDate'
        title:
          $ref: '#/components/schemas/EntryTitle'
      required:
        - id
        - postingDate
        - valueDate
        - title
      additionalProperties: false
    Error:
      required:
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
      additionalProperties: true