5 технических ошибок при интеграции онлайн-записи в Яндекс Карты

Интеграция онлайн-записи через API Яндекса занимает в среднем один месяц. Матчинг карточки с фидом длится от 2 до 7 дней. Владельцы сетей теряют клиентов из-за простых ошибок: статус cancelled с одной буквой «l» вместо двух ломает передачу бронирований. Система жестко регламентирует форматы ответов сервера, требуя полного соответствия данным в Яндекс Бизнесе.

Почему не проходит матчинг организаций

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

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

Проверяйте поля перед отправкой через

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

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

Проблемы с часовыми поясами и форматами времени

Сервис требует передачу времени в формате ISO 8601 с указанием часового пояса организации. Разработчики часто отправляют данные в UTC или по московскому времени для всех филиалов.

Это приводит к смещению слотов. Клиент из Владивостока видит доступное время ночью, а утренние часы пропадают из виджета.

Параметр datetime должен содержать часовой пояс конкретной организации. Верный формат: 2023-10-15T11:48:00+03:00.

Пустой список слотов передавайте как {"availableTimeSlots": []}. Значение null или пустое тело запроса вызывает ошибку парсинга на стороне Яндекса.

Нарушение спецификации ответов сервера

Протокол обмена данными не допускает отклонений. Сервер партнера обязан принимать заголовок Accept: application/json. Отсутствие поддержки этого MIME-типа генерирует ошибку 406 Not Acceptable.

Частая проблема — двойная JSON-сериализация. Сервер преобразует объект в строку, а затем оборачивает строку в JSON. Яндекс получает статус 200, но данные нечитаемы. Возвращайте объект напрямую.

Ошибки аутентификации возникают при неверной настройке JWT. Токен генерируется в режиме --no-iat без временной метки. Пустое поле sub приводит к статусу 400 Bad Request.

Ограничения для нестандартных рубрик

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

Рубрики медицины, автосервисов и развлечений требуют ручной разблокировки через менеджера Яндекса. Ресторанный бизнес работает по отдельной спецификации: отсутствует поле duration, применяется фиксированная сетка слотов.

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

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

Актуальность расписания поддерживается через вебхуки. Изменение статуса в CRM должно отражаться на платформе Яндекса. Отсутствие уведомлений ведет к двойному бронированию.

Сервер отправляет PUT-запрос при переносе или отмене. Ответы на GET и PUT запросы содержат поля status и comment. Статус отмены — cancelled. Вариант с одной буквой вызывает отказ в обновлении.

Для аналитики в Яндекс Бизнесе передавайте статусы visited или not_visited после завершения визита.

Ошибки при выборе способа подключения

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

Прямая интеграция API онлайн-записи в Яндекс Бизнесе требует прохождения E2E-теста. Одиночной компании проще использовать готовое решение.

Пример: Автосервис на одну точку

1. Менеджер Яндекса отклоняет заявку из-за размера сети.
2. Владелец регистрируется в партнерской CRM.
3. Переносит расписание в интерфейс партнера.
4. Включает модуль онлайн-записи в кабинете.
5. Проходит автоматическую модерацию.

Кнопка «Записаться онлайн» появится в профиле в течение 10 дней.

Чек-лист перед запуском

Переход в боевую среду возможен только после успешного E2E-теста. Проверка этих пунктов сокращает время ожидания:

1. Поле rubrics заполнено у каждой организации.
2. Адреса скопированы из Яндекс Карт.
3. Сервер принимает заголовок Accept: application/json.
4. Ответы возвращают Content-Type: application/json без редиректов.
5. Идентификаторы id передаются как строки.
6. Параметр datetime содержит часовой пояс.
7. Пустой список слотов возвращает {"availableTimeSlots»: []}.
8. Статус отмены — cancelled.
9. Необязательные пустые поля исключены из ответа.
10. Вебхук срабатывает при изменении статуса в CRM.
11. Тестовый хост содержит от 10 организаций.

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