# API-Referenz Verträge (App-Kennung vertraege)

> 20 App-Tools. Aufruf immer mit `POST /api/app-tools`, Header `X-API-KEY`, Body `{"name": "<tool>", "input": {…}}`. Welche Tools ein Schlüssel nutzen darf, zeigt `GET /api/app-tools` der Instanz.

Quelle: https://support.unitedsynergy.com/api/referenz/vertraege/

## Datenobjekte

Die Standard-Aktionen je Datenobjekt: list (suchen und blättern), get (einen Datensatz lesen), create, update und delete. Nicht jedes Objekt bietet alle fünf an.

### Verträge: `vertraege.vertrag.*`

#### vertraege.vertrag.list

Liste/Suche: Verträge

- Art: Lesen
- Rechte: Vertrag lesen
- Datenklassen: B (intern)
- Eingabe:
  - `search` (string): Freitextsuche
  - `filters` (object): Feld=Wert-Filter
  - `limit` (integer)
  - `offset` (integer)
  - `orderBy` (string)
- Beispiel: `{"name":"vertraege.vertrag.list","input":{}}`

#### vertraege.vertrag.get

Detail: Verträge

- Art: Lesen
- Rechte: Vertrag lesen
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.vertrag.get","input":{"id":"<id>"}}`

#### vertraege.vertrag.create

Anlegen: Verträge

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Vertrag anlegen
- Datenklassen: B (intern)
- Eingabe:
  - `nummer` (string)
  - `bezeichnung` (string, Pflicht)
  - `vertragsartCode` (string, Pflicht)
  - `statusCode` (string)
  - `kontoId` (string, Pflicht)
  - `kontaktId` (string)
  - `objektId` (string)
  - `rolleTenant` (string)
  - `gegenstand` (string)
  - `beginn` (string)
  - `ende` (string)
  - `laufzeitMonate` (number)
  - `autoVerlaengerung` (boolean)
  - `verlaengerungMonate` (number)
  - `kuendigungsfristMonate` (number)
  - `gekuendigtAm` (string)
  - `gekuendigtZum` (string)
  - `unterzeichnetAm` (string)
  - `wert` (number)
  - `waehrung` (string)
  - `abrechnungsrhythmus` (string)
  - `verantwortlichUserId` (string)
  - `bemerkung` (string)
- Beispiel: `{"name":"vertraege.vertrag.create","input":{"bezeichnung":"<bezeichnung>","vertragsartCode":"<vertragsartCode>","kontoId":"<kontoId>"}}`

#### vertraege.vertrag.update

Ändern: Verträge

- Art: Ändern, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Vertrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht): ID des Datensatzes
  - `nummer` (string)
  - `bezeichnung` (string)
  - `vertragsartCode` (string)
  - `statusCode` (string)
  - `kontoId` (string)
  - `kontaktId` (string)
  - `objektId` (string)
  - `rolleTenant` (string)
  - `gegenstand` (string)
  - `beginn` (string)
  - `ende` (string)
  - `laufzeitMonate` (number)
  - `autoVerlaengerung` (boolean)
  - `verlaengerungMonate` (number)
  - `kuendigungsfristMonate` (number)
  - `gekuendigtAm` (string)
  - `gekuendigtZum` (string)
  - `unterzeichnetAm` (string)
  - `wert` (number)
  - `waehrung` (string)
  - `abrechnungsrhythmus` (string)
  - `verantwortlichUserId` (string)
  - `bemerkung` (string)
- Beispiel: `{"name":"vertraege.vertrag.update","input":{"id":"<id>"}}`

#### vertraege.vertrag.delete

Löschen: Verträge

- Art: Löschen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Vertrag löschen
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.vertrag.delete","input":{"id":"<id>"}}`

### Vertragspositionen: `vertraege.position.*`

#### vertraege.position.list

Liste/Suche: Vertragspositionen

- Art: Lesen
- Rechte: Vertrag lesen
- Datenklassen: B (intern)
- Eingabe:
  - `search` (string): Freitextsuche
  - `filters` (object): Feld=Wert-Filter
  - `limit` (integer)
  - `offset` (integer)
  - `orderBy` (string)
- Beispiel: `{"name":"vertraege.position.list","input":{}}`

#### vertraege.position.get

Detail: Vertragspositionen

- Art: Lesen
- Rechte: Vertrag lesen
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.position.get","input":{"id":"<id>"}}`

#### vertraege.position.create

Anlegen: Vertragspositionen

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Vertrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `vertragId` (string, Pflicht)
  - `position` (number)
  - `artikelId` (string)
  - `bezeichnung` (string, Pflicht)
  - `beschreibung` (string)
  - `menge` (number)
  - `einheit` (string)
  - `einzelpreis` (number)
  - `rabattProzent` (number)
  - `intervall` (string)
  - `gesamt` (number)
- Beispiel: `{"name":"vertraege.position.create","input":{"vertragId":"<vertragId>","bezeichnung":"<bezeichnung>"}}`

#### vertraege.position.update

Ändern: Vertragspositionen

- Art: Ändern, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Vertrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht): ID des Datensatzes
  - `vertragId` (string)
  - `position` (number)
  - `artikelId` (string)
  - `bezeichnung` (string)
  - `beschreibung` (string)
  - `menge` (number)
  - `einheit` (string)
  - `einzelpreis` (number)
  - `rabattProzent` (number)
  - `intervall` (string)
  - `gesamt` (number)
- Beispiel: `{"name":"vertraege.position.update","input":{"id":"<id>"}}`

#### vertraege.position.delete

Löschen: Vertragspositionen

- Art: Löschen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Vertrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.position.delete","input":{"id":"<id>"}}`

## Wertelisten

Auswahllisten der App wie Status, Arten oder Kategorien. Du pflegst sie mit denselben fünf Aktionen. Die Werte (code) nutzt du in den Feldern der Datenobjekte.

### Vertragsarten: `vertraege.vertragsart.*`

#### vertraege.vertragsart.list

Liste/Suche: Katalog „Vertragsarten" (vertraege)

- Art: Lesen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `onlyAktiv` (boolean): Nur aktive Einträge
- Beispiel: `{"name":"vertraege.vertragsart.list","input":{}}`

#### vertraege.vertragsart.get

Detail: Katalog „Vertragsarten" (vertraege)

- Art: Lesen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.vertragsart.get","input":{"id":"<id>"}}`

#### vertraege.vertragsart.create

Anlegen: Katalog „Vertragsarten" (vertraege)

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `label` (string, Pflicht): Anzeige-Text
  - `code` (string): Optional, sonst aus label abgeleitet. Immutable
  - `color` (string): Tailwind-Paar, z.B. "bg-blue-100 text-blue-700"
  - `icon` (string): Lucide-Icon-Name
  - `beschreibung` (string)
- Beispiel: `{"name":"vertraege.vertragsart.create","input":{"label":"<label>"}}`

#### vertraege.vertragsart.update

Ändern: Katalog „Vertragsarten" (vertraege)

- Art: Ändern, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
  - `label` (string)
  - `color` (string)
  - `icon` (string)
  - `beschreibung` (string)
  - `aktiv` (boolean)
- Beispiel: `{"name":"vertraege.vertragsart.update","input":{"id":"<id>"}}`

#### vertraege.vertragsart.delete

Löschen: Katalog „Vertragsarten" (vertraege)

- Art: Löschen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.vertragsart.delete","input":{"id":"<id>"}}`

### Vertragsstatus: `vertraege.status.*`

#### vertraege.status.list

Liste/Suche: Katalog „Vertragsstatus" (vertraege)

- Art: Lesen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `onlyAktiv` (boolean): Nur aktive Einträge
- Beispiel: `{"name":"vertraege.status.list","input":{}}`

#### vertraege.status.get

Detail: Katalog „Vertragsstatus" (vertraege)

- Art: Lesen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.status.get","input":{"id":"<id>"}}`

#### vertraege.status.create

Anlegen: Katalog „Vertragsstatus" (vertraege)

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `label` (string, Pflicht): Anzeige-Text
  - `code` (string): Optional, sonst aus label abgeleitet. Immutable
  - `color` (string): Tailwind-Paar, z.B. "bg-blue-100 text-blue-700"
  - `icon` (string): Lucide-Icon-Name
  - `beschreibung` (string)
- Beispiel: `{"name":"vertraege.status.create","input":{"label":"<label>"}}`

#### vertraege.status.update

Ändern: Katalog „Vertragsstatus" (vertraege)

- Art: Ändern, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
  - `label` (string)
  - `color` (string)
  - `icon` (string)
  - `beschreibung` (string)
  - `aktiv` (boolean)
- Beispiel: `{"name":"vertraege.status.update","input":{"id":"<id>"}}`

#### vertraege.status.delete

Löschen: Katalog „Vertragsstatus" (vertraege)

- Art: Löschen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Einstellungen verwalten
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"vertraege.status.delete","input":{"id":"<id>"}}`