# API-Referenz Aufträge (App-Kennung auftraege)

> 31 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/auftraege/

## 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.

### Aufträge: `auftraege.auftrag.*`

#### auftraege.auftrag.list

Liste/Suche: Aufträge

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

#### auftraege.auftrag.get

Detail: Aufträge

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

#### auftraege.auftrag.create

Anlegen: Aufträge

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Auftrag anlegen
- Datenklassen: B (intern)
- Eingabe:
  - `nummer` (string)
  - `bezeichnung` (string, Pflicht)
  - `externeNummer` (string)
  - `auftragsartCode` (string, Pflicht)
  - `gewerkCode` (string)
  - `statusCode` (string)
  - `prioritaet` (string)
  - `parentId` (string)
  - `kontoId` (string, Pflicht)
  - `kontaktId` (string)
  - `objektId` (string)
  - `vertragId` (string)
  - `verantwortlichPersonId` (string)
  - `vorOrtPersonId` (string)
  - `kolonneKstId` (string)
  - `kostenstelleId` (string)
  - `eingangAm` (string)
  - `beginnGeplant` (string)
  - `endeGeplant` (string)
  - `fristBis` (string)
  - `abgeschlossenAm` (string)
  - `beschreibung` (string)
  - `bemerkung` (string)
  - `wert` (number)
  - `waehrung` (string)
- Beispiel: `{"name":"auftraege.auftrag.create","input":{"bezeichnung":"<bezeichnung>","auftragsartCode":"<auftragsartCode>","kontoId":"<kontoId>"}}`

#### auftraege.auftrag.update

Ändern: Aufträge

- Art: Ändern, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Auftrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht): ID des Datensatzes
  - `nummer` (string)
  - `bezeichnung` (string)
  - `externeNummer` (string)
  - `auftragsartCode` (string)
  - `gewerkCode` (string)
  - `statusCode` (string)
  - `prioritaet` (string)
  - `parentId` (string)
  - `kontoId` (string)
  - `kontaktId` (string)
  - `objektId` (string)
  - `vertragId` (string)
  - `verantwortlichPersonId` (string)
  - `vorOrtPersonId` (string)
  - `kolonneKstId` (string)
  - `kostenstelleId` (string)
  - `eingangAm` (string)
  - `beginnGeplant` (string)
  - `endeGeplant` (string)
  - `fristBis` (string)
  - `abgeschlossenAm` (string)
  - `beschreibung` (string)
  - `bemerkung` (string)
  - `wert` (number)
  - `waehrung` (string)
- Beispiel: `{"name":"auftraege.auftrag.update","input":{"id":"<id>"}}`

#### auftraege.auftrag.delete

Löschen: Aufträge

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

### Beteiligte am Auftrag: `auftraege.beteiligter.*`

#### auftraege.beteiligter.list

Liste/Suche: Beteiligte am Auftrag

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

#### auftraege.beteiligter.get

Detail: Beteiligte am Auftrag

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

#### auftraege.beteiligter.create

Anlegen: Beteiligte am Auftrag

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Auftrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `auftragId` (string, Pflicht)
  - `rolleCode` (string, Pflicht)
  - `kontoId` (string)
  - `kontaktId` (string)
  - `bezeichnung` (string)
  - `bemerkung` (string)
  - `position` (number)
- Beispiel: `{"name":"auftraege.beteiligter.create","input":{"auftragId":"<auftragId>","rolleCode":"<rolleCode>"}}`

#### auftraege.beteiligter.update

Ändern: Beteiligte am Auftrag

- Art: Ändern, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Auftrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht): ID des Datensatzes
  - `auftragId` (string)
  - `rolleCode` (string)
  - `kontoId` (string)
  - `kontaktId` (string)
  - `bezeichnung` (string)
  - `bemerkung` (string)
  - `position` (number)
- Beispiel: `{"name":"auftraege.beteiligter.update","input":{"id":"<id>"}}`

#### auftraege.beteiligter.delete

Löschen: Beteiligte am Auftrag

- Art: Löschen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Auftrag ändern
- Datenklassen: B (intern)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"auftraege.beteiligter.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.

### Auftragsarten: `auftraege.auftragsart.*`

#### auftraege.auftragsart.list

Liste/Suche: Katalog „Auftragsarten" (auftraege)

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

#### auftraege.auftragsart.get

Detail: Katalog „Auftragsarten" (auftraege)

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

#### auftraege.auftragsart.create

Anlegen: Katalog „Auftragsarten" (auftraege)

- 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":"auftraege.auftragsart.create","input":{"label":"<label>"}}`

#### auftraege.auftragsart.update

Ändern: Katalog „Auftragsarten" (auftraege)

- 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":"auftraege.auftragsart.update","input":{"id":"<id>"}}`

#### auftraege.auftragsart.delete

Löschen: Katalog „Auftragsarten" (auftraege)

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

### Auftragsstatus: `auftraege.status.*`

#### auftraege.status.list

Liste/Suche: Katalog „Auftragsstatus" (auftraege)

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

#### auftraege.status.get

Detail: Katalog „Auftragsstatus" (auftraege)

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

#### auftraege.status.create

Anlegen: Katalog „Auftragsstatus" (auftraege)

- 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":"auftraege.status.create","input":{"label":"<label>"}}`

#### auftraege.status.update

Ändern: Katalog „Auftragsstatus" (auftraege)

- 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":"auftraege.status.update","input":{"id":"<id>"}}`

#### auftraege.status.delete

Löschen: Katalog „Auftragsstatus" (auftraege)

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

### Beteiligtenrollen: `auftraege.beteiligtenrolle.*`

#### auftraege.beteiligtenrolle.list

Liste/Suche: Katalog „Beteiligtenrollen" (auftraege)

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

#### auftraege.beteiligtenrolle.get

Detail: Katalog „Beteiligtenrollen" (auftraege)

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

#### auftraege.beteiligtenrolle.create

Anlegen: Katalog „Beteiligtenrollen" (auftraege)

- 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":"auftraege.beteiligtenrolle.create","input":{"label":"<label>"}}`

#### auftraege.beteiligtenrolle.update

Ändern: Katalog „Beteiligtenrollen" (auftraege)

- 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":"auftraege.beteiligtenrolle.update","input":{"id":"<id>"}}`

#### auftraege.beteiligtenrolle.delete

Löschen: Katalog „Beteiligtenrollen" (auftraege)

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

### Gewerke: `auftraege.gewerk.*`

#### auftraege.gewerk.list

Liste/Suche: Katalog „Gewerke" (auftraege)

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

#### auftraege.gewerk.get

Detail: Katalog „Gewerke" (auftraege)

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

#### auftraege.gewerk.create

Anlegen: Katalog „Gewerke" (auftraege)

- 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":"auftraege.gewerk.create","input":{"label":"<label>"}}`

#### auftraege.gewerk.update

Ändern: Katalog „Gewerke" (auftraege)

- 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":"auftraege.gewerk.update","input":{"id":"<id>"}}`

#### auftraege.gewerk.delete

Löschen: Katalog „Gewerke" (auftraege)

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

## Weitere Aktionen

Eigene Aktionen der App, zum Beispiel Auswertungen, Versand, Zuordnungen oder Abläufe über mehrere Datensätze.

#### auftraege.wartung_erzeugen

Wartungsaufträge aus Verträgen: zeigt je Wartungsvertrag (Merkmal intervall_monate) letzte und nächste Wartung (letzte + Intervall, Felder letzte_wartung/naechste_wartung am Vertrag) und legt fällige Wartungsaufträge an (30 Tage Vorlauf, je Vertrag höchstens ein offener). Standard ist dryRun=true (nur Vorschau); mit dryRun=false wird angelegt.

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Auftrag anlegen, vertraege: Vertrag lesen
- Datenklassen: C (vertraulich)
- Datenschutz: Liest Verträge des Mandanten und legt Aufträge an; keine Daten verlassen den Mandanten.
- Eingabe:
  - `dryRun` (boolean): true (Standard) = nur Vorschau, false = anlegen
  - `vorlaufTage` (number): Tage vor Fälligkeit, ab denen angelegt wird (Standard 30)
- Beispiel: `{"name":"auftraege.wartung_erzeugen","input":{}}`