Интеграция Booking API онлайн-записи в Яндекс Картах для салонов красоты: архитектура, протоколы и синхронизация

Кнопка записи в карточке организации на Яндекс Картах дает рост конверсии из просмотра в целевое действие на 28-35% (замеры по локальной выдаче Москвы и Санкт-Петербурга). При этом более 60% бьюти-сетей сталкиваются с техническими сбоями: отмена визита в CRM не доходит до интерфейса Карт, слоты дублируются, а запрос падает с ошибкой 406. По регламенту Яндекс Бизнеса нативная кнопка подключается двумя путями: через аккредитованные CRM-платформы либо через прямое подключение к Booking API со строгими требованиями к протоколам обмена.

Партнерский шлюз или собственный API: условия подключения

Для салонов красоты действуют два регламента подключения к бронированию. Первый вариант рассчитан на организации с фактическим адресом: салон подключает аккредитованную CRM-систему из официального списка (YClients, Altegio, Dikidi, 1 °C Салон красоты, Arnica, Sonline). Шлюз между карточкой и базой расписания уже настроен разработчиками сервиса, а запуск кнопки занимает до 10 рабочих дней после включения интеграции в кабинете CRM.

Второй сценарий регламентирован официальной справкой сервиса: онлайн-запись в Яндекс Картах через CRM и прямой API. Он открыт двум категориям заявителей: разработчикам CRM-систем, которые хотят стать партнером Яндекса и уже подключили более 300 компаний в свою систему, и крупным сетям, которые хотят подключить онлайн-запись через собственную CRM-систему. Если у вас 10 или 25 студий, заявку на прямой коннектор отклонят на этапе ручной модерации Яндекса. Для таких сетей подходят только готовые интеграции.

Прямой API дает полный контроль над клиентской базой, исключает абонентскую плату сторонним сервисам и позволяет настраивать кастомные алгоритмы распределения мастеров внутри корпоративной базы данных.

Сравнение технических подходов к интеграции с геосервисами для бьюти-бизнеса.

Технические требования к серверу и протоколам обмена

Интеграция Booking API работает по архитектуре REST. Сервер партнера обязан возвращать заголовок Content-Type: application/json на каждый входящий запрос. Редиректы с HTTPS на незащищенный HTTP запрещены политикой безопасности. Если сервер не находит в запросе Яндекса заголовок Accept: application/json или отдает другой MIME-тип, сессия прерывается с ошибкой 406.

Авторизация выполняется по токенам JSON Web Token (JWT). Яндекс требует генерации ключа строго в режиме --no-iat: временная метка создания не должна попадать в полезную нагрузку (payload). Ошибки в структуре payload блокируют валидацию на шлюзе до обращения к базе расписания салона.

Время передается строго с таймзоной геоточки по стандарту ISO 8601. Для салона в Екатеринбурге строка времени содержит смещение: 2023-10-15T11:48:00+05:00. Передача времени в UTC без смещения сдвигает записи в интерфейсе на величину часового пояса и ломает график мастеров.

Структура продуктового фида бьюти-предприятия

Синхронизация стартует с выгрузки JSON-фида. В фид входят филиалы, список специалистов, каталог процедур и сетка цен. Корректная настройка онлайн-записи в Яндекс Бизнесе требует совпадения идентификаторов точек с пермалинками карточек.

В объекте филиала поле permalink дублирует номер карточки салона в базе Яндекс Карт. Название точки передается без внутренних меток филиалов, если их нет в публичном профиле. Если на Картах салон называется «Персона Новокузнецкая», в фид уходит «Персона Новокузнецкая» либо сетевое название «Персона». Если в Картах указана только сеть, а в фид передано локальное имя района, сопоставление падает.

Персонал описывается в блоке resources. Имя и фамилия мастера передаются в параметре title. Должность и квалификация уходят в поле description. Стаж и сертификаты заносятся в поле information. Ссылки на фотографии сотрудников должны вести на внешнее хранилище с рабочими заголовками ответа.

Каждая позиция в блоке services содержит массив ID специалистов, допущенных к работе. Если окрашивание длится 180 минут у стажера и 120 минут у топ-стилиста, длительность задается через свойство durationSeconds в объекте мастера. Необязательные поля без значений нельзя оставлять пустыми: значения null ломают валидатор схемы, их нужно исключать из выгрузки.

Обработка временных окон и бронирований

При клике по кнопке записи в приложении Яндекс Карт шлюз запрашивает слоты через GET /companies/{id}/slots. Запрос передает ID услуг и опционально ID мастера. Бэкенд салона рассчитывает окна с учетом перерывов, пересменок и занятости кресел.

Частая ошибка самописных систем — пустой ответ или null, когда свободных окон на дату нет. Спецификация Booking API требует возвращать валидный JSON с пустым массивом: {"availableTimeSlots": []}. Иной формат Яндекс считает падением сервера партнера и снижает индекс надежности коннектора.

Фиксация записи идет через метод POST /bookings. Ответ бэкенда возвращает присвоенный bookingId и статус confirmed. Для сценариев с ручным подтверждением используется статус pending. Сервер обязан сохранять текст из поля comment: комментарий клиента должен присутствовать при создании брони и возвращаться в методах GET и PUT /bookings/{id}.

Перенос или отмена визита идут через PUT /bookings/{id}. В статусе отмены разработчики часто допускают ошибку, отправляя американское написание с одной «l». Спецификация Яндекса принимает только британский вариант: cancelled. Запрос со значением canceled парсер отклоняет.

Двусторонняя синхронизация: вебхуки и жизненный цикл визита

Интеграция не работает в одностороннем режиме через входящие запросы. Если клиент отменяет визит по звонку администратору, слот в Яндекс Картах должен освободиться сразу. Для этого настраивается двусторонний обмен через вебхуки.

При изменении брони в CRM (перенос времени, смена мастера, отмена) сервер партнера отправляет запрос на эндпоинт: PUT https://partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId}. Данные должны уходить в течение 2-3 минут после правки в журнале записи.

Завершающий шаг жизненного цикла — фиксация факта визита. После окончания слота CRM отправляет вебхук со статусом visited (клиент пришел) или not_visited (неявка). На основе этих данных алгоритмы отсекают спам-записи и защищают карточку от накруток со стороны конкурентов.

Контрольные точки валидации при обмене данными со шлюзом.

Пошаговое подключение через партнерские CRM

Для большинства салонов разработка прямого API не оправдана экономически. Достаточно использовать готовый партнерский шлюз. Процесс не требует работы с кодом:

Администратор авторизуется в панели управления CRM (YClients, Altegio и др.), открывает раздел сетевых интеграций и выбирает модуль геосервисов Яндекса. В модуле включается передача данных по филиалам. Система сопоставляет адреса точек с базой через геокодер и формирует связку.

После этого карточка уходит на модерацию. При активной Рекламной подписке или Приоритетном размещении в Яндекс Картах кнопка включается в рекламном кабинете. В разделе «Материалы» (или «Реклама в Картах») выбирается кнопка действия, указывается текст «Записаться онлайн», а в поле ссылки вставляется адрес виджета бронирования. Детали влияния кнопки на выдачу описаны в статье про онлайн-запись для салона красоты в Яндекс Бизнесе.

Интерфейс формы бронирования зафиксирован в едином шаблоне Карт. Менять стили, цвета и порядок шагов выбора мастера нельзя: Яндекс использует унифицированный виджет для всех CRM-платформ.

Кейс: настройка онлайн-записи для сети барбершопов на 3 филиала

Сеть барбершопов «Бородачъ» в Казани (3 адреса, 14 мастеров, учет в облачной системе Dikidi) настраивала прямую запись по следующему алгоритму:

1. Сверка карточек. В кабинете Яндекс Бизнеса проверили реквизиты точек. Адреса, телефоны и графики работы привели в полное соответствие с филиальной сеткой в Dikidi.
2. Синхронизация услуг. В Dikidi сгруппировали каталог по категориям («Стрижки», «Борода», «Комплексы»). Каждому мастеру проставили персональный хронометраж и список услуг с фиксированными рублевыми ценами без диапазонов «от».
3. Активация модуля. Во вкладке интеграции с Яндекс Картами в Dikidi включили синхронизацию для всех трех адресов.
4. Модерация каналов. Данные ушли в партнерский шлюз. Проверка связки филиалов с базой Карт заняла 7 рабочих дней.
5. Настройка кнопки действия. В кампании Яндекс Бизнеса в блоке «Материалы» маркетолог активировал кнопку «Записаться онлайн» со ссылкой на виджет.

Результат настройки: в карточках сети появилась кнопка прямого бронирования. Пользователи выбирают время в приложении Яндекс Карт, слоты сразу резервируются в сетке Dikidi, а администраторы получают уведомления в CRM без ручной обработки заявок.

Почему Яндекс отклоняет заявку: частые ошибки синхронизации

При тестировании прямого API или запуске шлюза через CRM заявка чаще всего блокируется по трем причинам.

Первая — рассинхронизация услуг и мастеров. Если уволенный мастер отключен в CRM, но его ID возвращается в ответе GET /companies/{id}/resources, интерфейс предложит записаться к несуществующему сотруднику. Запрос на бронь упадет с ошибкой 500, а карточку исключат из показа кнопки.

Вторая — ошибка пагинации в фиде точек. При запросе GET /companies/feed валидатор Яндекса читает pagination.cursor. Если бэкенд отдает один и тот же блок адресов по кругу, а параметр pagination.hasMore не принимает значение false, интеграция не проходит автоматический аудит.

Третья — нестабильный тестовый стенд (Testing host). При самостоятельной разработке заявитель передает тестовый контур минимум на 10 действующих точек (или от 10% общей базы). На нем модератор Яндекса выполняет полный цикл E2E-тестов: бронь, перенос, отмену со статусом cancelled и отправку статуса visited. Ошибка на любом этапе вебхука блокирует релиз в продакшн.

Чек-лист готовности карточки и расписания к интеграции

1. Основная рубрика в Яндекс Бизнесе — салон красоты, барбершоп, парикмахерская или ногтевая студия.
2. Фактический адрес подтвержден, точка входа точно установлена на Яндекс Картах.
3. В базе отсутствуют дубликаты карточки с совпадающим адресом и контактами.
4. В прайс-листе CRM зафиксированы точные рублевые цены без формулировок «от».
5. Для каждой услуги задан хронометраж в минутах или секундах.
6. Каждый работающий мастер привязан к услугам и рабочему графику.
7. Ответы API отдаются в UTF-8 с заголовком Content-Type: application/json.
8. Временные метки передаются по стандарту ISO 8601 с часовым поясом геоточки.
9. При отсутствии слотов бэкенд возвращает пустой массив availableTimeSlots без null.
10. Статус отмены передается строкой cancelled с двойной «l».
11. На бэкенде работают вебхуки для передачи ручных правок из CRM в Яндекс.
12. CRM отправляет вебхуки со статусами visited и not_visited после закрытия таймслота.

Частые вопросы