673 lines
18 KiB
YAML
673 lines
18 KiB
YAML
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
|
|
|