La Booking API est disponible dès maintenant pour les workflows publics de planification.
Ce que couvre ce guide
- Comment s’authentifier et appeler les endpoints de réservation en sécurité.
- Comment découvrir les établissements, lister les services, lire les disponibilités et terminer le parcours de réservation.
- Quand utiliser Booking API directement vs l’intégration MCP.
API de réservation vs MCP
- Utilisez Booking API lorsque vous construisez votre propre intégration backend/client et souhaitez un contrôle HTTP direct.
- Utilisez MCP lorsque votre client est natif MCP et doit appeler des outils comme list_services et get_availability.
- Les deux approches reposent sur la même logique de réservation et les mêmes contrôles de conflit.
Si vous souhaitez un flux conversationnel prêt à être intégré pour la réservation des clients, consultez Agent de chat de réservation.
Authentification
- Créez des identifiants API dans Paramètres → Clients API.
- Demandez un token depuis /oauth/token avec les identifiants client.
- Appelez Booking API avec Authorization: Bearer <token>.
Scopes utilisés par les workflows de réservation : org:read, availability:read, appointments:write.
Carte des endpoints
GET /api/v1/locations- Listez les établissements de réservation actifs de votre organisation.GET /api/v1/services- Listez les services de votre organisation, y compris les location_ids.GET /api/v1/availability- Lisez les créneaux disponibles par service et par date, avec location_id lorsque nécessaire.POST /api/v1/appointments/hold- Créez un hold temporaire avant la confirmation en utilisant la même location_id lorsque c’est nécessaire.POST /api/v1/appointments/confirm- Confirmez un hold et créez le rendez-vous.POST /api/v1/appointments/reschedule- Replanifiez un rendez-vous existant via booking_id.POST /api/v1/appointments/cancel- Annulez un rendez-vous existant via booking_id.
Séquence recommandée
- Listez les établissements si l’organisation peut réserver dans plus d’un lieu.
- Laissez l’utilisateur choisir un établissement lorsque c’est nécessaire.
- Listez les services et ne gardez que ceux qui couvrent cet établissement.
- Récupérez les disponibilités avec service_id, date et location_id lorsque nécessaire.
- Créez le hold avec la même location_id.
- Confirmez la réservation avec les coordonnées.
- Conservez la booking_id afin de pouvoir replanifier ou annuler plus tard.
Notes de fiabilité
- Utilisez l’idempotence pour les appels create/confirm afin d’éviter les doublons lors des retries.
- Traitez les holds comme temporaires et confirmez rapidement.
- Gérez explicitement les réponses 401/403/404 et conflits dans l’UX client.
Note de périmètre
Les API publiques actuelles se concentrent sur les opérations de réservation. Les API de gestion sont prévues dans une phase ultérieure.