🔍 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.
✨ Tipp: Werte mit Einheit „Zeit“
Für KPIs mit der Einheit „Zeit“ geben Sie den Wert als Minuten seit 0:00 Uhr an.
Beispiele:
-
2:43 Uhr nachmittags (14:43) →
14 × 60 + 43 = 883 -
08:00 Uhr morgens →
8 × 60 = 480
🔍 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
- Bei KPIs mit Einheit "Uhrzeit" (Time) wird der Wert als Gesamtminuten seit Mitternacht übermittelt (z. B.
14:43 = 883)
✨ Tipps & Best Practices
-
🧪 Beginnen Sie mit Tests im Swagger Editor oder Postman
-
🔄 Aktualisieren Sie KPI-Werte regelmäßig für konsistente Auswertungen
-
🧾 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).
Wie übergebe ich Uhrzeit-basierte KPI-Werte?
👉 Bei KPIs mit der Einheit "Uhrzeit" senden Sie die Minuten seit 00:00 Uhr als Ganzzahl. Beispiel: 14:43 Uhr = 883.