Интеграция CRM с Яндекс Картами: техническое руководство

Прямое подключение к API бронирования Яндекса доступно крупным сетям, которые хотят подключить онлайн-запись через собственную CRM-систему, и разработчикам CRM-систем, которые хотят стать партнером Яндекса и уже подключили более 300 компаний в свою систему. Малый бизнес с 1 — 20 филиалами использует готовые CRM из списка официальных партнеров Яндекса. Попытка создания собственного коннектора для единичной точки приводит к отказу на этапе подачи заявки в Яндекс Бизнес.

Два пути интеграции

Кнопка «Записаться онлайн» в Яндекс Картах работает по двум схемам. Первая — использование облачной CRM из пула аккредитованных партнеров (Dikidi, 1 °C Салон красоты, Атол, Битрикс, Клатч, НаПоправку, ПрофиГид, ПрофСалон, Яндекс Еда, Alika, Altegio, Amango, Arnica, Beauty Expert, Clean Expert, Core12, MastersPro, Rient, RocketWash, Salebot, Sonline, Sycret, Tetradka, Torrow, Universe Soft, YClients). Владелец заполняет карточки услуг и график мастеров, активирует интеграцию, после чего данные синхронизируются с серверами Яндекса автоматически.

Вторая схема — разработка собственного API-модуля. Она необходима сетям с кастомными базами данных или ERP-системами. При наличии менее 300 адресов Яндекс отклоняет заявку на прямое API. В таком случае бизнес использует партнерскую CRM или настраивает кнопку действия со ссылкой на внешний виджет бронирования.

Встроенный виджет открывается внутри интерфейса Яндекс Карт, данные клиента подтягиваются из Яндекс ID. Внешняя ссылка перенаправляет пользователя в мобильный браузер, что увеличивает потери трафика на 25 — 40% из-за ручного ввода данных.

Детальный разбор инструментов доступен в материале про онлайн-запись в Яндекс Картах.

Требования к прямому подключению

Для сетей Яндекс устанавливает регламент: наличие фактического адреса обязательно. Интернет-магазины без самовывоза или выездные мастера подключиться к API не могут. По умолчанию для подключения доступны только рубрики сегмента красоты. Если у вашей организации другой основной вид деятельности — уточните это при первом контакте с менеджером. Смежные ниши согласовываются с техническим менеджером в индивидуальном порядке.

Разработка и тестирование интеграции занимают в среднем один месяц. Срок увеличивается при некорректных форматах данных или ошибках регрессионного тестирования. Коммуникация проходит через выделенного менеджера, которому передаются юридические реквизиты и векторный логотип в формате черного SVG (ограничение по высоте 16 пикселей).

Архитектура и технические требования

Обмен данными идет по протоколу HTTPS. Редиректы с HTTPS на HTTP запрещены. Запросы и ответы сервера партнера обязаны содержать заголовок Content-Type: application/json.

Сервер CRM обязан обрабатывать заголовок Accept: application/json. Отсутствие обработки или ответ с другим MIME-типом вызывает ошибку 406 Not Acceptable. При использовании JWT полезная нагрузка формируется по спецификации, токен генерируется без временной метки (--no-iat).

Время передается по стандарту ISO 8601 с указанием часового пояса филиала. Использование UTC без смещения недопустимо. Формат: 2026-04-15T14:30:00+03:00. Ошибки в поясе приводят к накладкам в расписании.

При отсутствии свободных окон CRM возвращает JSON-массив: {"availableTimeSlots": []}. Ответы null, false или пустые тела расцениваются валидатором как сбой, останавливающий синхронизацию.

Синхронизация статусов

При бронировании через Яндекс Карты сервис отправляет POST-запрос в CRM. В ответ CRM резервирует слот и возвращает идентификатор записи. Изменения (переносы, отмены) передаются обратно через PUT-запрос: https://partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId}. Задержка не должна превышать нескольких минут.

После визита передается маркер: visited или not_visited. Данные используются для анализа надежности партнера.

Базовое руководство для сферы услуг содержит инструкции по запуску через готовые коннекторы.

Сравнение архитектур

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

Интеграция проходит E2E-тестирование на тестовом хосте, повторяющем production-среду. Сценарий включает 9 шагов: выгрузка фида, проверка справочников услуг и персонала, генерация слотов, создание бронирования, чтение параметров, смещение слота, отмена, проверка вебхука и фиксация явки. Подробности для медцентров описаны в статье про онлайн-запись для клиник.

Кейс: автоматизация детейлинга

Детейлинг-центр в Самаре (4 мастера, ручной учет) терял 35% обращений в нерабочие часы. После подключения к Dikidi и настройки интеграции с Яндекс Картами за первую неделю 42 клиента оформили запись онлайн, 18 из них — вне рабочего времени администратора. Слоты блокировались автоматически, исключая овербукинг.

Ошибки настройки

Виджет пропадает при несоблюдении регламентов:

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

1. Идентификатор организации — уникальная строка.
2. Адрес и телефон идентичны данным в Яндекс Бизнесе.
3. Филиалы привязаны к поддерживаемым рубрикам.
4. Сервер возвращает заголовок Content-Type: application/json.
5. Валидация заголовка Accept: application/json.
6. Формат времени ISO 8601 с таймзоной филиала.
7. Пустые слоты — массив {"availableTimeSlots": []}.
8. Статус отмены — cancelled.
9. Необязательные поля исключены из JSON.
10. Вебхук отправляется в течение нескольких минут.
11. Передача статусов явки visited или not_visited.
12. Успешное прохождение 9 шагов E2E-теста.

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