API de disponibilidad hotelera: diseñar para la lentitud

El ticket suele llegar con aspecto inocente: «Añadir búsqueda de hoteles a la página de reservas — el proveedor nos dio una API de disponibilidad hotelera, hay sandbox, es cosa de un sprint». Lees la documentación, envías una petición para dos adultos en Madrid durante tres noches y llega una respuesta. Luego envías la misma petición para una ciudad con muchos más alojamientos y no llega nada durante un rato largo e incómodo. Cuando por fin llega, es un documento tan grande que tu parser JSON empieza a replantearse su carrera.
Ese es el momento en que el trabajo cambia de forma. La disponibilidad hotelera no es una consulta puntual. Es un fan-out: una sola pregunta del usuario se convierte en muchas preguntas a muchos proveedores, y cada uno responde a su propio ritmo, con su propio vocabulario y su propia idea de qué es una «habitación». El cliente que construyes tiene que seguir siendo útil mientras ese reparto todavía se está resolviendo. Este artículo trata de diseñar ese cliente, y está escrito para un desarrollador que domina REST y JSON pero que nunca ha tenido que explicarle a un hotel por qué una tarifa no reembolsable se mostró al huésped como cancelación gratuita.
Por qué una API de disponibilidad hotelera es más lenta que los endpoints habituales
Una búsqueda de vuelos y una de hoteles se parecen desde fuera: sale una consulta y vuelven opciones con precio. Por dentro no son el mismo problema. Si has leído nuestras notas sobre lo que implica de verdad integrar una API de reserva de vuelos, ya sabes que el precio que buscas no siempre es el precio que reservas. Los hoteles añaden encima una segunda dificultad: el volumen.
Una sola ciudad puede tener cientos de alojamientos. Cada uno vende varios tipos de habitación. Cada tipo de habitación se vende bajo varios planes tarifarios — con desayuno, sin desayuno, reembolsable, no reembolsable, tarifa de socio, tarifa de paquete. Cada plan puede venir de más de un proveedor: un bedbank, un channel manager, un contrato directo, un mayorista con el que firmaste porque su allotment en un hotel concreto era mejor que el de nadie. Multiplica todo eso y una búsqueda «sencilla» es un árbol enorme montado a partir de fuentes que no se ponen de acuerdo ni en los nombres ni en los identificadores.
Así que la parte lenta rara vez es tu código. Es el proveedor más lento al que decidiste esperar.
Resultados progresivos o respuesta completa: elige a propósito
Hay dos formas honestas de devolver resultados de búsqueda hotelera, y la mayoría de integraciones acaban en un punto intermedio incómodo.
Esperar a todos. El backend reparte la petición, espera a que cada proveedor responda o agote su tiempo, fusiona, elimina duplicados, ordena y devuelve una lista completa. El resultado es limpio: una petición, una respuesta y precios comparables porque están todos sobre la mesa. El coste: el usuario mira un indicador de carga tanto tiempo como tarde tu proveedor más lento, siempre.
Enviar lo que va llegando. El backend inicia el reparto y devuelve al instante un identificador de búsqueda. El cliente consulta ese identificador, o mantiene abierto un flujo, y recibe resultados por lotes a medida que responden los proveedores. Los primeros hoteles aparecen rápido. El coste es complejidad en todo lo demás: la lista se reordena mientras el usuario la lee, la etiqueta de «más barato» puede moverse y un hotel que llegó de un proveedor puede recibir más tarde una tarifa menor de otro.
Si tu interfaz es una página de búsqueda delante de una persona, lo progresivo casi siempre es lo correcto: esa persona está explorando, no lanzando un proceso por lotes, y una página que trabaja a la vista es mejor que una que piensa en silencio. Si tu consumidor es otra máquina — un proceso de comparación de tarifas, una herramienta de reservas corporativas que necesita una única respuesta definitiva — esperar suele ser más simple y correcto.
Elijas lo que elijas, tres reglas mantienen cuerdo a un cliente progresivo:
- Cada lote lleva un estado de finalización de la búsqueda completa, para que el cliente distinga entre «aún no hay más resultados» y «ya no habrá más resultados».
- Los resultados se fusionan en el servidor con una clave de hotel estable, no se añaden al final sin más. El cliente nunca debería tener que deducir que dos tarjetas son el mismo edificio.
- La ordenación por precio es provisional hasta que termina la búsqueda, y la interfaz lo dice. Los usuarios perdonan una lista que se asienta; no perdonan una etiqueta de «precio más bajo» que resulta falsa.
Modelar habitaciones y planes tarifarios para que no se derrumben
Aquí es donde la mayoría de integraciones hoteleras fallan en silencio, y el fallo aparece meses después como un ticket de soporte, no como un informe de error.
El modelo tentador es plano: un hotel tiene una lista de ofertas y cada oferta tiene un nombre de habitación y un precio. Se ve bien. Luego un proveedor devuelve «Deluxe King» y «Deluxe Room, 1 King Bed» para lo que es claramente la misma habitación, otro devuelve el mismo nombre para dos habitaciones realmente distintas (una con vistas a la ciudad y otra sin ellas), y un tercero devuelve un precio por noche mientras todos los demás dan el precio por estancia. Una lista plana no puede decirte cuál de estos casos tienes delante. Solo los muestra.
Un modelo que sobrevive al contacto con proveedores reales tiene al menos cuatro niveles, y los mantiene separados:
| Nivel | Qué contiene | El error que hay que evitar |
|---|---|---|
| Hotel | Tu propio identificador estable, vinculado al código de cada proveedor | Usar el ID de hotel de un proveedor como clave primaria |
| Habitación | Ocupación, configuración de camas y el texto de habitación del proveedor guardado tal cual | «Limpiar» los nombres de habitación hasta que dos habitaciones distintas se fusionen |
| Plan tarifario | Régimen de comidas, reembolsabilidad, forma de pago y proveedor de origen | Tratar el desayuno o la reembolsabilidad como parte del nombre de la habitación |
| Precio | Total de la estancia, moneda, qué impuestos y tasas incluye y cuáles se pagan en el hotel | Mostrar un precio por noche junto a precios por estancia u ocultar las tasas que se pagan a la llegada |
Puedes discrepar de dónde caen las líneas — algunos equipos separan la ocupación en su propio nivel, algo razonable en cuanto vendes reservas de varias habitaciones. Lo que no puedes hacer es fusionar niveles porque la interfaz solo muestre dos. La interfaz puede aplanar al renderizar. Los datos, no.
Un detalle merece su propia frase: guarda la descripción original de la habitación que envió el proveedor junto a todo lo que normalices. Cuando un huésped llegue y reciba una habitación distinta a la de su bono, lo primero que preguntará todo el mundo es qué envió realmente el proveedor.
Las políticas de cancelación son datos, no un párrafo
Muchos proveedores devuelven las condiciones de cancelación como texto libre: «Cancelación gratuita hasta 3 días antes de la llegada; después, penalización de 1 noche». La tentación de mostrar esa cadena y seguir adelante es enorme.
No lo hagas. Un texto no se puede comparar, ordenar, filtrar ni aplicar. Tu usuario quiere filtrar por tarifas reembolsables. Tu equipo financiero quiere saber qué reservas pasan a ser no reembolsables mañana para que la agencia contacte al cliente antes de que venza el plazo. Tu flujo posterior a la reserva tiene que decirle al cliente, en el momento exacto en que pulsa cancelar, cuánto se le va a cobrar. Nada de eso funciona sobre una frase.
Modela cada política como una lista ordenada de ventanas de penalización: desde este instante hasta aquel, la penalización es este importe (o esta parte de la estancia, o tantas noches). Los límites son marcas de tiempo con zona horaria — la del hotel, no la de tu servidor ni la del usuario — porque «3 días antes de la llegada» significa un momento distinto según desde qué medianoche cuentes. Guarda el texto original del proveedor junto a la versión estructurada, muestra la estructurada y trata cualquier discrepancia entre ambas como algo que investigar, no como algo que esconder.
Y vuelve a comprobar la política al reservar, no solo al buscar. Las políticas cambian entre las dos llamadas más a menudo de lo que nadie espera.
Lo que cuesta de verdad equivocarse
Una búsqueda lenta te cuesta conversiones; es malo, pero visible: alguien se quejará. Los fallos caros son los silenciosos.
Una tarifa mostrada como reembolsable que el proveedor trata como no reembolsable es una disputa con un cliente que tiene una captura de pantalla, y casi siempre la agencia acaba pagando la penalización. Un precio por noche mostrado como total de la estancia vende habitaciones por debajo de su coste hasta que alguien en contabilidad lo nota. Una habitación fusionada con otra distinta manda a una familia de cuatro a una habitación pensada para dos. Unas tasas que se pagan en el hotel y nunca se mostraron convierten una reseña de cinco estrellas en un contracargo. Cada uno de estos casos es una decisión de modelado tomada en el primer sprint, casi siempre bajo la etiqueta «ya lo limpiaremos».
Caché: lo que puedes guardar y lo que no
Todo equipo que integra una API hotelera acaba preguntando si puede cachear resultados para que la búsqueda sea más rápida y barata. La respuesta es sí, para algunas cosas, y la línea que las separa importa más que cualquier cifra de rendimiento.
El contenido estático — nombres de hoteles, direcciones, coordenadas, fotos, listas de servicios, descripciones de habitaciones — cambia poco y es justo lo que debes cachear, con generosidad, en tu propio almacenamiento. Revisa las condiciones del proveedor sobre cómo puedes guardarlo y mostrarlo; algunas licencias lo restringen. Pedirlo en vivo en cada búsqueda es lento y no aporta nada.
Las tarifas y la disponibilidad en vivo son otro asunto. Un precio cacheado es una suposición sobre lo que cobrará el proveedor, y los proveedores no respetan tus suposiciones. Un caché breve de resultados puede ser aceptable para mostrar una página — siempre que cada camino de reserva vuelva a tarificar con el proveedor antes de cobrar y que la interfaz trate un precio cambiado como un resultado normal y no como un error. Algunos proveedores además limitan la proporción entre búsquedas y reservas; un caché agresivo que les oculte tu tráfico real no es un resquicio en el que confiar.
Lo que nunca debes cachear es cualquier cosa que represente un compromiso: un token de precio retenido, una referencia de reserva, una cotización de cancelación. Pertenecen a un usuario y a un momento.
Antes de darlo por terminado
Una comprobación breve que vale la pena pasar sobre tu integración antes de que gestione reservas reales:
- La búsqueda devuelve un estado de finalización y el cliente se comporta distinto antes y después.
- Los hoteles se identifican con tu propio ID, al que se vincula el código de cada proveedor.
- Habitación, plan tarifario y precio son objetos separados en tus datos, muestre lo que muestre la pantalla.
- Cada precio indica si es por noche o por estancia, y qué se paga a la llegada.
- Las políticas de cancelación se guardan como ventanas de penalización con fecha en la zona horaria del hotel, conservando el texto original.
- El camino de reserva vuelve a tarificar y relee la política antes de cobrar a nadie.
- Nada que represente un compromiso se sirve jamás desde una caché.
Si estás valorando construir todo esto contra cada proveedor por separado o partir de una plataforma que ya se ha topado con estos problemas, el lado contractual importa tanto como el código — nuestro artículo sobre contratos de consolidador hotelero y tarifas bedbank explica qué pedir. Nuestras propias API de vuelos y hoteles se abren con una conversación, no con una clave de autoservicio; si ese es el camino que quieres explorar, inicia esa conversación desde la página de API de viajes.
El fan-out nunca desaparece. Un buen cliente simplemente deja de fingir que no está ahí.