Gebruiksscenario: Afspraak via de API boeken

Via de Public API kunt u een afspraak volledig vanuit uw eigen systeem triggeren – bijvoorbeeld vanuit uw eigen website, een app of een kiosk-terminal. Hiervoor zijn vijf aanroepen nodig die op elkaar voortbouwen: u vraagt eerst de beschikbare diensten op, bepaalt de geschikte medewerkers, reserveert een tijdslot, voegt de klantgegevens toe en voltooit de boeking.

De procedure in vijf stappen

1. 1
   Diensten opvragen
   U stuurt de ID van uw locatie (servicerGroupId) en ontvangt alle beschikbare diensten terug – gegroepeerd (groups) en individueel (services) met benaming, duur en prijs. Optioneel beperkt filter de selectie.
   Onthoud de id van elke gewenste dienst.

   Verzoek POST https://<UwBedrijf>.belbo.com/externalBooking/calcGroups servicerGroupId=16
2. 2
   Geschikte medewerkers bepalen
   Met de lijst van dienst-ID's (selectedProducts, door komma's gescheiden) vraagt u op welke medewerkers deze diensten kunnen uitvoeren. Het antwoord levert onder groupToServicers per positie de mogelijke medewerkers met naam en ID – als de beoordelingsmodule actief is, ook het gemiddelde beoordeling.
   Onthoud de id van de gewenste medewerker – of -1 voor „willekeurig".

   Verzoek POST https://<UwBedrijf>.belbo.com/externalBooking/calcServicers servicerGroupId=16&selectedProducts=180612
3. 3
   Boeking starten – Tijdslot reserveren
   Deze aanroep verwacht een JSON-body met datum, tijd, de gekozen diensten en de medewerker. Het boekt nog niet, maar reserveert het tijdslot. U ontvangt terug de twee sleutels die u voor de resterende stappen nodig hebt: appointmentId en appointmentParticipantId. Als de afspraak inmiddels is geboekt, antwoordt de interface met "result": "GIVEN".

   Verzoek (JSON-body, verkort) POST https://<UwBedrijf>.belbo.com/newAppointment/bookAppointmentAPI { "date": "15.07.2026", "time": "13:00", "selectedProducts": [180612], "servicerGroupId": 16, "bookingGroups": { "0": -1 }, "bookingSource": "Your API" }
4. 4
   Klantgegevens toevoegen
   U voegt nu de klantgegevens toe aan de gereserveerde boeking: naam, voornaam, aanhef, mobiel nummer en e-mailadres. De velden privacy, terms en webBooking bevestigen privacy en algemene voorwaarden – haal deze toestemming in uw eigen interface op, voordat u hier yes stuurt.

   Verzoek POST https://<UwBedrijf>.belbo.com/externalBooking/persistCustomerData appointmentId=…&firstName=Petra&name=Lustig&genderType=FEMALE &mobile=0123456789&email=petra@example.com&privacy=yes&terms=yes
5. 5
   Boeking afronden
   Alleen deze aanroep maakt van de reservering een vaste afspraak. Met "result": "OK" is de boeking in de kalender zichtbaar en stuurt Belbo bevestigingse-mails naar klant en bedrijf.

   Verzoek POST https://<UwBedrijf>.belbo.com/externalBooking/finalizeBooking appointmentId=…&appointmentParticipantId=…

Waar u op moet letten