Inici ràpid
Aquesta guia et porta de no res a una integració funcional en uns 30 minuts. Al final tindràs:
- preus en viu d’hotels en una ciutat, des de la Partner API,
- un enllaç de reserva que reconeix les reserves al teu compte,
- una reserva de prova i un webhook que t’avisa que s’ha fet.
Tot passa en staging, el nostre entorn de proves. No cal que ens demanis accés, i passar a producció després tampoc necessita aprovació.
És aquesta la guia adequada per a tu?
Section titled “És aquesta la guia adequada per a tu?”| Vols… | Comença aquí |
|---|---|
| Mostrar hotels a la teva app, web o producte d’IA i enviar viatgers a reservar, guanyant comissió | Aquesta guia |
| Reservar en nom dels teus clients com a agència de viatges autoritzada | Aquesta guia fins al Pas 5, després Reservar com a agència de viatges |
| Integrar hotels reservables sense escriure una integració | Web Components |
| Permetre que un agent d’IA cerqui i reservi | MCP Servers i Agentic Payments |
| Connectar un channel manager o PMS | Afegeix el teu Channel Manager |
Com funciona
Section titled “Com funciona”Utilitzes la Partner API per trobar hotels i els seus preus en viu. Cada hotel té un urlName estable. El converteixes en un enllaç a l’Enginy de Reserves de Wink, book.wink.travel, portant els teus IDs. El viatger reserva i paga allà, i la reserva es reconeix al teu compte.
Abans de començar
Section titled “Abans de començar”Necessitaràs:
grpcurl, o Postman o Insomnia. La Partner API és gRPC, no REST.curl.
Pas 1: Crea un compte a staging
Section titled “Pas 1: Crea un compte a staging”Staging és completament separat de producció, amb els seus propis accessos i comptes.
-
Ves a staging-app.wink.travel, clica
Sign-In / Registeri registra’t. -
Clica
Accountsa la barra lateral esquerra, desprésCreate, i tria I am an Affiliate. Les reserves que enviïs es reconeixeran a aquest compte. Mira Crear Compte.
Pas 2: Crea una aplicació
Section titled “Pas 2: Crea una aplicació”L’aplicació dóna credencials al teu codi.
-
A la targeta del teu compte, clica
Actions>Manage account, després la pestanyaApplications. -
Clica
Create new application, posa-li un nom i tria Machine-to-machine com a tipus de client. -
A sota de scopes, selecciona Inventory & rates (lectura). La Partner API comprova
inventory.read. -
Clica
Create applicationi copia el Client ID i el Client secret. El secret es mostra una sola vegada i no es pot recuperar després.
Consulta Applications per als altres tipus de client i scopes.
Pas 3: Obté un token d’accés
Section titled “Pas 3: Obté un token d’accés”curl -X POST https://staging-iam.wink.travel/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=<YOUR_CLIENT_ID>" \ -d "client_secret=<YOUR_CLIENT_SECRET>" \ -d "scope=inventory.read"Guarda el access_token de la resposta:
export WINK_TOKEN=<access_token>Els tokens caduquen. Al teu propi codi, deixa que una biblioteca OAuth2 els obtingui i refresqui. Mira Autenticació.
Si la sol·licitud del token és rebutjada, la resposta és un cos JSON amb un codi error:
error | Estat HTTP | Causa habitual |
|---|---|---|
invalid_client | 401 | Client ID o secret incorrecte, o credencials de producció usades a staging-iam |
invalid_scope | 400 | La sol·licitud demana un scope per al qual l’aplicació no està registrada |
unauthorized_client | 400 | L’aplicació no té permís per usar el grant client_credentials |
invalid_request | 400 | Falta un paràmetre obligatori, per exemple quan el cos és JSON en lloc d’un formulari |
Pas 4: Troba el teu ID de compte
Section titled “Pas 4: Troba el teu ID de compte”Cada crida a la Partner API indica el compte per al qual actues en un header managing-entity-id. Llista els comptes per als quals el teu token pot actuar:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -d '{}' \ staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccountsCopia el accountId del compte afiliat del Pas 1:
export WINK_ACCOUNT_ID=<accountId>Pas 5: Cerca hotels en una ciutat
Section titled “Pas 5: Cerca hotels en una ciutat”Staging té hotels de prova amb disponibilitat a Bangkok, així que aquesta cerca usa el seu slug, bangkok-thailand:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -H "managing-entity-id: $WINK_ACCOUNT_ID" \ -d '{ "urlName": "bangkok-thailand", "userSession": { "itinerary": { "startDate": "2026-12-01", "nights": 2, "room": { "adults": 2 } }, "currencyCode": "USD", "languageCode": "en" } }' \ staging-partner.wink.travel:443 wink.partner.v1.Search/SearchByCityUtilitza una data d’entrada futura; una data passada és rebutjada. Cada resultat porta:
name,starRatingiheroImageUrl, suficient per mostrar una fila de resultat,roomTypes, les ofertes en viu, habitació més barata primer,urlName, el slug que necessites per a l’enllaç de reserva.
Els preus són enters en unitats menors: divideix per 10 elevat a currencyExponent de la resposta (2 per USD, així 12500 és 125,00 $).
No saps el slug d’una ciutat? Resol-lo amb wink.partner.v1.Lookup/Search. Per al contingut complet d’una propietat, usa el servei Content. La referència de la Partner API documenta cada crida.
Pas 6: Construeix l’enllaç de reserva
Section titled “Pas 6: Construeix l’enllaç de reserva”https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID><urlName>és elurlNamede l’hotel del Pas 5.client-idés el Client ID de la teva aplicació del Pas 2.configuration-idés el teu ID de personalització:Manage account>Customizations. Una personalització també estableix la teva marca, idioma i moneda per defecte a la pàgina de reserva.
Passa la cerca del viatger
Section titled “Passa la cerca del viatger”Afegeix les dates, convidats, idioma i moneda del viatger al mateix enllaç perquè la pàgina de l’hotel s’obri amb aquests camps omplerts:
https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>&sd=2027-03-14&n=2&rc=a2&l=en&c=USD| Paràmetre | Significat | Exemple |
|---|---|---|
sd | Data d’entrada | sd=2027-03-14 |
n o ed | Nombre de nits, o data de sortida | n=2 o ed=2027-03-16 |
rc | Convidats per habitació | rc=a2 (2 adults) |
l | Idioma de visualització | l=en |
c | Moneda de visualització | c=USD |
p | Codi de promoció | p=ABC123 |
Aquests paràmetres sobreescriuen els valors per defecte de la teva personalització. La guia del botó Reserva ara cobreix el format complet de rc, incloent nens i diverses habitacions.
L’enllaç obre la pàgina de l’hotel; no pot preseleccionar una habitació ni una tarifa. El viatger tria l’habitació a la pàgina de l’hotel, al preu en viu.
Consulta Enllaçar directament per enllaçar a la pàgina principal de l’enginy de reserves en lloc d’un hotel concret.
Pas 7: Fes una reserva de prova
Section titled “Pas 7: Fes una reserva de prova”Obre el teu enllaç, tria dates i habitació, i paga amb una targeta de prova Stripe, per exemple 4242 4242 4242 4242 amb qualsevol data de caducitat futura i qualsevol CVC. No es cobra cap targeta real a staging. Apunta el codi de reserva a la pàgina de confirmació; comença per WNK.
Pas 8: Rep notificacions de reserves
Section titled “Pas 8: Rep notificacions de reserves”-
Al Portal, ves a
Applications > Webhooksi afegeix un endpoint que accepti peticionsPOST. -
Subscriu-te a
booking.create, o deixa la llista d’esdeveniments buida per rebre-ho tot mentre desenvolupes. -
Envia’t un esdeveniment de prova, després fes una altra reserva de prova i comprova que arriba.
Verifica la signatura de cada entrega abans de confiar-hi. Mira Integració Webhook i el Catàleg d’Esdeveniments Webhook.
Pas 9: Passa a producció
Section titled “Pas 9: Passa a producció”No hi ha cap pas d’aprovació per a desenvolupadors. (Els comptes d’agència de viatges es certifiquen primer; mira més avall.) Quan la teva integració funcioni a staging:
-
Crea un compte i una aplicació a app.wink.travel, com als Passos 1 i 2. Les credencials no es traslladen entre entorns.
-
Elimina
staging-de cada host:Staging Producció https://staging-iam.wink.travelhttps://iam.wink.travelstaging-partner.wink.travel:443partner.wink.travel:443https://staging-book.wink.travelhttps://book.wink.travel -
Torna a buscar el teu ID de compte de producció (Pas 4) i l’ID de personalització (Pas 6). Són diferents dels de staging.
L’ús de la Partner API es mesura en nits d’hotel, amb una quota mensual gratuïta. Mira Partner API per preus i límits.
Reservar com a agència de viatges
Section titled “Reservar com a agència de viatges”Si el teu compte és una agència de viatges autoritzada, no cal que enviïs viatgers a book.wink.travel: pots crear reserves directament amb wink.partner.v1.Booking/CreateBooking, i gestionar-les amb les altres crides Booking. Altres comptes envien els viatgers a l’enllaç de reserva.
Els comptes d’agència de viatges estan certificats: Wink revisa el registre de cada agència abans que pugui reservar. Les agències que volen cobrar directament als seus clients, com a comerciant registrat, han de reservar a través de la Partner API i obtenir l’aprovació escrita de Wink. Mira Començar com a agència de viatges i la referència de la Partner API.
Passos següents
Section titled “Passos següents”- Genera un client tipat a partir de l’esquema
.protoen lloc de cridargrpcurlmanualment. - Connecta el servidor MCP i usa les AI Skills perquè el teu assistent de codi escrigui la integració contra l’API en viu.
- Llegeix la llista completa d’entorns i hosts.
