meldestelle/docs/03_Development/Backend/API/Kassa_API.md

type, status, owner, last_update

type	status	owner	last_update
Reference	DRAFT	Backend Developer	2026-04-03

Kassa-API (Entwurf)

Abhängigkeit: Backend Sprint B‑2 (Kassa-Service) — laut Curator‑Roadmap noch offen. Dieses Dokument reserviert die Endpunkte und beschreibt die Erwartungen. Die Implementierungsdetails werden ergänzt, sobald der Service fertiggestellt ist.

Mandantenkontext: Erfordert X-Event-Id (ADR‑0021). Alle Kassa‑Operationen sind tenant‑lokal.

Endpunkte (geplant)

• GET /kassa/saldo — Liefert den aktuellen Saldo der Veranstaltung und optional pro Turnier.

  • Query: turnierId (optional, UUID)
  • Response: { saldoCents: long, currency: "EUR", scope: "veranstaltung"|"turnier", turnierId?: UUID }

• GET /zahlvorgaenge — Listet Kassa‑Buchungen/Zahlvorgänge (paginiert, filterbar).

  • Query: turnierId?, teilnehmerId?, typ? (EINZAHLUNG|AUSZAHLUNG|KORREKTUR), limit, offset
  • Response: Liste von Transaktionen mit Betrag, Zeit, Verweis (Teilnehmer/Turnier), Notiz

• POST /zahlvorgaenge — Erstellt einen neuen Zahlungsvorgang (Ein-/Auszahlung/Korrektur).

  • Body: { typ, betragCents, currency, referenz: { teilnehmerId?|turnierId? }, notiz? }
  • Wirkung: Aktualisiert teilnehmer_konten bzw. turnier_kassa atomar.

Validierung & Regeln (voraussichtlich)

• Atomare Konsistenz: Transaktion + Saldo‑Update innerhalb einer DB‑Transaktion.
• Negativsaldo optional durch Feature‑Flag blockierbar.
• Audit‑Trail pro Vorgang (who/when), Idempotenz‑Key optional.

Implementierungsstand

• Datenstrukturen teilnehmer_konten und turnier_kassa sind per Flyway angelegt (siehe Datenbankschema).
• Endpunkte folgen nach Abschluss Backend B‑2. Dieses Dokument wird dann auf status: ACTIVE gesetzt.