Интеграция Booking API для сетей фитнес-клубов: технический регламент

Прямая интеграция Booking API доступна разработчикам CRM-систем, которые уже подключили более 300 компаний, и крупным сетям с собственной IT-инфраструктурой. Одиночные клубы используют готовые партнерские решения. Разработка собственного шлюза занимает около месяца. Ошибки в формате таймзоны или статусах отмены ведут к отказу в переводе на Production Яндекс Карт.

Кому доступно прямое подключение

Интеграция требует наличия у организации фактического адреса. Процесс включает реализацию спецификации, настройку вебхуков и прохождение E2E-тестирования на стороне Яндекса. Прямая интеграция целесообразна для сетей с самописными ERP, где передача данных через сторонние шлюзы невозможна из-за требований безопасности или архитектуры абонементов.

Срок интеграции зависит от корректности данных. Яндекс останавливает тестирование при редиректах с HTTPS на HTTP или возврате пустого тела вместо пустого массива для слотов.

Согласование заявки и брендинг

По умолчанию для подключения доступны только рубрики сегмента красоты. Если у вашей организации другой основной вид деятельности — уточните это при первом контакте с менеджером. При подаче заявки через менеджера в Telegram укажите основной вид деятельности. Для заявки предоставьте юридическое и маркетинговое название бренда. Логотип — черный векторный SVG без растровых элементов. Ограничение по высоте — 16 пикселей. После проверки менеджер выдает доступы к спецификации и тестовому окружению.

Требования к серверу и форматам обмена

Обмен данными идет в формате JSON. Заголовок Accept: application/json обязателен. Отсутствие заголовка или неверный формат вызывают ошибку 406. Аутентификация через JWT, токен генерируется в режиме --no-iat. Время передается в формате ISO 8601 с учетом таймзоны филиала. Необязательные поля с отсутствующими значениями исключаются из ответа. Передача null вызывает ошибки парсинга.

Фиды организаций и расписание

Идентификаторы организаций (ID) передаются строками и уникальны. В фиде заполняется поле rubrics, названия филиалов должны совпадать с карточками в Яндекс Картах. Данные о тренерах передаются через ключ ресурсов: title — имя и фамилия, description — должность. Пагинация обязательна, переход по pagination.cursor не должен зацикливаться.

Синхронизация через вебхуки

Вебхуки обеспечивают двусторонний обмен. При отмене или переносе тренировки в CRM информация передается методом PUT https://partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId}. Статусы посещения visited или not_visited проставляются после завершения времени бронирования.

E2E-тестирование

Яндекс проводит сквозное тестирование на тестовом хосте. Окружение должно содержать не менее 10 организаций (минимум 10% от сети). Автоматика проверяет создание бронирования через POST /bookings, перенос и отмену. После успешного прохождения 9 шагов теста открывается доступ к Production.

Пример интеграции сети на 12 точек

1. Подача заявки: черный SVG 16px.
2. Настройка тестового сервера: выгрузка 12 филиалов в фид.
3. Генерация JWT-токенов с параметром --no-iat.
4. Разметка тренеров: title и description.
5. Настройка отдачи {"availableTimeSlots": []} для занятых часов.
6. Реализация вебхука visited при проходе через турникет.

Пилотный запуск

После получения доступа к Production запускайте интеграцию поэтапно. Начните с 1-5 точек. В течение одной-двух недель отслеживайте логи вебхуков, дубликаты бронирований и корректность статусов. После стабилизации фид расширяется на всю сеть.

Чек-лист готовности

1. Пагинация pagination.cursor и pagination.hasMore работают корректно.
2. ID уникальны, строковый тип.
3. Поле rubrics заполнено.
4. Названия филиалов идентичны Яндекс Картам.
5. Заголовок Accept: application/json настроен.
6. Редиректы с HTTPS отключены.
7. Переменные datetime содержат timezone.
8. Пустые слоты отдают {"availableTimeSlots": []}.
9. Статус cancelled написан без ошибок.
10. Значения null исключены из JSON.
11. Вебхук отправляет статус посещения.

FAQ