Додайте свій Channel Manager
Цей посібник проведе розробників channel manager та PMS через повний процес інтеграції з Wink — від створення облікових записів до відображення інвентарю та запуску першого повного тесту.
Середовища
Section titled “Середовища”API Channel Manager (Integrations) доступний у двох середовищах. Використовуйте staging для всього розроблення та сертифікації; переходьте до production лише при запуску.
| Середовище | Базова URL |
|---|---|
| Production | https://integrations.wink.travel |
| Staging | https://staging-integrations.wink.travel |
Посилання на API
Section titled “Посилання на API”API Channel Manager відповідає стандартам протоколу OTA (SOAP/XML) для сумісності з існуючими системами гостинності. Почніть з ознайомлення з документацією партнерських кінцевих точок:
Channel Manager API — Партнерські кінцеві точки
Кроки інтеграції
Section titled “Кроки інтеграції”-
Створіть обліковий запис користувача Wink
Зареєструйтесь на staging-app.wink.travel. Усі наведені нижче кроки виконуються у staging — повний процес потрібно повторити у production перед запуском.
-
Створіть обліковий запис Affiliate / Channel Manager
Під своїм новим користувачем створіть обліковий запис і виберіть тип облікового запису Affiliate / Channel Manager. Саме цей обліковий запис буде використовуватися для автентифікації вашої інтеграції.
-
Зареєструйте додаток і отримайте перший токен
Створіть Application і прив’яжіть його до облікового запису channel manager зі кроку 2. Виберіть тип клієнта MACHINE_2_MACHINE — це інтеграція сервер-сервер без перенаправлення кінцевого користувача. Негайно скопіюйте Client ID та Secret Key; секретний ключ показується лише один раз і не може бути отриманий повторно.
Додаток створює токен доступу, який кожен виклик у цьому посібнику передає як
Authorization: Bearer <access_token>. Обміняйте свої облікові дані на токен за допомогою грантуclient_credentialsнаhttps://staging-iam.wink.travel/oauth2/token, запитуючи областіintegrations.read integrations.write. Зробіть це перед тим, як рухатися далі — без токена ви не зможете отримати ідентифікатори облікових записів або звертатися до будь-якої кінцевої точки Channel Manager. Детальніше див. у розділі Authentication про повний процес, хост production та повний каталог областей. -
Створіть обліковий запис готелю
Під тим самим користувачем створіть другий обліковий запис і виберіть тип облікового запису Hotel. Це дасть вам власність, яку можна використовувати для тестування без залучення реального готелю.
-
Підтвердіть, що обидва облікові записи схвалені
Жоден обліковий запис не можна використовувати, доки він не буде схвалений: несхвалений обліковий запис channel manager не відображається у списку channel manager жодного готелю, а несхвалений готель не повертається API.
- Staging — схвалення автоматичне. Обидва облікові записи доступні одразу після створення, і нічого додатково запитувати не потрібно.
- Production — схвалення ручне. Надішліть контактній особі Wink інтеграцій імена обох облікових записів та користувача, під яким вони створені, і дочекайтеся підтвердження перед продовженням.
-
Зв’яжіть два облікові записи
Увійдіть в обліковий запис Hotel і перейдіть до Channels → Channel manager. Виберіть свій обліковий запис channel manager зі списку — це зв’яже власність з вашою інтеграцією. Якщо ваш обліковий запис відсутній у списку, він ще не схвалений; див. крок 5.
-
Створіть базовий тип кімнати та тарифний план
В обліковому записі Hotel створіть принаймні один тип кімнати та один тарифний план. Вони потрібні, щоб ваша інтеграція могла надсилати оновлення тарифів і доступності або отримувати бронювання.
-
Відобразіть і протестуйте
У вашій системі відобразіть ідентифікатори типу кімнати та тарифного плану, які повертає API. Надішліть оновлення тарифу та доступності, потім зробіть тестове бронювання і перевірте, що кінцева точка отримання бронювання повертає його правильно.
Пошук ідентифікаторів облікових записів
Section titled “Пошук ідентифікаторів облікових записів”Кожен шлях 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, щоб бути доступним для бронювання або видимим у Channel Manager API. Ваш обліковий запис channel manager буде мати статусPENDING_APPROVALдо проходження сертифікації; це очікувано і не блокує розробку.
Сертифікація
Section titled “Сертифікація”Сертифікація — це спосіб довести (і для Wink підтвердити), що ваша інтеграція правильно відображає інвентар, надсилає тарифи та доступність, а також отримує бронювання повністю. Вона розроблена як самообслуговування: ви керуєте кожним кроком зі своєї системи і подаєте один пакет доказів наприкінці. Wink перевіряє пакет і, у разі успіху, переводить ваш обліковий запис Affiliate / Channel Manager зі статусу PENDING_APPROVAL у ACTIVE.
Сертифікація виконується повністю у середовищі staging
(https://staging-integrations.wink.travel). У цьому розділі не використовується production.
Що ви доведете
Section titled “Що ви доведете”-
Аутентифікація. Ваш OAuth2 клієнт може отримати токен доступу і успішно викликати кінцеву точку
/pingдля вашого облікового запису Affiliate / Channel Manager. -
Відображення інвентарю. Ви можете отримати список готелів, підключених до вашого облікового запису, отримати master rate (комбінація типу кімнати × тарифного плану), який ви налаштували, і правильно визначити
masterRateIdentifier, на який буде орієнтована ваша система. -
Надсилання тарифів і доступності. Ви можете оновити всі сім днів сертифікаційного тижня окремо — різні комбінації суми, кількості, прапорців закриття при заїзді / виїзді та мінімальної/максимальної тривалості перебування для кожного дня — і прочитати точні значення назад з Wink.
-
Отримання бронювання. Ви можете отримати реальне тестове бронювання, зроблене для вашої тестової власності, відобразити його у власному інтерфейсі PMS/CM з правильними даними про перебування, гостя та сумою, а потім відобразити скасування після того, як Wink позначить бронювання як скасоване.
Передумови
Section titled “Передумови”Перед початком сертифікації виконайте кроки 1–7 з розділу Кроки інтеграції, щоб мати:
- Користувача Wink у staging з обліковим записом Affiliate / Channel Manager та обліковим записом Hotel, пов’язаним з ним (Channels → Channel manager). Облікові записи staging схвалюються автоматично, тому нічого додатково запитувати не потрібно.
- Принаймні один тип кімнати та один тарифний план, створені в обліковому записі Hotel. Опублікуйте готель, щоб він був доступний для бронювання на
https://staging-book.wink.travel/hotel/<your-slug>. - Зареєстрований додаток під вашим обліковим записом Affiliate / Channel Manager з Client ID, Secret Key та областями
integrations.read integrations.write(див. Authentication). managingEntityIdentifierвашого облікового запису Affiliate / Channel Manager таpropertyIdentifierвашого облікового запису Hotel (обидва — UUID, див. Пошук ідентифікаторів облікових записів).
Загальні конвенції запитів
Section titled “Загальні конвенції запитів”Кожен запит у цьому розділі використовує такі заголовки:
Authorization: Bearer <access_token>Wink-Version: 2.0Accept: application/json<access_token>отримується за грантомclient_credentialsнаhttps://staging-iam.wink.travel/oauth2/token— див. Authentication.- Заголовок
Wink-Versionобов’язковий; без нього запит не буде спрямований до v2 JSON API. Content-Type: application/jsonдодається уPUTзапитах з тілом.
У прикладах нижче заповнювачі відповідають значенням, які ви отримали у Передумовах:
| Заповнювач | Значення |
|---|---|
{managingEntityIdentifier} | ID вашого облікового запису Affiliate / Channel Manager (UUID) — див. Пошук ідентифікаторів облікових записів. |
{propertyIdentifier} | ID облікового запису Hotel (власність), пов’язаний з обліковим записом CM. |
{masterRateIdentifier} | Master rate (комбінація типу кімнати × тарифного плану), який ви сертифікуєте. |
{bookingIdentifier} | ID тестового бронювання у staging, отриманий із виклику списку бронювань. |
Крок A — Ping
Section titled “Крок 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 — Список власностей
Section titled “Крок 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.
Крок C — Отримання master rates
Section titled “Крок C — Отримання master rates”Отримайте власність разом з усіма master rate (комбінаціями типу кімнати × тарифного плану), які вона публікує. Виберіть той, який ви плануєте сертифікувати, і запишіть його 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. Кожен запис містить тип кімнати, тарифний план, обмеження по кількості гостей, базовий тариф і модифікатори тарифу, які потрібно зберегти при надсиланні щоденних тарифів.
Крок D — Завантаження сертифікаційного тижня
Section titled “Крок 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 | Відсутність доступності. |
| 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). Збережіть цю відповідь — вона буде частиною ваших доказів.
Крок E — Зчитування сертифікаційного тижня
Section titled “Крок 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 — Зробіть тестове бронювання
Section titled “Крок F — Зробіть тестове бронювання”Відкрийте у браузері таку URL, замінивши <your-slug> на slug облікового запису Hotel, який ви опублікували у Передумовах:
https://staging-book.wink.travel/hotel/<your-slug>Виберіть дати заїзду та виїзду, які повністю входять у ваш сертифікаційний тиждень, оберіть комбінацію типу кімнати + тарифного плану, яку ви сертифікували, і завершіть бронювання. Staging використовує тестовий платіжний шлях — реальна карта не списується.
Після відображення сторінки підтвердження запишіть код бронювання (формат WNKxxxxx), який бачить гість.
Крок G — Отримайте бронювання
Section titled “Крок 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 / channel manager і переконайтеся, що оператор бачить коректно:
bookingCode,bookingIdentifier,createdDate- Гість:
firstName,lastName,email totalAmount+currencyCode(чиста сума, яку отримує готель за всі кімнати)paymentMethodType,paymentMethodStatus,salesChannelName- Кожен запис у
roomStays:guestRoomName,ratePlanName,adults,children,startDate,endDateта сума за кімнату
Зробіть скріншот бронювання у вашому інтерфейсі — цей скріншот є одним із необхідних доказів.
Крок H — Скасуйте бронювання і перевірте
Section titled “Крок H — Скасуйте бронювання і перевірте”Попросіть команду Wink скасувати тестове бронювання від вашого імені (або скасуйте його самостійно через Extranet облікового запису Hotel, якщо маєте дозвіл). Потім повторно отримайте те саме бронювання за викликом із Кроку G.
Переконайтеся, що у відповіді тепер є:
cancelled: true- Заповнений часовий штамп
cancelDate paymentMethodStatus, що відображає статус скасування (CANCELLED,PARTIALLY_REFUNDEDабоFULLY_REFUNDEDзалежно від політики повернення)
Імпортуйте оновлене бронювання у ваш інтерфейс і переконайтеся, що оператор бачить скасування — статус, часовий штамп скасування та будь-який індикатор повернення, який підтримує ваш UI. Зробіть другий скріншот скасованого бронювання у вашому UI. Це останній доказ.
Крок I — Надішліть пакет доказів
Section titled “Крок I — Надішліть пакет доказів”Упакуйте наступне в один архів (.zip) з назвою
wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip:
-
Транскрипт 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тощо). Прийнятні формати — прості текстові файли.httpабо один експорт.har. -
Скріншот UI: активне бронювання. Скріншот із Кроку G, що показує сертифікаційне бронювання у вашому PMS / channel manager UI з чітко видимими гостем, датами, типом кімнати, тарифним планом і сумою.
-
Скріншот UI: скасоване бронювання. Скріншот із Кроку H, що показує те саме бронювання у вашому UI після скасування з чітко видимим статусом скасування та часовим штампом.
-
Підсумок сертифікації. Короткий
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.
Сповіщення через webhook
Section titled “Сповіщення через webhook”Ви можете підписатися на події webhook channel manager, щоб отримувати сповіщення в режимі реального часу:
channel-manager.update.rate— отримано оновлення тарифу.channel-manager.update.availability— отримано оновлення доступності.channel-manager.update— загальне оновлення channel manager.
Деталі див. у Каталозі подій webhook.
Додаткове читання
Section titled “Додаткове читання”- Channel Manager API — Повна документація кінцевих точок API.
- Channel manager — Управління постачальниками тарифів в Extranet.
- Каталог подій webhook — Всі доступні для підписки події.
- Build on Wink — Огляд платформи для розробників.
