Przejdź do głównej zawartości

Dodaj swojego Channel Managera

Ten przewodnik przeprowadza deweloperów channel managerów i PMS przez cały proces integracji z Wink — od tworzenia kont po mapowanie zasobów i przeprowadzenie pierwszego testu end-to-end.

API Channel Managera (Integracje) jest dostępne w dwóch środowiskach. Używaj staging do całego rozwoju i certyfikacji; przełącz się na produkcję dopiero przy uruchomieniu.

ŚrodowiskoPodstawowy URL
Produkcjahttps://integrations.wink.travel
Staginghttps://staging-integrations.wink.travel

API Channel Managera stosuje standardy protokołu OTA (SOAP/XML) dla kompatybilności z istniejącymi systemami hotelarskimi. Zacznij od przeglądu dokumentacji punktów końcowych partnera:

Channel Manager API — punkty końcowe partnera

  1. Utwórz konto użytkownika Wink

    Zarejestruj się na staging-app.wink.travel. Wszystkie poniższe kroki wykonuj na staging — cały proces powtórz na produkcji przed uruchomieniem.

  2. Utwórz konto Affiliate / Channel Manager

    Pod nowym użytkownikiem utwórz konto i wybierz typ konta Affiliate / Channel Manager. To konto będzie używane do uwierzytelniania integracji.

  3. Zarejestruj aplikację i wygeneruj pierwszy token

    Utwórz Aplikację i powiąż ją z kontem channel managera z kroku 2. Wybierz typ klienta MACHINE_2_MACHINE — to integracja serwer-serwer bez przekierowania użytkownika końcowego. Natychmiast skopiuj Client ID i Secret Key; klucz sekretu jest pokazany tylko raz i nie można go odzyskać.

    Aplikacja generuje token dostępu, który każdy wywołanie w tym przewodniku przesyła jako Authorization: Bearer <access_token>. Wymień swoje dane uwierzytelniające na token używając grant client_credentials pod https://staging-iam.wink.travel/oauth2/token, żądając zakresów integrations.read integrations.write. Zrób to przed kontynuacją — bez tokena nie możesz pobrać identyfikatorów kont ani uzyskać dostępu do żadnego punktu końcowego Channel Managera. Zobacz Uwierzytelnianie dla pełnego przebiegu, hosta produkcyjnego i katalogu zakresów.

  4. Utwórz konto Hotelu

    Pod tym samym użytkownikiem utwórz drugie konto i wybierz typ konta Hotel. To daje Ci nieruchomość do testów bez angażowania prawdziwego hotelu.

  5. Potwierdź zatwierdzenie obu kont

    Żadne konto nie może być używane, dopóki nie zostanie zatwierdzone: niezatwierdzone konto channel managera nie pojawia się na liście channel managerów żadnego hotelu, a niezatwierdzony hotel nie jest zwracany przez API.

    • Staging — zatwierdzenie jest automatyczne. Oba konta są dostępne od razu po utworzeniu i nie trzeba niczego zgłaszać.
    • Produkcja — zatwierdzenie jest ręczne. Prześlij kontaktowi Wink integracji nazwy obu kont i użytkownika, pod którym są, a następnie poczekaj na potwierdzenie przed kontynuacją.
  6. Połącz oba konta

    Zaloguj się na konto Hotelu i przejdź do Kanały → Channel manager. Wybierz swoje konto channel managera z listy — to połączy nieruchomość z Twoją integracją. Jeśli Twoje konto nie jest na liście, nie zostało jeszcze zatwierdzone; zobacz krok 5.

  7. Utwórz podstawowy typ pokoju i plan taryfowy

    W koncie Hotelu utwórz co najmniej jeden typ pokoju i jeden plan taryfowy. Są one wymagane, zanim Twoja integracja będzie mogła przesyłać ceny i dostępność lub pobierać rezerwacje.

  8. Mapuj i testuj

    W swoim systemie zmapuj identyfikatory typu pokoju i planu taryfowego zwrócone przez API. Prześlij aktualizację ceny i dostępności, następnie wykonaj testową rezerwację i zweryfikuj, czy punkt końcowy pobierania rezerwacji zwraca ją poprawnie.

Każda ścieżka API Channel Managera jest ograniczona do Twojego konta:

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

{managingEntityIdentifier} to ID konta (UUID) Twojego konta channel managera — nie hotelu. Pobierz je wraz z ID i aktualnym statusem każdego innego konta, które posiada Twój użytkownik, z Platform API:

Okno terminala
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"

Odpowiedź to tablica kont, które posiadasz:

[
{
"id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
"type": "CHANNEL_MANAGER",
"name": "Twój Channel Manager",
"status": "ACTIVE"
},
{
"id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
"type": "HOTEL",
"name": "Twoja nieruchomość testowa",
"urlName": "twoja-nieruchomosc-testowa",
"status": "ACTIVE"
}
]
  • id wpisu channel managera to Twój {managingEntityIdentifier}.
  • id wpisu HOTEL to Twój {propertyIdentifier}.
  • status pozwala potwierdzić, że każde konto jest zatwierdzone — najbardziej przydatne na produkcji, gdzie zatwierdzenie jest ręczne. Hotel musi mieć status ACTIVE, aby był rezerwowany lub widoczny dla API Channel Managera. Twoje konto channel managera będzie miało status PENDING_APPROVAL aż do przejścia Certyfikacji; jest to oczekiwane i nie blokuje rozwoju.

Certyfikacja to sposób, w jaki udowadniasz — i Wink potwierdza — że Twoja integracja poprawnie mapuje zasoby, przesyła ceny i dostępność oraz odbiera rezerwacje end-to-end. Jest zaprojektowana jako samoobsługowa: wykonujesz każdy krok ze swojego systemu i przesyłasz pojedynczy pakiet dowodów na koniec. Wink przegląda pakiet i po pozytywnym wyniku zmienia status Twojego konta Affiliate / Channel Manager z PENDING_APPROVAL na ACTIVE.

Certyfikacja odbywa się całkowicie na środowisku staging (https://staging-integrations.wink.travel). Nic z tej sekcji nie dotyczy produkcji.

  1. Uwierzytelnianie. Twój klient OAuth2 potrafi uzyskać token dostępu i poprawnie wywołać punkt /ping na koncie Affiliate / Channel Manager.

  2. Mapowanie zasobów. Potrafisz wylistować hotel(e) powiązane z Twoim kontem, pobrać skonfigurowaną główną taryfę (typ pokoju × plan taryfowy) i poprawnie zidentyfikować masterRateIdentifier, na który skierujesz swój system.

  3. Przesyłanie cen i dostępności. Potrafisz niezależnie zaktualizować wszystkie siedem dni tygodnia certyfikacyjnego — różne kombinacje kwoty, ilości, flag zamknięcia przy przyjeździe / wyjeździe oraz minimalnej/maksymalnej długości pobytu na każdy dzień — i odczytać dokładne wartości z powrotem z Wink.

  4. Pobieranie rezerwacji. Potrafisz pobrać prawdziwą rezerwację ze środowiska staging wykonaną na Twojej nieruchomości testowej, wyświetlić ją w swoim PMS/CM z poprawnym pokojem, gościem i sumą, a następnie odzwierciedlić anulowanie po oznaczeniu rezerwacji jako anulowanej przez Wink.

Przed rozpoczęciem certyfikacji wykonaj kroki 1–7 z Kroków integracji, aby mieć:

  • Użytkownika Wink na staging z kontem Affiliate / Channel Manager i kontem Hotel powiązanym z nim (Kanały → Channel manager). Konta staging są zatwierdzane automatycznie, więc nie trzeba niczego zgłaszać.
  • Co najmniej jeden typ pokoju i jeden plan taryfowy utworzony w koncie Hotelu. Opublikuj hotel, aby był rezerwowany pod adresem https://staging-book.wink.travel/hotel/<twoj-slug>.
  • Zarejestrowaną aplikację pod kontem Affiliate / Channel Manager z Client ID, Secret Key i zakresami integrations.read integrations.write (zobacz Uwierzytelnianie).
  • managingEntityIdentifier konta Affiliate / Channel Manager oraz propertyIdentifier konta Hotelu (oba to UUID — zobacz Znajdowanie identyfikatorów kont).

Każde zapytanie w tej sekcji używa nagłówków:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json
  • <access_token> pochodzi z grantu client_credentials pod https://staging-iam.wink.travel/oauth2/token — zobacz Uwierzytelnianie.
  • Nagłówek Wink-Version jest wymagany; jego brak spowoduje, że nie zostanie wywołane API JSON w wersji v2.
  • Content-Type: application/json jest dodawany do zapytań PUT z ciałem.

W przykładach poniżej symbole zastępcze odpowiadają wartościom zebranym w Wymaganiach wstępnych:

Symbol zastępczyZnaczenie
{managingEntityIdentifier}ID Twojego konta Affiliate / Channel Manager (UUID) — zobacz Znajdowanie identyfikatorów kont.
{propertyIdentifier}ID konta Hotelu (nieruchomości) powiązanego z kontem CM.
{masterRateIdentifier}Główna taryfa (kombinacja typu pokoju × planu taryfowego), którą certyfikujesz.
{bookingIdentifier}ID rezerwacji ze środowiska staging zwrócone przez wywołanie listy rezerwacji.

Potwierdź, że Twoje dane uwierzytelniające odnoszą się do oczekiwanego konta Affiliate / Channel Manager.

Okno terminala
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"

Oczekiwana odpowiedź:

{
"apiVersion": "2.0",
"name": "Nazwa Twojego konta Channel Manager",
"status": "PENDING_APPROVAL"
}

Odpowiedź 200 z pasującą nazwą name oznacza, że uwierzytelnianie i rozpoznanie konta są poprawne. status będzie miał wartość PENDING_APPROVAL aż Wink Cię zatwierdzi.

Pobierz stronicowaną listę hoteli powiązanych z Twoim kontem i potwierdź obecność nieruchomości testowej.

Okno terminala
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"

Odpowiedź to strona Spring z wpisami ChannelManagerProperty. Znajdź wpis, którego identifier odpowiada Twojemu {propertyIdentifier} i zanotuj currencyCode — będzie potrzebny do interpretacji aktualizacji cen w Kroku D.

Pobierz nieruchomość wraz ze wszystkimi głównymi taryfami (kombinacje typu pokoju × planu taryfowego), które publikuje. Wybierz tę, którą zamierzasz certyfikować i zanotuj jej identifier jako swój {masterRateIdentifier}.

Okno terminala
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"

Odpowiedź to PropertyWithRoomRateList: blok property oraz tablica rooms wpisów PropertyRoomRate. Każdy wpis zawiera typ pokoju, plan taryfowy, limity zajętości, podstawową cenę oraz modyfikatory cen, które zachowasz przy przesyłaniu dziennych stawek.

Załaduj siedmiodniowy kalendarz cen obejmujący pierwsze siedem dni kalendarzowych miesiąca następującego po miesiącu, w którym zaczynasz certyfikację. Na przykład, jeśli zaczynasz 21 sierpnia, celuj w okres od 1 do 7 września.

Wyślesz siedem osobnych wywołań PUT — po jednym na każdy dzień — gdzie startDate == endDate. Każdy dzień ma celowo inną kombinację kwoty, ilości, flag zamknięcia przy przyjeździe / wyjeździe oraz limitów długości pobytu, aby każdy zapisywalny parametr był przetestowany przynajmniej raz. Wartości są w walucie nieruchomości (zapisanej w Kroku B); pomiń currencyCode, a zostanie ustawiony domyślnie.

DzieńKwotaIlośćclosedOnArrivalclosedOnDepartureminLengthOfStaymaxLengthOfStayCo udowadnia
1100.005falsefalse130Dzień bazowy.
2125.004falsefalse114Zmiana kwoty + ilości + maxLengthOfStay.
3150.003truefalse130Zmiana closedOnArrival.
4175.002falsetrue27Zmiana closedOnDeparture + węższy zakres LOS.
5200.000falsefalse130Ilość wyprzedana.
6225.005falsefalse35Restrykcyjny zakres LOS.
7250.001falsefalse130Dostępność ostatniego pokoju.

Ciało zapytania dla Dnia 1 wygląda tak. Powtórz, dostosowując startDate / endDate / wartości zgodnie z tabelą, dla Dni 2–7.

Okno terminala
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
}'

Każde PUT zwraca 200 z tablicą zaktualizowanych wpisów PropertyRate dla przesłanego zakresu (jeden wpis, gdy startDate == endDate). Zachowaj tę odpowiedź — będzie częścią Twoich dowodów.

Pobierz cały tydzień w jednym wywołaniu i potwierdź, że wartości każdego dnia odpowiadają tym z tabeli w Kroku D — włącznie z flagami boolean i zakresem długości pobytu.

Okno terminala
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"

Odpowiedź to PropertyRoomRateWithRateList. Tablica rates musi zawierać siedem wpisów, po jednym na dzień, każdy z amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay i maxLengthOfStay, które załadowałeś. Każda rozbieżność oznacza, że odpowiadające PUT z Kroku D nie zostało poprawnie zapisane — popraw to i zweryfikuj ponownie przed kontynuacją.

Otwórz w przeglądarce następujący URL, zastępując <your-slug> slugiem konta Hotelu, które opublikowałeś w Wymaganiach wstępnych:

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

Wybierz datę przyjazdu i wyjazdu mieszczącą się w tygodniu certyfikacji, wybierz kombinację typu pokoju + plan taryfowy, którą certyfikowałeś, i zakończ rezerwację. Staging używa ścieżki płatności testowej — żadna karta nie jest obciążana.

Po wyświetleniu strony potwierdzenia zanotuj kod rezerwacji (format WNKxxxxx) pokazany gościowi.

Pobierz wszystkie rezerwacje utworzone dla Twojej nieruchomości testowej w oknie obejmującym czas rezerwacji.

Okno terminala
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"

Znajdź wpis, którego bookingCode odpowiada kodowi z Kroku F. Zanotuj jego bookingIdentifier. Następnie pobierz tę pojedynczą rezerwację:

Okno terminala
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"

Odpowiedź to PropertyBooking. Zaimportuj ją do swojego PMS / UI channel managera i potwierdź, że operator widzi poprawnie:

  • bookingCode, bookingIdentifier, createdDate
  • Gościa: firstName, lastName, email
  • totalAmount + currencyCode (kwota netto, którą hotel otrzymuje za wszystkie pokoje)
  • paymentMethodType, paymentMethodStatus, salesChannelName
  • Każdy wpis w roomStays: guestRoomName, ratePlanName, adults, children, startDate, endDate oraz kwotę za pokój

Zrób zrzut ekranu rezerwacji tak, jak pojawia się w Twoim UI — ten zrzut jest jednym z wymaganych dowodów.

Poproś zespół Wink o anulowanie rezerwacji certyfikacyjnej w Twoim imieniu (lub anuluj ją samodzielnie z Extranetu konta Hotelu, jeśli masz takie uprawnienia). Następnie ponownie pobierz tę samą rezerwację wywołaniem z Kroku G.

Potwierdź, że odpowiedź teraz zawiera:

  • cancelled: true
  • Wypełniony znacznik czasu cancelDate
  • paymentMethodStatus odzwierciedlający cykl anulowania (CANCELLED, PARTIALLY_REFUNDED lub FULLY_REFUNDED w zależności od polityki zwrotów)

Zaimportuj zaktualizowaną rezerwację do swojego UI i potwierdź, że operator widzi anulowanie — status, znacznik czasu anulowania oraz wskaźnik zwrotu, jeśli Twój UI go obsługuje. Zrób drugi zrzut ekranu anulowanej rezerwacji w swoim UI. To jest ostateczny dowód.

Spakuj następujące elementy do pojedynczego archiwum (.zip) o nazwie wink-cert-<twoja-nazwa-channel-managera>-<rrrr-mm-dd>.zip:

  1. Transkrypcja API. Dla każdego zapytania wykonanego w krokach A–H przechwyć pełne żądanie HTTP (metoda, URL, nagłówki żądania z wartością Authorization zamazaną oraz ciało JSON dla wywołań PUT) oraz pełną odpowiedź HTTP (kod statusu, nagłówki odpowiedzi i ciało JSON). Uporządkuj transkrypcję tak, aby każda para żądanie/odpowiedź była wyraźnie oznaczona nazwą kroku (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json itd.). Akceptowane są pliki tekstowe .http lub pojedynczy eksport .har.

  2. Zrzut ekranu UI: aktywna rezerwacja. Zrzut z Kroku G pokazujący rezerwację certyfikacyjną wyświetloną w Twoim PMS / channel manager UI, z czytelnymi danymi gościa, datami, typem pokoju, planem taryfowym i sumą.

  3. Zrzut ekranu UI: anulowana rezerwacja. Zrzut z Kroku H pokazujący tę samą rezerwację w Twoim UI po anulowaniu, z czytelnym statusem anulowania i znacznikiem czasu.

  4. Podsumowanie certyfikacji. Krótki plik README.md w archiwum zawierający:

    • Nazwę i wersję Twojego channel managera / PMS.
    • Użyte managingEntityIdentifier, propertyIdentifier, masterRateIdentifier i bookingIdentifier.
    • Slug hotelu stagingowego (ten <your-slug> w https://staging-book.wink.travel/hotel/<your-slug>).
    • Zakres dat tygodnia certyfikacji (Dzień 1 → Dzień 7 w formacie ISO-8601).
    • Imię, nazwisko i email inżyniera, który przeprowadził certyfikację.

Wyślij archiwum do swojego kontaktu ds. integracji Wink. Wink przejrzy je, skontaktuje się w razie rozbieżności i — po pozytywnym wyniku — zmieni status Twojego konta Affiliate / Channel Manager z PENDING_APPROVAL na ACTIVE. Twoja integracja będzie wtedy gotowa do wdrożenia produkcyjnego.

Możesz subskrybować zdarzenia webhook channel managera, aby otrzymywać powiadomienia w czasie rzeczywistym:

  • channel-manager.update.rate — otrzymano aktualizację ceny.
  • channel-manager.update.availability — otrzymano aktualizację dostępności.
  • channel-manager.update — ogólna aktualizacja channel managera.

Szczegóły znajdziesz w Katalogu zdarzeń webhook.