meldestelle/backend/services/billing/billing-service/src/main/resources/openapi/documentation.yaml

openapi: 3.0.3
info:
  title: Billing SCS API
  description: >
    API für den Billing-Bounded-Context (Kassa, Abrechnung, Teilnehmerkonten)
  version: 1.0.0
servers:
  - url: http://localhost:8089
    description: Lokaler Entwicklungs-Server
paths:
  /api/billing/konten:
    get:
      summary: Teilnehmerkonto suchen
      description: Sucht ein Konto basierend auf Veranstaltungs-ID und Personen-ID. Erstellt das Konto, falls es nicht existiert.
      parameters:
        - name: veranstaltungId
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: personId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Teilnehmerkonto
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KontoDto'
        '400':
          description: Ungültige UUID-Formate
    post:
      summary: Teilnehmerkonto erstellen oder abrufen
      description: Erstellt ein neues Teilnehmerkonto für eine Veranstaltung und eine Person.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKontoRequest'
      responses:
        '200':
          description: Teilnehmerkonto (neu erstellt oder bestehend)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KontoDto'
        '400':
          description: Validierungsfehler
  /api/billing/konten/{kontoId}:
    get:
      summary: Teilnehmerkonto nach ID abrufen
      parameters:
        - name: kontoId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Details zum Teilnehmerkonto
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KontoDto'
        '404':
          description: Konto nicht gefunden
        '400':
          description: Ungültige Konto-ID
  /api/billing/konten/{kontoId}/buchungen:
    get:
      summary: Buchungshistorie abrufen
      description: Liefert alle Buchungen für ein bestimmtes Teilnehmerkonto.
      parameters:
        - name: kontoId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Liste von Buchungen
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BuchungDto'
        '400':
          description: Ungültige Konto-ID
    post:
      summary: Buchung hinzufügen
      description: Führt eine neue Buchung auf dem Teilnehmerkonto durch und aktualisiert den Saldo.
      parameters:
        - name: kontoId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuchungRequest'
      responses:
        '200':
          description: Aktualisiertes Teilnehmerkonto nach der Buchung
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KontoDto'
        '400':
          description: Validierungsfehler oder ungültige Konto-ID
components:
  schemas:
    KontoDto:
      type: object
      properties:
        kontoId:
          type: string
          format: uuid
        veranstaltungId:
          type: string
          format: uuid
        personId:
          type: string
          format: uuid
        personName:
          type: string
        saldoCent:
          type: integer
          format: int64
          description: Aktueller Saldo in Cent
        bemerkungen:
          type: string
          nullable: true
        updatedAt:
          type: string
          format: date-time
          description: Zeitpunkt der letzten Aktualisierung
    BuchungDto:
      type: object
      properties:
        buchungId:
          type: string
          format: uuid
        kontoId:
          type: string
          format: uuid
        betragCent:
          type: integer
          format: int64
          description: Betrag in Cent (positiv für Gutschriften, negativ für Belastungen)
        typ:
          $ref: '#/components/schemas/BuchungsTyp'
        verwendungszweck:
          type: string
        gebuchtAm:
          type: string
          format: date-time
    CreateKontoRequest:
      type: object
      required:
        - veranstaltungId
        - personId
        - personName
      properties:
        veranstaltungId:
          type: string
          format: uuid
        personId:
          type: string
          format: uuid
        personName:
          type: string
          minLength: 1
    BuchungRequest:
      type: object
      required:
        - betragCent
        - typ
        - verwendungszweck
      properties:
        betragCent:
          type: integer
          format: int64
        typ:
          $ref: '#/components/schemas/BuchungsTyp'
        verwendungszweck:
          type: string
          minLength: 1
    BuchungsTyp:
      type: string
      enum:
        - NENNGEBUEHR
        - KOPPELGEBUEHR
        - NACHNENNGEBUEHR
        - STARTGEBUEHR
        - EINZAHLUNG
        - AUSZAHLUNG
        - SONSTIGES