Zimun: Appointment Scheduling & Booking Service: 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 lister les services, lire la disponibilité et finaliser le flux 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/services - Listez les services de votre organisation.
• GET /api/v1/availability - Lisez les créneaux disponibles par service et par date.
• POST /api/v1/appointments/hold - Créez un hold temporaire avant confirmation.
• POST /api/v1/appointments/confirm - Confirmez un hold et créez le rendez-vous.
• POST /api/v1/appointments/reschedule - Replanifiez un rendez-vous existant par rendez-vous_id.
• POST /api/v1/appointments/cancel - Annulez un rendez-vous existant par rendez-vous_id.

Séquence recommandée

1. Listez les services et laissez l'utilisateur en choisir un.
2. Récupérez la disponibilité pour le service choisi.
3. Créez un hold pour le créneau sélectionné.
4. Confirmez la réservation avec les coordonnées.
5. Si nécessaire, reprogrammez ou annulez plus tard en utilisant le rendez-vous_id de votre état d'intégration.

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.