Бърз старт
Това ръководство ви води от нищо до работеща интеграция за около 30 минути. В края ще имате:
- актуални цени за хотели в град, от Partner API,
- линк за резервация, който кредитира резервациите към вашия акаунт,
- тестова резервация и webhook, който ви уведомява, че е направена.
Всичко се случва в staging, нашата тестова среда. Не е нужно да ни искате достъп, а преминаването към продукция по-късно не изисква одобрение.
Това ли е правилното ръководство за вас?
Section titled “Това ли е правилното ръководство за вас?”| Искате да… | Започнете тук |
|---|---|
| Показвате хотели в приложението, сайта или AI продукта си и изпращате пътници да резервират, печелейки комисионна | Това ръководство |
| Резервирате от името на вашите клиенти като лицензирана туристическа агенция | Това ръководство до Стъпка 5, след което Резервация като туристическа агенция |
| Вградите резервационни хотели без да пишете интеграция | Web Components |
| Позволите на 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: Създайте staging акаунт
Section titled “Стъпка 1: Създайте staging акаунт”Staging е напълно отделен от продукцията, с отделни входове и акаунти.
-
Отидете на staging-app.wink.travel, кликнете
Sign-In / Registerи се регистрирайте. -
Кликнете
Accountsв лявото меню, след товаCreateи изберете I am an Affiliate. Резервациите, които изпращате, се кредитира към този акаунт. Вижте Create Account.
Стъпка 2: Създайте приложение
Section titled “Стъпка 2: Създайте приложение”Приложението дава на вашия код идентификационните му данни.
-
В картата на акаунта си кликнете
Actions>Manage account, след това табаApplications. -
Кликнете
Create new application, дайте му име и изберете Machine-to-machine като тип клиент. -
Под scopes изберете Inventory & rates (read). Partner API проверява за
inventory.read. -
Кликнете
Create applicationи копирайте Client ID и Client secret. Секретът се показва веднъж и не може да бъде възстановен по-късно.
Вижте Applications за другите типове клиенти и scopes.
Стъпка 3: Вземете access token
Section titled “Стъпка 3: Вземете access token”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 библиотека за вземане и обновяване. Вижте Authentication.
Ако заявката за токен е отхвърлена, отговорът е 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: Намерете вашия account ID
Section titled “Стъпка 4: Намерете вашия account ID”Всяко повикване към Partner API посочва акаунта, за който действате, в хедър managing-entity-id. Избройте акаунтите, за които вашият токен може да действа:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -d '{}' \ staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccountsКопирайте accountId на affiliate акаунта от Стъпка 1:
export WINK_ACCOUNT_ID=<accountId>Стъпка 5: Търсете хотели в град
Section titled “Стъпка 5: Търсете хотели в град”Staging има тестови хотели с наличност в Банкок, затова тази заявка използва неговия 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 справочникът документира всяко повикване.
Стъпка 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е вашият customization 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 |
Тези параметри презаписват настройките по подразбиране от персонализацията ви. Ръководството за Book Now бутон описва пълния формат на rc, включително деца и няколко стаи.
Линкът отваря страницата на хотела; не може да избере предварително стая или цена. Пътникът избира стаята на страницата на хотела, на актуалната цена.
Вижте Linking directly за директно свързване към началната страница на резервационния двигател вместо към един хотел.
Стъпка 7: Направете тестова резервация
Section titled “Стъпка 7: Направете тестова резервация”Отворете линка си, изберете дати и стая и платете с Stripe тестова карта, например 4242 4242 4242 4242 с произволна бъдеща дата на валидност и произволен CVC. В staging не се таксува реална карта. Запишете кода на резервацията на страницата за потвърждение; започва с WNK.
Стъпка 8: Получавайте известия за резервации
Section titled “Стъпка 8: Получавайте известия за резервации”-
В Portal отидете на
Applications > Webhooksи добавете endpoint, който приемаPOSTзаявки. -
Абонирайте се за
booking.create, или оставете списъка с събития празен, за да получавате всичко по време на разработка. -
Изпратете си тестово събитие, след това направете още една тестова резервация и наблюдавайте пристигането ѝ.
Проверявайте подписа на всяка доставка преди да ѝ се доверите. Вижте Webhook Integration и Webhook Events Catalog.
Стъпка 9: Преминете в продукция
Section titled “Стъпка 9: Преминете в продукция”Няма одобрение за разработчици. (Акаунтите на туристически агенции се сертифицират първо; вижте по-долу.) Когато интеграцията ви работи в staging:
-
Създайте акаунт и приложение на app.wink.travel, както в Стъпки 1 и 2. Идентификационните данни не се пренасят между средите.
-
Премахнете
staging-от всеки хост:Staging Продукция https://staging-iam.wink.travelhttps://iam.wink.travelstaging-partner.wink.travel:443partner.wink.travel:443https://staging-book.wink.travelhttps://book.wink.travel -
Потърсете отново production account ID (Стъпка 4) и customization ID (Стъпка 6). Те са различни от staging.
Използването на Partner API се измерва в хотел-нощи, с безплатен месечен лимит. Вижте Partner API за цени и ограничения.
Резервация като туристическа агенция
Section titled “Резервация като туристическа агенция”Ако вашият акаунт е лицензирана туристическа агенция, не е нужно да изпращате пътници към book.wink.travel: можете да създавате резервации директно с wink.partner.v1.Booking/CreateBooking и да ги управлявате с другите Booking повиквания. Другите акаунти изпращат пътниците към линка за резервация.
Акаунтите на туристически агенции се сертифицират: Wink преглежда регистрацията на всяка агенция преди да може да резервира. Агенциите, които искат сами да събират плащания от клиентите си като търговец на запис, трябва да резервират чрез Partner API и да получат писмено одобрение от Wink. Вижте Getting Started as a Travel Agency и Partner API справочника.
Следващи стъпки
Section titled “Следващи стъпки”- Генерирайте типизиран клиент от
.protoсхемата вместо да използватеgrpcurlръчно. - Свържете MCP сървъра и използвайте AI Skills, за да накарате вашия кодиращ асистент да напише интеграцията към живия API.
- Прочетете пълния списък с средите и хостовете.
