Добавяне на Вашия Channel Manager
Това ръководство води разработчиците на channel manager и PMS през целия процес на интеграция с Wink — от създаване на акаунти до картографиране на инвентара и провеждане на първия ви тест от край до край.
Околна среда
Section titled “Околна среда”Channel Manager (Integrations) API е наличен в две среди. Използвайте staging за цялото разработване и сертифициране; преминете към production само при пускане в експлоатация.
| Среда | Основен URL |
|---|---|
| Production | https://integrations.wink.travel |
| Staging | https://staging-integrations.wink.travel |
API справочник
Section titled “API справочник”Channel Manager API следва стандартите на OTA протокола (SOAP/XML) за съвместимост с вече съществуващи системи за хотелиерство. Започнете с преглед на документацията за партньорските крайни точки:
Channel Manager API — Партньорски крайни точки
Стъпки за интеграция
Section titled “Стъпки за интеграция”-
Създайте Wink потребителски акаунт
Регистрирайте се на staging-app.wink.travel. Всички стъпки по-долу използват staging — ще повторите целия процес в production преди пускане в експлоатация.
-
Създайте вашия Affiliate / Channel Manager акаунт
Под новия потребител създайте акаунт и изберете типа акаунт Affiliate / Channel Manager. Това е акаунтът, с който вашата интеграция ще се удостоверява.
-
Регистрирайте приложение и издайте първия си токен
Създайте Приложение и го свържете с channel manager акаунта от стъпка 2. Изберете MACHINE_2_MACHINE като тип клиент — това е интеграция сървър към сървър без пренасочване към краен потребител. Копирайте Client ID и Secret Key веднага; секретният ключ се показва само веднъж и не може да бъде възстановен.
Приложението издава bearer токена, който всеки повик в това ръководство носи като
Authorization: Bearer <access_token>. Разменете вашите идентификационни данни за такъв токен чрезclient_credentialsgrant къмhttps://staging-iam.wink.travel/oauth2/token, като заявите обхватитеintegrations.read integrations.write. Направете това преди да продължите — не можете да търсите идентификатори на акаунти или да достигнете до каквато и да е крайна точка на Channel Manager без токен. Вижте Authentication за пълния поток, production хоста и пълния каталог на обхватите. -
Създайте хотелски акаунт
Под същия потребител създайте втори акаунт и изберете типа акаунт Hotel. Това ви дава имот, който можете да използвате за тестове без да включвате реален хотел.
-
Потвърдете, че и двата акаунта са одобрени
Нито един акаунт не може да се използва, докато не бъде одобрен: неодобрен channel manager акаунт не се показва в списъка с channel manager-и на хотел, а неодобрен хотел не се връща от API-то.
- Staging — одобрението е автоматично. И двата акаунта са използваеми веднага след създаването им и не е необходимо да се прави заявка.
- Production — одобрението е ръчно. Изпратете на вашия контакт за Wink интеграции имената на двата акаунта и потребителя, под който са, след което изчакайте потвърждение преди да продължите.
-
Свържете двата акаунта
Влезте в хотелския акаунт и отидете на Channels → Channel manager. Изберете вашия channel manager акаунт от списъка — това свързва имота с вашата интеграция. Ако акаунтът ви не е в списъка, той все още не е одобрен; вижте стъпка 5.
-
Създайте основен тип стая и тарифен план
В хотелския акаунт създайте поне един тип стая и един тарифен план. Те са необходими преди вашата интеграция да може да изпраща цени и наличности или да извлича резервации.
-
Картографирайте и тествайте
Във вашата собствена система картографирайте идентификаторите на тип стая и тарифен план, върнати от API-то. Изпратете актуализация на цена и наличност, след това направете тестова резервация и проверете дали крайният пункт за извличане на резервации я връща правилно.
Намиране на идентификаторите на вашия акаунт
Section titled “Намиране на идентификаторите на вашия акаунт”Всяка пътека на Channel Manager API е ограничена до вашия собствен акаунт:
/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 клиент може да получи access token и успешно да извика
/pingкрайна точка срещу вашия Affiliate / Channel Manager акаунт. -
Картографиране на инвентара. Можете да изброите хотела(ите), свързани с вашия акаунт, да извлечете master rate (комбинация тип стая × тарифен план), който сте конфигурирали, и правилно да идентифицирате
masterRateIdentifier, към който вашата система ще насочва. -
Изпращане на цени и наличности. Можете да актуализирате всички седем дни от седмицата за сертификация независимо — с различна комбинация от сума, количество, флагове за затваряне при пристигане / заминаване и минимална/максимална продължителност на престой за всеки ден — и да прочетете точно тези стойности обратно от Wink.
-
Извличане на резервация. Можете да извлечете реална staging резервация, направена за вашия тестов имот, да я покажете във вашия PMS/CM интерфейс с правилната стая, гост и обща сума, след което да отразите анулиране, след като Wink маркира резервацията като анулирана.
Предварителни условия
Section titled “Предварителни условия”Преди да започнете сертификацията, завършете стъпки 1–7 от Стъпки за интеграция, така че да имате:
- Wink потребител в staging с Affiliate / Channel Manager акаунт и Hotel акаунт, свързани помежду си (Channels → Channel manager). Staging акаунтите се одобряват автоматично, така че няма нужда от заявка.
- Поне един тип стая и един тарифен план създадени в хотелския акаунт. Публикувайте
хотела, за да може да се резервира на
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на вашия хотелски акаунт (и двете са UUID — вижте Намиране на идентификаторите на акаунта).
Общи конвенции за заявки
Section titled “Общи конвенции за заявки”Всяка заявка в този раздел използва следните заглавки:
Authorization: Bearer <access_token>Wink-Version: 2.0Accept: application/json<access_token>идва отclient_credentialsgrant къмhttps://staging-iam.wink.travel/oauth2/token— вижте Authentication.- Заглавката
Wink-Versionе задължителна; ако я пропуснете, няма да се насочи към v2 JSON API. Content-Type: application/jsonсе добавя приPUTзаявки с тяло.
В примерите по-долу, плейсхолдерите съответстват на стойностите, които сте събрали в Предварителни условия:
| Плейсхолдер | Значение |
|---|---|
{managingEntityIdentifier} | Вашият Affiliate / Channel Manager акаунт ID (UUID) — вижте Намиране на идентификаторите на акаунта. |
{propertyIdentifier} | Хотелският акаунт (имот) ID, който сте свързали с 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 rates (комбинации тип стая × тарифен план), които публикува. Изберете този, срещу който възнамерявате да сертифицирате, и запишете неговия 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-а на хотелския акаунт, който публикувахте в Предварителни условия:
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 UI и потвърдете,
че всеки от следните елементи се показва правилно на оператор:
bookingCode,bookingIdentifier,createdDate- Гост:
firstName,lastName,email totalAmount+currencyCode(нетната сума, която хотелът получава за всички стаи)paymentMethodType,paymentMethodStatus,salesChannelName- Всеки запис в
roomStays:guestRoomName,ratePlanName,adults,children,startDate,endDateи сума за всяка стая
Направете екранна снимка на резервацията, както се показва във вашия UI — тази снимка е един от изискваните доказателствени артефакти.
Стъпка H — Отменете резервацията и потвърдете
Section titled “Стъпка H — Отменете резервацията и потвърдете”Помолете екипа на Wink да отмени сертификационната резервация от ваше име (или я отменете сами от екстранета на хотелския акаунт, ако имате това разрешение). След това извлечете отново същата резервация с повикването от Стъпка G.
Потвърдете, че отговорът вече показва:
cancelled: true- Попълнен времеви печат
cancelDate paymentMethodStatus, отразяващ жизнения цикъл на анулирането (CANCELLED,PARTIALLY_REFUNDED, илиFULLY_REFUNDEDв зависимост от политиката за възстановяване)
Импортирайте тази обновена резервация във вашия UI и потвърдете, че анулирането е видимо за оператора — статус, времеви печат на анулирането и всеки индикатор за възстановяване, който вашият 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, и т.н.). Приемат се plain-text.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).
- Името и имейла на инженера, който е провел сертификацията.
Изпратете архива на вашия контакт за Wink интеграции. Wink ще прегледа, ще последва при всяко
несъответствие и — при одобрение — ще промени статуса на вашия Affiliate / Channel Manager акаунт от
PENDING_APPROVAL на ACTIVE. След това вашата интеграция е готова за onboarding в 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 — Управление на доставчици на цени в екстранета.
- Каталог на webhook събитията — Всички събития, за които може да се абонирате.
- Build on Wink — Преглед на платформата за разработчици.
