Was ist eine UUID und wo finde ich sie?

Gilt für: Benutzer mit Zugangsdaten für die REST API · Modul: Integrationen & API

Eine UUID (Universally Unique Identifier) ist eine 36-stellige Kennung, mit der ValueStreamer jedes Objekt eindeutig identifiziert: Benutzer, Teams, Kennzahlen, Subkacheln, Listen, Listeneinträge, Abweichungen und Maßnahmen. Die UUID entsteht beim Anlegen des Objekts, bleibt danach unverändert und lässt sich nicht bearbeiten. In der REST API setzen Sie UUIDs als Pfadparameter ein, etwa in /exchange/list/{list-id}/{team-id}. Die passende UUID rufen Sie vorher über den jeweiligen Meta-Endpunkt ab.

Voraussetzungen

Zugangsdaten für die REST API Ihrer ValueStreamer-Instanz. Alle Aufrufe erfordern HTTP Basic Auth, siehe API-Authentifizierung & Fehlercodes.
Basis-URL Ihrer Instanz: https://api-<tenant>.valuestreamer.de/api/. Alle Pfade in diesem Artikel sind relativ dazu.

So ist eine UUID aufgebaut

32 hexadezimale Zeichen in fünf Gruppen, getrennt durch vier Bindestriche im Muster 8-4-4-4-12:

4f8a2c71-93be-4b0d-a1e6-7c2d5e9f3b48

Der Wert ist zufällig vergeben und trägt keine Bedeutung. Aus einer UUID lässt sich weder ablesen, um welches Objekt es sich handelt, noch wann es angelegt wurde. Eine UUID lässt sich auch nicht hochzählen oder aus einem Namen ableiten. Sie müssen sie abrufen und unverändert übernehmen.

ℹ️ Hinweis: UUIDs sind kein Zugangsschlüssel. Ohne gültige Anmeldedaten führt eine bekannte UUID zu keinem Zugriff.

Welcher Endpunkt liefert welche UUID

Objekt	Endpunkt, der die UUID liefert	Eingesetzt als
Benutzer	`GET /exchange/users`	Benutzerbezug in weiteren Aufrufen
Team	`GET /exchange/teams`	`{team-id}`
Übergeordnetes Team	`GET /exchange/teams` (Feld `parentTeam`)	Kaskadenstruktur auswerten
Kennzahl	`GET /exchange/kpi`	`{kpi-id}`
Subkachel und Kennzahlenwert	`GET /exchange/kpi/{kpi-id}`	`{sub-tile-id}`, `kpiValueId`
Liste	`GET /exchange/list/meta`	`{list-id}`
Felder einer Liste	`GET /exchange/list/meta/{list-id}`	Feldnamen und Feldtypen prüfen
Listeneintrag	`GET /exchange/list/{list-id}/{team-id}`	`{entry-id}`
Abweichung	`GET /exchange/deviations?team={team-id}`	`{id}` in `/exchange/deviations/{id}`
Abweichungskategorie	`GET /exchange/deviation-categories`	Kategorie beim Anlegen einer Abweichung

Die Endpunkte für Benutzer und Teams sind ausführlich beschrieben in User- & Team-IDs abrufen.

✨ Tipp: Legen Sie die UUIDs, die Ihre Integration dauerhaft braucht, einmalig in der Konfiguration Ihres Skripts oder Ihrer Middleware ab, statt sie bei jedem Lauf erneut abzufragen. Da sie sich nicht ändern, bleiben sie gültig, solange das Objekt existiert.

So sieht der Ablauf im Aufruf aus

Zuerst die Team-UUID abrufen:

GET https://api-<tenant>.valuestreamer.de/api/exchange/teams

Dann die zurückgegebene UUID im Zielaufruf einsetzen:

GET https://api-<tenant>.valuestreamer.de/api/exchange/list/     9c1f7a30-5d42-4e18-b7c9-2a6e8d4f1b03/4f8a2c71-93be-4b0d-a1e6-7c2d5e9f3b48

Die erste UUID ist die Liste, die zweite das Team. Die Reihenfolge der Pfadparameter ist verbindlich.

⚠️ Achtung: Prüfen Sie die Reihenfolge, bevor Sie schreibende Aufrufe absetzen. Zwei vertauschte UUIDs sind formal gültig und werden vom Format-Check nicht erkannt. Sie führen zu einem 404 oder schreiben im ungünstigen Fall in das falsche Objekt.

Wenn es nicht klappt

Symptom	Ursache	Lösung
`400 Bad Request`	UUID falsch formatiert, gekürzt, mit Leerzeichen oder Anführungszeichen übernommen	Wert unverändert aus der Antwort des Meta-Endpunkts übernehmen, Muster 8-4-4-4-12 prüfen
`404 Not found`	UUID existiert nicht, gehört zu einem anderen Objekttyp oder das Objekt wurde gelöscht	UUID über den Meta-Endpunkt erneut abfragen
`404 Not found` trotz korrekter UUIDs	Kombination passt nicht, etwa eine Liste, die dem angegebenen Team nicht zugeordnet ist	Zuordnung über `GET /exchange/list/meta` prüfen
Aufruf liefert leere Ergebnisliste	UUID verweist auf ein Objekt ohne Daten im abgefragten Zeitraum	Filterparameter prüfen, nicht die UUID

Bleibt der Aufruf nach Prüfung der UUIDs fehlerhaft, wenden Sie sich an den ValueStreamer Support und geben Sie den vollständigen Aufruf, die verwendeten UUIDs und den Antwortcode an.

Weiterführende Artikel

User- & Team-IDs abrufen: der nächste Schritt, wenn Sie konkret Benutzer- oder Team-UUIDs brauchen.
API-Authentifizierung & Fehlercodes: welche Anmeldedaten nötig sind und was die Antwortcodes bedeuten.
Architektur & Nutzung der REST API im ValueStreamer: Basis-URL, Aufbau der Endpunkte und Datenfluss im Überblick.
API-Dokumentationen & YAML-Dateien zum Download: vollständige Spezifikation je Modul als PDF und YAML.

Häufige Fragen

Ändert sich die UUID eines Objekts, wenn ich es umbenenne? Nein. Name, Kurzname und Zuordnung lassen sich ändern, die UUID bleibt unverändert. Sie ist der einzige Bezug, auf den sich eine Integration dauerhaft verlassen kann.

Kann ich eine UUID selbst vergeben oder ändern? Nein. ValueStreamer vergibt die UUID beim Anlegen des Objekts. Sie ist weder in der Oberfläche noch über die API editierbar.

Warum steht in manchen Beispielen /api/exchange/... und in anderen nur /exchange/...? Gemeint ist derselbe Endpunkt. /api/ ist Teil der Basis-URL https://api-<tenant>.valuestreamer.de/api/, die relativen Pfade beginnen danach mit /exchange/.

Bekomme ich nach dem Löschen eines Objekts dessen UUID erneut? Nein. Eine UUID wird nicht wiederverwendet. Aufrufe auf die UUID eines gelöschten Objekts beantwortet die API mit 404 Not found.