🔍 Inhalt
- Voraussetzungen
- Authentifizierung
- Endpunkte im Überblick
- Datensatz erstellen oder aktualisieren (PUT)
- Datensätze abfragen (GET)
- Datensätze löschen (DELETE)
- Technische Hinweise
- Tipps & Best Practices
- FAQ
Voraussetzungen
🔐 API-Zugangsdaten (Username + Passwort für HTTP Basic Auth)🌐 Zugriff auf eine ausführende Umgebung (z. B. Power Automate, Python, Postman, Swagger UI oder eigene Integrationslösung)
🧾 UUIDs für KPI, Team und ggf. Sub-Tile/KPI-Wert (können über Meta-Endpunkte abgerufen werden)
🔑 Authentifizierung
Die Authentifizierung erfolgt über HTTP Basic Auth.
Header-Beispiel:
Authorization: Basic <Base64-kodierter Benutzername:Passwort>
ℹ️ Hinweis: Der Zugriff ist nur für Benutzer mit entsprechender API-Berechtigung möglich.
🔗 Endpunkte im Überblick (KPI)
| Methode | Endpunkt | Beschreibung |
|---|---|---|
| GET | /exchange/kpi-data |
Liste aller KPI-Daten abrufen |
| GET | /exchange/kpi-data/{date}/{team-id}/{kpi-id} |
Einzelnen Datensatz abrufen |
| PUT | /exchange/kpi-data/{date}/{team-id}/{kpi-id} |
KPI-Datensatz erstellen oder aktualisieren |
| DELETE | /exchange/kpi-data/{date}/{team-id}/{kpi-id} |
KPI-Datensatz löschen |
📥 KPI-Datensatz erstellen oder aktualisieren (PUT)
Beispiel-Aufruf:
PUT /exchange/kpi-data/2022-11-01/8dca904d-9134-3bb0-95b7-3f72ae3dfacf/c3ba32c2-a13a-0000-0000-000000000000
📸 Screenshot: Swagger UI – PUT-Aufruf für KPI-Daten
Header:
Content-Type: application/vs.v2.0+json
Authorization: Basic <base64-Zugangsdaten>Body (Beispiel):
{
"values": [
{
"kpiValueId": "79cf2f74-0e9c-45b5-bc4d-f437079dde7c",
"value": 177
},
{
"kpiValueId": "fd2c7750-79e1-4514-89a2-e9c103db4d6b",
"value": 190
}
]
}✨ Tipp: Sie können auch nur einzelne Werte (z. B. nur "target") senden – die API ergänzt oder aktualisiert bestehende Werte intelligent.
🔍 KPI-Datensätze abrufen (GET)
Beispiel: Alle Werte einer KPI innerhalb eines Zeitraums abfragen:
GET /exchange/kpi-data?kpi-id={kpi-id}&team-id={team-id}&from=2022-10-01&to=2022-10-31
📸 Screenshot: Swagger UI – GET mit Filterparametern
ℹ️ Hinweis: Zeitraum darf maximal 31 Tage (Tageseinträge) oder 6 Monate (Wochen/Monate) umfassen.
❌ KPI-Datensatz löschen (DELETE)
DELETE /exchange/kpi-data/2022-11-01/8dca904d-9134-3bb0-95b7-3f72ae3dfacf/c3ba32c2-a13a-0000-0000-000000000000
⚠️ Achtung: Gelöschte Einträge können nicht wiederhergestellt werden.
📌 Technische Hinweise
-
Jeder KPI-Wert ist eindeutig identifiziert durch:
date + team + kpi (+ sub-tile) -
Die API akzeptiert nur einen Datensatz pro Tag/KPI/Team/Sub-Tile
-
Datumsformat:
yyyy-MM-dd(auch bei Wochen- und Monatseinträgen)-
Woche: Datum des Montags
-
Monat: Datum des 1. Tags
-
-
Sub-Tiles sind optional, aber bei granularer Strukturierung notwendig
✨ Tipps & Best Practices
-
🧪 Beginnen Sie mit Tests im Swagger Editor oder Postman
-
🔄 Aktualisieren Sie KPI-Werte regelmäßig für konsistente Auswertungen
-
🧩 Tragen Sie Werte nur auf unterster Teamebene ein – Aggregationen erfolgen automatisch
-
🧾 Prüfen Sie UUIDs von KPI, Team, Sub-Tile, KPI-Wert über Meta-Endpunkte
❓ FAQ
Wie finde ich die benötigten UUIDs (KPI, Team, KPI-Werte)?
👉 Nutzen Sie die Meta-Endpunkte /exchange/kpi und /exchange/kpi/{kpi-id}.
Was passiert, wenn ich dieselben Werte erneut sende?
👉 Die API erkennt bestehende Kombinationen und überschreibt vorhandene Werte (PUT = Create/Update).
Kann ich nur Sollwerte senden?
👉 Nein– wenn Zielwerte fehlen, ergänzt die API diese ggf. mit Standardwerten (0) oder übernimmt historische Zielwerte.