Добавьте свой Channel Manager

Это руководство проведет разработчиков channel manager и PMS через полный процесс интеграции с Wink — от создания аккаунтов до сопоставления инвентаря и проведения первого сквозного теста.

Окружения

API Channel Manager (Integrations) доступен в двух окружениях. Используйте staging для всей разработки и сертификации; переключайтесь на production только при запуске.

Окружение	Базовый URL
Production	https://integrations.wink.travel
Staging	https://staging-integrations.wink.travel

Справочник по API

API Channel Manager следует стандартам протокола OTA (SOAP/XML) для совместимости с существующими системами гостиничного бизнеса. Начните с изучения документации по партнерским эндпоинтам:

Channel Manager API — Партнерские эндпоинты

Шаги интеграции

1. Создайте учетную запись пользователя Wink

   Зарегистрируйтесь на staging-app.wink.travel. Все последующие шаги выполняются в staging — полный процесс повторяется в production перед запуском.

2. Создайте учетную запись Affiliate / Channel Manager

   Под вашим новым пользователем создайте аккаунт и выберите тип аккаунта Affiliate / Channel Manager. Именно под этим аккаунтом будет проходить аутентификация вашей интеграции.

3. Зарегистрируйте приложение и получите первый токен

   Создайте Application и привяжите его к аккаунту channel manager из шага 2. Выберите тип клиента MACHINE_2_MACHINE — это интеграция сервер-сервер без перенаправления конечного пользователя. Сразу скопируйте Client ID и Secret Key; секретный ключ показывается только один раз и не может быть восстановлен.

   Приложение генерирует bearer-токен, который используется в каждом вызове в этом руководстве как Authorization: Bearer <access_token>. Обменяйте свои учетные данные на токен с помощью гранта client_credentials по адресу https://staging-iam.wink.travel/oauth2/token, запрашивая области integrations.read integrations.write. Сделайте это перед продолжением — без токена вы не сможете получить идентификаторы аккаунтов или обратиться к любому эндпоинту Channel Manager. Полный процесс, адрес production и полный каталог областей смотрите в разделе Аутентификация.

4. Создайте аккаунт отеля

   Под тем же пользователем создайте второй аккаунт и выберите тип Hotel. Это даст вам объект недвижимости для тестирования без участия реального отеля.

5. Подтвердите одобрение обоих аккаунтов

   Ни один аккаунт не может использоваться до одобрения: неутвержденный аккаунт channel manager не отображается в списке channel manager отеля, а неутвержденный отель не возвращается API.

   • Staging — одобрение происходит автоматически. Оба аккаунта доступны сразу после создания, ничего дополнительно запрашивать не нужно.
   • Production — одобрение вручную. Отправьте контактному лицу Wink интеграций имена обоих аккаунтов и пользователя, под которым они созданы, и дождитесь подтверждения перед продолжением.

6. Свяжите два аккаунта

   Войдите в аккаунт отеля и перейдите в Extranet → Distribution → Channel Manager. Выберите ваш аккаунт channel manager из списка — это свяжет объект недвижимости с вашей интеграцией. Если аккаунт отсутствует в списке, он еще не одобрен; см. шаг 5.

7. Создайте базовый тип номера и тарифный план

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

8. Сопоставьте и протестируйте

   В вашей системе сопоставьте идентификаторы типа номера и тарифного плана, возвращаемые API. Отправьте обновление тарифа и доступности, затем сделайте тестовое бронирование и проверьте, что эндпоинт получения бронирования возвращает его корректно.

Заметка

Повторите все вышеуказанные шаги в production перед запуском, включая регистрацию отдельного production-приложения — учетные данные staging не работают в production. Учтите время на проверку Wink на шаге 5 — в отличие от staging, production-аккаунты не одобряются автоматически. Команда Wink перенесет все отели, уже использующие ваш channel manager, на ваш новый production-аккаунт.

Поиск идентификаторов ваших аккаунтов

Каждый путь API Channel Manager ограничен вашим аккаунтом:

/api/managing-entity/{managingEntityIdentifier}/channel-manager/...

{managingEntityIdentifier} — это ID аккаунта (UUID) вашего channel manager аккаунта, а не отеля. Получите его вместе с ID и текущим статусом всех других аккаунтов вашего пользователя через Platform API:

curl -s -X GET \
  "https://staging-api.wink.travel/api/managing-entity/list" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

Ответ — массив аккаунтов, которыми вы владеете:

[
  {
    "id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
    "type": "CHANNEL_MANAGER",
    "name": "Ваш Channel Manager",
    "status": "ACTIVE"
  },
  {
    "id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
    "type": "HOTEL",
    "name": "Ваша тестовая недвижимость",
    "urlName": "your-test-property",
    "status": "ACTIVE"
  }
]

• id записи channel manager — это ваш {managingEntityIdentifier}.
• id записи HOTEL — это ваш {propertyIdentifier}.
• status показывает, что аккаунт одобрен — особенно важно в production, где одобрение вручную. Отель должен иметь статус ACTIVE, чтобы быть доступным для бронирования и видимым в API Channel Manager. Ваш channel manager аккаунт будет иметь статус PENDING_APPROVAL до прохождения сертификации; это ожидаемо и не блокирует разработку.

Осторожно

Этот запрос выполняется к Platform API (https://staging-api.wink.travel в staging, https://api.wink.travel в production), а не к хостам Channel Manager API, указанным в разделе Окружения. Используйте тот же access token — он выдается на пользователя, а не на API.

Сертификация

Сертификация — это способ доказать и подтвердить Wink, что ваша интеграция корректно сопоставляет инвентарь, отправляет тарифы и доступность, а также получает бронирования сквозным образом. Процесс рассчитан на самостоятельное выполнение: вы управляете каждым шагом из своей системы и в конце отправляете единый пакет доказательств. Wink проверяет пакет и, при успешном прохождении, переводит ваш аккаунт Affiliate / Channel Manager из статуса PENDING_APPROVAL в ACTIVE.

Сертификация проводится полностью в staging окружении (https://staging-integrations.wink.travel). В этом разделе не используется production.

Что вы докажете

1. Аутентификация. Ваш OAuth2 клиент может получить access token и успешно вызвать эндпоинт /ping для вашего аккаунта Affiliate / Channel Manager.

2. Сопоставление инвентаря. Вы можете получить список отелей, связанных с вашим аккаунтом, извлечь мастер-тариф (комбинация типа номера и тарифного плана), который вы настроили, и правильно определить masterRateIdentifier, на который будет ориентирована ваша система.

3. Отправка тарифов и доступности. Вы можете обновить все семь дней недели сертификации по отдельности — с разными значениями цены, количества, флагов закрытия заезда/выезда и ограничений минимальной/максимальной продолжительности пребывания — и прочитать эти значения обратно из Wink.

4. Получение бронирования. Вы можете получить реальное бронирование в staging, сделанное для вашей тестовой недвижимости, отобразить его в своем PMS/CM интерфейсе с правильными данными по номеру, гостю и сумме, а затем отразить отмену после того, как Wink отметит бронирование как отмененное.

Предварительные условия

Перед началом сертификации выполните шаги 1–7 из раздела Шаги интеграции, чтобы у вас было:

• Пользователь Wink в staging с аккаунтами Affiliate / Channel Manager и Hotel, связанными между собой (Extranet → Distribution → Channel Manager). Аккаунты в staging одобряются автоматически, поэтому ничего дополнительно запрашивать не нужно.
• Как минимум один тип номера и один тарифный план, созданные в аккаунте отеля. Опубликуйте отель, чтобы он был доступен для бронирования по адресу https://staging-book.wink.travel/hotel/<your-slug>.
• Зарегистрированное приложение под вашим аккаунтом Affiliate / Channel Manager с Client ID, Secret Key и областями integrations.read integrations.write (см. Аутентификация).
• managingEntityIdentifier вашего аккаунта Affiliate / Channel Manager и propertyIdentifier аккаунта отеля (оба — UUID, см. Поиск идентификаторов ваших аккаунтов).

Общие соглашения по запросам

Каждый запрос в этом разделе использует следующие заголовки:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json

• <access_token> получается через грант client_credentials по адресу https://staging-iam.wink.travel/oauth2/token — см. Аутентификация.
• Заголовок Wink-Version обязателен; без него запрос не попадет в JSON API версии 2.
• Content-Type: application/json добавляется в PUT запросах с телом.

В примерах ниже заполните плейсхолдеры значениями, полученными в разделе Предварительные условия:

Плейсхолдер	Значение
{managingEntityIdentifier}	ID вашего аккаунта Affiliate / Channel Manager (UUID) — см. Поиск идентификаторов.
{propertyIdentifier}	ID аккаунта отеля (недвижимости), связанного с аккаунтом CM.
{masterRateIdentifier}	Мастер-тариф (комбинация типа номера и тарифного плана), который вы сертифицируете.
{bookingIdentifier}	ID бронирования в staging, полученный из списка бронирований.

Шаг A — Ping

Подтвердите, что ваши учетные данные соответствуют ожидаемому аккаунту Affiliate / Channel Manager.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/ping" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

Ожидаемый ответ:

{
  "apiVersion": "2.0",
  "name": "Название вашего аккаунта Channel Manager",
  "status": "PENDING_APPROVAL"
}

Ответ 200 с совпадающим name означает, что аутентификация и разрешение аккаунта корректны. status будет PENDING_APPROVAL до сертификации Wink.

Шаг B — Список объектов недвижимости

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

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/list?page=0&size=25" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

Ответ — объект Spring Page с записями ChannelManagerProperty. Найдите запись, у которой identifier совпадает с вашим {propertyIdentifier}, и запишите currencyCode — он понадобится для интерпретации обновлений тарифов в Шаге D.

Осторожно

Пустой список — это сигнал о конфигурации, а не ошибка запроса. Отель возвращается здесь только если он ACTIVE и назначен вашему аккаунту channel manager в Extranet → Distribution → Channel Manager. Проверьте оба условия через GET /api/managing-entity/list (см. Поиск идентификаторов) перед дальнейшей отладкой. В production добавляется третья причина: отель невидим до одобрения Wink.

Шаг C — Получение мастер-тарифов

Получите объект недвижимости вместе со всеми мастер-тарифами (комбинациями типа номера и тарифного плана), которые он публикует. Выберите тот, который собираетесь сертифицировать, и запишите его identifier как {masterRateIdentifier}.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

Ответ — объект PropertyWithRoomRateList: блок property и массив rooms с записями PropertyRoomRate. Каждая запись содержит тип номера, тарифный план, ограничения по вместимости, базовый тариф и модификаторы тарифа, которые нужно сохранять при отправке ежедневных тарифов.

Осторожно

Сертифицируйте только один мастер-тариф за весь процесс сертификации. В production ожидается сопоставление дополнительных типов номеров и тарифных планов, но пакет доказательств должен показывать работу только с одним мастер-тарифом.

Шаг D — Загрузка недели сертификации

Загрузите семидневный календарь тарифов, охватывающий первые семь календарных дней месяца, следующего за месяцем начала сертификации. Например, если вы начинаете 21 августа, выберите период с 1 по 7 сентября.

Вы отправите семь отдельных PUT запросов — по одному на каждый день — где startDate == endDate. Каждый день содержит специально подобранную комбинацию цены, количества, флагов закрытия заезда/выезда и ограничений по минимальной/максимальной продолжительности пребывания, чтобы проверить все поля. Значения указываются в валюте объекта недвижимости (записанной в Шаге B); если не указать currencyCode, он будет установлен по умолчанию.

День	Сумма	Количество	closedOnArrival	closedOnDeparture	minLengthOfStay	maxLengthOfStay	Что доказывает
1	100.00	5	false	false	1	30	Базовый день.
2	125.00	4	false	false	1	14	Изменение суммы, количества и maxLengthOfStay.
3	150.00	3	true	false	1	30	Переключение closedOnArrival.
4	175.00	2	false	true	2	7	Переключение closedOnDeparture и сужение окна LOS.
5	200.00	0	false	false	1	30	Продано полностью (количество 0).
6	225.00	5	false	false	3	5	Ограниченное окно LOS.
7	250.00	1	false	false	1	30	Доступность последнего номера.

Тело запроса для Дня 1 выглядит так. Повторите, изменяя startDate / endDate / значения согласно таблице для Дней 2–7.

curl -s -X PUT \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "startDate": "2026-09-01",
        "endDate":   "2026-09-01",
        "amount":    100.00,
        "master":    true,
        "closedOnArrival":   false,
        "closedOnDeparture": false,
        "quantity":          5,
        "minLengthOfStay":   1,
        "maxLengthOfStay":   30
      }'

Каждый PUT возвращает 200 с массивом обновленных записей PropertyRate за указанный период (одна запись при startDate == endDate). Сохраните этот ответ — он будет частью ваших доказательств.

Заметка

master должен быть true во всех вызовах недели сертификации. Это указывает Wink, что обновление — это шаблонный тариф, а не переопределение для конкретного бронирования.

Шаг E — Чтение недели сертификации

Получите всю неделю одним запросом и убедитесь, что значения каждого дня совпадают с отправленными в Шаге D — включая булевы флаги и окно продолжительности пребывания.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}?startDate=2026-09-01&endDate=2026-09-07" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

Ответ — объект PropertyRoomRateWithRateList. Его массив rates должен содержать семь записей, по одной на каждый день, с полями amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay и maxLengthOfStay, которые вы загрузили. Несовпадение любого поля означает, что соответствующий PUT из Шага D не сработал как ожидалось — исправьте и проверьте заново перед продолжением.

Шаг F — Сделайте тестовое бронирование

Откройте в браузере следующий URL, заменив <your-slug> на slug аккаунта отеля, опубликованного в Предварительных условиях:

https://staging-book.wink.travel/hotel/<your-slug>

Выберите даты заезда и выезда, полностью попадающие в неделю сертификации, выберите комбинацию типа номера и тарифного плана, которую вы сертифицировали, и завершите бронирование. В staging используется тестовый платежный путь — реальная карта не списывается.

После отображения страницы подтверждения запишите код бронирования (формат WNKxxxxx), показанный гостю.

Шаг G — Получите бронирование

Получите все бронирования, созданные для вашей тестовой недвижимости в интервале, охватывающем время бронирования.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/list?startDate=2026-09-01T00:00:00&endDate=2026-09-08T00:00:00" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

Найдите запись, у которой bookingCode совпадает с записанным в Шаге F кодом. Запишите ее bookingIdentifier. Затем получите это бронирование:

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/{bookingIdentifier}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

Ответ — объект PropertyBooking. Импортируйте его в свой PMS / UI channel manager и убедитесь, что оператор видит корректно:

• bookingCode, bookingIdentifier, createdDate
• Гостя: firstName, lastName, email
• totalAmount + currencyCode (чистая сумма, которую отель получает за все номера)
• paymentMethodType, paymentMethodStatus, salesChannelName
• Каждую запись в roomStays: guestRoomName, ratePlanName, adults, children, startDate, endDate и сумму по номеру

Сделайте скриншот бронирования в вашем UI — этот скриншот будет одним из обязательных доказательств.

Шаг H — Отмените бронирование и проверьте

Попросите команду Wink отменить тестовое бронирование от вашего имени (или отмените сами через Extranet аккаунта отеля, если у вас есть права). Затем повторно получите то же бронирование, как в Шаге G.

Убедитесь, что в ответе теперь есть:

• cancelled: true
• Заполненный временной штамп cancelDate
• paymentMethodStatus, отражающий статус отмены (CANCELLED, PARTIALLY_REFUNDED или FULLY_REFUNDED в зависимости от политики возврата)

Импортируйте обновленное бронирование в ваш UI и убедитесь, что оператор видит отмену — статус, время отмены и индикатор возврата, поддерживаемый вашим UI. Сделайте второй скриншот отмененного бронирования. Это финальный доказательный артефакт.

Шаг I — Отправьте пакет доказательств

Упакуйте следующее в один архив (.zip) с именем wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip:

1. Транскрипт API. Для каждого запроса из Шагов A–H сохраните полный HTTP-запрос (метод, URL, заголовки запроса с замазанным значением Authorization и JSON-тело для PUT запросов) и полный HTTP-ответ (код статуса, заголовки и JSON-тело). Структурируйте транскрипт так, чтобы каждая пара запрос/ответ была четко помечена соответствующим шагом (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json и т.д.). Подойдут plain-text .http файлы или единый .har экспорт.

2. Скриншот UI: активное бронирование. Скриншот из Шага G с отображением сертификационного бронирования в вашем PMS / channel manager UI, где четко видны гость, даты, тип номера, тарифный план и сумма.

3. Скриншот UI: отмененное бронирование. Скриншот из Шага H с тем же бронированием в вашем UI после отмены, где четко видны статус отмены и временная метка.

4. Резюме сертификации. Краткий README.md в архиве с перечислением:

   • Названия и версии вашего channel manager / PMS.
   • Использованных managingEntityIdentifier, propertyIdentifier, masterRateIdentifier и bookingIdentifier.
   • Slug отеля в staging (тот самый <your-slug> из https://staging-book.wink.travel/hotel/<your-slug>).
   • Даты недели сертификации (День 1 → День 7 в формате ISO-8601).
   • Имя и email инженера, проводившего сертификацию.

Отправьте архив вашему контактному лицу Wink интеграций. Wink проверит, уточнит при необходимости и — при успешном прохождении — переведет статус вашего аккаунта Affiliate / Channel Manager из PENDING_APPROVAL в ACTIVE. После этого ваша интеграция будет готова к запуску в production.

Совет

Автоматизируйте захват транскриптов. Семь PUT запросов в Шаге D и чтение в Шаге E — самые частые причины сбоев сертификации. Интерактивный HTTP-клиент, сохраняющий каждый запрос и ответ, сэкономит вам повторный запуск при ошибке в десятичной точке.

Уведомления через вебхуки

Вы можете подписаться на события webhook channel manager для получения уведомлений в реальном времени:

• channel-manager.update.rate — получено обновление тарифа.
• channel-manager.update.availability — получено обновление доступности.
• channel-manager.update — общее обновление channel manager.

Подробности смотрите в Каталоге событий вебхуков.

Дополнительные материалы

• Channel Manager API — Полная документация по API.
• Поставщики тарифов — Управление поставщиками тарифов в Extranet.
• Каталог событий вебхуков — Все доступные события для подписки.
• Разработка на Wink — Обзор платформы для разработчиков.