Lisa oma kanalihaldur

See juhend viib kanalihalduri ja PMS-i arendajad läbi kogu Winkiga integreerimise protsessi — alates kontode loomist kuni inventari kaardistamise ja esimese lõpp-lõpuni testini.

Keskkonnad

Kanalihalduri (Integratsioonide) API on saadaval kahes keskkonnas. Kasuta arendamiseks ja sertifitseerimiseks kõiki samme staging keskkonnas; lülitu tootmiskeskkonda alles käivitamisel.

Keskkond	Baas-URL
Tootmine	https://integrations.wink.travel
Staging	https://staging-integrations.wink.travel

API viide

Kanalihalduri API järgib OTA protokolli standardeid (SOAP/XML), et tagada ühilduvus olemasolevate majutusasutuste süsteemidega. Alusta partneri lõpp-punktide dokumentatsiooni läbivaatamisest:

Kanalihalduri API — Partneri lõpp-punktid

Integreerimise sammud

1. Loo Wink kasutajakonto

   Registreeru aadressil staging-app.wink.travel. Kõik alljärgnevad sammud toimuvad staging keskkonnas — tootmises kordad kogu protsessi enne käivitamist.

2. Loo oma Affiliate / Kanalihalduri konto

   Oma uue kasutaja all loo konto ja vali konto tüübiks Affiliate / Channel Manager. See on konto, millega su integratsioon autentib.

3. Registreeri rakendus ja loo esimene token

   Loo rakendus ja seo see kanalihalduri kontoga, mille lõid sammus 2. Vali kliendi tüübiks MACHINE_2_MACHINE — see on server-server integratsioon, kus lõppkasutajat ei suunata. Kopeeri kohe Client ID ja Secret Key; salajane võti kuvatakse ainult korra ja seda ei saa hiljem taastada.

   Rakendus loob bearer tokeni, mida iga selle juhendi API kõne kannab Authorization: Bearer <access_token>. Vaheta oma mandaadid tokeni vastu kasutades client_credentials grant’i aadressil https://staging-iam.wink.travel/oauth2/token, taotledes integrations.read integrations.write õigusi. Tee seda enne järgmiste sammude juurde liikumist — ilma tokenita ei saa kontode identifikaatoreid otsida ega Kanalihalduri API lõpp-punkte kasutada. Vaata Autentimise juhendit kogu protsessi, tootmiskeskkonna ja õiguste kataloogi kohta.

4. Loo Hotelli konto

   Sama kasutaja all loo teine konto ja vali konto tüübiks Hotel. See annab sulle testimiseks kinnistu, mis ei ole päris hotell.

5. Kinnita, et mõlemad kontod on heaks kiidetud

   Ühtegi kontot ei saa kasutada enne, kui see on heaks kiidetud: heaks kiitmata kanalihalduri konto ei ilmu ühegi hotelli kanalihaldurite nimekirja ja heaks kiitmata hotell ei ilmu API vastuses.

   • Staging — heakskiit on automaatne. Mõlemad kontod on kasutatavad kohe pärast loomist, midagi eraldi taotleda ei ole vaja.
   • Tootmine — heakskiit on käsitsi. Saada Wink integratsioonide kontaktile mõlema konto nimed ja kasutaja, kelle all need on, ning oota kinnitust enne jätkamist.

6. Ühenda mõlemad kontod

   Logi sisse Hotelli kontole ja mine Extranet → Distribution → Channel Manager. Vali kanalihalduri konto nimekirjast — see seob kinnistu sinu integratsiooniga. Kui sinu konto nimekirjas puudub, pole see veel heaks kiidetud; vaata sammu 5.

7. Loo põhiline toatüüp ja hinnaplaan

   Hotelli kontol loo vähemalt üks toatüüp ja üks hinnaplaan. Need on vajalikud, enne kui su integratsioon saab hindu ja saadavust uuendada või broneeringuid tõmmata.

8. Kaardista ja testi

   Oma süsteemis kaardista API-st saadud toatüübi ja hinnaplaani identifikaatorid. Saada hinnauuendus ja saadavuse uuendus, tee testbroneering ja veendu, et broneeringu päringu lõpp-punkt tagastab selle korrektselt.

Note

Korda kõiki ülaltoodud samme tootmiskeskkonnas enne käivitamist, sealhulgas registreeri eraldi tootmisrakendus — staging mandaadid ei tööta tootmises. Arvesta Wink’i ülevaatusega sammus 5 — tootmiskontosid ei kinnitata automaatselt nagu stagingus. Wink meeskond migreerib kõik hotellid, mis juba kasutavad sinu kanalihaldurit, sinu uude tootmiskontosse.

Oma konto identifikaatorite leidmine

Iga Kanalihalduri API rada on seotud sinu enda kontoga:

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

{managingEntityIdentifier} on sinu kanalihalduri konto ID (UUID) — mitte hotelli oma. Saa see koos kõigi teiste sinu kasutaja kontode ID ja olekuga Platvormi API kaudu:

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"

Vastus on massiiv sinu kontodest:

[
  {
    "id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
    "type": "CHANNEL_MANAGER",
    "name": "Sinu Kanalihaldur",
    "status": "ACTIVE"
  },
  {
    "id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
    "type": "HOTEL",
    "name": "Sinu Testkinnistu",
    "urlName": "sinu-testkinnistu",
    "status": "ACTIVE"
  }
]

• Kanalihalduri konto id on sinu {managingEntityIdentifier}.
• Hotelli konto id on sinu {propertyIdentifier}.
• status näitab, kas konto on heaks kiidetud — eriti oluline tootmises, kus heakskiit on käsitsi. Hotell peab olema ACTIVE, et seda saaks broneerida või Kanalihalduri API-st näha. Sinu kanalihalduri konto jääb PENDING_APPROVAL olekusse kuni Sertifitseerimiseni; see on ootuspärane ega takista arendust.

Caution

See päring käib Platvormi API vastu (https://staging-api.wink.travel stagingus, https://api.wink.travel tootmises), mitte Kanalihalduri API hostide vastu, mis on toodud Keskkondade all. Kasuta sama access tokenit — see on kasutajapõhine, mitte API-põhine.

Sertifitseerimine

Sertifitseerimine tõendab — ja Wink kinnitab —, et su integratsioon kaardistab inventari õigesti, uuendab hindu ja saadavust ning võtab vastu broneeringuid lõpp-lõpuni. See on mõeldud iseteenindusena: sa juhid kõiki samme oma süsteemist ja esitad lõpus ühe tõendite paketi. Wink vaatab selle üle ja kui see läbib, muudab su Affiliate / Kanalihalduri konto staatuse PENDING_APPROVAL-st ACTIVE-ks.

Sertifitseerimine toimub täielikult staging keskkonnas (https://staging-integrations.wink.travel). Selles jaotises ei puudutata tootmist.

Mida sa tõestad

1. Autentimine. Sinu OAuth2 klient saab access tokeni ja kutsub edukalt /ping lõpp-punkti oma Affiliate / Kanalihalduri konto vastu.

2. Inventari kaardistamine. Saad listida oma kontoga seotud hotelle, pärida konfigureeritud master hinna (toatüüp × hinnaplaan) ja õigesti tuvastada masterRateIdentifier, millele su süsteem suunab.

3. Hindade ja saadavuse uuendamine. Saad uuendada sertifitseerimisnädala kõiki seitset päeva eraldi — iga päev erineva kombinatsiooniga summast, kogusest, saabumise/lahkumise sulgemise lipust ja min/max peatumise pikkusest — ning lugeda Winkist täpselt samad väärtused tagasi.

4. Broneeringute tõmbamine. Saad pärida reaalse staging broneeringu, mis on tehtud sinu testkinnistu vastu, kuvada selle oma PMS/CM kasutajaliideses koos õige toa, külalise ja summaga ning kajastada tühistust, kui Wink märgib broneeringu tühistatuks.

Eeltingimused

Enne sertifitseerimise alustamist lõpeta Integreerimise sammude punktid 1–7, nii et sul on:

• Wink kasutaja stagingus, kellel on Affiliate / Channel Manager konto ja sellega seotud Hotel konto (Extranet → Distribution → Channel Manager). Staging kontod kinnitatakse automaatselt, seega pole vaja midagi taotleda.
• Vähemalt üks toatüüp ja üks hinnaplaan loodud Hotelli kontol. Avalda hotell, et see oleks broneeritav aadressil https://staging-book.wink.travel/hotel/<sinu-slug>.
• Registreeritud rakendus oma Affiliate / Kanalihalduri konto all, millel on Client ID, Secret Key ja integrations.read integrations.write õigused (vt Autentimine).
• Oma Affiliate / Kanalihalduri konto managingEntityIdentifier ja Hotelli konto propertyIdentifier (mõlemad UUID-d — vt Oma konto identifikaatorite leidmine).

Üldised päringu konventsioonid

Kõik selles jaotises olevad päringud kasutavad järgmisi päiseid:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json

• <access_token> saadakse client_credentials grant’iga aadressilt https://staging-iam.wink.travel/oauth2/token — vt Autentimine.
• Wink-Version päis on kohustuslik; selle puudumine ei suuna päringut v2 JSON API-le.
• Content-Type: application/json lisatakse PUT päringutele, millel on keha.

Järgnevas näidetes vastavad kohatäited väärtustele, mille kogusid eelnevalt Eeltingimustes:

Kohatäide	Tähendus
{managingEntityIdentifier}	Sinu Affiliate / Kanalihalduri konto ID (UUID) — vt Oma konto identifikaatorite leidmine.
{propertyIdentifier}	Hotelli konto (kinnistu) ID, mis on seotud CM kontoga.
{masterRateIdentifier}	Master hind (toatüüp × hinnaplaan), mille vastu sertifitseerid.
{bookingIdentifier}	Staging broneeringu ID, mis tagastati broneeringute nimekirja päringus.

Samm A — Ping

Kinnita, et sinu mandaadid viitavad oodatud Affiliate / Kanalihalduri kontole.

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"

Oodatud vastus:

{
  "apiVersion": "2.0",
  "name": "Sinu Kanalihalduri Konto Nimi",
  "status": "PENDING_APPROVAL"
}

200 vastus koos sobiva name väärtusega näitab, et autentimine ja konto tuvastus on õiged. status loeb PENDING_APPROVAL kuni Wink sind sertifitseerib.

Samm B — Hotellide nimekiri

Päringu abil saa oma kontoga seotud hotellide leheküljeline nimekiri ja kinnita, et sinu testkinnistu on olemas.

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"

Vastus on Spring Page tüüpi ChannelManagerProperty kirjetega. Leia kirje, mille identifier vastab sinu {propertyIdentifier}-le ja märgi selle currencyCode — seda vajad hinnauuenduste tõlgendamiseks Sammus D.

Caution

Tühi nimekiri on konfiguratsiooni signaal, mitte vigane päring. Hotell tagastatakse alles siis, kui see on ACTIVE ja on määratud sinu kanalihalduri kontole Extranet → Distribution → Channel Manager all. Kontrolli mõlemat GET /api/managing-entity/list abil (vt Oma konto identifikaatorite leidmine) enne edasist tõrkeotsingut. Tootmises lisa kolmas põhjus: hotell on siin nähtamatu kuni Wink selle heaks kiidab.

Samm C — Master hindade päring

Päringu abil saa kinnistu koos kõigi avaldatud master hindadega (toatüüp × hinnaplaan kombinatsioonid). Vali see, mille vastu sertifitseerid, ja märgi selle identifier oma {masterRateIdentifier}-ina.

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"

Vastus on PropertyWithRoomRateList: property plokk ja rooms massiiv PropertyRoomRate kirjetega. Iga kirje näitab toatüüpi, hinnaplaani, täituvuspiiranguid, baasihinda ja hinnamuutjaid, mida säilitad päevaste hindade uuendamisel.

Caution

Sertifitseeri kogu sertifitseerimisprotsessi jooksul ühe master hinna vastu. Täiendavate toatüüpide ja hinnaplaanide kaardistamine on tootmises oodatud, kuid tõendite pakett peab näitama ainult ühe master hinna kasutamist lõpp-lõpuni.

Samm D — Laadi sertifitseerimisnädal

Laadi seitsmepäevane hinnakalender, mis katab kuu esimese seitsme kalendripäeva järgmisel kuul pärast sertifitseerimise algust. Näiteks, kui alustad 21. augustil, sihi 1. septembrist kuni 7. septembrini.

Saadad seitsme eraldi PUT päringu — iga päev eraldi — kus startDate == endDate. Iga päev kannab teadlikult erinevat kombinatsiooni summast, kogusest, saabumise/lahkumise sulgemise lipust ja min/max peatumise pikkusest, et iga kirjutatav väli saaks vähemalt korra testitud. Väärtused on kinnistu valuutas (märkisid Sammus B); jäta currencyCode välja, see võetakse õigesti vaikimisi.

Päev	Summa	Kogus	closedOnArrival	closedOnDeparture	minLengthOfStay	maxLengthOfStay	Mida see tõendab
1	100.00	5	false	false	1	30	Alguspunkt.
2	125.00	4	false	false	1	14	Summa + kogus + maxLengthOfStay muutus.
3	150.00	3	true	false	1	30	closedOnArrival lüliti.
4	175.00	2	false	true	2	7	closedOnDeparture lüliti + kitsam peatumise aken.
5	200.00	0	false	false	1	30	Müüdud kogus.
6	225.00	5	false	false	3	5	Piiratud peatumise aken.
7	250.00	1	false	false	1	30	Viimane toa saadavus.

Päringu keha esimese päeva jaoks näeb välja selline. Korda, muutes startDate / endDate / väärtusi vastavalt tabelile päevade 2 kuni 7 jaoks.

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

Iga PUT vastab 200 koos uuendatud PropertyRate kirjetega saadetud kuupäevavahemiku kohta (üks kirje, kui startDate == endDate). Salvesta see vastus — see on osa sinu tõenditest.

Note

master peaks olema true kõigil sertifitseerimisnädala päringutel. See ütleb Winkile, et sinu uuendus on mallihind, mitte broneeringupõhine ülekate.

Samm E — Loe sertifitseerimisnädal tagasi

Päringu abil saa kogu nädal ühe korraga ja kinnita, et iga päeva salvestatud väärtused vastavad Sammus D saadetud reale — kaasa arvatud loogilised lipud ja peatumise pikkuse piirangud.

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"

Vastus on PropertyRoomRateWithRateList. Selle rates massiiv peab sisaldama seitsme kirjet, üks iga päeva kohta, igaühes amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay ja maxLengthOfStay, mille sa laadisid. Kui mõni väli ei klapi, tähendab see, et vastav Sammus D tehtud PUT ei jõudnud õigesti kohale — paranda see ja testi uuesti enne jätkamist.

Samm F — Tee testbroneering

Ava brauseris järgmine URL, asendades <your-slug> Hotelli konto slugiga, mille avaldasid eeltingimustes:

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

Vali saabumise ja lahkumise kuupäevad, mis jäävad täielikult sertifitseerimisnädala sisse, vali sertifitseeritud toatüübi ja hinnaplaani kombinatsioon ning lõpeta broneering. Staging kasutab testmakse rada — reaalset kaarti ei võeta.

Kui kinnitusleht kuvatakse, märgi üles külalisele näidatud broneeringukood (vormingus WNKxxxxx).

Samm G — Tõmba broneering

Päringu abil saa kõik broneeringud, mis on tehtud sinu testkinnistu vastu ajavahemikus, mis hõlmab broneeringu ajatemplit.

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"

Leia kirje, mille bookingCode vastab Sammus F salvestatud koodile. Märgi selle bookingIdentifier. Seejärel päringu abil saa see üksik broneering:

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"

Vastus on PropertyBooking. Impordi see oma PMS / kanalihalduri kasutajaliidesesse ja kinnita, et operaator näeb korrektselt:

• bookingCode, bookingIdentifier, createdDate
• Külaline: firstName, lastName, email
• totalAmount + currencyCode (netosumma, mille hotell kõigi tubade eest saab)
• paymentMethodType, paymentMethodStatus, salesChannelName
• Iga kirje roomStays sees: guestRoomName, ratePlanName, adults, children, startDate, endDate ja toa kohta amount

Tee broneeringust ekraanipilt oma kasutajaliideses — see on üks nõutud tõenditest.

Samm H — Tühista broneering ja kontrolli

Palun Wink meeskonnal tühistada sertifitseerimisbroneering sinu eest (või tühista see ise Hotelli konto Extraneti kaudu, kui sul on selleks õigus). Seejärel päringu abil uuesti sama broneering.

Kinnita, et vastus nüüd näitab:

• cancelled: true
• Täidetud cancelDate ajatemplit
• paymentMethodStatus, mis kajastab tühistamise elutsüklit (CANCELLED, PARTIALLY_REFUNDED või FULLY_REFUNDED vastavalt tagasimakse poliitikale)

Impordi uuendatud broneering oma kasutajaliidesesse ja kinnita, et operaator näeb tühistust — staatust, tühistamise kuupäeva ja kõiki sinu UI poolt toetatud tagasimakse indikaatoreid. Tee teine ekraanipilt tühistatud broneeringust oma UI-s. See on viimane tõend.

Samm I — Esita oma tõendite pakett

Paki järgmised failid ühte arhiivi (.zip), mille nimeks pane wink-cert-<sinu-kanalihalduri-nimi>-<aaaa-kk-pp>.zip:

1. API transkriptsioon. Iga sammudes A kuni H tehtud päringu puhul salvesta täielik HTTP päring (meetod, URL, päised koos Authorization väärtuse varjamisega ja PUT päringute JSON keha) ja täielik HTTP vastus (staatuskood, päised ja JSON keha). Struktureeri transkriptsioon nii, et iga päringu/vastuse paar on selgelt märgistatud vastava sammuga (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json jne). Sobivad on ka tavalise tekstina .http failid või üks .har eksport.

2. UI ekraanipilt: aktiivne broneering. Sammust G pärit ekraanipilt, mis näitab sertifitseerimisbroneeringut sinu PMS / kanalihalduri UI-s koos külalise, kuupäevade, toa, hinnaplaani ja kogusummaga selgelt loetavana.

3. UI ekraanipilt: tühistatud broneering. Sammust H pärit ekraanipilt samast broneeringust sinu UI-s pärast tühistamist, kus tühistatud staatus ja kuupäev on selgelt loetavad.

4. Sertifitseerimise kokkuvõte. Lühike README.md arhiivi sees, mis sisaldab:

   • Sinu kanalihalduri / PMS-i nimi ja versioon.
   • Kasutatud managingEntityIdentifier, propertyIdentifier, masterRateIdentifier ja bookingIdentifier.
   • Staging hotelli slug (see <your-slug> aadressil https://staging-book.wink.travel/hotel/<your-slug>).
   • Sertifitseerimisnädala kuupäevavahemik (Päev 1 → Päev 7 ISO-8601 formaadis).
   • Sertifitseerimise teostanud inseneri nimi ja e-post.

Saada arhiiv oma Wink integratsioonide kontaktile. Wink vaatab selle üle, küsib vajadusel täpsustusi ja — kui läbitud — muudab su Affiliate / Kanalihalduri konto staatuse PENDING_APPROVAL-st ACTIVE-ks. Seejärel on su integratsioon valmis tootmisse viimiseks.

Tip

Automatiseeri transkriptsiooni salvestamine. Sammus D tehtud seitse PUT päringut ja Sammus E tehtud tagasiloetav päring on kõige sagedasemad sertifitseerimisvead — interaktiivne HTTP klient, mis salvestab iga päringu ja vastuse jooksvalt, säästab sind täielikust kordamisest, kui mõni väärtus on veidi vale.

Webhook teavitused

Võid tellida kanalihalduri webhook sündmusi, et saada reaalajas teavitusi:

• channel-manager.update.rate — hinnauuendus laekus.
• channel-manager.update.availability — saadavuse uuendus laekus.
• channel-manager.update — üldine kanalihalduri uuendus.

Vaata Webhook sündmuste kataloogi detailide jaoks.

Täiendav lugemine

• Kanalihalduri API — Täielik API lõpp-punktide dokumentatsioon.
• Hinnapakkujad — Hinnapakkujate haldamine Extranetis.
• Webhook sündmuste kataloog — Kõik tellitavad sündmused.
• Arenda Wink platvormil — Platvormi ülevaade arendajatele.