Saltar al contingut

Afegeix el teu Channel Manager

Aquesta guia acompanya els desenvolupadors de channel manager i PMS durant tot el procés d’integració amb Wink — des de la creació dels comptes fins al mapeig de l’inventari i la realització de la primera prova completa.

L’API de Channel Manager (Integrations) està disponible en dos entorns. Utilitza staging per a tot el desenvolupament i la certificació; canvia a producció només en el moment del llançament.

EntornURL base
Produccióhttps://integrations.wink.travel
Staginghttps://staging-integrations.wink.travel

L’API de Channel Manager segueix els estàndards del protocol OTA (SOAP/XML) per garantir la compatibilitat amb sistemes hotelers existents. Comença revisant la documentació dels endpoints per a partners:

Channel Manager API — Endpoints per a partners

  1. Crea un compte d’usuari Wink

    Registra’t a staging-app.wink.travel. Tots els passos següents utilitzen staging — repetiràs tot el procés a producció abans del llançament.

  2. Crea el teu compte d’Afiliat / Channel Manager

    Amb el nou usuari, crea un compte i selecciona el tipus de compte Afiliat / Channel Manager. Aquest serà el compte amb què s’autenticarà la teva integració.

  3. Registra una aplicació i genera el teu primer token

    Crea una Aplicació i vincula-la al compte de channel manager del pas 2. Tria MACHINE_2_MACHINE com a tipus de client — és una integració servidor a servidor sense redirecció d’usuari final. Copia immediatament el Client ID i la Secret Key; la clau secreta es mostra només una vegada i no es pot recuperar.

    L’aplicació és la que genera el token bearer que cada crida d’aquesta guia porta com a Authorization: Bearer <access_token>. Canvia les teves credencials per un token fent servir el grant client_credentials contra https://staging-iam.wink.travel/oauth2/token, sol·licitant els àmbits integrations.read integrations.write. Fes-ho abans de continuar — no podràs consultar identificadors de comptes ni accedir a cap endpoint de Channel Manager sense token. Consulta Autenticació per al flux complet, l’host de producció i el catàleg complet d’àmbits.

  4. Crea un compte d’Hotel

    Amb el mateix usuari, crea un segon compte i selecciona el tipus Hotel. Això et proporciona una propietat per fer proves sense involucrar un hotel real.

  5. Confirma que ambdós comptes estan aprovats

    Cap compte es pot utilitzar fins que no estigui aprovat: un compte de channel manager no aprovat no apareix a la llista de channel managers de cap hotel, i un hotel no aprovat no és retornat per l’API.

    • Staging — l’aprovació és automàtica. Ambdós comptes són usables tan bon punt els crees, i no cal sol·licitar res.
    • Producció — l’aprovació és manual. Envia al contacte d’integracions de Wink els noms dels dos comptes i l’usuari sota el qual estan, i espera la confirmació abans de continuar.
  6. Connecta els dos comptes

    Inicia sessió al compte d’Hotel i ves a Channels → Channel manager. Selecciona el teu compte de channel manager de la llista — això vincula la propietat a la teva integració. Si el teu compte no apareix a la llista, encara no està aprovat; consulta el pas 5.

  7. Crea un tipus d’habitació i un pla tarifari bàsics

    Dins del compte d’Hotel, crea almenys un tipus d’habitació i un pla tarifari. Són obligatoris abans que la teva integració pugui enviar tarifes i disponibilitat o recuperar reserves.

  8. Mapeig i prova

    Al teu propi sistema, mapeja els identificadors del tipus d’habitació i del pla tarifari retornats per l’API. Envia una actualització de tarifa i una d’disponibilitat, després fes una reserva de prova i comprova que l’endpoint de recuperació de reserves la retorna correctament.

Com trobar els identificadors dels teus comptes

Section titled “Com trobar els identificadors dels teus comptes”

Cada ruta de l’API de Channel Manager està limitada al teu propi compte:

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

{managingEntityIdentifier} és l’ID del compte (un UUID) del teu compte de channel manager — no de l’hotel. Obtingues-lo, juntament amb l’ID i l’estat actual de qualsevol altre compte que tingui el teu usuari, des de l’API de la Plataforma:

Finestra del terminal
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"

La resposta és un array amb els comptes que posseeixes:

[
{
"id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
"type": "CHANNEL_MANAGER",
"name": "El teu Channel Manager",
"status": "ACTIVE"
},
{
"id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
"type": "HOTEL",
"name": "La teva propietat de prova",
"urlName": "your-test-property",
"status": "ACTIVE"
}
]
  • L’id de l’entrada channel manager és el teu {managingEntityIdentifier}.
  • L’id de l’entrada HOTEL és el teu {propertyIdentifier}.
  • status és on confirmes que cada compte està aprovat — especialment útil a producció, on l’aprovació és manual. L’hotel ha de tenir l’estat ACTIVE abans de poder reservar-lo o que sigui visible per a l’API de Channel Manager. El teu compte de channel manager continuarà mostrant PENDING_APPROVAL fins que passis la Certificació; això és esperat i no bloqueja el desenvolupament.

La certificació és com demostres — i com Wink confirma — que la teva integració mapeja correctament l’inventari, envia tarifes i disponibilitat, i rep reserves de principi a fi. Està dissenyada per ser auto-servei: tu controles cada pas des del teu propi sistema i submits un únic paquet d’evidències al final. Wink revisa el paquet i, si és correcte, promociona el teu compte d’Afiliat / Channel Manager de PENDING_APPROVAL a ACTIVE.

La certificació es fa completament contra l’entorn staging (https://staging-integrations.wink.travel). Res d’aquesta secció afecta producció.

  1. Autenticació. El teu client OAuth2 pot obtenir un token d’accés i cridar amb èxit l’endpoint /ping contra el teu compte d’Afiliat / Channel Manager.

  2. Mapeig d’inventari. Pots llistar l’hotel o hotels connectats al teu compte, recuperar la tarifa mestre (tipus d’habitació × pla tarifari) que has configurat, i identificar correctament el masterRateIdentifier que el teu sistema utilitzarà.

  3. Enviament de tarifes i disponibilitat. Pots actualitzar els set dies d’una setmana de certificació de manera independent — amb diferents combinacions d’import, quantitat, flags de tancament a l’arribada / sortida, i mínim/màxim de durada d’estada per a cada dia — i llegir els valors exactes que Wink emmagatzema.

  4. Recuperació de reserves. Pots recuperar una reserva real de staging feta contra la teva propietat de prova, mostrar-la a la teva pròpia interfície PMS/CM amb l’habitació, hoste i total correctes, i reflectir una cancel·lació un cop Wink marqui la reserva com a cancel·lada.

Abans de començar la certificació, completa els passos 1–7 de Passos d’integració per assegurar-te que tens:

  • Un usuari Wink a staging amb un compte Afiliat / Channel Manager i un compte Hotel connectats (Channels → Channel manager). Els comptes de staging s’aproven automàticament, així que no cal sol·licitar res.
  • Almenys un tipus d’habitació i un pla tarifari creats dins del compte d’Hotel. Publica l’hotel perquè sigui reservable a https://staging-book.wink.travel/hotel/<your-slug>.
  • Una aplicació registrada sota el teu compte d’Afiliat / Channel Manager amb un Client ID, Secret Key, i els àmbits integrations.read integrations.write (consulta Autenticació).
  • El managingEntityIdentifier del teu compte d’Afiliat / Channel Manager i el propertyIdentifier del teu compte d’Hotel (ambdós són UUIDs — consulta Com trobar els identificadors dels teus comptes).

Cada petició d’aquesta secció utilitza aquests headers:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json
  • <access_token> prové del grant client_credentials contra https://staging-iam.wink.travel/oauth2/token — consulta Autenticació.
  • El header Wink-Version és obligatori; si no es posa, no es dirigirà a l’API JSON v2.
  • Content-Type: application/json s’afegeix a les peticions PUT que porten cos.

Al llarg dels exemples següents, els placeholders corresponen als valors que has obtingut a Prerequisits:

PlaceholderSignificat
{managingEntityIdentifier}L’ID del teu compte d’Afiliat / Channel Manager (UUID) — consulta Com trobar els identificadors dels teus comptes.
{propertyIdentifier}L’ID del compte d’Hotel (propietat) que vas connectar al compte de CM.
{masterRateIdentifier}La tarifa mestre (combinació tipus d’habitació × pla tarifari) que certificaràs.
{bookingIdentifier}L’ID de la reserva de staging retornat per la crida de llista de reserves.

Confirma que les teves credencials corresponen al compte d’Afiliat / Channel Manager que esperes.

Finestra del terminal
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"

Resposta esperada:

{
"apiVersion": "2.0",
"name": "Nom del teu compte de Channel Manager",
"status": "PENDING_APPROVAL"
}

Una resposta 200 amb un name coincident indica que l’autenticació i la resolució del compte són correctes. status mostrarà PENDING_APPROVAL fins que Wink et certifiqui.

Recupera la llista paginada d’hotels vinculats al teu compte i confirma que la teva propietat de prova hi és.

Finestra del terminal
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"

La resposta és una Page de Spring amb entrades ChannelManagerProperty. Localitza l’entrada amb identifier que coincideixi amb el teu {propertyIdentifier} i anota el seu currencyCode — el necessitaràs per interpretar les actualitzacions de tarifes al Pas D.

Recupera la propietat juntament amb totes les tarifes mestres (combinacions tipus d’habitació × pla tarifari) que publica. Tria la que vols certificar i anota el seu identifier com a {masterRateIdentifier}.

Finestra del terminal
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"

La resposta és un objecte PropertyWithRoomRateList: un bloc property més un array rooms d’entrades PropertyRoomRate. Cada entrada exposa el tipus d’habitació, pla tarifari, límits d’ocupació, tarifa base i els modificadors de tarifa que conservaràs quan enviïs tarifes diàries.

Pas D — Carrega la setmana de certificació

Section titled “Pas D — Carrega la setmana de certificació”

Carrega un calendari de tarifes de set dies que cobreixi els primers set dies del mes següent al mes en què comences la certificació. Per exemple, si comences el 21 d’agost, targeta de l’1 al 7 de setembre.

Enviaràs set crides PUT separades — una per dia — on startDate == endDate. Cada dia porta una combinació diferent d’import, quantitat, flags de tancament a l’arribada / sortida, i límits mínim/màxim de durada d’estada perquè cada camp editable s’executi almenys una vegada. Els valors són en la moneda de la propietat (anotada al Pas B); si omets currencyCode es posarà per defecte correctament.

DiaImportQuantitatclosedOnArrivalclosedOnDepartureminLengthOfStaymaxLengthOfStayQuè demostra
1100.005falsefalse130Dia base.
2125.004falsefalse114Canvi d’import + quantitat + maxLengthOfStay.
3150.003truefalse130Canvi de closedOnArrival.
4175.002falsetrue27Canvi de closedOnDeparture + finestra de durada d’estada més estricta.
5200.000falsefalse130Quantitat esgotada.
6225.005falsefalse35Finestra restrictiva de durada d’estada.
7250.001falsefalse130Última habitació disponible.

El cos de la petició per al Dia 1 és així. Repeteix, ajustant startDate / endDate / valors per cada fila, per als Dies 2 a 7.

Finestra del terminal
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
}'

Cada PUT respon amb un 200 i un array d’entrades PropertyRate actualitzades per al rang enviat (una entrada quan startDate == endDate). Guarda aquesta resposta — formarà part de les teves evidències.

Pas E — Llegeix la setmana de certificació

Section titled “Pas E — Llegeix la setmana de certificació”

Recupera tota la setmana en una sola crida i confirma que els valors emmagatzemats per a cada dia coincideixen amb la fila enviada al Pas D — incloent els flags booleans i la finestra de durada d’estada.

Finestra del terminal
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"

La resposta és un PropertyRoomRateWithRateList. El seu array rates ha de contenir set entrades, una per dia, cadascuna amb els camps amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay i maxLengthOfStay que vas carregar. Qualsevol discrepància indica que el corresponent PUT del Pas D no es va aplicar correctament — corregeix-ho i verifica abans de continuar.

Obre l’URL següent en un navegador, substituint <your-slug> pel slug del compte d’Hotel que vas publicar als Prerequisits:

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

Selecciona una data d’arribada i una de sortida que caiguin completament dins la setmana de certificació, tria la combinació de tipus d’habitació + pla tarifari que vas certificar, i completa la reserva. Staging utilitza un camí de pagament de prova — no es carrega cap targeta real.

Quan aparegui la pàgina de confirmació, anota el codi de reserva (format WNKxxxxx) que es mostra a l’hoste.

Recupera totes les reserves creades per la teva propietat de prova dins d’una finestra que cobreixi la marca temporal de la reserva.

Finestra del terminal
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"

Troba l’entrada amb bookingCode que coincideixi amb el codi que vas anotar al Pas F. Anota el seu bookingIdentifier. Després recupera aquesta reserva individual:

Finestra del terminal
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"

La resposta és un PropertyBooking. Importa-la a la teva pròpia interfície PMS / channel manager i confirma que es mostren correctament per a un operador:

  • bookingCode, bookingIdentifier, createdDate
  • Hoste: firstName, lastName, email
  • totalAmount + currencyCode (l’import net que l’hotel rep per totes les habitacions)
  • paymentMethodType, paymentMethodStatus, salesChannelName
  • Cada entrada a roomStays: guestRoomName, ratePlanName, adults, children, startDate, endDate, i per habitació amount

Fes una captura de pantalla de la reserva tal com apareix a la teva pròpia UI — aquesta captura és un dels artefactes d’evidència requerits.

Pas H — Cancel·la la reserva i verifica

Section titled “Pas H — Cancel·la la reserva i verifica”

Demana a l’equip de Wink que cancel·li la reserva de certificació en el teu nom (o cancel·la-la tu mateix des de l’Extranet del compte d’Hotel si tens permís). Després torna a recuperar la mateixa reserva amb la crida del Pas G.

Confirma que la resposta ara mostra:

  • cancelled: true
  • Un timestamp cancelDate completat
  • Un paymentMethodStatus que reflecteixi el cicle de cancel·lació (CANCELLED, PARTIALLY_REFUNDED, o FULLY_REFUNDED segons la política de reemborsament)

Importa aquesta reserva actualitzada a la teva UI i confirma que la cancel·lació és visible per a l’operador — estat, timestamp de cancel·lació i qualsevol indicador de reemborsament que la teva UI suporti. Fes una segona captura de pantalla de la reserva cancel·lada a la teva UI. Aquest és l’últim artefacte d’evidència.

Pas I — Envia el teu paquet d’evidències

Section titled “Pas I — Envia el teu paquet d’evidències”

Empaqueta el següent en un únic arxiu (.zip) anomenat wink-cert-<nom-del-teu-channel-manager>-<aaaa-mm-dd>.zip:

  1. Transcripció de l’API. Per a cada petició feta als passos A a H, captura la petició HTTP completa (mètode, URL, headers amb el valor Authorization ocult, i el cos JSON per a les crides PUT) i la resposta HTTP completa (codi d’estat, headers i cos JSON). Organitza la transcripció perquè cada parell petició/resposta estigui clarament etiquetat amb el pas corresponent (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json, etc.). Es poden usar fitxers .http en text pla o una exportació .har única.

  2. Captura de pantalla UI: reserva activa. La captura del Pas G que mostra la reserva de certificació dins la teva pròpia UI PMS / channel manager, amb hoste, dates, tipus d’habitació, pla tarifari i total clarament llegibles.

  3. Captura de pantalla UI: reserva cancel·lada. La captura del Pas H que mostra la mateixa reserva a la teva UI després de la cancel·lació, amb l’estat cancel·lat i el timestamp clarament llegibles.

  4. Resum de la certificació. Un curt README.md dins l’arxiu que inclogui:

    • El nom i versió del teu channel manager / PMS.
    • Els identificadors managingEntityIdentifier, propertyIdentifier, masterRateIdentifier i bookingIdentifier que vas usar.
    • El slug de l’hotel de staging (el <your-slug> a https://staging-book.wink.travel/hotel/<your-slug>).
    • El rang de dates de la setmana de certificació (Dia 1 → Dia 7 en format ISO-8601).
    • El nom i correu electrònic de l’enginyer que va fer la certificació.

Envia l’arxiu al teu contacte d’integracions de Wink. Wink revisarà, farà seguiment de qualsevol discrepància i — si tot és correcte — canviarà l’estat del teu compte d’Afiliat / Channel Manager de PENDING_APPROVAL a ACTIVE. La teva integració serà llavors elegible per a l’onboarding a producció.

Pots subscriure’t als esdeveniments webhook de channel manager per rebre notificacions en temps real:

  • channel-manager.update.rate — Actualització de tarifa rebuda.
  • channel-manager.update.availability — Actualització de disponibilitat rebuda.
  • channel-manager.update — Actualització general de channel manager.

Consulta el Catàleg d’esdeveniments webhook per a més detalls.