Guía de integración

La API de Booking.com: cómo funciona el acceso y qué te permite hacer de verdad

Escrita para el ingeniero o el fundador técnico al que han mandado a las APIs de conectividad de Booking.com. Explica cómo funcionan la designación como partner y la conexión por propiedad, el modelo de datos del que depende todo lo demás, y los dos o tres comportamientos que hacen que un cambio de tarifas en Booking.com funcione sobre el papel y no cambie nada en la práctica.

Qué es la API de Booking.com

Las APIs de Booking.com están pensadas para proveedores de conectividad: los channel managers y sistemas de gestión de propiedades que mantienen el alojamiento sincronizado en nombre de muchas propiedades a la vez. No son APIs para consumidores, no hay una superficie pública de búsqueda o reserva para terceros y no hay un portal de desarrolladores en el que registrarse.

En la práctica son varias superficies de producto bajo una misma relación: disponibilidad y tarifas, reservas, configuración de propiedad y habitaciones, contenido, mensajes, reseñas y cargos financieros. Se comportan de forma distinta entre sí, se conceden por separado y partes de la superficie más antigua son XML y no JSON. Si vienes de Airbnb, casi ninguna de tus premisas se mantiene.

¿Cómo consigo acceso a la API de Booking.com?

Tres capas, concedidas por tres partes distintas, igual que en Airbnb pero con otra forma.

1. Booking.com designa a tu empresa como proveedor de conectividad. Lo solicitas, te evalúan comercial y técnicamente, y hay un paso de certificación para las superficies que quieres usar. Es una relación a nivel de empresa que se mide en meses.
2. Recibes credenciales para una cuenta de máquina. A diferencia de los tokens OAuth por anfitrión de Airbnb, una sola cuenta de máquina actúa por todas las propiedades conectadas contigo. Esa única credencial es el radio de impacto de todo tu negocio, y cambia cómo debes leer los errores; mira la nota de abajo.
3. Cada propiedad te conecta desde su propia Extranet. El anfitrión entra en la Extranet de Booking.com, abre la lista de proveedores de conectividad, busca tu proveedor por nombre y pulsa Conectar. Hasta que lo hace, tu cuenta de máquina no puede ver esa propiedad. También necesitará tener a mano su Hotel ID numérico.

Con Repull, la parte de cara al anfitrión es una única sesión alojada con tu marca; el anfitrión completa el paso en la Extranet y pega su Hotel ID, y tú recibes una conexión. El paso a paso está en Conectar Booking.com.

curl -X POST 'https://api.repull.dev/v1/connect/booking' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "redirectUrl": "https://yourapp.com/connected" }'

Propiedades, habitaciones y planes de tarifa

Si entiendes esto, el resto de Booking.com encaja. Si no, cada endpoint parece arbitrario.

Booking.com property   "hotel_id": 5432505        ← the building
└── room               "roomBookingId": 543250501 ← what a guest books
    └── rate plan      "rateId": 98765            ← the terms it sells on
        └── price at an occupancy                ← what you actually write

Una propiedad es un edificio. Las habitaciones son lo que reservan los huéspedes. Los planes de tarifa son las condiciones comerciales con las que se vende una habitación, y un precio pertenece a una combinación (habitación, plan de tarifa, fecha, ocupación), no a una noche. Una villa de un dormitorio es el caso sencillo; un aparthotel de veinte unidades es una única propiedad con veinte habitaciones, y eso es lo normal, no un caso raro.

La misma unidad también puede aparecer en más de una propiedad de Booking.com, normalmente porque se volvió a publicar con el tiempo, y una habitación que no está asignada a uno de tus anuncios no pertenece a nada: sus reservas no tienen dónde caer. Asigna las habitaciones durante el flujo de conexión, no después.

¿Puedo actualizar tarifas con la API de Booking.com?

Sí, y es la superficie más usada de toda la relación. Escribes un precio para una habitación en un plan de tarifa sobre un rango de fechas, opcionalmente con restricciones de estancia y de llegada en la misma llamada.

curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "rates",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "price": 210,
      "currency": "USD",
      "occupancy": 4
    }]
  }'

roomId y rateId salen de GET /v1/channels/booking/properties/{id}/rooms. Todo lo demás de la petición —y hay más de lo que esperas— está en Actualizar precios en Booking.com.

¿Por qué mi cambio de precio en Booking.com no hizo nada?

Es la pregunta que trae a la gente a esta página, y tiene dos respuestas independientes. Las dos parecen un éxito.

La ocupación forma parte de la clave, no es una preferencia

Booking.com no guarda “el precio de esta noche”. Guarda un precio para una noche para un número de personas en un plan de tarifa. Así que la ocupación que envías decide qué precio estás sobrescribiendo. Cada importe se envía con una, la indiques o no.

• Indica una ocupación por encima del máximo al que el plan pone precio y Booking.com acepta la petición y descarta el importe sin decir nada. La noche conserva lo que tenía —a menudo 0.00— y la confirmación es idéntica, byte a byte, a la de una escritura correcta.
• Indica una por debajo y recibes un 400. El precio publicado no cambia.
• La capacidad de huéspedes de tu propio anuncio no es el dato que cuenta. Manda el número que Booking.com tiene para ese plan de tarifa. Léelo en lugar de deducirlo.

Repull obtiene la ocupación de los propios datos de Booking.com para el par (habitación, plan de tarifa) cuando no la indicas, te devuelve el valor usado y de dónde salió, y rechaza la escritura con un 422 cuando no puede resolverla. Nunca se envía un importe a ciegas.

El acuse de recibo no es una confirmación

Booking.com suele responder a una escritura de tarifas con un acuse de recibo sin estado por fecha. El cuerpo es literalmente:

{"ok": ""}

Rangos de fechas y la noche que pierdes

Por debajo, el XML de disponibilidad y tarifas recibe un rango cuya fecha to no se escribe: es un límite exclusivo, igual que la fecha de salida excluye la última noche. La mayoría de calendarios que habrás integrado antes tratan los dos extremos como noches. Así que lo natural es leer “del 1 al 7 de agosto” como siete noches, pero en la petición son seis, y la noche que pierdes sin darte cuenta es la última de cada rango que escribes.

Es una conversión de una línea y un bug de una semana, porque solo te cuesta la última noche: el calendario parece más o menos bien, una comprobación rápida pasa, y el hueco aparece como una reserva perdida en lugar de como un error.

El inventario es una escritura aparte

Poner precio a una noche no la abre a la venta, y abrirla no le pone precio. Las habitaciones a la venta y el cierre de ventas son su propio tipo de actualización; enviarlos en una actualización de tarifas se rechaza en lugar de ignorarse en silencio.

# Close a night: zero rooms to sell, stop-sell on
curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "availability",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "availableRooms": 0,
      "closed": true
    }]
  }'

Detalles en Enviar disponibilidad a Booking.com. Si prefieres escribir un calendario una sola vez y que llegue a todos los canales conectados, eso es PUT /v1/availability/{propertyId}, con PATCH /v1/availability/batch para muchas propiedades a la vez.

Restricciones que existen y otras que no

La estancia mínima y máxima (por fecha de estancia y por fecha de llegada), el cierre a la llegada y el cierre a la salida existen y se pueden fijar por habitación, plan de tarifa y rango de fechas.

Varias restricciones que la gente espera simplemente no están en la notificación que acepta Booking.com, entre ellas una duración exacta de estancia en la llegada y la antelación mínima o máxima de reserva. Lo correcto es rechazarlas de forma visible. Una restricción que se acepta y luego no se envía es el único fallo que no puedes ver en una respuesta, así que Repull responde 422 indicando el campo en lugar de descartarlo. Consulta restriction_not_supported y Estancia mínima y restricciones.

Reservas, mensajes, reseñas y cargos

• Reservas: listarlas y confirmarlas. La confirmación no es un trámite opcional: las reservas nuevas se quedan en cola hasta que las confirmas, y un partner que nunca confirma vuelve a leer las mismas reservas una y otra vez. Reservas.
• Mensajes: listar conversaciones y enviar. Más limitado que la superficie de hilos de Airbnb; no hay edición, ni reacciones, ni estado de lectura. Mensajes con huéspedes.
• Reseñas: listar y responder. Reseñas.
• Cargos y tasas: lectura y escritura. Cargos y tasas.
• Configuración y puesta en marcha: crear la entidad legal, comprobar que todo está listo, fijar contactos y políticas, y abrir una propiedad a la venta. Configuración y puesta en marcha.
• Sin modificaciones. Booking.com no tiene un equivalente al flujo de modificaciones de Airbnb. Los cambios de fechas y precio en una reserva existente no son una operación de la API.

La matriz de capacidades pone Airbnb y Booking.com uno al lado del otro, y marca lo parcial como parcial en lugar de redondearlo hacia arriba.

¿Por qué la Content API devuelve 403?

Porque el contenido es su propia superficie de producto, con su propio permiso y su propia ruta base, separada de las superficies de disponibilidad, tarifas y reservas. Una propiedad puede estar totalmente activa —recibiendo reservas y aceptando todas tus escrituras de tarifas y disponibilidad— mientras cada llamada de contenido para esa misma propiedad responde 403.

Cuando pasa, el instinto es sospechar del token, luego del id de la propiedad y luego de los permisos del anfitrión en la Extranet. Normalmente no es nada de eso. La capacidad no se te concedió para esa superficie, y reconectar no lo cambia. Confirma qué capacidades incluye de verdad tu relación de partner antes de meter la gestión de fotos o descripciones en una versión.

El contenido, donde está disponible, cubre fotos, descripciones, servicios, instalaciones y políticas, a nivel de propiedad o de habitación, y Booking.com revisa los cambios de texto antes de publicarlos, así que una escritura es el inicio de un proceso, no el final. Contenido y fotos.

Lo que cuesta construirlo por tu cuenta

1. Designación como partner y certificación. Meses, con revisión comercial y un paso de certificación técnica por superficie. No puedes prometer una fecha a ningún cliente.
2. Un modelo de seguridad con credencial compartida. Una sola cuenta de máquina para todas las propiedades a las que das servicio. Rotación, almacenamiento y un clasificador de errores lo bastante cuidadoso como para que un 401 global durante una caída no desconecte en masa a tus clientes.
3. El modelo y la asignación. De propiedades a habitaciones, a planes de tarifa y a tus propios anuncios, incluidas propiedades con varias habitaciones, unidades republicadas y habitaciones sin asignar cuyas reservas no tienen adónde ir.
4. Verificación de escrituras. Como el acuse de recibo no prueba nada, una integración correcta vuelve a leer y concilia. Eso es una llamada más, un tiempo de espera y una máquina de estados, en la ruta más caliente que tienes.
5. Convenciones que no encajan. Límites de fecha exclusivos, precios ligados a la ocupación, inventario separado de las tarifas, restricciones que no existen, XML donde esperabas JSON.
6. Roturas continuas. Igual que con cualquier API de partners: nunca llega a cero.

El resumen honesto es que Booking.com es una integración más pesada que Airbnb y no comparte casi ninguna de sus premisas: otro modelo de autenticación, otro modelo de datos, otra semántica de fechas y otra definición de escritura correcta. Los equipos que acaban de terminar Airbnb siempre lo subestiman. La guía de la API de Airbnb es la comparación.

Dónde encaja Repull

Repull es una API REST y una sola clave para Booking.com, Airbnb, Vrbo, Plum Guide y los sistemas de gestión de propiedades que los anfitriones ya usan. Nosotros tenemos las relaciones con los partners; las propiedades se conectan solas a través de un flujo alojado con tu marca.

• Un único flujo de conexión alojado. POST /v1/connect/{provider}, con la asignación de habitaciones incluida. Connect.
• Escrituras que te dicen la verdad. Verificación por relectura en tarifas, ocupación resuelta y devuelta, restricciones no soportadas rechazadas en lugar de descartadas, y rangos de fechas inclusivos en ambos extremos.
• Una escritura de calendario para todos los canales. PUT /v1/availability/{propertyId} envía precio y disponibilidad a todos los canales a los que está conectada una propiedad.
• Webhooks con historial de entregas y reenvío, en lugar de la fontanería de notificaciones de cada canal. Webhooks.

Empieza por la guía de inicio rápido, o lee el resumen de canales. Si eres una plataforma que integra esto para sus propios clientes, y no para ti, la guía para plataformas cubre ese modelo pregunta por pregunta.

Si las propiedades que estás integrando ya están en un sistema de gestión de propiedades, ese es un segundo problema distinto: un PMS te da su propia visión de una reserva, no la API del canal. Las guías de Guesty, Hostaway, Hospitable, Lodgify y OwnerRez explican lo que expone cada uno, y la matriz de cobertura los tiene todos. Una sola clave cubre a la vez una conexión con un PMS y una conexión directa con un canal.

Preguntas frecuentes