Customers-API

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

Geschrieben von Erdinc Akay

Zuletzt aktualisiert Vor 26 Tagen

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`. 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.

Tag-Validierung

Wenn tags gesendet wird, entfernt octoja zunächst leere bzw. 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.

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..." }    ]  }}

Einen Kunden löschen

Gibt 400 Bad Request zurück, wenn dem Kunden noch Agenten zugewiesen sind — unabhängig davon, ob der Agent online, offline oder anderweitig inaktiv 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