Швидкий старт
Цей посібник проведе вас від нічого до робочої інтеграції приблизно за 30 хвилин. Наприкінці ви матимете:
- актуальні ціни на готелі в місті через Partner API,
- посилання для бронювання, яке зараховує бронювання на ваш рахунок,
- тестове бронювання та webhook, що повідомляє про його створення.
Усе відбувається у стенді, нашому тестовому середовищі. Вам не потрібно просити у нас доступ, а перехід у продакшн пізніше також не потребує схвалення.
Чи підходить вам цей посібник?
Section titled “Чи підходить вам цей посібник?”| Ви хочете… | Почніть тут |
|---|---|
| Показувати готелі у вашому додатку, сайті або AI-продукті та направляти мандрівників на бронювання, отримуючи комісію | Цей посібник |
| Бронювати від імені ваших клієнтів як ліцензоване туристичне агентство | Цей посібник до Кроку 5, потім Бронювання як туристичне агентство |
| Вбудувати бронювані готелі без написання інтеграції | Веб-компоненти |
| Дозволити AI-агенту шукати та бронювати | MCP Servers та Agentic Payments |
| Підключити channel manager або PMS | Додати ваш Channel Manager |
Як це працює
Section titled “Як це працює”Ви використовуєте Partner API для пошуку готелів та їх актуальних цін. Кожен готель має стабільний urlName. Ви перетворюєте його на посилання на Wink Booking Engine, book.wink.travel, передаючи ваші ідентифікатори. Мандрівник бронює та оплачує там, а бронювання зараховується на ваш рахунок.
Перед початком
Section titled “Перед початком”Вам знадобиться:
grpcurl, або Postman чи Insomnia. Partner API працює через gRPC, а не REST.curl.
Крок 1: Створіть обліковий запис у стенді
Section titled “Крок 1: Створіть обліковий запис у стенді”Стенд повністю відокремлений від продакшну, має власні логіни та облікові записи.
-
Перейдіть на staging-app.wink.travel, натисніть
Sign-In / Registerі зареєструйтесь. -
У лівому меню натисніть
Accounts, потімCreateі оберіть I am an Affiliate. Бронювання, які ви надсилаєте, зараховуються на цей рахунок. Див. Створення облікового запису.
Крок 2: Створіть додаток
Section titled “Крок 2: Створіть додаток”Додаток надає вашому коду облікові дані.
-
На картці вашого облікового запису натисніть
Actions>Manage account, потім вкладкуApplications. -
Натисніть
Create new application, дайте йому назву та оберіть тип клієнта Machine-to-machine. -
У розділі scopes виберіть Inventory & rates (читання). Partner API перевіряє наявність
inventory.read. -
Натисніть
Create applicationі скопіюйте Client ID та Client secret. Секрет показується один раз і пізніше не відновлюється.
Див. Applications для інших типів клієнтів і scopes.
Крок 3: Отримайте токен доступу
Section titled “Крок 3: Отримайте токен доступу”curl -X POST https://staging-iam.wink.travel/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=<YOUR_CLIENT_ID>" \ -d "client_secret=<YOUR_CLIENT_SECRET>" \ -d "scope=inventory.read"Збережіть access_token з відповіді:
export WINK_TOKEN=<access_token>Токени мають термін дії. У вашому коді використовуйте бібліотеку OAuth2 для отримання та оновлення токенів. Див. Аутентифікація.
Якщо запит токена відхилено, відповідь містить JSON з кодом error:
error | HTTP статус | Звичайна причина |
|---|---|---|
invalid_client | 401 | Неправильний client ID або secret, або використання продакшн-облікових даних на staging-iam |
invalid_scope | 400 | Запит містить scope, на який додаток не зареєстрований |
unauthorized_client | 400 | Додаток не має права використовувати grant client_credentials |
invalid_request | 400 | Відсутній обов’язковий параметр, наприклад, тіло у форматі JSON замість форми |
Крок 4: Знайдіть ID вашого облікового запису
Section titled “Крок 4: Знайдіть ID вашого облікового запису”Кожен виклик Partner API вказує обліковий запис, від імені якого ви дієте, у заголовку managing-entity-id. Перелічіть облікові записи, для яких ваш токен має права:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -d '{}' \ staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccountsСкопіюйте accountId афілійованого облікового запису з Кроку 1:
export WINK_ACCOUNT_ID=<accountId>Крок 5: Пошук готелів у місті
Section titled “Крок 5: Пошук готелів у місті”У стенді є тестові готелі з доступністю в Бангкоку, тому цей пошук використовує його slug, bangkok-thailand:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -H "managing-entity-id: $WINK_ACCOUNT_ID" \ -d '{ "urlName": "bangkok-thailand", "userSession": { "itinerary": { "startDate": "2026-12-01", "nights": 2, "room": { "adults": 2 } }, "currencyCode": "USD", "languageCode": "en" } }' \ staging-partner.wink.travel:443 wink.partner.v1.Search/SearchByCityВикористовуйте дату заїзду у майбутньому; минулі дати відхиляються. Кожен результат містить:
name,starRatingтаheroImageUrl— достатньо для відображення рядка результату,roomTypes— актуальні пропозиції, починаючи з найдешевшої кімнати,urlName— slug, потрібний для посилання на бронювання.
Ціни — цілі числа у мінорних одиницях: поділіть на 10 у степені currencyExponent з відповіді (2 для USD, отже 12500 — це $125.00).
Не знаєте slug міста? Знайдіть його через wink.partner.v1.Lookup/Search. Для повного вмісту об’єкта використовуйте сервіс Content. Повний опис викликів у Partner API reference.
Крок 6: Створіть посилання для бронювання
Section titled “Крок 6: Створіть посилання для бронювання”https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID><urlName>—urlNameготелю з Кроку 5.client-id— Client ID вашого додатку з Кроку 2.configuration-id— ваш ID кастомізації:Manage account>Customizations. Кастомізація також встановлює ваш брендинг, мову за замовчуванням і валюту на сторінці бронювання.
Передайте пошук мандрівника
Section titled “Передайте пошук мандрівника”Додайте дати, гостей, мову та валюту мандрівника до того самого посилання, щоб сторінка готелю відкривалась із заповненими полями:
https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>&sd=2027-03-14&n=2&rc=a2&l=en&c=USD| Параметр | Значення | Приклад |
|---|---|---|
sd | Дата заїзду | sd=2027-03-14 |
n або ed | Кількість ночей або дата виїзду | n=2 або ed=2027-03-16 |
rc | Гості на кімнату | rc=a2 (2 дорослих) |
l | Мова відображення | l=en |
c | Валюта відображення | c=USD |
p | Промокод | p=ABC123 |
Ці параметри переважають налаштування за замовчуванням у вашій кастомізації. Повний формат rc, включно з дітьми та кількома кімнатами, описаний у Посібнику з кнопки Book Now.
Посилання відкриває сторінку готелю; воно не може заздалегідь вибрати кімнату чи тариф. Мандрівник обирає кімнату на сторінці готелю за актуальною ціною.
Див. Пряме посилання для посилання на головну сторінку системи бронювання замість окремого готелю.
Крок 7: Зробіть тестове бронювання
Section titled “Крок 7: Зробіть тестове бронювання”Відкрийте ваше посилання, оберіть дати та кімнату, і оплатіть за допомогою тестової картки Stripe, наприклад 4242 4242 4242 4242 з будь-якою майбутньою датою закінчення та будь-яким CVC. У стенді реальна карта не списується. Запам’ятайте код бронювання на сторінці підтвердження; він починається з WNK.
Крок 8: Отримуйте сповіщення про бронювання
Section titled “Крок 8: Отримуйте сповіщення про бронювання”-
У Portal перейдіть до
Applications > Webhooksі додайте endpoint, який приймаєPOSTзапити. -
Підпишіться на
booking.createабо залиште список подій порожнім, щоб отримувати всі події під час розробки. -
Надішліть тестову подію собі, потім зробіть ще одне тестове бронювання і перевірте, що подія прийшла.
Перевіряйте підпис кожної доставки перед тим, як довіряти їй. Див. Інтеграція Webhook та Каталог подій Webhook.
Крок 9: Перейдіть у продакшн
Section titled “Крок 9: Перейдіть у продакшн”Для розробників немає кроку схвалення. (Облікові записи туристичних агентств сертифікуються спочатку; див. нижче.) Коли ваша інтеграція працює у стенді:
-
Створіть обліковий запис і додаток на app.wink.travel, як у Кроках 1 і 2. Облікові дані не переносяться між середовищами.
-
Видаліть
staging-з усіх хостів:Стенд Продакшн https://staging-iam.wink.travelhttps://iam.wink.travelstaging-partner.wink.travel:443partner.wink.travel:443https://staging-book.wink.travelhttps://book.wink.travel -
Знову знайдіть ID вашого продакшн-рахунку (Крок 4) та ID кастомізації (Крок 6). Вони відрізняються від стенду.
Використання Partner API рахується у готельних ночах, з безкоштовним місячним лімітом. Див. Partner API для інформації про тарифи та обмеження.
Бронювання як туристичне агентство
Section titled “Бронювання як туристичне агентство”Якщо ваш обліковий запис — ліцензоване туристичне агентство, вам не потрібно направляти мандрівників на book.wink.travel: ви можете створювати бронювання безпосередньо через wink.partner.v1.Booking/CreateBooking і керувати ними через інші виклики Booking. Інші облікові записи направляють мандрівників на посилання для бронювання.
Облікові записи туристичних агентств сертифікуються: Wink перевіряє реєстрацію кожного агентства перед тим, як воно зможе бронювати. Агентства, які хочуть самостійно приймати оплату від клієнтів як продавці, повинні бронювати через Partner API та отримати письмовий дозвіл Wink. Див. Початок роботи як туристичне агентство та Partner API reference.
Наступні кроки
Section titled “Наступні кроки”- Згенеруйте типізований клієнт з
.protoсхеми замість ручного викликуgrpcurl. - Підключіть MCP server і використовуйте AI Skills, щоб ваш помічник з кодування написав інтеграцію з живим API.
- Ознайомтеся з повним списком середовищ і хостів.
