Pāriet uz saturu

Pievienojiet savu kanālu pārvaldnieku

Šis ceļvedis ved kanālu pārvaldnieku un PMS izstrādātājus cauri pilnam integrācijas procesam ar Wink — no kontu izveides līdz inventāra kartēšanai un pirmajam pilna cikla testam.

Kanālu pārvaldnieka (Integrāciju) API ir pieejams divās vidēs. Izmantojiet staging vidi visai izstrādei un sertifikācijai; pārejiet uz produkciju tikai pirms palaišanas.

VideBāzes URL
Produkcijahttps://integrations.wink.travel
Staginghttps://staging-integrations.wink.travel

Kanālu pārvaldnieka API seko OTA protokola standartiem (SOAP/XML), lai nodrošinātu saderību ar esošajām viesnīcu sistēmām. Sāciet ar partnera galapunktu dokumentācijas pārskatīšanu:

Kanālu pārvaldnieka API — Partnera galapunkti

  1. Izveidojiet Wink lietotāja kontu

    Reģistrējieties vietnē staging-app.wink.travel. Visi tālāk minētie soļi tiek veikti staging vidē — pilnu procesu atkārtosiet arī produkcijā pirms palaišanas.

  2. Izveidojiet savu Affiliate / Kanālu pārvaldnieka kontu

    Sava jaunā lietotāja ietvaros izveidojiet kontu un izvēlieties konta tipu Affiliate / Channel Manager. Šis konts tiks izmantots jūsu integrācijas autentifikācijai.

  3. Reģistrējiet lietotni un izveidojiet savu pirmo tokenu

    Izveidojiet Lietotni un sasaistiet to ar kanālu pārvaldnieka kontu no 2. soļa. Izvēlieties klienta tipu MACHINE_2_MACHINE — tā ir servera-servera integrācija bez gala lietotāja pāradresācijas. Nekavējoties kopējiet Client ID un Secret Key; slepenā atslēga tiek parādīta tikai vienreiz un to nevar atkārtoti iegūt.

    Lietotne ģenerē bearer tokenu, ko katrs šī ceļveža izsaukums nes kā Authorization: Bearer <access_token>. Apmainiet savas akreditācijas datus pret tokenu, izmantojot client_credentials grant pie https://staging-iam.wink.travel/oauth2/token, pieprasot integrations.read integrations.write piekļuves tiesības. To izdariet pirms turpināšanas — bez tokena nevarēsiet piekļūt konta identifikatoriem vai Kanālu pārvaldnieka galapunktiem. Skatiet Autentifikācija pilnai plūsmai, produkcijas hostam un pilnam piekļuves tiesību katalogam.

  4. Izveidojiet viesnīcas kontu

    Tā paša lietotāja ietvaros izveidojiet otro kontu un izvēlieties konta tipu Hotel. Tas nodrošina īpašumu, ko var izmantot testēšanai bez reālas viesnīcas iesaistes.

  5. Apstipriniet abu kontu apstiprinājumu

    Neviens konts nav izmantojams, kamēr tas nav apstiprināts: neapstiprināts kanālu pārvaldnieka konts neparādās nevienā viesnīcas kanālu pārvaldnieku sarakstā, un neapstiprināta viesnīca netiek atgriezta API.

    • Staging — apstiprinājums ir automātisks. Abi konti ir izmantojami uzreiz pēc izveides, un nav nepieciešams nekas pieprasīt.
    • Produkcija — apstiprinājums ir manuāls. Nosūtiet Wink integrāciju kontaktpersonai abu kontu nosaukumus un lietotāju, zem kura tie atrodas, un gaidiet apstiprinājumu pirms turpināšanas.
  6. Savienojiet abus kontus

    Piesakieties viesnīcas kontā un dodieties uz Channels → Channel manager. Izvēlieties savu kanālu pārvaldnieka kontu no saraksta — tas sasaista īpašumu ar jūsu integrāciju. Ja jūsu konts nav sarakstā, tas vēl nav apstiprināts; skatiet 5. soli.

  7. Izveidojiet pamata istabas tipu un cenu plānu

    Viesnīcas kontā izveidojiet vismaz vienu istabas tipu un vienu cenu plānu. Tie ir nepieciešami, lai jūsu integrācija varētu nosūtīt cenas un pieejamību vai saņemt rezervācijas.

  8. Kartējiet un testējiet

    Savā sistēmā kartējiet istabas tipa un cenu plāna identifikatorus, ko atgriež API. Nosūtiet cenu un pieejamības atjauninājumus, veiciet testa rezervāciju un pārbaudiet, vai rezervāciju izgūšanas galapunkts to pareizi atgriež.

Katrs Kanālu pārvaldnieka API ceļš ir saistīts ar jūsu pašu kontu:

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

{managingEntityIdentifier} ir jūsu kanālu pārvaldnieka konta ID (UUID) — nevis viesnīcas. Iegūstiet to kopā ar citu jūsu lietotāja kontu ID un pašreizējo statusu no Platformas 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"

Atbilde ir masīvs ar jūsu kontiem:

[
{
"id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
"type": "CHANNEL_MANAGER",
"name": "Jūsu kanālu pārvaldnieks",
"status": "ACTIVE"
},
{
"id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
"type": "HOTEL",
"name": "Jūsu testa īpašums",
"urlName": "your-test-property",
"status": "ACTIVE"
}
]
  • Kanālu pārvaldnieka ieraksta id ir jūsu {managingEntityIdentifier}.
  • Viesnīcas ieraksta id ir jūsu {propertyIdentifier}.
  • status ļauj pārbaudīt, vai katrs konts ir apstiprināts — īpaši svarīgi produkcijā, kur apstiprinājums ir manuāls. Viesnīcai jābūt ar statusu ACTIVE, lai tā būtu rezervējama vai redzama Kanālu pārvaldnieka API. Jūsu kanālu pārvaldnieka konts saglabā statusu PENDING_APPROVAL līdz brīdim, kad izietat Sertifikāciju; tas ir gaidāms un neietekmē izstrādi.

Sertifikācija pierāda — un Wink apstiprina — ka jūsu integrācija pareizi kartē inventāru, nosūta cenas un pieejamību, kā arī saņem rezervācijas pilnā ciklā. Tā ir paredzēta kā pašapkalpošanās process: jūs veicat katru soli savā sistēmā un beigās iesniedzat vienu pierādījumu komplektu. Wink pārskata komplektu un, ja tas ir veiksmīgs, maina jūsu Affiliate / Kanālu pārvaldnieka konta statusu no PENDING_APPROVAL uz ACTIVE.

Sertifikācija notiek pilnībā staging vidē (https://staging-integrations.wink.travel). Nekas šajā sadaļā neietekmē produkciju.

  1. Autentifikācija. Jūsu OAuth2 klients var iegūt piekļuves tokenu un veiksmīgi izsaukt /ping galapunktu pret jūsu Affiliate / Kanālu pārvaldnieka kontu.

  2. Inventāra kartēšana. Jūs varat uzskaitīt viesnīcu(-as), kas piesaistītas jūsu kontam, izgūt galveno cenu (istabas tips × cenu plāns), ko konfigurējāt, un pareizi identificēt masterRateIdentifier, uz kuru jūsu sistēma mērķēs.

  3. Cenu un pieejamības nosūtīšana. Jūs varat neatkarīgi atjaunināt visas septiņas sertifikācijas nedēļas dienas — ar dažādām summām, daudzumiem, ierobežojumiem ierašanās un izrakstīšanās dienā, kā arī minimālo/maksimālo uzturēšanās ilgumu katrai dienai — un precīzi nolasīt šīs vērtības atpakaļ no Wink.

  4. Rezervāciju izgūšana. Jūs varat izgūt reālu staging rezervāciju, kas veikta pret jūsu testa īpašumu, parādīt to savā PMS/kanālu pārvaldnieka UI ar pareizu istabas uzturēšanos, viesi un kopējo summu, un pēc tam atspoguļot atcelšanu, kad Wink atzīmē rezervāciju kā atcelto.

Pirms sākat sertifikāciju, pabeidziet 1.–7. soļus no Integrācijas soļi, lai jums būtu:

  • Wink lietotājs staging vidē ar Affiliate / Channel Manager kontu un tam piesaistītu Hotel kontu (Channels → Channel manager). Staging konti tiek apstiprināti automātiski, tāpēc nav nepieciešams nekas pieprasīt.
  • Vismaz viens istabas tips un viens cenu plāns izveidots viesnīcas kontā. Publicējiet viesnīcu, lai tā būtu rezervējama vietnē https://staging-book.wink.travel/hotel/<your-slug>.
  • Reģistrēta lietotne jūsu Affiliate / Channel Manager kontā ar Client ID, Secret Key un integrations.read integrations.write piekļuves tiesībām (skatiet Autentifikācija).
  • Jūsu Affiliate / Channel Manager konta managingEntityIdentifier un viesnīcas konta propertyIdentifier (abi ir UUID — skatiet Konta identifikatoru atrašana).

Katrs pieprasījums šajā sadaļā izmanto šādus galvenes:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json
  • <access_token> iegūts ar client_credentials grant pie https://staging-iam.wink.travel/oauth2/token — skatiet Autentifikācija.
  • Galvene Wink-Version ir obligāta; tās neiekļaušana novirzīs prom no v2 JSON API.
  • Content-Type: application/json tiek pievienots PUT pieprasījumiem ar ķermeni.

Tālākajos piemēros vietturi atbilst vērtībām, ko ieguvāt Priekšnosacījumos:

Viettura nosaukumsNozīme
{managingEntityIdentifier}Jūsu Affiliate / Channel Manager konta ID (UUID) — skatiet Konta identifikatoru atrašana.
{propertyIdentifier}Viesnīcas konta (īpašuma) ID, kas piesaistīts CM kontam.
{masterRateIdentifier}Galvenā cena (istabas tips × cenu plāns), pret kuru veiksiet sertifikāciju.
{bookingIdentifier}Staging rezervācijas ID, ko atgrieza rezervāciju saraksta izsaukums.

Pārbaudiet, vai jūsu akreditācijas dati atbilst gaidītajam Affiliate / Channel Manager kontam.

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"

Sagaidāmā atbilde:

{
"apiVersion": "2.0",
"name": "Jūsu kanālu pārvaldnieka konta nosaukums",
"status": "PENDING_APPROVAL"
}

200 atbilde ar atbilstošu name norāda, ka autentifikācija un konta identifikācija ir pareiza. status lasīs PENDING_APPROVAL līdz Wink apstiprinās jūs.

Iegūstiet lapotu viesnīcu sarakstu, kas piesaistītas jūsu kontam, un pārliecinieties, ka jūsu testa īpašums ir klāt.

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"

Atbilde ir Spring Page ar ChannelManagerProperty ierakstiem. Atrodiet ierakstu, kura identifier atbilst jūsu {propertyIdentifier}, un pierakstiet tā currencyCode — tas būs nepieciešams cenu atjauninājumu interpretācijai Solis D.

Iegūstiet īpašumu kopā ar visām galvenajām cenām (istabas tips × cenu plāns), ko tas publicē. Izvēlieties to, pret kuru vēlaties sertificēties, un pierakstiet tā identifier kā {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"

Atbildes aploksne ir PropertyWithRoomRateList: property bloks un rooms masīvs ar PropertyRoomRate ierakstiem. Katrs ieraksts satur istabas tipu, cenu plānu, noslogojuma ierobežojumus, bāzes cenu un cenu modifikatorus, ko saglabāsiet, nosūtot dienas cenas.

Solis D — Ielādējiet sertifikācijas nedēļu

Section titled “Solis D — Ielādējiet sertifikācijas nedēļu”

Ielādējiet septiņu dienu cenu kalendāru, kas aptver pirmās septiņas kalendāra dienas mēnesī, kas seko mēnesim, kurā sākat sertifikāciju. Piemēram, ja sākat 21. augustā, mērķējiet uz 1.–7. septembri.

Nosūtīsiet septiņus atsevišķus PUT pieprasījumus — pa vienam katrai dienai — kur startDate == endDate. Katru dienu veido apzināti atšķirīga summa, daudzums, ierobežojumu karodziņi un uzturēšanās ilguma ierobežojumi, lai katrs raksturojams lauks tiktu pārbaudīts vismaz vienu reizi. Vērtības ir īpašuma valūtā (pierakstīta 2. solī); ja izlaidīsiet currencyCode, tas tiks pareizi noklusēts.

Dienas nr.SummaDaudzumsclosedOnArrivalclosedOnDepartureminLengthOfStaymaxLengthOfStayKo tas pierāda
1100.005falsefalse130Pamata diena.
2125.004falsefalse114Summa + daudzums + maxLengthOfStay maiņa.
3150.003truefalse130closedOnArrival maiņa.
4175.002falsetrue27closedOnDeparture maiņa + stingrāks uzturēšanās ilgums.
5200.000falsefalse130Izpārdots daudzums.
6225.005falsefalse35Ierobežots uzturēšanās ilgums.
7250.001falsefalse130Pēdējā istaba pieejama.

Pieprasījuma ķermenis 1. dienai izskatās šādi. Atkārtojiet, pielāgojot startDate / endDate / vērtības katrai dienai no 2. līdz 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
}'

Katrs PUT atbild ar 200 un atjaunināto PropertyRate ierakstu masīvu par nosūtīto periodu (viens ieraksts, ja startDate == endDate). Saglabājiet šo atbildi — tā būs daļa no jūsu pierādījumiem.

Solis E — Nolasiet sertifikācijas nedēļu

Section titled “Solis E — Nolasiet sertifikācijas nedēļu”

Iegūstiet visu nedēļu vienā pieprasījumā un pārliecinieties, ka katras dienas saglabātās vērtības atbilst tām, ko nosūtījāt Solī D — ieskaitot loģiskos karodziņus un uzturēšanās ilguma ierobežojumus.

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"

Atbilde ir PropertyRoomRateWithRateList. Tā rates masīvā jābūt septiņiem ierakstiem, pa vienam katrai dienai, katram ar amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay un maxLengthOfStay, ko ielādējāt. Ja kāds lauks neatbilst, tas nozīmē, ka attiecīgais PUT Solī D nav veiksmīgi piemērots — labojiet un pārbaudiet vēlreiz pirms turpināt.

Atveriet pārlūkprogrammā šo URL, aizvietojot <your-slug> ar viesnīcas konta slugu, ko publicējāt Priekšnosacījumos:

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

Izvēlieties ierašanās un izrakstīšanās datumus, kas pilnībā ietilpst jūsu sertifikācijas nedēļā, izvēlieties sertificēto istabas tipu un cenu plānu, un pabeidziet rezervāciju. Staging izmanto testa maksājumu ceļu — nekāda reāla karte netiek ieturēta.

Kad apstiprinājuma lapa tiek parādīta, pierakstiet viesim redzamo rezervācijas kodu (formāts WNKxxxxx).

Iegūstiet visas rezervācijas, kas izveidotas jūsu testa īpašumam laika logā, kas aptver rezervācijas laiku.

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"

Atrodiet ierakstu, kura bookingCode atbilst jūsu Solī F pierakstītajam kodam. Pierakstiet tā bookingIdentifier. Tad izgūstiet šo vienu rezervāciju:

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"

Atbilde ir PropertyBooking. Importējiet to savā PMS / kanālu pārvaldnieka UI un pārliecinieties, ka operators redz pareizi:

  • bookingCode, bookingIdentifier, createdDate
  • Viesis: firstName, lastName, email
  • totalAmount + currencyCode (neto summa, ko viesnīca saņem par visām istabām)
  • paymentMethodType, paymentMethodStatus, salesChannelName
  • Katru ierakstu roomStays: guestRoomName, ratePlanName, adults, children, startDate, endDate un istabas līmeņa amount

Uzņemiet ekrānuzņēmumu ar rezervāciju, kā tā izskatās jūsu UI — šis ekrānuzņēmums ir viens no nepieciešamajiem pierādījumiem.

Solis H — Atceliet rezervāciju un pārbaudiet

Section titled “Solis H — Atceliet rezervāciju un pārbaudiet”

Lūdziet Wink komandai atcelt sertifikācijas rezervāciju jūsu vietā (vai atceliet to pats no viesnīcas konta Extranet, ja jums ir šī atļauja). Tad atkārtoti izgūstiet to pašu rezervāciju ar Solī G izmantoto izsaukumu.

Pārliecinieties, ka atbilde tagad rāda:

  • cancelled: true
  • Aizpildīts cancelDate laika zīmogs
  • paymentMethodStatus, kas atspoguļo atcelšanas statusu (CANCELLED, PARTIALLY_REFUNDED vai FULLY_REFUNDED atkarībā no atmaksas politikas)

Importējiet šo atjaunināto rezervāciju savā UI un pārliecinieties, ka operators redz atcelšanu — statusu, atcelšanas laiku un jebkuru jūsu UI atbalstītu atmaksas indikatoru. Uzņemiet otru ekrānuzņēmumu ar atcelto rezervāciju jūsu UI. Tas ir pēdējais pierādījumu materiāls.

Solis I — Iesniedziet pierādījumu komplektu

Section titled “Solis I — Iesniedziet pierādījumu komplektu”

Iesaiņojiet šādus materiālus vienā arhīvā (.zip) ar nosaukumu wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip:

  1. API transkripts. Katram pieprasījumam no soļiem A līdz H saglabājiet pilnu HTTP pieprasījumu (metode, URL, pieprasījuma galvenes ar Authorization vērtības anonimizāciju un JSON ķermeni PUT pieprasījumiem) un pilnu HTTP atbildi (statusa kods, atbildes galvenes un JSON ķermenis). Strukturējiet transkriptu tā, lai katrs pieprasījums/atbilde būtu skaidri apzīmēta ar attiecīgo soli (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json utt.). Pieņemami ir gan teksta .http faili, gan viens .har eksports.

  2. UI ekrānuzņēmums: aktīvā rezervācija. Ekrānuzņēmums no soļa G, kurā redzama sertifikācijas rezervācija jūsu PMS / kanālu pārvaldnieka UI ar viesi, datumiem, istabas tipu, cenu plānu un kopējo summu skaidri salasāmu.

  3. UI ekrānuzņēmums: atcelta rezervācija. Ekrānuzņēmums no soļa H, kurā redzama tā pati rezervācija jūsu UI pēc atcelšanas ar skaidri salasāmu atcelšanas statusu un laika zīmogu.

  4. Sertifikācijas kopsavilkums. Īss README.md arhīvā ar:

    • Jūsu kanālu pārvaldnieka / PMS nosaukumu un versiju.
    • Izmantotajiem managingEntityIdentifier, propertyIdentifier, masterRateIdentifier un bookingIdentifier.
    • Staging viesnīcas slugu (<your-slug> no https://staging-book.wink.travel/hotel/<your-slug>).
    • Sertifikācijas nedēļas datumu diapazonu (1. diena → 7. diena ISO-8601 formātā).
    • Inženiera vārdu un e-pastu, kas veica sertifikāciju.

Nosūtiet arhīvu savai Wink integrāciju kontaktpersonai. Wink pārskatīs, sekos līdzi jebkādām neatbilstībām un — ja viss būs kārtībā — mainīs jūsu Affiliate / Channel Manager konta statusu no PENDING_APPROVAL uz ACTIVE. Tad jūsu integrācija būs gatava produkcijas pieslēgšanai.

Jūs varat abonēt kanālu pārvaldnieka webhook notikumus, lai saņemtu reāllaika paziņojumus:

  • channel-manager.update.rate — saņemts cenu atjauninājums.
  • channel-manager.update.availability — saņemts pieejamības atjauninājums.
  • channel-manager.update — vispārīgs kanālu pārvaldnieka atjauninājums.

Skatiet Webhook notikumu katalogu sīkākai informācijai.