Guide de l’API de réservation

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

1. Créez des identifiants API dans Paramètres → Clients API.
2. Demandez un token depuis /oauth/token avec les identifiants client.
3. 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 - Reprogrammez un rendez-vous existant via booking_id.
• POST /api/v1/appointments/cancel - Annulez un rendez-vous existant via booking_id.

Réservations de rendez-vous (prestations à prix ferme). Un hold ou un rendez-vous créé via cette interface pour une prestation ou une ressource à prix ferme constitue une réservation de rendez-vous au sens des Conditions générales (partie C, clause 13, § 2), et non un contrat portant sur la prestation. La réponse de hold et la réponse de réservation contiennent alors kind: "reservation", contract: "on_site", le prix dans price_cents, avec price_label, dont le texte est exactement « Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt » (prix de l’organisation, payable sur place ; le prix et le contrat sont convenus sur place), ainsi que notice, avec ce texte fixe : « Terminreservierung: Mit dieser Reservierung ist noch kein Vertrag über die Leistung geschlossen. Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt. » (En français : « Réservation de rendez-vous : aucun contrat portant sur la prestation n’est encore conclu par cette réservation. Prix de l’organisation, payable sur place ; le prix et le contrat sont convenus sur place. ») Votre interface doit afficher cette mention au client final, au plus tard en même temps que le résultat de la réservation ; cette obligation vous incombe au titre de la partie B, clause 8, § 5, point c), des Conditions générales. La réponse de hold la contient afin qu’elle puisse être affichée avant que le client final n’envoie la réservation ; toute version dans une autre langue doit être complète et fidèle. Par cette interface, Zimun ne recueille ni ne documente aucun consentement du client final à ses propres conditions, n’accepte ni paiement en ligne ni carte de paiement, et envoie à l’adresse e-mail transmise avec la réservation un avis de réservation, et non une confirmation de réservation.

Séquence recommandée

1. Listez les établissements si l’organisation peut réserver dans plus d’un lieu.
2. Laissez l’utilisateur choisir un établissement lorsque c’est nécessaire.
3. Listez les services et ne gardez que ceux qui couvrent cet établissement.
4. Récupérez les disponibilités avec service_id, date et location_id lorsque nécessaire.
5. Créez le hold avec la même location_id.
6. Confirmez la réservation avec les coordonnées.
7. Conservez la booking_id afin de pouvoir reprogrammer 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.