Подключение к API онлайн‑записи
Важно
Cпособ подходит только организациям с фактическим адресом:
- крупным сетям, которые хотят подключить онлайн-запись через собственную CRM-систему;
- разработчикам CRM-систем, которые хотят стать партнером Яндекса и уже подключили более 300 компаний в свою систему.
На этой странице описан процесс подключения к API онлайн-записи, требования, выходящие за рамки спецификации, и типовые ошибки.
Основные требования
- Владелец организации должен завести профиль организации в Яндекс Бизнесе.
- Профиль должен быть актуальным на момент подключения к API онлайн‑записи.
- В профиле организации указаны часы работы.
Спецификация
| Для кого | Ссылка |
|---|---|
| Основная спецификация. Для рубрик сегмента красоты и некоторых других (например, детских студий, музыкальных школ) | https://yandex.kz/maps/booking/partners/api/ |
| Для ресторанов и партнеров, интегрирующихся с сервисом бронирования столов в ресторанах | https://yandex.kz/maps/booking/partners/api/tables |
| Для автомоек | https://yandex.kz/maps/booking/partners/api/carwashes.html |
Как подключиться
Интеграция занимает в среднем один месяц. Срок может увеличиваться в зависимости от факторов:
- насколько корректно партнер реализует API в соответствии со спецификацией;
- качества данных, которые партнер предоставляет;
- скорости устранения партнером обнаруженных при подключении ошибок.
Инструкция состоит из шагов:
Шаг 1. Согласуйте заявку
Шаг 2. Настройте тестовую среду
Шаг 3. Подготовьте фид
Шаг 4. Реализуйте API бронирований
Шаг 5. Обеспечьте синхронизацию данных
Шаг 6. Проверьте и запустите решение
Шаг 1. Согласуйте заявку
Внимание
Если вы хотите подключить несколько брендов — создайте отдельную заявку для каждого.
-
Прочитайте оферту.
-
Откройте форму заявки.
-
Выберите Подключиться через API Яндекса.
-
Заполните поля.
Важно
По умолчанию для подключения доступны только рубрики сегмента красоты. Если у вашей организации другой основной вид деятельности — уточните это при первом контакте с менеджером.
-
Нажмите Отправить. Менеджер свяжется с вами в Telegram для согласования заявки.
-
Подготовьте информацию для менеджера:
- Юридическое название компании — как указано в регистрационных документах.
- Маркетинговое название — бренд, под которым сервис представлен пользователям. Будет отображаться в блоке о партнере внутри виджета записи.
- Ссылку на сайт партнера — если есть. Будет отображаться в блоке о партнере внутри виджета записи.
- Логотип — черный векторный SVG без встроенных растровых изображений, ограничение по высоте — 16 px.
Как это выглядит

-
После согласования заявки вы получите:
partnerName;- секрет для JWT для production- и тестового окружений.
Шаг 2. Настройте тестовую среду
Подготовьте тестовый хост, на котором Яндекс будет проводить проверку перед запуском и регрессионное тестирование.
- Требования к тестовой среде:
-
-
Отдельный тестовый хост.
Иначе запросы из тестовой среды Яндекса будут создавать реальные бронирования в production-системе партнера.
-
В тестовом списке — только реальные организации из системы партнера, а не созданные вручную тестовые компании.
На моковых данных большинство проблем, которые проявляются при заливке реального фида, не воспроизводятся.
-
Размер тестового списка организаций:
- не меньше 10 позиций;
- не меньше 10% от общего числа организаций в production-фиде.
-
Все операции работают как в production-среде: получение услуг и мастеров, создание, перенос и отмена бронирований.
-
Тестовая среда доступна постоянно и поддерживается в актуальном состоянии.
-
При обнаружении проблем партнер устраняет их в течение двух рабочих дней с момента обращения.
-
Важно
Если партнер не соблюдает требования к тестовой среде, Яндекс вправе отключить его от сервиса.
Шаг 3. Подготовьте фид
Подготовьте и опубликуйте фид для загрузки организаций.
Требования к фиду
|
Параметр |
Описание |
|
Пагинация |
Название полей, которые отвечают за разбиение данных на страницы в ответе точки доступа к API, строго Другие варианты не распознаются. |
|
Рубрики |
Значения поля Произвольные строки не принимаются. Нельзя указывать в этом поле имена сотрудников, специализации или любые другие данные. Если вы не заполните поле — матчинг будет значительно хуже. |
|
|
ID организации в системе партнера. Должно быть уникальным для каждой организации в фиде. Тип данных — строка. |
|
Адрес |
Адрес корректный, со знаками пунктуации в нужных местах. Скопируйте точный адрес из карточки организации или строения/дома в интерфейсе Яндекс Карт. |
|
Координаты |
Координаты имеют приоритет над текстовым адресом — лучше передать только корректный адрес, чем адрес с приблизительными координатами. Скопируйте точные координаты и адрес из карточки организации в интерфейсе Яндекс Карт. |
|
Название |
Название бренда соответствует названию в профиле Яндекс Бизнеса или названию в карточке организации в интерфейсе Яндекс Карт. Не используйте название филиала вместо названия сети. Правильно:
Неправильно: В Картах |
Пример фида
{
"companies": [
{
"id": "company-002",
"permalink": "1234567890",
"name": {
"text": "Барбершоп «Acme»",
"localizedText": [{"lang": "en", "text": "Barbershop «Acme»"}]
},
"address": "Россия, Санкт-Петербург, Невский проспект, дом 100",
"coordinates": {"lat": 59.931336, "lon": 30.360489},
"phones": ["+71234567890", "+71234567891"],
"urls": ["https://acme-barber.ru"],
"bookingUrl": "https://acme-barber.ru/online-booking",
"photos": [
"https://acme-barber.ru/photos/interior-1.jpg",
"https://acme-barber.ru/photos/interior-2.jpg"
],
"rubrics": ["Барбершоп", "Салон красоты"],
"resources": [
{
"id": "res-001",
"title": "Иван Иванов",
"description": "Барбер, стилист",
"information": "Опыт 8 лет. Специализация: фейды, классические стрижки, моделирование бороды.",
"rating": 4.9,
"reviewsCount": 142,
"image": "https://acme-barber.ru/photos/alexey.jpg"
},
{
"id": "res-002",
"title": "Петр Иванов",
"description": "Барбер",
"rating": 4.7,
"reviewsCount": 85
},
{
"id": "res-003",
"title": "Дмитрий Иванов",
"description": "Барбер-стажер"
}
],
"services": [
{
"id": "svc-010",
"title": "Стрижка машинкой",
"category": "Стрижки",
"price": {"currencyCode": "RUB", "range": [900, 900]},
"durationSeconds": 2400,
"resources": [{"id": "res-001"}, {"id": "res-002"}, {"id": "res-003", "durationSeconds": 3600}]
},
{
"id": "svc-011",
"title": "Стрижка + борода",
"category": "Стрижки",
"price": {"currencyCode": "RUB", "range": [1500, 1500]},
"durationSeconds": 3600,
"resources": [{"id": "res-001"}, {"id": "res-002"}]
},
{
"id": "svc-012",
"title": "Моделирование бороды",
"category": "Борода",
"price": {"currencyCode": "RUB", "range": [600, 600]},
"durationSeconds": 1800,
"resources": [{"id": "res-001"}, {"id": "res-002"}, {"id": "res-003"}]
}
]
},
{
"id": "company-004",
"name": "Ногтевая студия «Acme»",
"address": "Россия, Екатеринбург, улица Ленина, дом 8",
"coordinates": {"lat": 56.838483, "lon": 60.605581},
"phones": ["+71234567890"],
"photos": [
"https://acme-nails.ru/photos/studio.jpg",
"https://acme-nails.ru/photos/work1.jpg",
"https://acme-nails.ru/photos/work2.jpg"
],
"rubrics": ["Ногтевая студия", "Салон красоты"],
"resources": [
{
"id": "nail-001",
"title": "Мария Иванова",
"description": "Мастер маникюра и педикюра",
"rating": 4.8,
"reviewsCount": 76,
"image": "https://acme-nails.ru/photos/anna.jpg"
},
{
"id": "nail-002",
"title": "Анна Иванова",
"description": "Мастер маникюра",
"rating": 4.5,
"reviewsCount": 43
}
],
"services": [
{
"id": "nail-svc-001",
"title": "Маникюр классический",
"category": "Маникюр",
"price": {"currencyCode": "RUB", "range": [800]},
"durationSeconds": 3600,
"resources": [{"id": "nail-001"}, {"id": "nail-002"}]
},
{
"id": "nail-svc-002",
"title": "Маникюр с гель-лаком",
"category": "Маникюр",
"description": "Покрытие гель-лаком, выбор из 200+ цветов",
"image": "https://acme-nails.ru/photos/gel.jpg",
"price": {"currencyCode": "RUB", "range": [1200, 1800]},
"durationSeconds": 5400,
"resources": [{"id": "nail-001"}, {"id": "nail-002", "durationSeconds": 6600}]
},
{
"id": "nail-svc-003",
"title": "Педикюр классический",
"category": "Педикюр",
"price": {"currencyCode": "RUB", "range": [1500]},
"durationSeconds": 4800,
"resources": [{"id": "nail-001"}]
}
]
},
{
"id": "company-006",
"name": "Фотостудия «Acme»",
"address": "Россия, Новосибирск, улица Красный проспект, дом 22",
"coordinates": {"lat": 54.989208, "lon": 82.896376},
"phones": ["+71234567890"],
"bookingUrl": "https://acme-studio.ru/book",
"photos": ["https://acme-studio.ru/photos/studio-main.jpg"],
"rubrics": ["Фотостудия"],
"services": [
{
"id": "photo-001",
"title": {
"text": "Аренда студии (1 час)",
"localizedText": [{"lang": "en", "text": "Studio rental (1 hour)"}]
},
"description": "Полностью оборудованная студия с несколькими фонами",
"price": {"currencyCode": "RUB", "range": [2000, 2000]},
"durationSeconds": 3600
},
{
"id": "photo-002",
"title": {
"text": "Фотосессия с ретушью (2 часа)",
"localizedText": [{"lang": "en", "text": "Photo shoot with retouch (2 hours)"}]
},
"description": "Съемка + 10 отретушированных фотографий",
"price": {"currencyCode": "RUB", "range": [5000, 8000]},
"durationSeconds": 7200,
"resources": [{"id": "photo-res-001"}]
}
],
"resources": [
{
"id": "photo-res-001",
"title": "Мария Иванова",
"description": "Фотограф",
"information": "Специализация: портрет, семейные фотосессии, love story. Лауреат конкурса «Фото года 2023».",
"rating": 5.0,
"reviewsCount": 27,
"image": "https://acme-studio.ru/photos/mary.jpg"
}
]
},
],
"pagination": {
"cursor": "company-008",
"hasMore": false
}
}
Матчинг
После публикации фида организации должны пройти матчинг — сопоставление организации из фида организациям в системе Яндекса.
Матчинг проходит с фиксированным расписанием как периодический фоновый процесс и занимает 2–7 дней.
Если организация не прошла матчинг автоматически — обратитесь в поддержку через форму.
Permalink в фиде
Совет
Укажите permalink организации в фиде, чтобы автоматически сопоставить ее с карточкой в Яндекс Картах.
Для чего:
Если вы укажете permalink, это исключит проблемы с матчингом и упростит интеграцию.
Как добавить:
Добавьте значение идентификатора в поле permalink объекта FeedCompany.
Где найти permalink
- В Личном кабинете Яндекс Бизнеса найдите нужную организацию в списке ваших компаний.
- Перейдите в профиль организации.
- Скопируйте идентификатор из ссылки в адресной строке браузера.
Важно
- Ответственность за корректность
permalinkлежит на партнере. - Система использует указанный
permalinkсразу, без дополнительной проверки. - Ошибки в
permalinkприведут к неверному матчингу, и записи будут отображаться не в том месте, которое ожидает пользователь.
Передача permalink в фиде не ускоряет процесс матчинга. Организация появится в Яндекс Картах после очередного цикла обработки фида.
Шаг 4. Реализуйте API бронирований
Реализуйте API по спецификации для двух окружений:
- Production — production-хост с реальными данными.
- Testing — тестовый хост, на котором Яндекс проводит проверку перед запуском и регрессионное тестирование.
Чтобы интеграция с API прошла успешно, соблюдайте требования:
|
Параметр |
Описание |
|
Протокол |
Все ответы возвращают Нет редиректов с HTTPS на HTTP. |
|
Аутентификация |
При работе с JWT:
В заголовке запроса к API указано |
|
Ключ ресурсов |
Когда система передает данные о сотрудниках (например, при записи на услуги), укажите имя и фамилию в поле |
|
Пустой список слотов |
Если нет доступных слотов записи, возвращается |
|
Время |
Во всех Пример: |
|
Комментарии |
Поле |
|
Статусы |
GET и PUT Статус Правильно: |
|
Необязательные поля |
Если для поля нет значения — не включайте поле в ответ. Значение |
Шаг 5. Обеспечьте синхронизацию данных
Используйте вебхуки, чтобы синхронизировать данные о бронированиях и посещениях между системой партнера и сервисом Яндекса. Это поможет поддерживать информацию в актуальном состоянии и улучшит качество сервиса.
Обязательные требования:
- Уведомление об изменении статуса
-
Для чего:
Чтобы данные о бронированиях (переносы, отмены и т.д.) были актуальными как в системе партнера, так и на платформе Яндекса.
Как работает:
Если в системе изменился статус бронирования, сообщите об этом Яндексу через вебхук
PUT https://partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId}.В запросе укажите имя партнера
partnerNameи идентификатор бронированияbookingId. - Статусы посещения
-
Для чего:
Чтобы учитывать реальные посещения и анализировать работу сервиса. Помогает оценить, насколько эффективно работает система бронирования, и выявить возможные проблемы.
Как работает:
Проставьте статусы посещения сразу после того, как клиент посетил или не посетил организацию. Актуальный список статусов смотрите в спецификации.
Шаг 6. Проверьте и запустите решение
Прежде чем запускать интеграцию с Яндексом полностью, дождитесь, когда Яндекс протестирует реализацию API и сообщит, что она работает в production-среде. После этого проведите запуск в несколько этапов:
- Запустите одну-пять пилотных точек.
- Убедитесь в стабильной работе в течение одной-двух недель.
- Масштабируйте решение — добавьте остальные организации в фид.
Совет
Перед запуском сверьтесь с чеклистом.
Чеклист перед запуском
Фид организаций
- Пагинация: поля
pagination.cursorиpagination.hasMore. - Все
id— строки, уникальны, без дубликатов. - У каждой организации заполнено поле
rubrics. - Адреса корректны.
- Нет пустых полей.
- Названия соответствуют карточке организации в Яндекс Картах.
Аутентификация и протокол
- Сервер принимает
Accept: application/json - Все ответы возвращают
Content-Type: application/json - Нет редиректа с HTTPS на HTTP
API бронирований
- Все ID — строки.
- Все
datetimeсодержатtimezoneконкретной организации. - Пустой список слотов:
{"availableTimeSlots": []}, неnullи не пустое тело. - Статус
cancelledс двойной «l». - GET и PUT
/bookings/{id}возвращают поляstatusиcomment. - Необязательные поля без значения не включаются в ответ.
Тестовая среда и вебхуки
-
Тестовый хост предоставлен, содержит ≥ 10 организаций и ≥ 10% от основного списка.
-
Все операции на тестовом хосте работают как в production-среде.
-
Вебхук на Яндекс работает при изменении статуса.
-
Пройден полный сквозной (E2E) тест
Перед переходом на Production Яндекс проводит полный E2E-тест на тестовом хосте. Убедитесь, что все шаги проходят без ошибок:
-
Фид организаций —
GET /companies/feedвозвращает не меньше 10 реальных организаций. Пагинация работает: при переходе поpagination.cursorсписок не зацикливается,pagination.hasMoreкорректно сигнализирует о конце. -
Услуги и мастера — для каждой организации
GET /companies/{id}/servicesиGET /companies/{id}/resourcesвозвращают непустые списки с корректными ID и именами. -
Доступные слоты —
GET /companies/{id}/slots?serviceIds[]=...возвращает слоты с timezone конкретной организации. При отсутствии слотов ответ{"availableTimeSlots": []}, неnullи не пустое тело. -
Создание бронирования —
POST /bookingsвозвращаетbookingIdи статусconfirmed(илиpending, если предусмотрено договором). Бронирование реально появляется в системе партнера. -
Просмотр бронирования —
GET /bookings/{id}возвращает все поля:status,comment,resources,services,datetimeсtimezone. -
Перенос —
PUT /bookings/{id}с новым временем изменяет запись. ОтветgetBookingсодержит актуальный статус. -
Отмена —
PUT /bookings/{id}со статусомcancelled(двойная «l»). Повторный GET подтверждает статусcancelled. -
Вебхук при изменении статуса на стороне партнера — при отмене или переносе бронирования из интерфейса/системы партнера Яндекс получает
PUT https://partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId}с актуальным статусом в течение нескольких минут. -
Статус посещения — после завершения времени бронирования партнер проставляет
visitedилиnot_visitedчерез тот же вебхук. Яндекс проверяет получение этих статусов.
-
Типовые проблемы
|
Проблема |
Причина |
Решение |
|
400 Bad Request при любом запросе |
Пустое поле |
Установите |
|
406 Not Acceptable |
Сервер не поддерживает |
Явно разрешите этот MIME‑тип в конфигурации сервера. |
|
Ответ 200, но данные не читаются |
Двойная JSON‑сериализация — объект сериализован в строку, строка снова сериализована в JSON. |
Возвращайте объект напрямую. |
|
CANCEL_FORBIDDEN / UPDATE_FORBIDDEN |
Партнер не разрешает изменение или отмену. |
Политика изменений должна быть согласована с менеджером Яндекса и зафиксирована в договоре. По умолчанию поддержка UPDATE и CANCEL обязательна. |
|
Слоты отображаются в неправильное время |
В |
Использовать фактический часовой пояс каждой организации, а не UTC или московское время. |
|
Рубрики медицины/авто/развлечений не работают |
Нестандартные сегменты заблокированы по умолчанию. |
Чтобы разблокировать, обратитесь к менеджеру. |
Организации не матчатся
- Возможные причины:
-
- Неактуальный профиль в Яндекс Бизнесе.
- В профиле не указаны часы работы.
- Некорректно заполнено поле
rubricsили его нет. - Название организации не совпадает с названием бренда в Картах.
- Некорректный адрес или координаты.
- Пустые поля.
- С момента публикации прошло меньше семи дней.
- Решение:
-
Важно
Убедитесь, что владелец организации завел и актуализировал профиль в Яндекс Бизнесе.
Если профиль есть в Яндекс Бизнесе и данные в нем актуальны, проверьте заполнение фида в порядке приоритета:
- Есть поле
rubrics, заполнено корректными значениями из официального списка. - Название в фиде совпадает с названием бренда в Яндекс Картах.
- Адрес и координаты корректны. Они скопированы из Карт с сохранением пунктуации.
- Нет пустых полей.
Если ошибок из этого списка нет, убедитесь, что с момента публикации фида прошло больше семи дней.
Если после проверки всех пунктов организация все равно не прошла матчинг — обратитесь в поддержку через форму.
- Есть поле
Частые вопросы
Сколько времени занимает матчинг?
Обычно 2-7 дней. При неудаче проверьте рубрики, название и адрес. См. подробнее в разделе Организации не матчатся.
Можно ли подключить несколько брендов к одному аккаунту?
Нет. Один аккаунт соответствует одному API‑хосту. Для разных брендов заведите отдельные аккаунты.
При этом бренды-партнеры должны иметь уникальное название и визуальное оформление, а не быть вариациями одного и того же. Это нужно для того, чтобы владельцы организаций могли четко ассоциировать себя с определенным брендом, а в будущем — без труда выбирать нужного партнера из списка интеграций.
Важно избегать ситуаций, когда названия брендов похожи, например, «Acme.Клиника» и «Acme.Стоматология». Это может привести к путанице, особенно в случае организаций, которые предлагают несколько видов услуг одновременно (например, клиники, где есть стоматологические услуги и услуги других врачей).
Что делать, если serviceIds[] некорректно парсятся?
Убедитесь, что сервер обрабатывает query‑параметры вида serviceIds[]=svc1&serviceIds[]=svc2 (URL‑encoded массив).
Рубрики медицины/авто/развлечений не подключаются
Эти сегменты заблокированы по умолчанию. Чтобы разблокировать, обратитесь к менеджеру.
У нас ресторан. Есть особенности?
Да, особенности есть:
- отдельная спецификация;
- нет поля
duration; - фиксированная сетка слотов;
- особая финансовая модель.
Уточните условия у менеджера при первом контакте по заявке.
|
Полезные ссылки |
JSON Web Token. Формат токена, который используется для передачи информации между сторонами в компактной и безопасной форме.
Искусственно созданные данные, которые имитируют реальные. Их используют в разработке и тестировании программного обеспечения.
Ссылка вида https://yandex.ru/maps/-/XXXXXXXX, где XXXXXXXX — уникальный идентификатор объекта, который используется для однозначной идентификации организации в Яндекс Картах.

