Zimun: Appointment Scheduling & Booking Service: Booking API Guide

Booking API доступний зараз для публічних процесів планування.

Що охоплює цей посібник

• Як безпечно автентифікуватися та викликати ендпойнти бронювання.
• Як знаходити локації, переглядати послуги, читати доступність і завершувати потік бронювання.
• Коли використовувати Booking API напряму, а коли — інтеграцію MCP.

Booking API проти MCP

• Використовуйте Booking API, коли створюєте власну інтеграцію бекенда/клієнта та потребуєте прямого контролю через HTTP.
• Використовуйте MCP, коли ваш клієнт нативно підтримує MCP і має викликати такі інструменти, як list_services та get_availability.
• Обидва шляхи побудовані навколо однакової логіки бронювання та перевірок конфліктів.

Якщо ви хочете готовий до вбудовування розмовний потік для клієнтського бронювання, перегляньте Чат-агент бронювання.

Автентифікація

1. Створіть API-облікові дані в Налаштуваннях → API-клієнти.
2. Запросіть токен у /oauth/token за допомогою облікових даних клієнта.
3. Викликайте Booking API із заголовком Authorization: Bearer <token>.

Області, що використовуються процесами бронювання: org:read, availability:read, appointments:write.

Карта ендпойнтів

• GET /api/v1/locations - Перелік активних локацій бронювання вашої організації.
• GET /api/v1/services - Перелічіть послуги вашої організації, включно з location_ids.
• GET /api/v1/availability - Зчитуйте доступні слоти за послугою та датою, із location_id, коли це потрібно.
• POST /api/v1/appointments/hold - Створіть тимчасове утримання перед підтвердженням, використовуючи той самий location_id, коли потрібно.
• POST /api/v1/appointments/confirm - Підтвердіть утримання та створіть запис.
• POST /api/v1/appointments/reschedule - Перенесіть наявний запис за booking_id.
• POST /api/v1/appointments/cancel - Скасувати наявний запис за booking_id.

Рекомендована послідовність

1. Перелічіть локації, якщо організація може бронювати в кількох місцях.
2. Дозвольте користувачу вибрати локацію за потреби.
3. Перелічіть послуги та залиште лише ті, що покривають цю локацію.
4. Отримати доступність із service_id, датою та location_id за потреби.
5. Створити утримання з тим самим location_id.
6. Підтвердіть бронювання з контактними даними.
7. Зберігайте booking_id, щоб мати можливість пізніше перенести або скасувати.

Примітки щодо надійності

• Використовуйте ідемпотентність для викликів створення/підтвердження, щоб уникнути дублів під час повторних спроб.
• Сприймайте резервування як тимчасові й підтверджуйте швидко.
• Явно обробляйте відповіді 401/403/404 і конфлікти в інтерфейсі клієнта.

Примітка щодо охоплення

Поточні публічні API зосереджені на операціях бронювання. Management API заплановані на пізніший етап.