Ir al contenido

Flujo de reserva

1. Token (auth, valid ~1h)
│
▼
2. HotelRates (search, returns rateKey valid 60 min)
│
▼
3. CheckRates (validate rate, returns NEW rateKey valid 20 min)
│
▼
4. BookingHold (block inventory, returns bookingKey valid 5 min)
│
▼
5. BookingNew (confirm reservation, returns bookingId)
│
├─→ BookingGet (retrieve booking details by ID)
└─→ BookingDelete (cancel — wait 90s after creation)
  • Si recibes un timeout o un error 5xx de BookingNew, no reinicies el flujo — ver la estrategia de reintento en BookingNew.
  • Una reserva CONFIRMED puede no tener todavía el número de confirmación del hotel; estará disponible después en hotels[].confirmationCode mediante BookingGet — ver BookingNew.
  • client puede enviarse en BookingNew (flujo actual) o, junto con los huéspedes por habitación (roomCriteria), en BookingHold — ver Guest data in the hold.
Paso Entrada Salida TTL
Token client_id + client_secret access_token ~1 hora
Rates hotelIds + dates + paxes rateKey (rates) 60 min
CheckRates rateKey de Rates rateKey (checkrates) 20 min
BookingHold rateKey de CheckRates bookingKey 5 min
BookingNew bookingKey bookingId n/a

El servicio de Rates soporta consultar múltiples habitaciones simultáneamente. La respuesta solo devuelve tipos de habitación donde la misma habitación está disponible para todas las habitaciones solicitadas.

  • Un rateKey por respuesta representa el costo total de todas las habitaciones combinadas.
  • No selecciones múltiples rateKeys para una reserva multi-habitación — un solo rateKey ya incluye todas las habitaciones.

Ejemplo: al solicitar 2 habitaciones solo se devuelven tipos donde hay 2 habitaciones iguales disponibles; el monto del rateKey = costo de ambas habitaciones.

La API no soporta modificaciones de reservas. Para “modificar” una reserva, debes:

  1. Cancelar la reserva existente (mínimo 90s después de su creación).
  2. Crear una nueva reserva con los cambios deseados.
  • Máximo 50 IDs de hotel por llamada a /hotels/rates.
  • Máximo 28 días de rango de estancia por consulta.
  • Rate limit por channel (HTTP 429 al excederlo).
Error Síntoma Solución
Saltarse CheckRates antes de Hold Error 4002 en /bookings/hold Llama siempre a CheckRates primero
Usar un rateKey caducado (>60 min) Error 4001 / 4006 / sold_out Vuelve a buscar vía /hotels/rates
Llamar a Cancel <90s después de la reserva Error 1203 (la reserva aún se está creando) Espera al menos 90 segundos
Reservar con el rateKey de Rates en vez del de CheckRates Error 4002 en Hold Usa el rateKey devuelto por CheckRates
Cotizar >28 días Error 3003 Divide en múltiples consultas
CheckIn en el pasado Error 3001 Usa la fecha de hoy o fechas futuras
CheckOut <= CheckIn Error 3002 CheckOut debe ser estrictamente posterior a CheckIn
Habitación sin ningún adulto Error 3004 Cada habitación requiere al menos un pax de 18+ años