Подключение к 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. Согласуйте заявку

Внимание

Если вы хотите подключить несколько брендов — создайте отдельную заявку для каждого.

  1. Прочитайте оферту.

  2. Откройте форму заявки.

  3. Выберите Подключиться через API Яндекса.

  4. Заполните поля.

    Важно

    По умолчанию для подключения доступны только рубрики сегмента красоты. Если у вашей организации другой основной вид деятельности — уточните это при первом контакте с менеджером.

  5. Нажмите Отправить. Менеджер свяжется с вами в Telegram для согласования заявки.

  6. Подготовьте информацию для менеджера:

    • Юридическое название компании — как указано в регистрационных документах.
    • Маркетинговое название — бренд, под которым сервис представлен пользователям. Будет отображаться в блоке о партнере внутри виджета записи.
    • Ссылку на сайт партнера — если есть. Будет отображаться в блоке о партнере внутри виджета записи.
    • Логотип — черный векторный SVG без встроенных растровых изображений, ограничение по высоте — 16 px.
    Как это выглядит

    booking-widget-logo

  7. После согласования заявки вы получите:

    • partnerName;
    • секрет для JWT для production- и тестового окружений.

Шаг 2. Настройте тестовую среду

Подготовьте тестовый хост, на котором Яндекс будет проводить проверку перед запуском и регрессионное тестирование.

Требования к тестовой среде:
  • Отдельный тестовый хост.

    Иначе запросы из тестовой среды Яндекса будут создавать реальные бронирования в production-системе партнера.

  • В тестовом списке — только реальные организации из системы партнера, а не созданные вручную тестовые компании.

    На моковых данных большинство проблем, которые проявляются при заливке реального фида, не воспроизводятся.

  • Размер тестового списка организаций:

    • не меньше 10 позиций;
    • не меньше 10% от общего числа организаций в production-фиде.
  • Все операции работают как в production-среде: получение услуг и мастеров, создание, перенос и отмена бронирований.

  • Тестовая среда доступна постоянно и поддерживается в актуальном состоянии.

  • При обнаружении проблем партнер устраняет их в течение двух рабочих дней с момента обращения.

Важно

Если партнер не соблюдает требования к тестовой среде, Яндекс вправе отключить его от сервиса.

Шаг 3. Подготовьте фид

Подготовьте и опубликуйте фид для загрузки организаций.

Требования к фиду

Параметр

Описание

Пагинация

Название полей, которые отвечают за разбиение данных на страницы в ответе точки доступа к API, строго pagination.cursor и pagination.hasMore.

Другие варианты не распознаются.

Рубрики

Значения поля rubrics должны строго соответствовать официальному списку рубрик.

Произвольные строки не принимаются. Нельзя указывать в этом поле имена сотрудников, специализации или любые другие данные.

Если вы не заполните поле — матчинг будет значительно хуже.

id

ID организации в системе партнера. Должно быть уникальным для каждой организации в фиде.

Тип данных — строка.

Адрес

Адрес корректный, со знаками пунктуации в нужных местах.

Скопируйте точный адрес из карточки организации или строения/дома в интерфейсе Яндекс Карт.

Координаты

Координаты имеют приоритет над текстовым адресом — лучше передать только корректный адрес, чем адрес с приблизительными координатами.

Скопируйте точные координаты и адрес из карточки организации в интерфейсе Яндекс Карт.

Название

Название бренда соответствует названию в профиле  Яндекс Бизнеса или названию в карточке организации в интерфейсе Яндекс Карт.

Не используйте название филиала вместо названия сети.

Правильно:

  • В Картах Acme Новокузнецкая, в фиде Acme Новокузнецкая.
  • В Картах Acme Новокузнецкая, в фиде Acme.

Неправильно: В Картах Acme, в фиде Acme Новокузнецкая.

Пример фида

   {
    "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 объекта FeedCompany.

Где найти permalink
  1. В Личном кабинете Яндекс Бизнеса найдите нужную организацию в списке ваших компаний.
  2. Перейдите в профиль организации.
  3. Скопируйте идентификатор из ссылки в адресной строке браузера.

Важно

  • Ответственность за корректность permalink лежит на партнере.
  • Система использует указанный permalink сразу, без дополнительной проверки.
  • Ошибки в permalink приведут к неверному матчингу, и записи будут отображаться не в том месте, которое ожидает пользователь.

Передача permalink в фиде не ускоряет процесс матчинга. Организация появится в Яндекс Картах после очередного цикла обработки фида.

Шаг 4. Реализуйте API бронирований

Реализуйте API по спецификации для двух окружений:

  • Production — production-хост с реальными данными.
  • Testing — тестовый хост, на котором Яндекс проводит проверку перед запуском и регрессионное тестирование.

Чтобы интеграция с API прошла успешно, соблюдайте требования:

Параметр

Описание

Протокол

Все ответы возвращают Content-Type: application/json.

Нет редиректов с HTTPS на HTTP.

Аутентификация

При работе с JWT:

  • укажите payload в соответствии со спецификацией;
  • генерируйте токен в режиме --no-iat без временной метки в payload (см. подробнее в статье JSON Web Token).

В заголовке запроса к API указано Accept: application/json. Если сервер не укажет этот заголовок или  укажет другой формат, API вернет ошибку 406.

Ключ ресурсов

Когда система передает данные о сотрудниках (например, при записи на услуги), укажите имя и фамилию в поле title, а должность в description.

Пустой список слотов

Если нет доступных слотов записи, возвращается {"availableTimeSlots": []}. Нельзя возвращать пустое тело запроса или null.

Время

Во всех datetime указан часовой пояс конкретной организации. Timestamp в формате ISO 8601.

Пример: datetime=2023-10-15T11:48:00+03:00

Комментарии

Поле comment есть во всех ответах GET и PUT /bookings/{id}, не только в POST.

Статусы

GET и PUT /bookings/{id} возвращают поля status.

Статус cancelled пишется через двойную «l»:

Правильно: cancelled
Неправильно: canceled

Необязательные поля

Если для поля нет значения — не включайте поле в ответ. Значение null может вызвать ошибки парсинга.

Шаг 5. Обеспечьте синхронизацию данных

Используйте вебхуки, чтобы синхронизировать данные о бронированиях и посещениях между системой партнера и сервисом Яндекса. Это поможет поддерживать информацию в актуальном состоянии и улучшит качество сервиса.

Обязательные требования:

Уведомление об изменении статуса

Для чего:

Чтобы данные о бронированиях (переносы, отмены и т.д.) были актуальными как в системе партнера, так и на платформе Яндекса.

Как работает:

Если в системе изменился статус бронирования, сообщите об этом Яндексу через вебхук PUT https://partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId}.

В запросе укажите имя партнера partnerName и идентификатор бронирования bookingId.

Статусы посещения

Для чего:

Чтобы учитывать реальные посещения и анализировать работу сервиса. Помогает оценить, насколько эффективно работает система бронирования, и выявить возможные проблемы.

Как работает:

Проставьте статусы посещения сразу после того, как клиент посетил или не посетил организацию. Актуальный список статусов смотрите в спецификации.

Шаг 6. Проверьте и запустите решение

Прежде чем запускать интеграцию с Яндексом полностью, дождитесь, когда Яндекс протестирует реализацию API и сообщит, что она работает в production-среде. После этого проведите запуск в несколько этапов:

  1. Запустите одну-пять пилотных точек.
  2. Убедитесь в стабильной работе в течение одной-двух недель.
  3. Масштабируйте решение — добавьте остальные организации в фид.

Совет

Перед запуском сверьтесь с чеклистом.

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

Фид организаций
  • Пагинация: поля 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-тест на тестовом хосте. Убедитесь, что все шаги проходят без ошибок:

    1. Фид организаций — GET /companies/feed возвращает не меньше 10 реальных организаций. Пагинация работает: при переходе по pagination.cursor список не зацикливается, pagination.hasMore корректно сигнализирует о конце.

    2. Услуги и мастера — для каждой организации GET /companies/{id}/services и GET /companies/{id}/resources возвращают непустые списки с корректными ID и именами.

    3. Доступные слоты — GET /companies/{id}/slots?serviceIds[]=... возвращает слоты с timezone конкретной организации. При отсутствии слотов ответ {"availableTimeSlots": []}, не null и не пустое тело.

    4. Создание бронирования — POST /bookings возвращает bookingId и статус confirmed (или pending, если предусмотрено договором). Бронирование реально появляется в системе партнера.

    5. Просмотр бронирования — GET /bookings/{id} возвращает все поля: status, comment, resources, services, datetime с timezone.

    6. Перенос — PUT /bookings/{id} с новым временем изменяет запись. Ответ getBooking содержит актуальный статус.

    7. Отмена — PUT /bookings/{id} со статусом cancelled (двойная «l»). Повторный GET подтверждает статус cancelled.

    8. Вебхук при изменении статуса на стороне партнера — при отмене или переносе бронирования из интерфейса/системы партнера Яндекс получает PUT https://partner.maps.yandex.net/booking/v1/partners/{partnerName}/{bookingId} с актуальным статусом в течение нескольких минут.

    9. Статус посещения — после завершения времени бронирования партнер проставляет visited или not_visited через тот же вебхук. Яндекс проверяет получение этих статусов.

Типовые проблемы

Проблема

Причина

Решение

400 Bad Request при любом запросе

Пустое поле sub в JWT.

Установите "sub": "<partnerName>" в payload.

406 Not Acceptable

Сервер не поддерживает Accept: application/json.

Явно разрешите этот MIME‑тип в конфигурации сервера.

Ответ 200, но данные не читаются

Двойная JSON‑сериализация — объект сериализован в строку, строка снова сериализована в JSON.

Возвращайте объект напрямую.

CANCEL_FORBIDDEN / UPDATE_FORBIDDEN

Партнер не разрешает изменение или отмену.

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

Слоты отображаются в неправильное время

В datetime отсутствует timezone или указана неверная зона.

Использовать фактический часовой пояс каждой организации, а не UTC или московское время.

Рубрики медицины/авто/развлечений не работают

Нестандартные сегменты заблокированы по умолчанию.

Чтобы разблокировать, обратитесь к менеджеру.

Организации не матчатся

Возможные причины:
  • Неактуальный профиль в Яндекс Бизнесе.
  • В профиле не указаны часы работы.
  • Некорректно заполнено поле rubrics или его нет.
  • Название организации не совпадает с названием бренда в Картах.
  • Некорректный адрес или координаты.
  • Пустые поля.
  • С момента публикации прошло меньше семи дней.
Решение:

Важно

Убедитесь, что владелец организации завел и актуализировал профиль в Яндекс Бизнесе.

Если профиль есть в Яндекс Бизнесе и данные в нем актуальны, проверьте заполнение фида в порядке приоритета:

  1. Есть поле rubrics, заполнено корректными значениями из официального списка.
  2. Название в фиде совпадает с названием бренда в Яндекс Картах.
  3. Адрес и координаты корректны. Они скопированы из Карт с сохранением пунктуации.
  4. Нет пустых полей.

Если ошибок из этого списка нет, убедитесь, что с момента публикации фида прошло больше семи дней.

Если после проверки всех пунктов организация все равно не прошла матчинг — обратитесь в поддержку через форму.

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

Сколько времени занимает матчинг?

Обычно 2-7 дней. При неудаче проверьте рубрики, название и адрес. См. подробнее в разделе Организации не матчатся.

Можно ли подключить несколько брендов к одному аккаунту?

Нет. Один аккаунт соответствует одному API‑хосту. Для разных брендов заведите отдельные аккаунты.

При этом бренды-партнеры должны иметь уникальное название и визуальное оформление, а не быть вариациями одного и того же. Это нужно для того, чтобы владельцы организаций могли четко ассоциировать себя с определенным брендом, а в будущем — без труда выбирать нужного партнера из списка интеграций.

Важно избегать ситуаций, когда названия брендов похожи, например, «Acme.Клиника» и «Acme.Стоматология». Это может привести к путанице, особенно в случае организаций, которые предлагают несколько видов услуг одновременно (например, клиники, где есть стоматологические услуги и услуги других врачей).

Что делать, если serviceIds[] некорректно парсятся?

Убедитесь, что сервер обрабатывает query‑параметры вида serviceIds[]=svc1&serviceIds[]=svc2 (URL‑encoded массив).

Рубрики медицины/авто/развлечений не подключаются

Эти сегменты заблокированы по умолчанию. Чтобы разблокировать, обратитесь к менеджеру.

У нас ресторан. Есть особенности?

Да, особенности есть:

Уточните условия у менеджера при первом контакте по заявке.

Письмо в поддержку



Также вы можете перейти на сервис

   



JSON Web Token. Формат токена, который используется для передачи информации между сторонами в компактной и безопасной форме.

Искусственно созданные данные, которые имитируют реальные. Их используют в разработке и тестировании программного обеспечения.

Ссылка вида https://yandex.ru/maps/-/XXXXXXXX, где XXXXXXXX — уникальный идентификатор объекта, который используется для однозначной идентификации организации в Яндекс Картах.

адрес в карточке организации

адрес в карточке дома