Zimun: Appointment Scheduling & Booking Service: Booking API Guide

API бронирования уже доступен для публичных сценариев планирования.

О чём это руководство

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

Booking API и MCP

• Используйте API бронирования, когда строите собственную бэкенд- или клиентскую интеграцию и хотите прямого контроля по HTTP.
• Используйте MCP, когда ваш клиент изначально поддерживает MCP и должен вызывать инструменты вроде list_services и get_availability.
• Оба пути построены на одной и той же логике бронирования и проверке конфликтов.

Если вы хотите готовый к встраиванию диалоговый процесс для клиентского бронирования, посмотрите Чат-агент бронирования.

Аутентификация

1. Создайте учётные данные API в разделе «Настройки → API-клиенты».
2. Запросите токен у /oauth/token, используя client credentials.
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 сосредоточены на операциях бронирования. API управления планируются на более позднем этапе.