Cas d’usage : Réserver un rendez-vous via l’API

Via l'API publique, vous pouvez déclencher une réservation de rendez-vous entièrement depuis votre propre système – par exemple à partir de votre propre site web, d'une application ou d'une borne de kiosque. Cela nécessite cinq appels qui s'appuient les uns sur les autres : vous commencez par interroger les services réservables, identifiez les employés appropriés, réservez une plage horaire, joignez les données clients et finalisez la réservation.

Sélectionner Interroger les services et les employés (étapes 1–2).

Réserver Bloquer provisoirement la plage horaire (étape 3).

Finaliser Joindre les données clients et réserver (étapes 4–5).

Les cinq interfaces font partie de l'API publique et ne nécessitent pas de clé API. Dans les exemples, remplacez <IhrGeschäft> par le nom de votre propre calendrier. Vous trouverez une vue d'ensemble de toutes les interfaces dans la référence API.

Le processus en cinq étapes

1
Interroger les services
Vous envoyez l'ID de votre site (servicerGroupId) et recevez tous les services réservables en retour – regroupés (groups) et individuels (services) avec désignation, durée et prix. Optionnellement, filter restreint la sélection.
Mémorisez l'id de chaque service souhaité.
Requête POST https://<IhrGeschäft>.belbo.com/externalBooking/calcGroups servicerGroupId=16
2
Identifier les employés appropriés
Avec la liste des IDs de service (selectedProducts, séparés par des virgules), vous interrogez quels employés peuvent exécuter ces services. La réponse fournit sous groupToServicers pour chaque position les employés possibles avec nom et ID – si le module d'évaluation est activé, également la moyenne des évaluations.
Mémorisez l'id de l'employé souhaité – ou -1 pour « n'importe lequel ».
Requête POST https://<IhrGeschäft>.belbo.com/externalBooking/calcServicers servicerGroupId=16&selectedProducts=180612
3
Démarrer la réservation – Réserver la plage horaire
Cet appel s'attend à un corps JSON avec date, heure, services choisis et employé. Il ne réserve pas encore, mais réserve la plage horaire. En retour, vous obtenez les deux clés dont vous avez besoin pour les étapes restantes : appointmentId et appointmentParticipantId. Si le rendez-vous a entre-temps été pris, l'interface répond avec "result": "GIVEN".
Requête (corps JSON, abrégé) 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
Ajouter les données clients
Vous joignez maintenant les données clients à la réservation : nom, prénom, titre de civilité, numéro mobile et adresse e-mail. Les champs privacy, terms et webBooking confirment la protection des données et les CGV – obtenez ces consentements dans votre propre interface avant d'envoyer yes ici.
Requête 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
Finaliser la réservation
Cet appel seul transforme la réservation en rendez-vous définitif. Avec "result": "OK", la réservation est visible dans le calendrier, et Belbo envoie les e-mails de confirmation au client et à l'entreprise.
Requête POST https://<IhrGeschäft>.belbo.com/externalBooking/finalizeBooking appointmentId=…&appointmentParticipantId=…

Ce à quoi vous devez faire attention

D'où vient l'heure ?

L'étape 3 a besoin de date et heure. Quels créneaux sont réellement libres est fourni par l'interface Rendez-vous disponibles – avec les mêmes indications sur site, services et employé.

Transporter deux clés

Tout après l'étape 3 dépend de appointmentId et appointmentParticipantId. Conservez les deux jusqu'à la finalisation dans votre session.

La réservation n'est pas une réservation définitive

Si vous abandonnez entre l'étape 3 et 5, il ne reste qu'une réservation incomplète – le rendez-vous n'est pas réservé et aucun e-mail n'est envoyé.

Tous les champs en détail Paramètres, exemples de réponses et autres interfaces se trouvent dans la référence API.

Vers la référence API