BookingHold
Endpoint
Sección titulada «Endpoint»POST {base_url}/1.0/bookings/holdBloquea una habitación y tarifa específicas durante 5 minutos para dar tiempo a confirmar.
Headers
Sección titulada «Headers»| Header | Valor |
|---|---|
Authorization |
Bearer <access_token> |
Content-Type |
application/json |
Accept |
application/json |
Cuerpo de la petición
Sección titulada «Cuerpo de la petición»{ "rateKey": "<rateKey from /hotels/checkrates>"}| Campo | Tipo | Descripción |
|---|---|---|
rateKey |
string | Ver el aviso de arriba sobre el origen del rateKey |
client |
object | Opcional. Titular de la reserva |
client.name |
string | Nombre |
client.surname |
string | Apellido |
client.contactData[].email |
string | |
client.contactData[].phone.countryCode |
string | Código de país |
client.contactData[].phone.number |
string | Número de teléfono |
roomCriteria[] |
array | Opcional. Una entrada por habitación |
roomCriteria[].roomId |
int | Número de la habitación dentro de la cotización, de 1 a N, en el orden en que se pidieron las habitaciones en HotelRates — ver Guest data in the hold |
roomCriteria[].paxes[] |
array | Huéspedes de la habitación |
roomCriteria[].paxes[].age |
int | Edad del huésped |
roomCriteria[].paxes[].name |
string | Nombre del huésped |
roomCriteria[].paxes[].surname |
string | Apellido del huésped |
Guest data in the hold
Sección titulada «Guest data in the hold»BookingHold acepta, de forma opcional, client y roomCriteria, enviados juntos como en el ejemplo de abajo. Este flujo convive con el actual: client puede seguir enviándose en BookingNew, como documenta BookingNew.
- Envía
roomIdde 1 a N en el orden de las habitaciones de HotelRates, y envía el arrayroomCriteriaen ese mismo orden. - Por cada habitación, envía los mismos huéspedes (cantidad y edades) que se cotizaron en HotelRates.
Ejemplo de petición con dos habitaciones, una de ellas con un menor:
{ "rateKey": "<rateKey from /hotels/checkrates>", "client": { "name": "Jane", "surname": "Doe", "contactData": [ { "email": "jane.doe@example.com", "phone": { "countryCode": "+52", "number": "5512312322" } } ] }, "roomCriteria": [ { "roomId": 1, "paxes": [ { "age": 30, "name": "Jane", "surname": "Doe" }, { "age": 32, "name": "John", "surname": "Doe" } ] }, { "roomId": 2, "paxes": [ { "age": 41, "name": "Maria", "surname": "Lopez" }, { "age": 10, "name": "Ana", "surname": "Lopez" } ] } ]}Petición de BookingNew en este flujo:
{ "bookingKey": "<bookingKey from /bookings/hold>", "clientReference": "99999", "commentsForHotel": "Special requests..."}Observado en una muestra:
- BookingNew se aceptó solo con
bookingKey,clientReferenceycommentsForHotel. - En BookingGet, el
primaryGuestde cada habitación fue el primer huésped de esa habitación.
Respuesta (éxito)
Sección titulada «Respuesta (éxito)»{ "bookingKey": "oDvxthDyTDD9xNd...XYZ=", "eventId": "441542bd-f08e-40ed-81e9-11fbd08b0915", "error": null}| Campo | Tipo | Descripción |
|---|---|---|
bookingKey |
string | Token usado en BookingNew. Válido 5 minutos. |
eventId |
string | ID de traza |
error |
object|null | Detalles del error, o null en caso de éxito |
Ventana de tiempo
Sección titulada «Ventana de tiempo»El bookingKey expira 5 minutos después de su emisión. Tras la expiración, la habitación se libera y debes reiniciar desde CheckRates (o antes).
Errores específicos de este endpoint
Sección titulada «Errores específicos de este endpoint»| Código | HTTP | Mensaje | Causa | Qué hacer |
|---|---|---|---|---|
| 1101 | 400 | The provided key has already been used previously | rateKey ya usado en un Hold | Obtén un rateKey nuevo con CheckRates |
| 4001 | 400 | Invalid Hold Request, can not parse the rateKey | rateKey corrupto, codificado incorrectamente, o vacío | Envía el rateKey de CheckRates completo y sin modificar |
| 4002 | 400 | You cannot invoke 'Hold' without first performing a 'CheckRates' |
Hold invocado con el rateKey de Rates en lugar del de CheckRates |
Usa el rateKey devuelto por CheckRates, no por Rates |
| 4003 | 400 | RateKey from CheckRates older than 20 min | El rateKey de CheckRates tiene más de 20 min |
Repite CheckRates |
| 4008 | 400 | The requested rate is no longer available. |
No definida. La respuesta no indica el motivo. Observado en una respuesta. La petición de Hold se envió menos de 20 segundos después de un CheckRates exitoso. 4008 y 4009 devuelven el mismo mensaje; la diferencia entre ellos no está definida. | Solicita un rateKey nuevo repitiendo Rates y CheckRates. No uses el código para distinguir la causa. |
| 4009 | 400 | The requested rate is no longer available. |
No definida. La respuesta no indica el motivo. Observado en una respuesta. La petición de Hold se envió menos de 20 segundos después de un CheckRates exitoso. 4008 y 4009 devuelven el mismo mensaje; la diferencia entre ellos no está definida. | Solicita un rateKey nuevo repitiendo Rates y CheckRates. No uses el código para distinguir la causa. |
Patrones de diagnóstico
Sección titulada «Patrones de diagnóstico»| Síntoma | Causa probable |
|---|---|
| 4001 con un rateKey de apariencia válida | El rateKey contiene caracteres no seguros para URL (+, /, =) — verifica que se envíe en el body JSON, no como parámetro de URL |
| 4002 | Llamar a Hold con el rateKey de /rates en vez de /checkrates |
| 1101 al reintentar | El Hold anterior tuvo éxito silenciosamente; busca un bookingKey en tus logs |
Headers opcionales (informativo)
Sección titulada «Headers opcionales (informativo)»Algunas implementaciones envían un header adicional para tracking; no es validado por la API, pero puede ser útil en los logs:
| Header | Propósito |
|---|---|
CustomerIp |
IP de origen del cliente para analítica |
Este header es opcional. Su presencia no cambia el comportamiento.

