Kundendaten ändern | Handleiding

POST


																https://…/office/api/updateCustomer

Diese Schnittstelle gehört zur Geschützten API und benötigt einen API-Schlüssel. Den Token erstellen Sie in Ihrem Kalender unter den globalen Einstellungen als API Zugang – siehe API-Schnittstellen.

Diese Schnittstelle ändert bei einem bestehenden Kunden die interne Notiz, die Zusatzfelder und/oder den Kundenstatus. Die Stammdaten – Name, E-Mail-Adresse, Telefonnummern und Anrede – werden hier nicht geändert. Welche Werte ein Kunde derzeit hat und wie seine Zusatzfelder heißen, liefert die Kundenabfrage.

Mindestens eines der drei Felder note, additionalFields und customerStatus muss übergeben werden. Weggelassen heißt unverändert, leer heißt löschen.

Übergabe der Werte

Der Kunde wird über die URL angesprochen – token und id sind immer URL-Parameter. Die Änderungen selbst schicken Sie entweder als JSON-Body mit dem Header Content-Type: application/json oder als Formular- bzw. URL-Parameter:

{
  "note": "Bevorzugt Termine vormittags",
  "customerStatus": "Stammkunde",
  "additionalFields": {
    "allergien": "keine"
  }
}

Zusatzfelder

Zusatzfelder werden über ihren keyName adressiert – das ist der Wert key in der Antwort der Kundenabfrage. Im JSON-Body sind beide Schreibweisen zulässig: als Objekt {"keyName":"Wert"} oder als Liste [{"key":"keyName","value":"Wert","header":"optional"}]. Als Parameter lautet die Schreibweise additionalFields.keyName=Wert; der keyName darf dabei Punkte enthalten, zum Beispiel additionalFields.other0.3130517799631012=123.

Nicht unterstützt sind Zusatzfelder mit Binärinhalt, also die Typen image, multipleImages, document, multipleDocuments und pictureMarking.

Kundenstatus

Über customerStatus geben Sie den Namen eines Kundenstatus des Accounts an, genau so geschrieben wie in den Einstellungen. Der Wechsel wird mit der Kategorie „API“ in der Kundenhistorie protokolliert. Soll der Status im Zuge einer Buchung gesetzt werden, geht das direkt beim Abschluss der Buchung über Kundendaten zur Buchung hinzufügen (Geschützte API); ein zusätzlicher Aufruf dieser Schnittstelle ist dafür nicht nötig.

Beispielaufruf

Als JSON-Body:

curl -s -X POST 'https://demo.belbo.com/office/api/updateCustomer?token=IHR_TOKEN&id=38172646' 
  -H 'Content-Type: application/json' 
  -d '{"customerStatus":"Stammkunde","note":"Bevorzugt Termine vormittags","additionalFields":{"allergien":"keine"}}'

Als Formular-Parameter:

curl -s -X POST 'https://demo.belbo.com/office/api/updateCustomer' 
  --data-urlencode 'token=IHR_TOKEN' --data-urlencode 'id=38172646' 
  --data-urlencode 'customerStatus=Stammkunde' 
  --data-urlencode 'additionalFields.other0.3130517799631012=123'

Antwort

Bei Erfolg antwortet die Schnittstelle mit 200 OK und dem Kundenobjekt wie bei der Kundenabfrage, ergänzt um drei Felder: note enthält die interne Notiz nach der Änderung, customerStatus den Namen des aktuellen Kundenstatus und changes die Liste der tatsächlich vorgenommenen Änderungen, je Eintrag mit name, originalValue und newValue.

Fehlerfälle

Status	Meldung	Ursache
`200`	`Access denied`	Der Token fehlt, ist ungültig oder abgelaufen. Die Antwort ist reiner Text, kein JSON – so antworten alle Endpunkte der Geschützten API.
`400`	`nothing to update: give note, additionalFields and/or customerStatus`	Es wurde keines der drei änderbaren Felder übergeben.
	`invalid additionalFields`	Mindestens ein keyName gehört zu keinem Zusatzfeld des Accounts (`unknownKeys`) oder zu einem Feld mit Binärinhalt (`unsupportedKeys`). `availableKeys` nennt die zulässigen Schlüssel; gespeichert wird nichts.
	erklärende Meldung in `error`	`additionalFields` wurde in einem Format übergeben, das nicht gelesen werden kann.
	`customer status not found`	Der in `customerStatus` genannte Name gehört zu keinem Kundenstatus des Accounts. Die Antwort nennt in `availableStatuses` die verfügbaren Namen.
`404`	`customer not found`	Zu dieser `id` gibt es keinen Kunden, der Kunde gehört nicht zum Account des Tokens, oder er ist gelöscht.

Eine Änderung schlägt entweder vollständig an oder gar nicht: Bei unbekannten oder nicht unterstützten Zusatzfeldern und bei einem unbekannten Kundenstatus wird keines der übergebenen Felder gespeichert.

Parameter

Name	Übergabe
`token`	URL-Parameter Pflicht
Beispiel`IHR_TOKEN` API-Schlüssel des Zugangs. Er entscheidet zugleich, welcher Standort erreichbar ist: Der Kunde muss zu diesem Standort gehören.
`id`	URL-Parameter Pflicht
Beispiel`38172646` Kundennummer des zu ändernden Kunden.
`note`	Body Optional
Beispiel`Bevorzugt Termine vormittags` Interne Notiz zum Kunden. Ein leerer String löscht die Notiz, ein weggelassenes Feld lässt sie unverändert.
`additionalFields`	Body Optional
Beispiel`{"allergien":"keine"}` Zusatzfelder des Kunden, adressiert über ihren keyName. Im JSON-Body entweder als Objekt oder als Liste, als Parameter in der Form additionalFields.keyName=Wert. Ein leerer Wert löscht den Feldwert.
`customerStatus`	Body Optional
Beispiel`Stammkunde` Name eines Kundenstatus des Accounts, genau so geschrieben wie in den Einstellungen. Ein weggelassenes Feld lässt den Status unverändert.

Struktur zuletzt mit der Postman-Collection abgeglichen: 22.09.2026