Посібник з API бронювання

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.

Резервування часу (послуги з фіксованою ціною). Утримання (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.» (українською: «Резервування часу: цим резервуванням договір щодо послуги ще не укладено. Ціна організації, оплата на місці; ціна та договір узгоджуються на місці.») Ваш інтерфейс повинен показати кінцевому клієнтові цю примітку не пізніше ніж разом із результатом запису; це ваш обовʼязок згідно з підпунктом c пункту 8(5) Частини B Умов. Відповідь на запит утримання містить її, щоб її можна було показати ще до того, як кінцевий клієнт надішле запит на запис; переклад іншою мовою має бути повним і точним за змістом. Zimun через цей інтерфейс не отримує й не документує згоди кінцевого клієнта з власними положеннями, не приймає ні онлайн-оплати, ні платіжних карток та надсилає на адресу електронної пошти, передану разом із записом, повідомлення про резервування, а не підтвердження запису.

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

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

Про надійність

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

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

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