Интеграция сайта с Яндекс Бизнесом: технический чек-лист

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

Базовые требования к ресурсу и профилю

Управление профилями перенесено в Яндекс Бизнес. Владелец подтверждает права на профиль до начала технических работ. Модераторы проверяют совпадение юридического названия в заявке с регистрационными документами.

Для подключения виджета записи нужен черный векторный логотип в формате SVG без растровых изображений. Высота логотипа — 16 пикселей. Ссылка на сайт передается менеджеру при согласовании заявки.

API Яндекса открыто для рубрик сегмента красоты. Компании с другими видами деятельности запрашивают доступ у менеджера. Если оптимизация карточки в Яндекс Бизнесе проведена с нарушениями правил нейминга, заявка блокируется.

Технические условия для API-интеграции

Сервер партнера принимает запросы с заголовком Accept: application/json. При другом формате API Яндекса отдает ошибку 406. Ответы системы передаются с Content-Type: application/json. Редиректы с HTTPS на HTTP запрещены.

Аутентификация работает на базе JWT. Токен генерируется в режиме --no-iat, без временной метки в payload. Имя и фамилия мастера передаются в поле title, должность — в поле description. Время передается в формате ISO 8601 с указанием часового пояса, например: 15.10.2023T11:48:00+03:00.

Отсутствие свободных мест оформляется пустым массивом {"availableTimeSlots»: []}. Передача null или пустого тела вызывает ошибку парсинга. Необязательные поля без значений исключаются из ответа.

Элемент API	Правильное поведение	Частая ошибка
Статус отмены	cancelled	canceled
Пустые слоты	Возврат пустого массива []	Возврат значения null
Поле comment	Присутствует в ответах GET и PUT	Используется только в POST
Редиректы	Строго HTTPS	Перенаправление на HTTP

Таблица 1. Сравнение корректных и ошибочных ответов сервера.

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

Двусторонняя передача данных поддерживает актуальное расписание. При изменении статуса записи система отправляет PUT-запрос на partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId}. Задержка передачи ведет к накладкам в расписании.

Статусы посещения visited или not_visited проставляются после завершения времени бронирования. Яндекс использует их для оценки доходимости клиентов. Непередача финальных статусов — нарушение протокола.

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

Оформление XML-фида для сетевых компаний

Массовое обновление данных происходит через XML-файл в кодировке UTF-8. Документ не содержит пустых элементов и HTML-атрибутов. Текстовые поля очищаются от символов с ASCII-кодами 0-31. Заголовок файла начинается с первой строки и нулевого символа.

Адреса соответствуют фактическому расположению точек. Юридические адреса без физического офиса в фид не добавляются. Если на территории пропускной режим, это фиксируется при передаче файла.

Рубрики в XML-фиде совпадают с деятельностью на сайте. Комбинация «Шиномонтаж, Автосервис» проходит проверку. «Шиномонтаж, Кондитерская» отклоняется при ручном аудите.

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

Синхронизация данных сайта и профиля

Номера телефонов в файле и на сайте идентичны. Скрытые номера или телефоны, которых нет на сайте, приводят к ошибке валидации. Если используется колл-трекинг, подменный номер размещается на страницах до отправки XML-файла.

Сайт — источник данных для вторичных рубрик, графика в праздники и расположения входов. Операторы Яндекс Бизнеса сверяют график с заявленным в фиде через обзвон.

Тип данных	Требование	Последствия
Телефонный номер	Совпадение с сайтом	Удаление из профиля
Основная рубрика	Соответствие контенту	Смена модератором
График работы	Совпадение с ответом оператора	Блокировка записи

Таблица 2. Зависимость модерации от данных.

Тестовая среда и E2E-тесты

Разработка ведется в Production и Testing. Тестовый хост содержит не менее 10 реальных организаций (10% от списка). Операции дублируют логику боевой среды.

Специалисты Яндекса проводят E2E-тест. Запрос GET /companies/feed проверяет пагинацию. Поля pagination.cursor и pagination.hasMore обеспечивают перелистывание. Запросы GET /companies/{id}/services возвращают списки мастеров с идентификаторами.

Тестирование включает создание, перенос и отмену бронирования. Запрос POST /bookings возвращает bookingId и статус confirmed. При переносе через PUT /bookings/{id} система проверяет статус в ответе getBooking.

Проверить свою карточку можно за две минуты через Localis — Оценка карточки за 120 сек: сервис оценит заполнение, найдёт слабые места и подскажет что править в первую очередь.

Пример интеграции для автосервиса

Сеть из трех СТО подключала бронирование через Яндекс Карты. Предыдущая попытка через XML-файл провалилась из-за расхождений в телефонах.

Исходные данные: CRM самописная. Телефоны на сайте — изображения. График в Картах — круглосуточный, по факту — до 22:00. Карточки автосервиса в Яндекс Картах перед запуском Рекламной подписки не прошли верификацию.

Что сделали:

1. Заменили изображения телефонов на индексируемый текст.
2. Обновили график в Яндекс Бизнесе на 09:00–22:00.
3. Настроили JWT-токен в CRM с флагом --no-iat.
4. Развернули тестовый хост с 10 фиктивными мастерами и 5 подъемниками.
5. Настроили вебхук PUT на передачу статуса cancelled.
6. Отформатировали время в слотах в ISO 8601 с поясом +03:00.

Результат: после E2E-теста на тестовом хосте интеграция переведена в Production. На карточке появилась кнопка «Записаться онлайн», слоты синхронизируются каждые 5 минут.

Чек-лист перед модерацией

1. Вход в Яндекс Бизнес под аккаунтом владельца.
2. Юридическое название совпадает с ЕГРЮЛ.
3. Телефон на сайте представлен текстом и совпадает с профилем.
4. Основная рубрика соответствует услугам.
5. XML-фид в кодировке UTF-8 без HTML-тегов.
6. Тестовый хост содержит от 10 организаций с услугами.
7. Сервер отдает заголовки Content-Type: application/json.
8. Пустые слоты возвращают массив [].
9. Статус отмены — cancelled.
10. Вебхуки отправляют статусы visited.
11. Идентификаторы (id) — уникальные строки.
12. Редиректы с HTTPS на HTTP отключены.

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

Требуются ли документы для подтверждения адреса?

Яндекс Бизнес запрашивает видеозапись фасада с вывеской и интерьером или договор аренды при сомнениях в локации.

Возможна ли интеграция напрямую в систему Яндекса?

Интеграция требует разработки промежуточного API по спецификации Яндекса. Прямая передача без соблюдения форматов JSON и структуры вебхуков не работает.

Почему нет кнопки записи?

Кнопка появляется после E2E-теста и перевода хоста в Production. Причина задержки — ошибки пагинации в фиде или отсутствие поля timezone.

Как Яндекс проверяет актуальность данных?

Операторы или роботы совершают звонки. Если оформление профиля строительной компании в Яндекс Картах содержит неактуальный телефон, организация теряет верификацию.