Customers-API

Kunden auflisten, abrufen, erstellen, aktualisieren und löschen

Die Customers-API ermöglicht das Abfragen und Verwalten von Kunden-Datensätzen und ihren Standorten.

Die vollständige, stets aktuelle Liste der Endpoints, Parameter und Antwortfelder für die Version, die du betreibst, findest du in der interaktiven OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html.

Endpoints

Alle Anfragen müssen als angemeldeter Benutzer authentifiziert sein. Die erforderliche Berechtigung ist unten je Endpunkt angegeben; diese benutzerdefinierten Berechtigungsrichtlinien sind im Swagger-Schema nicht abgebildet.

Operation	Endpunkt	Hinweise
Auflisten	`GET /api/customers`	Authentifizierter Benutzer. Optionales `search` filtert nach Kundenname, externer Referenz oder Tag.
Abrufen	`GET /api/customers/{id}`	Authentifizierter Benutzer.
Erstellen	`POST /api/customers`	`customers.manage`, und der Aufrufer muss für alle Kunden (global) berechtigt sein — ein auf bestimmte Kunden eingeschränkter Benutzer erhält trotz der Berechtigung `403 Forbidden`. Erforderlich: `name`. `externalReference` ist optional (eigene PSA- oder Abrechnungsreferenz).
Aktualisieren	`POST /api/customers/{id}`	`customers.manage`. Verwendet den `UpdateValue<T>`-Envelope — siehe unten.
Löschen	`DELETE /api/customers/{id}`	`customers.manage`. Soft-Delete — siehe unten.

Einen Kunden aktualisieren

Aktualisierungen verwenden den UpdateValue<T>-Envelope. Jedes skalare Feld, das du ändern möchtest, muss als { "hasValue": true, "value": ... } verpackt werden. Lass das Feld weg (oder sende { "hasValue": false }), um es unverändert zu lassen. Bei nullbaren Feldern setzt du "value": null innerhalb des Envelopes, um den aktuellen Wert zu löschen.

Das Feld sites verwendet einen UpdateList<T>-Envelope — eine Liste von Hinzufügen-/Aktualisieren-/Entfernen-Operationen statt eines Ersatz-Arrays.

Beispiel-Body, der den Kunden umbenennt, die externe Referenz löscht und die Tag-Liste ersetzt:

{
  "newName":              { "hasValue": true, "value": "Acme GmbH" },
  "newExternalReference": { "hasValue": true, "value": null },
  "tags":                 { "hasValue": true, "value": ["vip", "managed"] }
}

Wichtige Felder (die vollständige Liste und die Typen stehen in Swagger):

newExternalReference, address und contact sind nullbar — sende "value": null innerhalb des Envelopes, um sie zu löschen.
tags ersetzt beim Senden die gesamte Liste; lass das Feld weg, um die Tags unverändert zu lassen. Siehe Tag-Validierung unten.
sites ist eine Operationsliste, kein Ersatz-Array. Siehe Standorte verwalten unten.
customFields ersetzt beim Senden die gesamte Feld-Map; lass das Feld weg, um die eigenen Felder unverändert zu lassen. Siehe Eigene Felder unten.

Tag-Validierung

Wenn tags gesendet wird, entfernt octoja zunächst leere und nur aus Leerzeichen bestehende Einträge und dedupliziert das Array. Anschließend validiert octoja das Ergebnis vor dem Speichern. Der Endpunkt gibt 400 Bad Request zurück, wenn mehr als 50 Tags verbleiben oder wenn ein einzelnes Tag 100 Zeichen überschreitet.

Der Endpunkt gibt 403 Forbidden zurück, wenn die Liste einen Tag-Wert einführt, der noch nicht im Kunden-Tag-Katalog steht, und dem Aufrufer die Berechtigung tags.create-custom fehlt. Für Tag-Werte, die bereits im Katalog stehen, ist keine zusätzliche Berechtigung nötig.

Standorte verwalten

Das Feld sites akzeptiert eine Liste von Operationen. Jeder Eintrag hat die Form { "op": "Add" | "Update" | "Remove", "id": <siteId oder null>, "values": { "name": { "hasValue": true, "value": "..." } } }. Die Eigenschaft name innerhalb von values ist selbst ein UpdateValue<string>-Envelope.

Add — erfordert values.name; id wird weggelassen oder ist null.
Update — erfordert id (die vorhandene siteId) und values.name; benennt den Standort um.
Remove — erfordert id; values kann weggelassen werden.

Beispiel-Body, der einen Standort hinzufügt, einen weiteren umbenennt und einen dritten entfernt:

{
  "sites": {
    "hasValue": true,
    "value": [
      { "op": "Add",    "values": { "name": { "hasValue": true, "value": "Standort Berlin" } } },
      { "op": "Update", "id": "1c2e...", "values": { "name": { "hasValue": true, "value": "Zentrale München" } } },
      { "op": "Remove", "id": "9af3..." }
    ]
  }
}

Eigene Felder

Das Feld customFields enthält die eigenen Felder, die in deinem Mandanten für Kunden definiert sind — als Map, deren Schlüssel jeweils der key der Definition ist. Verpacke die Map wie jedes andere Feld in einen UpdateValue-Envelope.

octoja prüft jeden Wert gegen seine Definition und gibt 400 Bad Request zurück, wenn ein Wert nicht zum Typ der Definition passt, die Längenbegrenzung eines Feldes vom Typ Text oder Mehrzeiliger Text überschreitet oder keiner Option einer Auswahlliste entspricht. Schlüssel ohne passende Definition werden ignoriert. Sende einen Schlüssel als null oder als leere Zeichenkette, um den Wert dieses Feldes zu löschen.

Die gesendete Map ersetzt die gespeicherte Map — nimm also jedes Feld auf, das erhalten bleiben soll:

{
  "customFields": {
    "hasValue": true,
    "value": {
      "contract-tier": "Gold",
      "renewal-date":  "2027-01-31",
      "seats":         250
    }
  }
}

Kunden, die über POST /api/customers angelegt werden, starten mit den Standardwerten aus deinen Definitionen für eigene Kundenfelder.

Einen Kunden löschen

Gibt 400 Bad Request zurück, wenn dem Kunden noch Geräte zugewiesen sind — unabhängig davon, ob das Gerät online, offline oder anderweitig inaktiv ist, und unabhängig davon, ob darauf ein Agent läuft oder ob es ein agentloses Netzwerkgerät wie ein Switch, eine Firewall oder ein NAS ist. Weise diese Geräte zuerst neu zu oder entferne sie.

Das Löschen eines Kunden ist ein Soft-Delete. Der Kunde wird als gelöscht markiert und erscheint nicht mehr in normalen API-Ergebnissen. Zugehörige Datensätze bleiben erhalten.

Customer-Objekt