Preskočiť na obsah

Pridajte svoj Channel Manager

Tento návod prevedie vývojárov channel managerov a PMS celým procesom integrácie s Wink — od vytvorenia účtov až po mapovanie inventára a spustenie prvého end-to-end testu.

Channel Manager (Integrations) API je dostupné v dvoch prostrediach. Používajte staging pre všetký vývoj a certifikáciu; prepnite na produkciu až pri spustení do prevádzky.

ProstredieZákladná URL
Produkciahttps://integrations.wink.travel
Staginghttps://staging-integrations.wink.travel

Channel Manager API dodržiava štandardy OTA protokolu (SOAP/XML) pre kompatibilitu s existujúcimi hotelovými systémami. Začnite prehliadnutím dokumentácie partner endpointov:

Channel Manager API — Partner endpoints

  1. Vytvorte si používateľský účet Wink

    Zaregistrujte sa na staging-app.wink.travel. Všetky kroky nižšie používajú staging — celý proces zopakujete v produkcii pred spustením do prevádzky.

  2. Vytvorte si účet Affiliate / Channel Manager

    Pod novým používateľom vytvorte účet a vyberte typ účtu Affiliate / Channel Manager. Tento účet bude používaný na autentifikáciu vašej integrácie.

  3. Zaregistrujte aplikáciu a vytvorte svoj prvý token

    Vytvorte Aplikáciu a priraďte ju k účtu channel managera z kroku 2. Vyberte MACHINE_2_MACHINE ako typ klienta — ide o server-to-server integráciu bez presmerovania koncového používateľa. Ihneď si skopírujte Client ID a Secret Key; tajný kľúč sa zobrazí iba raz a nie je možné ho získať znova.

    Aplikácia vytvára bearer token, ktorý každý volanie v tomto návode používa ako Authorization: Bearer <access_token>. Vymieňajte svoje poverenia za token pomocou client_credentials grant na https://staging-iam.wink.travel/oauth2/token, žiadajúc rozsahy integrations.read integrations.write. Urobte to pred pokračovaním — bez tokenu nemôžete získať identifikátory účtov ani volať žiadny Channel Manager endpoint. Kompletný postup nájdete v Authentication, vrátane produkčného hostiteľa a zoznamu rozsahov.

  4. Vytvorte Hotelový účet

    Pod tým istým používateľom vytvorte druhý účet a vyberte typ účtu Hotel. Tento účet vám poskytne nehnuteľnosť na testovanie bez zapojenia skutočného hotela.

  5. Potvrďte, že oba účty sú schválené

    Žiadny účet nemôžete používať, kým nie je schválený: neschválený channel manager účet sa nezobrazí v zozname channel managerov žiadneho hotela a neschválený hotel nie je vrátený API.

    • Staging — schválenie je automatické. Oba účty sú použiteľné hneď po vytvorení a nie je potrebné nič žiadať.
    • Produkcia — schválenie je manuálne. Pošlite Wink kontaktnému integrátorovi mená oboch účtov a používateľa, pod ktorým sú vedené, a počkajte na potvrdenie pred pokračovaním.
  6. Prepojte oba účty

    Prihláste sa do Hotelového účtu a prejdite na Kanály → Channel manager. Vyberte svoj channel manager účet zo zoznamu — tým prepojíte nehnuteľnosť s vašou integráciou. Ak váš účet v zozname nie je, ešte nebol schválený; pozrite krok 5.

  7. Vytvorte základný typ izby a cenový plán

    V rámci Hotelového účtu vytvorte aspoň jeden typ izby a jeden cenový plán. Tieto sú potrebné predtým, než vaša integrácia môže posielať ceny a dostupnosť alebo sťahovať rezervácie.

  8. Mapujte a testujte

    Vo vlastnom systéme namapujte identifikátory typu izby a cenového plánu, ktoré vráti API. Pošlite aktualizáciu ceny a dostupnosti, potom vykonajte testovaciu rezerváciu a overte, že endpoint na získanie rezervácie ju správne vráti.

Ako nájsť identifikátory svojich účtov

Section titled “Ako nájsť identifikátory svojich účtov”

Každá cesta Channel Manager API je viazaná na váš vlastný účet:

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

{managingEntityIdentifier} je ID účtu (UUID) vášho channel manager účtu — nie hotela. Získajte ho spolu s ID a aktuálnym stavom všetkých ostatných účtov, ktoré vlastní váš používateľ, z Platform API:

Terminal window
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"

Odpoveď je pole účtov, ktoré vlastníte:

[
{
"id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
"type": "CHANNEL_MANAGER",
"name": "Váš Channel Manager",
"status": "ACTIVE"
},
{
"id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
"type": "HOTEL",
"name": "Vaša testovacia nehnuteľnosť",
"urlName": "your-test-property",
"status": "ACTIVE"
}
]
  • id záznamu channel managera je váš {managingEntityIdentifier}.
  • id záznamu HOTEL je váš {propertyIdentifier}.
  • status potvrdzuje, či je účet schválený — najmä užitočné v produkcii, kde je schválenie manuálne. Hotel musí mať stav ACTIVE, aby bol rezervovateľný alebo viditeľný pre Channel Manager API. Váš channel manager účet bude mať stav PENDING_APPROVAL až do úspešnej certifikácie; to je očakávané a neblokuje vývoj.

Certifikácia je spôsob, ako dokážete — a ako Wink potvrdzuje — že vaša integrácia správne mapuje inventár, posiela ceny a dostupnosť a prijíma rezervácie end-to-end. Je navrhnutá ako samoobslužná: každý krok riadite zo svojho systému a na konci predkladáte jeden balík dôkazov. Wink balík skontroluje a po úspechu zmení stav vášho Affiliate / Channel Manager účtu z PENDING_APPROVAL na ACTIVE.

Certifikácia prebieha výhradne v staging prostredí (https://staging-integrations.wink.travel). Nič z tejto sekcie sa nedotýka produkcie.

  1. Autentifikácia. Váš OAuth2 klient získa access token a úspešne zavolá endpoint /ping voči vášmu Affiliate / Channel Manager účtu.

  2. Mapovanie inventára. Viete získať zoznam hotelov pripojených k vášmu účtu, načítať master rate (kombináciu typu izby × cenového plánu), ktorý ste nastavili, a správne identifikovať masterRateIdentifier, na ktorý váš systém cieli.

  3. Posielanie cien a dostupnosti. Viete nezávisle aktualizovať všetkých sedem dní certifikačného týždňa — s rôznymi kombináciami ceny, množstva, príznakov zatvorenia pri príchode / odchode a minimálnej/maximálnej dĺžky pobytu pre každý deň — a prečítať si presné hodnoty späť od Wink.

  4. Sťahovanie rezervácií. Viete získať skutočnú staging rezerváciu vytvorenú pre vašu testovaciu nehnuteľnosť, zobraziť ju vo vlastnom PMS/CM UI so správnou izbou, hosťom a celkovou sumou, a potom zobraziť zrušenie, keď Wink označí rezerváciu ako zrušenú.

Pred začatím certifikácie dokončite kroky 1–7 z Krokov integrácie, aby ste mali:

  • Používateľa Wink na stagingu s účtom Affiliate / Channel Manager a účtom Hotel prepojeným s ním (Kanály → Channel manager). Stagingové účty sú schválené automaticky, takže nie je potrebné nič žiadať.
  • Aspoň jeden typ izby a jeden cenový plán vytvorený v rámci Hotelového účtu. Hotel publikujte, aby bol rezervovateľný na https://staging-book.wink.travel/hotel/<your-slug>.
  • Registrovanú aplikáciu pod vaším Affiliate / Channel Manager účtom s Client ID, Secret Key a rozsahmi integrations.read integrations.write (pozri Authentication).
  • managingEntityIdentifier vášho Affiliate / Channel Manager účtu a propertyIdentifier vášho Hotelového účtu (obe sú UUID — pozri Ako nájsť identifikátory svojich účtov).

Každý požiadavok v tejto sekcii používa tieto hlavičky:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json
  • <access_token> pochádza z client_credentials grantu na https://staging-iam.wink.travel/oauth2/token — pozri Authentication.
  • Hlavička Wink-Version je povinná; jej vynechanie nepresmeruje na v2 JSON API.
  • Content-Type: application/json sa pridáva pri PUT požiadavkách s telom.

V príkladoch nižšie zodpovedajú zástupné hodnoty hodnotám, ktoré ste získali v Predpokladoch:

Zástupný výrazVýznam
{managingEntityIdentifier}ID vášho Affiliate / Channel Manager účtu (UUID) — pozri Ako nájsť identifikátory svojich účtov.
{propertyIdentifier}ID Hotelového účtu (nehnuteľnosti), ktorý ste prepojili s CM účtom.
{masterRateIdentifier}Master rate (kombinácia typu izby × cenového plánu), ktorý budete certifikovať.
{bookingIdentifier}ID stagingovej rezervácie vrátené volaním zoznamu rezervácií.

Potvrďte, že vaše poverenia odkazujú na očakávaný Affiliate / Channel Manager účet.

Terminal window
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"

Očakávaná odpoveď:

{
"apiVersion": "2.0",
"name": "Názov vášho Channel Manager účtu",
"status": "PENDING_APPROVAL"
}

Odpoveď 200 s rovnakým name znamená, že autentifikácia a rozlíšenie účtu sú správne. status bude čítať PENDING_APPROVAL až do certifikácie Wink.

Získajte stránkovaný zoznam hotelov prepojených s vaším účtom a potvrďte, že vaša testovacia nehnuteľnosť je prítomná.

Terminal window
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"

Odpoveď je Spring Page záznamov ChannelManagerProperty. Nájdite záznam, ktorého identifier zodpovedá vášmu {propertyIdentifier} a zaznamenajte jeho currencyCode — budete ho potrebovať na interpretáciu aktualizácií cien v Kroku D.

Získajte nehnuteľnosť spolu so všetkými master rate (kombináciami typu izby × cenového plánu), ktoré publikuje. Vyberte ten, ktorý chcete certifikovať, a zaznamenajte jeho identifier ako váš {masterRateIdentifier}.

Terminal window
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"

Odpoveď je obálka PropertyWithRoomRateList: blok property plus pole rooms záznamov PropertyRoomRate. Každý záznam obsahuje typ izby, cenový plán, limity obsadenosti, základnú cenu a modifikátory cien, ktoré zachováte pri posielaní denných cien.

Krok D — Načítanie certifikačného týždňa

Section titled “Krok D — Načítanie certifikačného týždňa”

Načítajte sedemdňový kalendár cien pokrývajúci prvých sedem kalendárnych dní mesiaca nasledujúceho po mesiaci, v ktorom začínate certifikáciu. Napríklad, ak začínate certifikáciu 21. augusta, cielite na 1. až 7. september.

Pošlete sedem samostatných PUT volaní — jedno na každý deň — kde startDate == endDate. Každý deň má zámerne inú kombináciu sumy, množstva, príznakov zatvorenia pri príchode / odchode a minimálnej/maximálnej dĺžky pobytu, aby sa každý zapisovateľný parameter aspoň raz otestoval. Hodnoty sú v mene nehnuteľnosti (zaznamenanej v Kroku B); vynechaním currencyCode sa správne nastaví predvolená mena.

DeňSumaMnožstvoclosedOnArrivalclosedOnDepartureminLengthOfStaymaxLengthOfStayČo dokazuje
1100.005falsefalse130Základný deň.
2125.004falsefalse114Zmena sumy + množstva + maxLengthOfStay.
3150.003truefalse130Prepnutie closedOnArrival.
4175.002falsetrue27Prepnutie closedOnDeparture + užšie okno dĺžky pobytu.
5200.000falsefalse130Množstvo vypredané.
6225.005falsefalse35Obmedzujúce okno dĺžky pobytu.
7250.001falsefalse130Dostupnosť poslednej izby.

Telo požiadavky pre Deň 1 vyzerá takto. Opakujte, upravujúc startDate / endDate / hodnoty podľa riadkov pre dni 2 až 7.

Terminal window
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ždý PUT odpovie 200 s poľom aktualizovaných záznamov PropertyRate pre zaslaný rozsah (jeden záznam, keď startDate == endDate). Túto odpoveď si uložte — bude súčasťou vášho dôkazového balíka.

Krok E — Načítanie certifikačného týždňa späť

Section titled “Krok E — Načítanie certifikačného týždňa späť”

Načítajte celý týždeň jedným volaním a potvrďte, že uložené hodnoty pre každý deň zodpovedajú riadku, ktorý ste poslali v Kroku D — vrátane boolean príznakov a okna dĺžky pobytu.

Terminal window
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"

Odpoveď je PropertyRoomRateWithRateList. Pole rates musí obsahovať sedem záznamov, po jednom na každý deň, každý s hodnotami amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay a maxLengthOfStay, ktoré ste nastavili. Ak sa niektoré pole nezhoduje, znamená to, že príslušný PUT z Kroku D nebol správne aplikovaný — opravte to a znova overte pred pokračovaním.

Krok F — Vykonajte testovaciu rezerváciu

Section titled “Krok F — Vykonajte testovaciu rezerváciu”

Otvorte v prehliadači nasledujúcu URL, pričom <your-slug> nahraďte slugom Hotelového účtu, ktorý ste publikovali v Predpokladoch:

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

Vyberte dátum príchodu a odchodu, ktoré sú úplne v rámci certifikačného týždňa, zvoľte kombináciu typu izby + cenového plánu, ktorú ste certifikovali, a dokončite rezerváciu. Staging používa testovaciu platobnú cestu — žiadna skutočná karta nie je účtovaná.

Po zobrazení potvrdzovacej stránky si zaznamenajte kód rezervácie (formát WNKxxxxx), ktorý sa zobrazí hosťovi.

Získajte všetky rezervácie vytvorené pre vašu testovaciu nehnuteľnosť v časovom okne pokrývajúcom čas rezervácie.

Terminal window
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"

Nájdite záznam, ktorého bookingCode zodpovedá kódu, ktorý ste zaznamenali v Kroku F. Zaznamenajte jeho bookingIdentifier. Potom získajte túto jednu rezerváciu:

Terminal window
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"

Odpoveď je PropertyBooking. Importujte ju do vlastného PMS / channel-manager UI a potvrďte, že operátorovi sa správne zobrazí každý z nasledujúcich údajov:

  • bookingCode, bookingIdentifier, createdDate
  • Hosť: firstName, lastName, email
  • totalAmount + currencyCode (čistá suma, ktorú hotel dostane za všetky izby)
  • paymentMethodType, paymentMethodStatus, salesChannelName
  • Každý záznam v roomStays: guestRoomName, ratePlanName, adults, children, startDate, endDate a suma za izbu

Urobte screenshot rezervácie tak, ako sa zobrazuje vo vašom UI — tento screenshot je jedným z požadovaných dôkazových artefaktov.

Požiadajte tím Wink, aby za vás zrušil certifikačnú rezerváciu (alebo ju zrušte sami z Extranetu Hotelového účtu, ak máte oprávnenie). Potom znovu načítajte tú istú rezerváciu pomocou volania z Kroku G.

Potvrďte, že odpoveď teraz obsahuje:

  • cancelled: true
  • Vyplnený časový údaj cancelDate
  • paymentMethodStatus odrážajúci životný cyklus zrušenia (CANCELLED, PARTIALLY_REFUNDED alebo FULLY_REFUNDED podľa refundácie)

Importujte aktualizovanú rezerváciu do svojho UI a potvrďte, že zrušenie je viditeľné pre operátora — stav, čas zrušenia a akýkoľvek indikátor refundácie, ktorý vaše UI podporuje. Urobte druhý screenshot zrušenej rezervácie vo vašom UI. Toto je finálny dôkazový artefakt.

Zabaľte nasledujúce do jedného archívu (.zip) s názvom wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip:

  1. Prepis API. Pre každý požiadavok z krokov A až H zachyťte celý HTTP požiadavok (metóda, URL, hlavičky požiadavku s redigovanou hodnotou Authorization a JSON telo pre PUT volania) a celú HTTP odpoveď (status kód, hlavičky odpovede a JSON telo). Prepis štruktúrujte tak, aby každý pár požiadavok/odpoveď bol jasne označený podľa kroku (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json atď.). Prijateľné sú plain-text .http súbory alebo jeden .har export.

  2. Screenshot UI: aktívna rezervácia. Screenshot z Kroku G zobrazujúci certifikačnú rezerváciu vo vašom PMS / channel-manager UI, s hosťom, dátumami, typom izby, cenovým plánom a celkovou sumou jasne čitateľnými.

  3. Screenshot UI: zrušená rezervácia. Screenshot z Kroku H zobrazujúci tú istú rezerváciu vo vašom UI po zrušení, so zrušeným stavom a časovým údajom jasne čitateľnými.

  4. Zhrnutie certifikácie. Krátky README.md v archíve obsahujúci:

    • Názov a verziu vášho channel managera / PMS.
    • Použité managingEntityIdentifier, propertyIdentifier, masterRateIdentifier a bookingIdentifier.
    • Slug hotela na stagingu (t.j. <your-slug> v https://staging-book.wink.travel/hotel/<your-slug>).
    • Dátumové rozpätie certifikačného týždňa (Deň 1 → Deň 7 v ISO-8601).
    • Meno a email inžiniera, ktorý certifikáciu vykonal.

Odošlite archív svojmu Wink kontaktnému integrátorovi. Wink ho skontroluje, vyžiada si doplnenie pri nezrovnalostiach a — po úspechu — zmení stav vášho Affiliate / Channel Manager účtu z PENDING_APPROVAL na ACTIVE. Vaša integrácia je potom pripravená na produkčné nasadenie.

Môžete sa prihlásiť na odber udalostí channel manager webhookov a dostávať notifikácie v reálnom čase:

  • channel-manager.update.rate — prijatá aktualizácia ceny.
  • channel-manager.update.availability — prijatá aktualizácia dostupnosti.
  • channel-manager.update — všeobecná aktualizácia channel managera.

Podrobnosti nájdete v Katalógu webhook udalostí.