Подключение API онлайн-записи в Яндекс Бизнесе: технический гайд для юридических компаний

По запросу «юридическая консультация» в Москве Яндекс Карты фиксируют более 180 тысяч поисковых сессий ежемесячно. Конверсия из просмотра карточки в обращение падает в 2,5 раза, если клиенту предлагают только звонок или форму с обещанием перезвонить через 15 минут. Пользователь хочет зафиксировать время встречи с конкретным юристом. Кнопка «Записаться онлайн» в Яндекс Бизнесе требует интеграции с аккредитованными платформами или собственного API.

Два способа подключения онлайн-записи

Первый метод — использование партнерского сервиса из списка Яндекса. В пул входят Битрикс24, Altegio, Dikidi, 1 °C. Если юридическая фирма ведет учет в Битрикс24, активация бронирования сводится к включению коннектора в кабинете CRM и прохождению модерации.

Второй метод — прямое подключение к API Яндекс Бизнеса. Регламент рассчитан на крупные сети, которые хотят подключить онлайн-запись через собственную CRM-систему, или разработчиков CRM-систем, которые уже подключили более 300 компаний. Если юридическая компания — это федеральная коллегия с закрытым контуром безопасности, передача данных сторонним SaaS недопустима из-за адвокатской тайны. В этом случае собственное API — единственное решение.

Для небольших бюро без штата разработчиков есть альтернатива в рекламном кабинете. При покупке продвижения в Картах на вкладке «Материалы» настраивается кнопка «Записаться онлайн» с прямой ссылкой на лендинг с календарем. Нативный виджет внутри карточки доступен только через партнерскую CRM или прямой шлюз бронирования. Общие правила описаны в материале подключение онлайн-записи в Яндекс Бизнесе.

Сравнение архитектурных подходов к бронированию юридических консультаций.

Ограничения API и специфика юридических услуг

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

Интерфейс API настроен на сферу красоты и здоровья. Рубрики «юридические услуги», «адвокаты», «банкротство» требуют ручного согласования с техническим менеджером Яндекса. Необходимо зафиксировать, что слот записи соответствует времени консультации, а не аренде кабинета.

Срок интеграции прямого API составляет около месяца. Время увеличивается, если разработчики отступают от спецификации или медленно реагируют на замечания тестировщиков. После проверок кнопка действия появится в профиле в течение 10 дней.

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

Интеграция начинается с заполнения формы заявки, где выбирается пункт «Подключиться через API Яндекса». После отправки анкеты менеджер связывается с представителем компании в Telegram. Требуемый пакет данных:

После валидации менеджер регистрирует компанию, выдает идентификатор partnerName и пару секретных ключей для JWT. Детали процесса — в статье про прямую интеграцию API онлайн-записи в Яндекс Бизнесе.

Архитектура API и эндпоинты

Интеграция требует тестового (Testing) и боевого (Production) окружений. Яндекс взаимодействует с API через синхронные HTTP-запросы и асинхронные вебхуки. Сервер должен принимать заголовок Accept: application/json и возвращать ответы с Content-Type: application/json. Редиректы с HTTPS на HTTP запрещены.

Для авторизации используется JWT. Токен генерируется без временной метки (--no-iat) в payload. Ошибки в заголовках вызывают ответ 406 Not Acceptable.

Обязательные методы:

Метод получения слотов при отсутствии окон обязан возвращать {"availableTimeSlots": []}. Передача null или пустой строки расценивается как сбой.

Технические требования к обработке данных.

Настройка ресурсов и таймслотов

Юридические услуги сегментированы. Доверитель не пойдет к специалисту по семейным спорам за помощью по арбитражу. В методе GET /companies/{id}/resources ФИО специалиста передается в поле title, а должность и специализация — в description.

Таймслоты в GET /companies/{id}/slots должны соответствовать стандарту ISO 8601 с локальным смещением: 2026-10-15T11:00:00+03:00. Если филиалы в разных часовых поясах, сервер отдает интервалы в таймзоне запрашиваемого филиала.

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

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

После завершения консультации отправляются финальные статусы:

Систематическое отсутствие статусов ведет к отключению виджета. Подробности — в техническом гайде по онлайн-записи.

Подготовка тестовой среды

Тестирование на продакшене запрещено. Требования к тестовому хосту:

1. Размер списка — не менее 10 позиций и не менее 10% от рабочего фида.
2. Запрещены синтетические данные. Только реальные адреса и расписание.
3. Поддержка всех операций: бронирование, перенос, отмена.
4. Круглосуточная доступность.
5. Исправление ошибок в течение двух рабочих дней.

Сквозное E2E-тестирование

Яндекс запускает E2E-тест: проверяет фид, пагинацию, расчет слотов, создание бронирования, перенос и отмену. При успешном тесте запуск идет поэтапно: сначала 1-5 филиалов, через 1-2 недели — вся сеть.

Пример: сеть «Правовой Стандарт»

Сеть из 14 филиалов перевела запись на API. Нагрузка — 120 звонков в день на филиал.

1. Развернули api-booking.company.ru и stage-booking.company.ru.
2. Настроили GET /companies/{id}/resources с указанием специализаций.
3. Внедрили фильтр: исключение времени судебных заседаний из слотов для предотвращения овербукинга.
4. Реализовали JWT HS256 без --no-iat.
5. Настроили вебхук-обработчик с откликом до 40 секунд.
6. Прошли E2E-тест за 3 дня.

Результат: доля бронирований через Карты — 34% за первый месяц. Потери обращений в нерабочее время сведены к нулю.

Диагностика перед подключением

Интеграция не даст конверсий без подготовки карточки. Робот сопоставляет данные фида с профилем. Проверьте права доступа, график работы, прайс-лист и фото входной группы. Дополнительно изучите техническое руководство по онлайн-записи.

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

1. Права на все филиалы подтверждены под единым аккаунтом.
2. Адреса и названия в БД совпадают с Яндекс Картами.
3. Тестовый хост изолирован и содержит реальные данные.
4. Все ID передаются строками (String).
5. Сервер отдает Content-Type: application/json без редиректов.
6. JWT генерируется без iat.
7. Поле title — имя специалиста, description — специализация.
8. Таймслоты — ISO 8601 с локальным часовым поясом.
9. Пустые окна — {"availableTimeSlots": []}.
10. Необязательные параметры при отсутствии значений исключаются.
11. Статус отмены — cancelled.
12. Поле comment возвращается во всех методах.
13. Настроены вебхуки на изменение статуса.
14. Реализована передача финальных статусов визита.

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