Anwendungsfall: Termin über die API buchen

Über die Public API können Sie eine Terminbuchung vollständig aus Ihrem eigenen System heraus auslösen – etwa aus einer eigenen Website, einer App oder einem Kiosk-Terminal. Dafür sind fünf Aufrufe nötig, die aufeinander aufbauen: Sie fragen zuerst die buchbaren Leistungen ab, ermitteln die passenden Mitarbeiter, reservieren einen Zeitraum, hängen die Kundendaten an und schließen die Buchung ab.

Auswählen Leistungen und Mitarbeiter abfragen (Schritt 1–2).

Reservieren Zeitraum vorläufig blockieren (Schritt 3).

Abschließen Kundendaten anhängen und buchen (Schritt 4–5).

Alle fünf Schnittstellen gehören zur Public API und benötigen keinen API-Schlüssel. Ersetzen Sie in den Beispielen <IhrGeschäft> durch Ihren eigenen Kalender-Namen. Eine Übersicht aller Schnittstellen finden Sie in der API-Referenz.

Der Ablauf in fünf Schritten

1
Leistungen abfragen
Sie senden die ID Ihres Standorts (servicerGroupId) und erhalten alle buchbaren Leistungen zurück – gruppiert (groups) und einzeln (services) mit Bezeichnung, Dauer und Preis. Optional grenzt filter die Auswahl ein.
Merken Sie sich die id jeder gewünschten Leistung.
Anfrage POST https://<IhrGeschäft>.belbo.com/externalBooking/calcGroups servicerGroupId=16
2
Passende Mitarbeiter ermitteln
Mit der Liste der Leistungs-IDs (selectedProducts, kommasepariert) fragen Sie ab, welche Mitarbeiter diese Leistungen ausführen können. Die Antwort liefert unter groupToServicers je Position die möglichen Mitarbeiter samt Namen und ID – bei aktivem Bewertungsmodul zusätzlich den Bewertungsschnitt.
Merken Sie sich die id des gewünschten Mitarbeiters – oder -1 für „beliebig“.
Anfrage POST https://<IhrGeschäft>.belbo.com/externalBooking/calcServicers servicerGroupId=16&selectedProducts=180612
3
Buchung starten – Zeitraum reservieren
Dieser Aufruf erwartet einen JSON-Body mit Datum, Uhrzeit, den gewählten Leistungen und dem Mitarbeiter. Er bucht noch nicht, sondern reserviert den Zeitraum. Zurück kommen die beiden Schlüssel, die Sie für die restlichen Schritte brauchen: appointmentId und appointmentParticipantId. Ist der Termin inzwischen vergeben, antwortet die Schnittstelle mit "result": "GIVEN".
Anfrage (JSON-Body, gekürzt) POST https://<IhrGeschäft>.belbo.com/newAppointment/bookAppointmentAPI { "date": "15.07.2026", "time": "13:00", "selectedProducts": [180612], "servicerGroupId": 16, "bookingGroups": { "0": -1 }, "bookingSource": "Your API" }
4
Kundendaten hinzufügen
Zur reservierten Buchung hängen Sie nun die Kundendaten an: Name, Vorname, Anrede, Mobilnummer und E-Mail-Adresse. Die Felder privacy, terms und webBooking bestätigen Datenschutz und AGB – holen Sie diese Zustimmung in Ihrer eigenen Oberfläche ein, bevor Sie hier yes senden.
Anfrage POST https://<IhrGeschäft>.belbo.com/externalBooking/persistCustomerData appointmentId=…&firstName=Petra&name=Lustig&genderType=FEMALE &mobile=0123456789&email=petra@example.com&privacy=yes&terms=yes
5
Buchung abschließen
Erst dieser Aufruf macht aus der Reservierung einen festen Termin. Mit "result": "OK" ist die Buchung im Kalender sichtbar, und Belbo verschickt die Bestätigungs-E-Mails an Kunde und Geschäft.
Anfrage POST https://<IhrGeschäft>.belbo.com/externalBooking/finalizeBooking appointmentId=…&appointmentParticipantId=…

Worauf Sie achten sollten

Woher kommt die Uhrzeit?

Schritt 3 braucht Datum und Uhrzeit. Welche Zeiten überhaupt frei sind, liefert die Schnittstelle Verfügbare Termine – mit denselben Angaben zu Standort, Leistungen und Mitarbeiter.

Zwei Schlüssel mitführen

Alles nach Schritt 3 hängt an appointmentId und appointmentParticipantId. Halten Sie beide bis zum Abschluss in Ihrer Sitzung vor.

Reservierung ist keine Buchung

Brechen Sie zwischen Schritt 3 und 5 ab, bleibt nur eine unvollständige Reservierung zurück – der Termin ist nicht gebucht und es wird keine E-Mail versendet.

Alle Felder im Detail Parameter, Beispielantworten und weitere Schnittstellen finden Sie in der API-Referenz.

Zur API-Referenz