Руководство по API бронирования

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.

Резервирование времени приёма (услуги с фиксированной ценой). Удержание (hold) или запись, созданные через этот интерфейс для услуги или ресурса с фиксированной ценой, являются резервированием времени приёма в смысле Общих условий (часть C, пункт 13(2)), а не договором об услуге. В этом случае ответ на создание удержания и ответ на создание записи содержат kind: "reservation", contract: "on_site", цену в price_cents и price_label в точной формулировке «Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt» (цена организации, оплата на месте; цена и договор согласуются на месте), а также notice со следующим фиксированным текстом: «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.» (по-русски: «Резервирование времени приёма: этим резервированием договор об услуге ещё не заключён. Цена организации, оплата на месте; цена и договор согласуются на месте»). Ваш интерфейс должен показать конечному клиенту это уведомление не позднее чем вместе с результатом бронирования; это ваша обязанность согласно Общим условиям (часть B, пункт 8(5), буква c). Ответ на создание удержания содержит уведомление, чтобы его можно было показать до того, как конечный клиент отправит запрос на запись; перевод на другой язык должен быть полным и точным по смыслу. Zimun не получает и не документирует через этот интерфейс согласия конечного клиента с положениями Zimun, не принимает ни онлайн-оплаты, ни банковских карт и отправляет на адрес электронной почты, переданный вместе с записью, сообщение о резервировании, а не подтверждение бронирования.

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

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

Заметки о надёжности

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

Заметка об области

Текущие публичные API сосредоточены на операциях записи. API управления планируются на более позднем этапе.