🔍 Inhalt
- Voraussetzungen
- Authentifizierung
- Endpunkte im Überblick
- Abweichung erstellen (POST)
- Abweichung aktualisieren (PUT)
- Abweichung abrufen & löschen (GET, DELETE)
- Beschreibung verwalten
- Technische Hinweise
- Tipps & Best Practices
- FAQ
Voraussetzungen
-
🔐 API-Zugangsdaten (Username + Passwort für HTTP Basic Auth)
-
🌐 Zugriff auf ein Tool zur Ausführung von HTTP-Requests (z. B. Power Automate, Python, Postman, Swagger UI)
-
🧲 Team-ID, Kategorie-ID und ggf. Quellobjekt-ID (z. B. KPI, Task, Prozessschritt)
Authentifizierung
Die Authentifizierung erfolgt per HTTP Basic Auth. Username und Passwort werden vom ValueStreamer Support zur Verfügung gestellt. Alle API-Aktivitäten erfolgen im Namen des technischen Benutzers API-USER und werden im Change-Log dokumentiert.
🔹 Endpunkte im Überblick
| Aktion | Methode | Pfad |
|---|---|---|
| Abweichungen abrufen | GET | /exchange/deviations?team={id} |
| Einzelne Abweichung holen | GET | /exchange/deviations/{id} |
| Neue Abweichung erstellen | POST | /exchange/deviations |
| Abweichung aktualisieren | PUT | /exchange/deviations/{id} |
| Abweichung löschen | DELETE | /exchange/deviations/{id} |
| Beschreibung abrufen | GET | /exchange/deviations/{id}/description |
| Beschreibung aktualisieren | PUT | /exchange/deviations/{id}/description |
✏️ Abweichung erstellen (POST)
Endpoint: /exchange/deviations
Method: POST
Content-Type: application/vs.v2.0+json
Pflichtfelder:
-
responsibleTeam: ID des verantwortlichen Teams -
category: ID der gewählten Kategorie -
deviationType: "ERROR" oder "PROBLEM" -
duration: Dauer in Minuten -
frequency: Häufigkeit (Zahl > 0) -
title: Kurztitel der Abweichung
Optional:
-
sourceEntity: Verlinkung zu KPI, Task etc.
⚠️ Nur Single Deviations können über die API erstellt werden. Kombinierte und Kind-Abweichungen nur über die GUI.
✏️ Abweichung aktualisieren (PUT)
Endpoint: /exchange/deviations/{id}
Method: PUT
Pflichtfelder:
-
title -
closed: true/false -
duration,frequency(bei Single & Child Deviations) -
category(bei Single Deviations)
Optional:
-
sourceEntity: Verknüpfung aktualisieren
✔ Kombinierte oder Kind-Abweichungen können aktualisiert werden, aber nur eingeschränkt: Dauer/Frequenz sind nicht änderbar.
📂 Abweichung abrufen & löschen
Einzelne Abweichung abrufen
GET /exchange/deviations/{id}
Optional mit ?include=COUNTERMEASURES für Gegenmaßnahmen
Beschreibung abrufen
GET /exchange/deviations/{id}/description (HTML Format)
Abweichung löschen
DELETE /exchange/deviations/{id}
⚠️ Löscht auch alle verknüpften Kindabweichungen, Gegenmaßnahmen, Go+See, Top Issues, Feedback. Verlinkte Tasks bleiben erhalten, aber die Verbindung wird entfernt.
📃 Beschreibung verwalten
Beschreibung lesen:
-
GET /exchange/deviations/{id}/description
Beschreibung aktualisieren:
-
PUT /exchange/deviations/{id}/description -
Content-Type:
text/html
💡 Technische Hinweise
-
Base URL:
https://api-<tenant>.valuestreamer.de/api/ -
Akzeptierter Content-Type:
application/vs.v2.0+json -
Auth Header:
Authorization: Basic <Base64-encoded> -
Max. 200 Ergebnisse pro Page
-
Filter möglich:
?team=...&status=ACTIVE|CLOSED|ALL&level=SINGLE|COMBINED|CHILDREN
📊 Tipps & Best Practices
-
Verwenden Sie
GET /teams/{id}/deviation-config, um gültige Kategorien pro Team zu sehen -
Nur aktive Kategorien sind verfügbar für POST/PUT
-
Kombinierte Abweichungen können nur über die GUI erstellt werden
-
Beschreibung kann als HTML gepflegt werden (z. B. für Formatierung, Links, Listen)
🚗 FAQ
Kann ich auch Aufgaben, KPIs oder Meetings verknüpfen?
-> Ja, per sourceEntity. Gültige Typen: KPI, LIST, PROCESSACTIVITY, TASK, MEETINGATTENDANCE
Kann ich mehrere Teams abfragen?
-> Nein, die Abfrage erfolgt immer teamweise über ?team={id}.
Wie sehe ich, ob eine Abweichung geschlossen ist?
-> Am Feld closed: true oder am Status CLOSED_...
Wie finde ich die richtige Kategorie-ID?
-> Über GET /exchange/deviation-categories oder teambezogen über GET /teams/{id}/deviation-config