Kundendaten zur Buchung hinzufügen (Geschützte API)

POST


																https://…/office/api/persistCustomerData

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 schließt eine Buchung ab, deren Uhrzeit zuvor über Buchung starten reserviert wurde. Sie ist das Gegenstück zur Public-API-Schnittstelle Kundendaten zur Buchung hinzufügen, läuft aber im Office-Kontext und benötigt deshalb einen API-Token. Zusätzlich lässt sich dabei ein bestehender Kunde des Accounts mit dem Termin verknüpfen und ein Kundenstatus setzen.

Ablauf

Uhrzeit über Buchung starten reservieren. Die Antwort liefert appointmentId und appointmentParticipantId.
Buchung mit dieser Schnittstelle abschließen.
Ergebnis über Termine für einen Kunden abfragen kontrollieren.

Alle Werte werden als Formular-Parameter im Body oder als URL-Parameter übergeben.

Bestehenden Kunden verknüpfen

Ohne customerId gelten dieselben Felder wie bei der Public-API-Variante, und es findet ein Dubletten-Abgleich statt: Stimmen Name, Vorname, E-Mail-Adresse und Mobilnummer mit einem bestehenden Kunden überein, wird der Termin diesem Kunden zugeordnet.

Mit customerId benennen Sie den Kunden selbst – die Kundennummer liefern Kundenabfrage und Kundensuche nach Mobilnummer. Der bei der Reservierung angelegte Kundenentwurf wird dann verworfen und die Stammdaten werden aus dem bestehenden Kunden übernommen; firstName, name, email, mobile, phone und genderType aus dem Aufruf werden ignoriert. Geprüft werden nur noch privacy, terms und minAge. Der Dubletten-Abgleich entfällt, weil der Kunde bereits eindeutig benannt ist.

Kundenstatus setzen

Über customerStatus geben Sie den Namen eines Kundenstatus des Accounts an, zum Beispiel Stammkunde. Der Status wird erst nach der erfolgreichen Buchung gesetzt – so landet er in jedem Fall bei dem Kunden, dem der Termin am Ende gehört, auch dann, wenn dieser erst durch den Dubletten-Abgleich bestimmt wurde. Die Änderung erscheint mit der Kategorie „API“ in der Kundenhistorie. Ist der Name unbekannt, antwortet die Schnittstelle mit 400 und der Liste der verfügbaren Namen; gespeichert wird dann nichts.

Beispielaufruf

Neuen Kunden anlegen:

curl -s -X POST 'https://demo.belbo.com/office/api/persistCustomerData' 
  --data-urlencode 'token=IHR_TOKEN' 
  --data-urlencode 'appointmentId=1f562b4c3e681501ad04deeecd414c25' 
  --data-urlencode 'appointmentParticipantId=9a1c4f0b7d2e8a6350c1bb94ef2277ad' 
  --data-urlencode 'genderType=FEMALE' 
  --data-urlencode 'firstName=Petra' 
  --data-urlencode 'name=Lustig' 
  --data-urlencode 'email=ihre-adresse@example.com' 
  --data-urlencode 'mobile=0123456789' 
  --data-urlencode 'privacy=true' --data-urlencode 'terms=true' --data-urlencode 'minAge=true'

Bestehenden Kunden verknüpfen und Kundenstatus setzen:

curl -s -X POST 'https://demo.belbo.com/office/api/persistCustomerData' 
  --data-urlencode 'token=IHR_TOKEN' 
  --data-urlencode 'appointmentId=1f562b4c3e681501ad04deeecd414c25' 
  --data-urlencode 'appointmentParticipantId=9a1c4f0b7d2e8a6350c1bb94ef2277ad' 
  --data-urlencode 'customerId=38172646' 
  --data-urlencode 'customerStatus=Stammkunde' 
  --data-urlencode 'privacy=true' --data-urlencode 'terms=true' --data-urlencode 'minAge=true'

Antwort

Bei Erfolg antwortet die Schnittstelle mit 200 OK und dem Feld result. Steht dort OK, ist die Buchung abgeschlossen; action: requirePayment oder action: requireTAN bedeuten, dass der Kunde die genannte Seite noch aufrufen bzw. die Buchung per SMS-TAN bestätigen muss. Auch INVALID und ERROR werden mit 200 ausgeliefert – werten Sie deshalb immer result aus und verlassen Sie sich nicht allein auf den HTTP-Status.

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`	`missing appointmentId`	`appointmentId` wurde nicht übergeben.
`400`	`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; gespeichert wird nichts.
`404`	`appointment not found`	Zu dieser `appointmentId` gibt es keinen Termin, oder der Termin gehört nicht zum Account des Tokens.
`404`	`customer not found`	Zu dieser `customerId` gibt es keinen Kunden, oder der Kunde gehört nicht zum Account des Tokens.

Parameter

Name	Übergabe
`token`	Body Pflicht
Beispiel`IHR_TOKEN` API-Schlüssel des Zugangs. Er entscheidet zugleich, welcher Standort erreichbar ist.
`appointmentId`	Body Pflicht
Beispiel`1f562b4c3e681501ad04deeecd414c25` Verschleierte Termin-ID aus der Antwort von "Buchung starten".
`appointmentParticipantId`	Body
Beispiel`9a1c4f0b7d2e8a6350c1bb94ef2277ad` Verschleierte Teilnehmer-ID aus der Antwort von "Buchung starten". Sie wird in der zurückgegebenen Ergebnis-URL wieder ausgegeben.
`customerId`	Body Optional
Beispiel`38172646` Kundennummer eines bestehenden Kunden des Accounts. Ist sie gesetzt, wird dieser Kunde mit dem Termin verknüpft und der bei der Reservierung angelegte Kundenentwurf verworfen.
`customerStatus`	Body Optional
Beispiel`Stammkunde` Name eines Kundenstatus des Accounts, genau so geschrieben wie in den Einstellungen. Der Status wird nach erfolgreicher Buchung auf den Kunden gesetzt und mit der Kategorie "API" in der Kundenhistorie vermerkt.
`genderType`	Body
Beispiel`FEMALE` Nur ohne customerId. Anrede bzw. Geschlecht des Kunden. Zulässige Werte: MALE, FEMALE, DIVERSE, UNKNOWN, KID.
`firstName`	Body
Beispiel`Petra` Nur ohne customerId. Vorname des Kunden.
`name`	Body
Beispiel`Lustig` Nur ohne customerId. Nachname des Kunden.
`email`	Body
Beispiel`ihre-adresse@example.com` Nur ohne customerId. E-Mail-Adresse des Kunden.
`mobile`	Body
Beispiel`0123456789` Nur ohne customerId. Mobilnummer des Kunden.
`phone`	Body
Beispiel`030123456` Nur ohne customerId. Festnetznummer des Kunden.
`privacy`	Body Pflicht
Beispiel`true` Zustimmung zur Datenschutzerklärung. Fehlt sie, antwortet die Schnittstelle mit result: INVALID.
`terms`	Body Pflicht
Beispiel`true` Zustimmung zu den AGB.
`minAge`	Body Pflicht
Beispiel`true` Bestätigung des Mindestalters.
`rightOfWithdrawal`	Body
Beispiel`true` Zustimmung zum Widerrufsrecht.
`marketing`	Body Optional
Beispiel`true` Einwilligung des Kunden in Werbung.
`hasMarketingBox`	Body Optional
Beispiel`true` Gibt an, dass die Werbeeinwilligung im Buchungsformular überhaupt abgefragt wurde.
`appointmentParticipant.customerComment`	Body Optional
Beispiel`Bitte hinteren Parkplatz nutzen` Anmerkung des Kunden zum Termin.
`additionalFields.<keyName>`	Body Optional
Beispiel`additionalFields.other0.3130517799631012=123` Zusatzfelder des Kunden, adressiert über ihren keyName - das ist der Wert "key" aus der Kundenabfrage.

Struktur zuletzt mit der Postman-Collection abgeglichen: 22.09.2026

Beispielantworten

200 Buchung abgeschlossen

{
    "result": "OK",
    "customerId": 38172646,
    "url": "https://demo.belbo.com/buchung/finale/<appointmentId>/<appointmentParticipantId>"
}

200 Zahlung erforderlich

{
    "result": "OK",
    "action": "requirePayment",
    "url": "https://demo.belbo.com/bezahlen/<appointmentId>/<appointmentParticipantId>"
}

200 Bestätigung per SMS-TAN erforderlich

{
    "result": "OK",
    "action": "requireTAN"
}

200 Validierungsfehler

{
    "result": "INVALID",
    "errors": {}
}

200 Buchungsfehler

{
    "result": "ERROR",
    "reason": "appointmentInvalid"
}