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.
Entorns
Section titled “Entorns”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.
| Entorn | URL base |
|---|---|
| Producció | https://integrations.wink.travel |
| Staging | https://staging-integrations.wink.travel |
Referència de l’API
Section titled “Referència de l’API”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
Passos d’integració
Section titled “Passos d’integració”-
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.
-
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ó.
-
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 grantclient_credentialscontrahttps://staging-iam.wink.travel/oauth2/token, sol·licitant els àmbitsintegrations.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. -
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.
-
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.
-
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.
-
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.
-
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:
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’
idde l’entrada channel manager és el teu{managingEntityIdentifier}. - L’
idde l’entradaHOTELé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’estatACTIVEabans de poder reservar-lo o que sigui visible per a l’API de Channel Manager. El teu compte de channel manager continuarà mostrantPENDING_APPROVALfins que passis la Certificació; això és esperat i no bloqueja el desenvolupament.
Certificació
Section titled “Certificació”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ó.
Què demostraràs
Section titled “Què demostraràs”-
Autenticació. El teu client OAuth2 pot obtenir un token d’accés i cridar amb èxit l’endpoint
/pingcontra el teu compte d’Afiliat / Channel Manager. -
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
masterRateIdentifierque el teu sistema utilitzarà. -
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.
-
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.
Prerequisits
Section titled “Prerequisits”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
managingEntityIdentifierdel teu compte d’Afiliat / Channel Manager i elpropertyIdentifierdel teu compte d’Hotel (ambdós són UUIDs — consulta Com trobar els identificadors dels teus comptes).
Convencions comunes de les peticions
Section titled “Convencions comunes de les peticions”Cada petició d’aquesta secció utilitza aquests headers:
Authorization: Bearer <access_token>Wink-Version: 2.0Accept: application/json<access_token>prové del grantclient_credentialscontrahttps://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/jsons’afegeix a les peticionsPUTque porten cos.
Al llarg dels exemples següents, els placeholders corresponen als valors que has obtingut a Prerequisits:
| Placeholder | Significat |
|---|---|
{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. |
Pas A — Ping
Section titled “Pas A — Ping”Confirma que les teves credencials corresponen al compte d’Afiliat / Channel Manager que esperes.
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.
Pas B — Llista de propietats
Section titled “Pas B — Llista de propietats”Recupera la llista paginada d’hotels vinculats al teu compte i confirma que la teva propietat de prova hi és.
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.
Pas C — Recupera les tarifes mestres
Section titled “Pas C — Recupera les tarifes mestres”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}.
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.
| Dia | Import | Quantitat | closedOnArrival | closedOnDeparture | minLengthOfStay | maxLengthOfStay | Què demostra |
|---|---|---|---|---|---|---|---|
| 1 | 100.00 | 5 | false | false | 1 | 30 | Dia base. |
| 2 | 125.00 | 4 | false | false | 1 | 14 | Canvi d’import + quantitat + maxLengthOfStay. |
| 3 | 150.00 | 3 | true | false | 1 | 30 | Canvi de closedOnArrival. |
| 4 | 175.00 | 2 | false | true | 2 | 7 | Canvi de closedOnDeparture + finestra de durada d’estada més estricta. |
| 5 | 200.00 | 0 | false | false | 1 | 30 | Quantitat esgotada. |
| 6 | 225.00 | 5 | false | false | 3 | 5 | Finestra restrictiva de durada d’estada. |
| 7 | 250.00 | 1 | false | false | 1 | 30 | Ú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.
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.
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.
Pas F — Fes una reserva de prova
Section titled “Pas F — Fes una reserva de prova”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.
Pas G — Recupera la reserva
Section titled “Pas G — Recupera la reserva”Recupera totes les reserves creades per la teva propietat de prova dins d’una finestra que cobreixi la marca temporal de la reserva.
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:
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
cancelDatecompletat - Un
paymentMethodStatusque reflecteixi el cicle de cancel·lació (CANCELLED,PARTIALLY_REFUNDED, oFULLY_REFUNDEDsegons 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:
-
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
Authorizationocult, i el cos JSON per a les cridesPUT) 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.httpen text pla o una exportació.harúnica. -
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.
-
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.
-
Resum de la certificació. Un curt
README.mddins l’arxiu que inclogui:- El nom i versió del teu channel manager / PMS.
- Els identificadors
managingEntityIdentifier,propertyIdentifier,masterRateIdentifieribookingIdentifierque vas usar. - El slug de l’hotel de staging (el
<your-slug>ahttps://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ó.
Notificacions webhook
Section titled “Notificacions webhook”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.
Lectures recomanades
Section titled “Lectures recomanades”- Channel Manager API — Documentació completa dels endpoints de l’API.
- Channel manager — Gestió de proveïdors de tarifes a l’Extranet.
- Catàleg d’esdeveniments webhook — Tots els esdeveniments subscrivibles.
- Construeix sobre Wink — Visió general de la plataforma per a desenvolupadors.
