Siirry sisältöön

Lisää kanavapäällikkösi

Tämä opas ohjaa kanavapäällikön ja PMS-kehittäjät koko integraatioprosessin läpi Wink-alustaan — käyttäjätilien luomisesta varaston kartoitukseen ja ensimmäisen end-to-end-testin suorittamiseen.

Channel Manager (Integrations) API on saatavilla kahdessa ympäristössä. Käytä staging-ympäristöä kaikessa kehityksessä ja sertifioinnissa; vaihda tuotantoon vasta käyttöönoton yhteydessä.

YmpäristöPerus-URL
Tuotantohttps://integrations.wink.travel
Staginghttps://staging-integrations.wink.travel

Channel Manager API noudattaa OTA-protokollan standardeja (SOAP/XML) yhteensopivuuden takaamiseksi olemassa olevien majoitusjärjestelmien kanssa. Aloita tutustumalla kumppanipäätepisteiden dokumentaatioon:

Channel Manager API — Kumppanipäätepisteet

  1. Luo Wink-käyttäjätili

    Rekisteröidy osoitteessa staging-app.wink.travel. Kaikki alla olevat vaiheet tehdään staging-ympäristössä — toistat koko prosessin tuotannossa ennen käyttöönottoa.

  2. Luo Affiliate / Channel Manager -tili

    Uuden käyttäjätilisi alla luo tili ja valitse Affiliate / Channel Manager -tilityyppi. Tämä on tili, jolla integraatiosi tunnistautuu.

  3. Rekisteröi sovellus ja luo ensimmäinen token

    Luo Sovellus ja liitä se kanavapäällikkötiliin vaiheessa 2. Valitse asiakastyypiksi MACHINE_2_MACHINE — kyseessä on palvelin-palvelin -integraatio ilman loppukäyttäjän uudelleenohjausta. Kopioi Client ID ja Secret Key heti; salainen avain näytetään vain kerran eikä sitä voi hakea uudelleen.

    Sovellus luo bearer-tokenin, jota jokainen tämän oppaan kutsu käyttää muodossa Authorization: Bearer <access_token>. Vaihda tunnistetietosi tokeniin käyttämällä client_credentials -granttia osoitteessa https://staging-iam.wink.travel/oauth2/token, pyytäen integrations.read integrations.write -scopeja. Tee tämä ennen jatkamista — et voi hakea tilitunnuksia tai käyttää Channel Managerin päätepisteitä ilman tokenia. Katso Authentication täydellinen prosessi, tuotantopalvelin ja scope-katalogi.

  4. Luo Hotelli-tili

    Samalla käyttäjällä luo toinen tili ja valitse Hotel -tilityyppi. Tämä antaa sinulle kiinteistön, jota voit käyttää testaukseen ilman oikeaa hotellia.

  5. Varmista, että molemmat tilit on hyväksytty

    Kumpaakaan tiliä ei voi käyttää ennen hyväksyntää: hyväksymätön kanavapäällikkötili ei näy missään hotellin kanavapäällikkölistassa, eikä hyväksymätöntä hotellia palauteta API:sta.

    • Staging — hyväksyntä on automaattinen. Molemmat tilit ovat käytettävissä heti luomisen jälkeen, eikä mitään tarvitse pyytää.
    • Tuotanto — hyväksyntä on manuaalinen. Lähetä Wink-integraatioiden yhteyshenkilölle molempien tilien nimet ja käyttäjä, jonka alla ne ovat, ja odota vahvistusta ennen jatkamista.
  6. Yhdistä tilit

    Kirjaudu Hotelli-tilille ja siirry kohtaan Channels → Channel manager. Valitse kanavapäällikkötilisi listalta — tämä linkittää kiinteistön integraatioosi. Jos tiliäsi ei ole listalla, sitä ei ole vielä hyväksytty; katso vaihe 5.

  7. Luo perushuonetyyppi ja hintasuunnitelma

    Hotelli-tilillä luo vähintään yksi huonetyyppi ja yksi hintasuunnitelma. Nämä ovat pakollisia, ennen kuin integraatiosi voi lähettää hintoja ja saatavuutta tai hakea varauksia.

  8. Kartoitus ja testaus

    Omassa järjestelmässäsi kartoita API:n palauttamat huonetyypin ja hintasuunnitelman tunnisteet. Lähetä hintapäivitys ja saatavuuspäivitys, tee testivaraus ja varmista, että varauksen hakupäätepiste palauttaa sen oikein.

Jokainen Channel Manager API -polku on rajattu omaan tiliisi:

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

{managingEntityIdentifier} on kanavapäällikkötilisi tilitunnus (UUID) — ei hotellin. Hae se sekä kaikkien muiden käyttäjäsi omistamien tilien tunnukset ja nykyiset tilat Platform API:sta:

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"

Vastaus on taulukko omistamistasi tileistä:

[
{
"id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
"type": "CHANNEL_MANAGER",
"name": "Kanavapäällikkösi",
"status": "ACTIVE"
},
{
"id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
"type": "HOTEL",
"name": "Testikiinteistösi",
"urlName": "your-test-property",
"status": "ACTIVE"
}
]
  • Kanavapäällikkötilin id on sinun {managingEntityIdentifier}.
  • Hotellitilin id on sinun {propertyIdentifier}.
  • status kertoo, onko tili hyväksytty — erityisen hyödyllinen tuotannossa, jossa hyväksyntä on manuaalista. Hotellin tulee olla ACTIVE ennen kuin se on varattavissa tai näkyy Channel Manager API:ssa. Kanavapäällikkötili pysyy PENDING_APPROVAL -tilassa, kunnes läpäiset Sertifioinnin; tämä on odotettua eikä estä kehitystä.

Sertifioinnilla todistat — ja Wink varmistaa — että integraatiosi kartoittaa varaston oikein, lähettää hinnat ja saatavuuden sekä vastaanottaa varaukset end-to-end. Se on suunniteltu itsepalveluksi: suoritat jokaisen vaiheen omasta järjestelmästäsi ja toimitat lopuksi yhden todistusaineistokansion. Wink arvioi aineiston ja hyväksynnän jälkeen nostaa Affiliate / Channel Manager -tilisi tilan PENDING_APPROVAL → ACTIVE.

Sertifiointi suoritetaan kokonaan staging-ympäristössä (https://staging-integrations.wink.travel). Mikään tässä osiossa ei koske tuotantoa.

  1. Tunnistautuminen. OAuth2-asiakkaasi saa access tokenin ja onnistuu kutsumaan /ping-päätepistettä Affiliate / Channel Manager -tililläsi.

  2. Varaston kartoitus. Voit listata tilillesi liitetyt hotellit, hakea määrittämäsi master-hinnan (huonetyyppi × hintasuunnitelma) ja tunnistaa oikein masterRateIdentifier-arvon, johon järjestelmäsi kohdistaa.

  3. Hintojen ja saatavuuden päivitys. Voit päivittää sertifiointiviikon kaikki seitsemän päivää erikseen — jokaiselle päivälle erilainen yhdistelmä määrää, saatavuutta, saapumisen/lähdön sulkemismerkintöjä sekä min/max oleskelun pituutta — ja lukea täsmälleen samat arvot takaisin Winkistä.

  4. Varausten haku. Voit hakea oikean staging-varauksen, joka on tehty testikiinteistöllesi, näyttää sen omassa PMS/CM-käyttöliittymässäsi oikeilla huone-, vieras- ja kokonaistiedoilla, ja heijastaa peruutuksen, kun Wink merkitsee varauksen peruutetuksi.

Ennen sertifioinnin aloittamista suorita Integraatiovaiheet kohdat 1–7, jotta sinulla on:

  • Wink-käyttäjä stagingissa, jolla on Affiliate / Channel Manager -tili ja siihen liitetty Hotel-tili (Channels → Channel manager). Staging-tilit hyväksytään automaattisesti, joten mitään ei tarvitse pyytää.
  • Vähintään yksi huonetyyppi ja yksi hintasuunnitelma luotuna Hotelli-tilillä. Julkaise hotelli, jotta se on varattavissa osoitteessa https://staging-book.wink.travel/hotel/<your-slug>.
  • Rekisteröity sovellus Affiliate / Channel Manager -tilillä, jolla on Client ID, Secret Key ja integrations.read integrations.write -scopet (katso Authentication).
  • Affiliate / Channel Manager -tilisi managingEntityIdentifier ja Hotelli-tilisi propertyIdentifier (molemmat UUID-muodossa — katso Tilitunnisteiden löytäminen).

Jokainen tämän osion pyyntö käyttää seuraavia otsikoita:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json
  • <access_token> saadaan client_credentials -grantilla osoitteesta https://staging-iam.wink.travel/oauth2/token — katso Authentication.
  • Wink-Version -otsikko on pakollinen; sen puuttuminen estää reitityksen v2 JSON API:in.
  • Content-Type: application/json lisätään PUT-pyyntöihin, joissa on runko.

Alla olevissa esimerkeissä paikkamerkit vastaavat arvoja, jotka keräsit Edellytyksissä:

PaikkamerkkiMerkitys
{managingEntityIdentifier}Affiliate / Channel Manager -tilisi ID (UUID) — katso Tilitunnisteiden löytäminen.
{propertyIdentifier}Hotelli-tilin (kiinteistön) ID, joka on liitetty CM-tiliin.
{masterRateIdentifier}Sertifioitava master-hinta (huonetyyppi × hintasuunnitelma).
{bookingIdentifier}Staging-varauksen ID, jonka varauslistakutsu palautti.

Varmista, että tunnistetietosi vastaavat odotettua Affiliate / Channel Manager -tiliä.

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"

Odotettu vastaus:

{
"apiVersion": "2.0",
"name": "Kanavapäällikkötilisi nimi",
"status": "PENDING_APPROVAL"
}

200-vastaus, jossa name täsmää, tarkoittaa, että tunnistautuminen ja tilin resoluutio ovat oikein. status lukee PENDING_APPROVAL kunnes Wink hyväksyy sinut.

Hae sivutettu lista tilillesi liitetyistä hotelleista ja varmista, että testikiinteistösi on mukana.

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"

Vastaus on Springin Page-objekti, joka sisältää ChannelManagerProperty-merkintöjä. Etsi merkintä, jonka identifier vastaa {propertyIdentifier} ja tallenna sen currencyCode — tarvitset sitä hintapäivitysten tulkintaan Vaiheessa D.

Hae kiinteistö ja kaikki sen julkaistut master-hinnat (huonetyyppi × hintasuunnitelma). Valitse sertifioitava ja tallenna sen identifier arvoksi {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"

Vastaus on PropertyWithRoomRateList: sisältää property-lohkon ja rooms-taulukon, jossa on PropertyRoomRate-merkintöjä. Jokainen sisältää huonetyypin, hintasuunnitelman, käyttöasteen rajat, perushinnan ja hintamuokkaimet, jotka säilytät päivittäisiä hintoja lähettäessäsi.

Lataa seitsemän päivän hintakalenteri, joka kattaa sertifiointia seuraavan kuukauden ensimmäiset seitsemän kalenteripäivää. Esimerkiksi, jos aloitat sertifioinnin 21. elokuuta, kohdistu 1.–7. syyskuuta.

Lähetät seitsemän erillistä PUT-kutsua — yksi päivää kohden — joissa startDate == endDate. Jokaiselle päivälle asetetaan tarkoituksella erilainen yhdistelmä määrää, saatavuutta, saapumisen/lähdön sulkemismerkintöjä sekä min/max oleskelun pituutta, jotta kaikki kirjoitettavat kentät testataan vähintään kerran. Arvot ovat kiinteistön valuutassa (tallennettu Vaiheessa B); jätä currencyCode pois, niin se oletetaan oikein.

PäiväMääräMäärä (quantity)closedOnArrivalclosedOnDepartureminLengthOfStaymaxLengthOfStayMitä todistaa
1100.005falsefalse130Peruspäivä.
2125.004falsefalse114Määrä + määrä + maxLengthOfStay muutos.
3150.003truefalse130closedOnArrival vaihtuu.
4175.002falsetrue27closedOnDeparture vaihtuu + tiukempi oleskelun pituus.
5200.000falsefalse130Loppuunmyyty määrä.
6225.005falsefalse35Rajoittava oleskelun pituus.
7250.001falsefalse130Viimeinen huone saatavilla.

Pyyntöpäivän 1 runko näyttää tältä. Toista, muuttaen startDate / endDate / arvot rivin mukaan, päiville 2–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
}'

Jokainen PUT vastaa 200 ja palauttaa taulukon päivitetyistä PropertyRate-merkinnöistä kyseiselle aikavälille (yksi merkintä, kun startDate == endDate). Tallenna vastaus — se on osa todistusaineistoasi.

Vaihe E — Lue sertifiointiviikko takaisin

Osio nimeltä “Vaihe E — Lue sertifiointiviikko takaisin”

Hae koko viikko yhdellä kutsulla ja varmista, että jokaisen päivän tallennetut arvot vastaavat vaiheessa D lähettämiäsi — mukaan lukien boolean-liput ja oleskelun pituuden rajat.

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"

Vastaus on PropertyRoomRateWithRateList. Sen rates-taulukossa on seitsemän merkintää, yksi päivää kohden, jokaisessa amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay ja maxLengthOfStay kuten latait. Jos mikään kenttä ei täsmää, vastaava PUT vaiheessa D ei onnistunut — korjaa ja varmista uudelleen ennen jatkoa.

Avaa selain ja mene osoitteeseen, korvaten <your-slug> Hotelli-tilisi slugilla, jonka julkaisit edellytyksissä:

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

Valitse saapumis- ja lähtöpäivät, jotka ovat kokonaan sertifiointiviikon sisällä, valitse sertifioimasi huonetyyppi + hintasuunnitelma ja tee varaus. Staging käyttää testimaksupolkua — korttia ei veloiteta.

Kun vahvistussivu latautuu, tallenna vieraille näytetty varauskoodi (muodossa WNKxxxxx).

Hae kaikki varaukset, jotka on tehty testikiinteistöllesi aikavälillä, joka kattaa varauksen aikaleiman.

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"

Etsi merkintä, jonka bookingCode vastaa vaiheessa F tallentamaasi koodia. Tallenna sen bookingIdentifier. Hae sitten kyseinen varaus:

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"

Vastaus on PropertyBooking. Tuo se omaan PMS / kanavapäällikkö-käyttöliittymääsi ja varmista, että seuraavat tiedot näkyvät oikein operaattorille:

  • bookingCode, bookingIdentifier, createdDate
  • Vieras: firstName, lastName, email
  • totalAmount + currencyCode (hotellin saama nettomäärä kaikista huoneista)
  • paymentMethodType, paymentMethodStatus, salesChannelName
  • Jokainen roomStays-merkintä: guestRoomName, ratePlanName, adults, children, startDate, endDate ja huonekohtainen amount

Ota kuvakaappaus varauksesta käyttöliittymässäsi — se on yksi vaadituista todistusaineistoista.

Pyydä Wink-tiimiä peruuttamaan sertifiointivaraus puolestasi (tai peruuta itse Hotelli-tilin Extranetistä, jos sinulla on oikeudet). Hae sitten sama varaus uudelleen vaiheessa G käytetyllä kutsulla.

Varmista, että vastaus näyttää nyt:

  • cancelled: true
  • Täytetty cancelDate aikaleima
  • paymentMethodStatus, joka heijastaa peruutuksen tilaa (CANCELLED, PARTIALLY_REFUNDED tai FULLY_REFUNDED palautuskäytännöstä riippuen)

Tuo päivitetty varaus omaan käyttöliittymääsi ja varmista, että peruutus näkyy operaattorille — tila, peruutusaikaleima ja mahdollinen hyvityksen merkintä. Ota toinen kuvakaappaus peruutetusta varauksesta käyttöliittymässäsi. Tämä on lopullinen todistusaineisto.

Pakkaa seuraavat tiedostot yhteen arkistoon (.zip) nimellä wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip:

  1. API-tallenne. Kaikista vaiheiden A–H pyynnöistä tallenna täydelliset HTTP-pyynnöt (metodi, URL, otsikot, joissa Authorization-arvo peitetty, ja PUT-kutsujen JSON-runko) sekä HTTP-vastaukset (statuskoodi, otsikot ja JSON-runko). Järjestä tallenne niin, että jokainen pyyntö/vastauspari on selkeästi nimetty vaiheensa mukaan (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json jne.). Tavalliset .http-tiedostot tai yksi .har-vienti käyvät.

  2. Käyttöliittymän kuvakaappaus: aktiivinen varaus. Kuvakaappaus vaiheesta G, jossa sertifiointivaraus näkyy omassa PMS / kanavapäällikkö-käyttöliittymässä, vieras, päivämäärät, huonetyyppi, hintasuunnitelma ja kokonaissumma selkeästi luettavissa.

  3. Käyttöliittymän kuvakaappaus: peruutettu varaus. Kuvakaappaus vaiheesta H, jossa sama varaus näkyy käyttöliittymässäsi peruutuksen jälkeen, peruutustila ja aikaleima selkeästi luettavissa.

  4. Sertifiointiyhteenveto. Lyhyt README.md arkistossa, jossa luetellaan:

    • Kanavapäällikkösi / PMS:n nimi ja versio.
    • Käytetyt managingEntityIdentifier, propertyIdentifier, masterRateIdentifier ja bookingIdentifier.
    • Staging-hotellin slug (se <your-slug> osoitteessa https://staging-book.wink.travel/hotel/<your-slug>).
    • Sertifiointiviikon päivämääräväli (Päivä 1 → Päivä 7 ISO-8601-muodossa).
    • Sertifioinnin suorittaneen insinöörin nimi ja sähköposti.

Lähetä arkisto Wink-integraatioiden yhteyshenkilölle. Wink arvioi aineiston, seuraa mahdollisia poikkeamia ja hyväksynnän jälkeen vaihtaa Affiliate / Channel Manager -tilisi tilan PENDING_APPROVAL → ACTIVE. Integraatiosi on tällöin valmis tuotantoon siirtymiseen.

Voit tilata kanavapäällikön webhook-tapahtumia saadaksesi reaaliaikaisia ilmoituksia:

  • channel-manager.update.rate — Hintapäivitys vastaanotettu.
  • channel-manager.update.availability — Saatavuuspäivitys vastaanotettu.
  • channel-manager.update — Yleinen kanavapäällikön päivitys.

Katso Webhook Events Catalog lisätietoja.