Inicio rápido
Esta guía te lleva de no tener nada a una integración funcional en unos 30 minutos. Al final tendrás:
- precios en vivo para hoteles en una ciudad, desde la Partner API,
- un enlace de reserva que acredita las reservas a tu cuenta,
- una reserva de prueba y un webhook que te avisa cuando sucede.
Todo ocurre en staging, nuestro entorno de pruebas. No necesitas pedirnos acceso, y pasar a producción después tampoco requiere aprobación.
¿Es esta la guía adecuada para ti?
Sección titulada «¿Es esta la guía adecuada para ti?»| Quieres… | Empieza aquí |
|---|---|
| Mostrar hoteles en tu app, sitio o producto de IA y enviar viajeros a reservar, ganando comisión | Esta guía |
| Reservar en nombre de tus clientes como agencia de viajes autorizada | Esta guía hasta el Paso 5, luego Reservar como agencia de viajes |
| Incrustar hoteles reservables sin escribir una integración | Componentes Web |
| Permitir que un agente de IA busque y reserve | Servidores MCP y Pagos Agentic |
| Conectar un channel manager o PMS | Añade tu Channel Manager |
Cómo funciona
Sección titulada «Cómo funciona»Usas la Partner API para encontrar hoteles y sus precios en vivo. Cada hotel tiene un urlName estable. Lo conviertes en un enlace al Motor de Reservas de Wink, book.wink.travel, con tus IDs. El viajero reserva y paga allí, y la reserva se acredita a tu cuenta.
Antes de empezar
Sección titulada «Antes de empezar»Necesitarás:
grpcurl, o Postman o Insomnia. La Partner API es gRPC, no REST.curl.
Paso 1: Crea una cuenta en staging
Sección titulada «Paso 1: Crea una cuenta en staging»Staging es completamente independiente de producción, con sus propios inicios de sesión y cuentas.
-
Ve a staging-app.wink.travel, haz clic en
Sign-In / Registery regístrate. -
Haz clic en
Accountsen la barra lateral izquierda, luego enCreate, y elige I am an Affiliate. Las reservas que envíes se acreditan a esta cuenta. Consulta Crear cuenta.
Paso 2: Crea una aplicación
Sección titulada «Paso 2: Crea una aplicación»La aplicación proporciona las credenciales para tu código.
-
En la tarjeta de tu cuenta, haz clic en
Actions>Manage account, luego en la pestañaApplications. -
Haz clic en
Create new application, ponle un nombre y elige Machine-to-machine como tipo de cliente. -
En scopes, selecciona Inventory & rates (lectura). La Partner API verifica
inventory.read. -
Haz clic en
Create applicationy copia el Client ID y el Client secret. El secreto se muestra una vez y no se puede recuperar después.
Consulta Applications para otros tipos de cliente y scopes.
Paso 3: Obtén un token de acceso
Sección titulada «Paso 3: Obtén un token de acceso»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 respuesta:
export WINK_TOKEN=<access_token>Los tokens expiran. En tu propio código, usa una librería OAuth2 para obtenerlos y renovarlos. Consulta Autenticación.
Si la solicitud del token es rechazada, la respuesta es un cuerpo JSON con un código error:
error | Estado HTTP | Causa habitual |
|---|---|---|
invalid_client | 401 | Client ID o secreto incorrectos, o credenciales de producción usadas en staging-iam |
invalid_scope | 400 | La solicitud pide un scope para el que la aplicación no está registrada |
unauthorized_client | 400 | La aplicación no tiene permiso para usar el grant client_credentials |
invalid_request | 400 | Falta un parámetro obligatorio, por ejemplo si el cuerpo es JSON en lugar de un formulario |
Paso 4: Encuentra tu ID de cuenta
Sección titulada «Paso 4: Encuentra tu ID de cuenta»Cada llamada a la Partner API nombra la cuenta para la que actúas en un encabezado managing-entity-id. Lista las cuentas para las que tu token puede actuar:
grpcurl -H "authorization: Bearer $WINK_TOKEN" \ -d '{}' \ staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccountsCopia el accountId de la cuenta afiliada del Paso 1:
export WINK_ACCOUNT_ID=<accountId>Paso 5: Busca hoteles en una ciudad
Sección titulada «Paso 5: Busca hoteles en una ciudad»Staging tiene hoteles de prueba con disponibilidad en Bangkok, así que esta búsqueda usa su 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/SearchByCityUsa una fecha de check-in en el futuro; una fecha pasada es rechazada. Cada resultado incluye:
name,starRatingyheroImageUrl, suficiente para mostrar una fila de resultados,roomTypes, las ofertas en vivo, la habitación más barata primero,urlName, el slug que necesitas para el enlace de reserva.
Los precios son enteros en unidades menores: divide por 10 elevado a currencyExponent de la respuesta (2 para USD, así 12500 es $125.00).
¿No conoces el slug de una ciudad? Resuélvelo con wink.partner.v1.Lookup/Search. Para el contenido completo de una propiedad, usa el servicio Content. La referencia de la Partner API documenta cada llamada.
Paso 6: Construye el enlace de reserva
Sección titulada «Paso 6: Construye el enlace de reserva»https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID><urlName>es elurlNamedel hotel del Paso 5.client-ides el Client ID de tu aplicación del Paso 2.configuration-ides tu ID de personalización:Manage account>Customizations. Una personalización también establece tu marca, idioma y moneda predeterminados en la página de reserva.
Pasa la búsqueda del viajero
Sección titulada «Pasa la búsqueda del viajero»Añade las fechas, huéspedes, idioma y moneda del viajero al mismo enlace para que la página del hotel se abra con esos datos rellenados:
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ámetro | Significado | Ejemplo |
|---|---|---|
sd | Fecha de check-in | sd=2027-03-14 |
n o ed | Número de noches, o fecha de check-out | n=2 o ed=2027-03-16 |
rc | Huéspedes por habitación | rc=a2 (2 adultos) |
l | Idioma de visualización | l=en |
c | Moneda de visualización | c=USD |
p | Código de promoción | p=ABC123 |
Estos parámetros sobrescriben los valores predeterminados de tu personalización. La guía del botón Reservar ahora cubre el formato completo de rc, incluyendo niños y varias habitaciones.
El enlace abre la página del hotel; no puede preseleccionar una habitación o tarifa. El viajero elige la habitación en la página del hotel, al precio en vivo.
Consulta Enlazar directamente para enlazar a la página principal del motor de reservas en lugar de a un solo hotel.
Paso 7: Haz una reserva de prueba
Sección titulada «Paso 7: Haz una reserva de prueba»Abre tu enlace, elige fechas y una habitación, y paga con una tarjeta de prueba Stripe, por ejemplo 4242 4242 4242 4242 con cualquier fecha de expiración futura y cualquier CVC. No se cobra ninguna tarjeta real en staging. Anota el código de reserva en la página de confirmación; empieza con WNK.
Paso 8: Recibe notificaciones sobre reservas
Sección titulada «Paso 8: Recibe notificaciones sobre reservas»-
En Portal, ve a
Applications > Webhooksy añade un endpoint que acepte solicitudesPOST. -
Suscríbete a
booking.create, o deja la lista de eventos vacía para recibir todo mientras desarrollas. -
Envíate un evento de prueba, luego haz otra reserva de prueba y observa que llegue.
Verifica la firma de cada entrega antes de confiar en ella. Consulta Integración de Webhooks y el Catálogo de eventos Webhook.
Paso 9: Pasa a producción
Sección titulada «Paso 9: Pasa a producción»No hay un paso de aprobación para desarrolladores. (Las cuentas de agencias de viajes se certifican primero; ver más abajo.) Cuando tu integración funcione en staging:
-
Crea una cuenta y una aplicación en app.wink.travel, como en los Pasos 1 y 2. Las credenciales no se transfieren entre entornos.
-
Elimina
staging-de cada host:Staging Producción https://staging-iam.wink.travelhttps://iam.wink.travelstaging-partner.wink.travel:443partner.wink.travel:443https://staging-book.wink.travelhttps://book.wink.travel -
Busca de nuevo tu ID de cuenta de producción (Paso 4) y tu ID de personalización (Paso 6). Son diferentes a los de staging.
El uso de la Partner API se mide en noches de hotel, con una cuota mensual gratuita. Consulta Partner API para precios y límites.
Reservar como agencia de viajes
Sección titulada «Reservar como agencia de viajes»Si tu cuenta es una agencia de viajes autorizada, no necesitas enviar viajeros a book.wink.travel: puedes crear reservas directamente con wink.partner.v1.Booking/CreateBooking y gestionarlas con las otras llamadas Booking. Otras cuentas envían viajeros al enlace de reserva.
Las cuentas de agencias de viajes están certificadas: Wink revisa el registro de cada agencia antes de que pueda reservar. Las agencias que quieran cobrar directamente a sus clientes, como comerciante registrado, deben reservar a través de la Partner API y obtener la aprobación escrita de Wink. Consulta Primeros pasos como agencia de viajes y la referencia de la Partner API.
Próximos pasos
Sección titulada «Próximos pasos»- Genera un cliente tipado desde el esquema
.protoen lugar de llamar agrpcurlmanualmente. - Conecta el servidor MCP y usa las AI Skills para que tu asistente de codificación escriba la integración contra la API en vivo.
- Lee la lista completa de entornos y hosts.
