Labels

Labels sind frei benannte Kennzeichen Ihres Partnerzugangs, mit denen Sie Anlagen markieren – etwa „Wartungsvertrag“, „VIP“ oder „Migration 2027“. Die Anlagenliste der Konsole zeigt sie in der Spalte Labels als farbige Badges. Mit dieser Schnittstelle legen Ihre eigenen Werkzeuge Labels an, vergeben sie und lesen sie wieder aus. Diese Seite ist die Referenz für Integratoren und für alle, die einen KI-Assistenten an den Controller anbinden.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Erweiterungen erfolgen additiv: neue Felder und neue Werte kommen hinzu, bestehende bleiben.

Grundlagen

• Basis-URL: https://cmp.sf-app.de/api/v1. Betreiben Sie den Controller selbst, setzen Sie Ihren eigenen Host ein.

• Authentifizierung: ein Konto des Controllers, für Skripte per HTTP Basic mit E-Mail-Adresse und Passwort eines lokalen Kontos – wie unter Aufmerksamkeit beschrieben.

• Je Partnerzugang: Labels gehören Ihrem Partnerzugang. Betreuen mehrere Partner dieselbe Anlage, sieht jeder nur seine eigenen Labels.

• Rollen:

  Aktion	Erlaubt für
  Labels lesen	alle Rollen
  Labels anlegen, ändern, löschen	Inhaber, Administratoren
  Labels an Anlagen vergeben und entfernen	Inhaber, Administratoren, Techniker

• Format: JSON, UTF-8.

Das Objekt „Label“

Feld	Typ	Beschreibung
id	String (UUID)	Kennung des Labels.
name	String	1 bis 40 Zeichen, ohne führende oder folgende Leerzeichen. Eindeutig im Partnerzugang, ohne Rücksicht auf Groß- und Kleinschreibung.
color	String oder null	Farbe als #rrggbb (klein geschrieben gespeichert). null zeigt die Konsole als neutrales Badge.
sites	Integer	Nur in der Liste: Zahl der sichtbaren Anlagen mit diesem Label.

Labels lesen

GET /api/v1/labels

Antwort 200

[
  {"id": "b6f0a3c1-2d4e-4f6a-9b8c-0d1e2f3a4b5c", "name": "VIP", "color": "#ffd400", "sites": 4},
  {"id": "0c9e8d7f-6a5b-4c3d-2e1f-0a9b8c7d6e5f", "name": "Wartungsvertrag", "color": "#0f7b3f", "sites": 37}
]

Die Labels einer Anlage stehen in der Anlagenliste GET /api/v1/sites im Feld labels jeder Anlage (id, name, color), nach Namen sortiert; eine Anlage ohne Label hat eine leere Liste.

Alle Anlagen mit Wartungsvertrag

curl -s -u "technik@partner.de:••••••" https://cmp.sf-app.de/api/v1/sites \
  | jq '[.[] | select(any(.labels[]?; .name == "Wartungsvertrag")) | .displayName]'

Label anlegen

POST /api/v1/labels
Content-Type: application/json

Body

{"name": "Wartungsvertrag", "color": "#0F7B3F"}

Die Antwort ist das angelegte Label mit sites = 0. color ist optional.

Label ändern

PATCH /api/v1/labels/{labelId}
Content-Type: application/json

Feld	Wirkung
name	Neuer Name. Fehlt das Feld, bleibt der Name.
color	Neue Farbe. Fehlt das Feld, bleibt die Farbe; ein leerer Wert "" entfernt sie.

Die Änderung gilt sofort an allen Anlagen mit diesem Label.

Label löschen

DELETE /api/v1/labels/{labelId}

Antwort 204. Das Label wird dabei von allen Anlagen entfernt.

Labels vergeben und entfernen

PUT /api/v1/labels/assignments
Content-Type: application/json

Feld	Pflicht	Beschreibung
siteIds	ja	Kennungen der Anlagen.
add	nein	Labels (Kennung oder Name), die alle genannten Anlagen erhalten.
remove	nein	Labels (Kennung oder Name), die von allen genannten Anlagen entfernt werden.

Zwei Anlagen als Wartungsvertrag markieren

curl -s -u "technik@partner.de:••••••" -X PUT -H "Content-Type: application/json" \
  -d '{"siteIds": ["1458d78f-6e4c-4cf2-b524-888b0c3caddf", "5b0c…"], "add": ["Wartungsvertrag"]}' \
  https://cmp.sf-app.de/api/v1/labels/assignments

Antwort 200

{"added": 2, "removed": 0}

Der Aufruf ist idempotent: Ein Label, das eine Anlage schon trägt, wird nicht doppelt gezählt; ein Label, das sie nicht trägt, wird beim Entfernen übersprungen. Alle Änderungen eines Aufrufs gelten gemeinsam oder gar nicht.

Anwendungsbeispiel

Ihr CRM führt die Wartungsverträge. Bei jedem neuen oder gekündigten Vertrag ruft es den Endpunkt mit add bzw. remove auf. In der Konsole sehen Ihre Techniker damit auf einen Blick, welcher Kunde bevorzugt betreut wird.

Fehler

Fehlerantworten tragen error (Code) und message (deutscher Text).

Status	error	Bedeutung
400	label_invalid	Name fehlt, ist länger als 40 Zeichen oder schon vergeben, oder die Farbe ist nicht #rrggbb.
400	no_sites	siteIds fehlt oder ist leer.
401	–	Nicht angemeldet oder falsches Passwort.
403	forbidden	Die Rolle des Kontos erlaubt die Aktion nicht (siehe Grundlagen).
404	not_found	Label gibt es nicht in Ihrem Partnerzugang, oder eine Anlage ist für Sie nicht sichtbar. Nichts wurde geändert.

Für KI-Assistenten (MCP)

Werkzeug	Wirkung	Benötigte Stufe
fleet_labels	operation: list (alle Labels mit Anzahl), get (Labels der Anlagen in sites), create (name, color), update (label, name, color), delete (label), assign und unassign (labels, sites). Labels per Kennung oder Name, Anlagen per Kennung oder Serverlizenzschlüssel, alternativ selectionId aus der Konsole.	Lesen; schreibende Operationen mit mode=apply: Lesen + Schreiben
fleet_list_sites	Je Anlage labels; das Argument label zeigt nur Anlagen mit diesem Label (Name, ohne Rücksicht auf Groß- und Kleinschreibung).	Lesen

Schreibende Operationen laufen zuerst als Probelauf und nennen, was geschehen würde; erst mode=apply speichert. Die Rollen gelten wie bei der REST-Schnittstelle.

fleet_labels: Label vergeben

{
  "operation": "assign",
  "labels": ["Wartungsvertrag"],
  "sites": ["K8P3F-8GQBF-AT7FT-XK6ZV", "1458d78f-6e4c-4cf2-b524-888b0c3caddf"],
  "mode": "apply"
}

Antwort

{"unknown": [], "sites": 2, "change": "setzen: Wartungsvertrag", "added": 2, "removed": 0, "outcome": "ok"}

Anwendungsbeispiel

Sie fragen Ihren Assistenten: „Welche Anlagen mit Wartungsvertrag sind offline?“ Er ruft fleet_list_sites mit label=Wartungsvertrag auf und nennt die Anlagen, deren online falsch ist.

Grenzen

Grenze	Wert
Name eines Labels	40 Zeichen
Anlagen je MCP-Aufruf	100