Retención y reanudación

La función «Retener y reanudar» de la API de Rapid Booking te permite ofrecer un modelo de reserva en dos pasos.

Con un modelo de reserva en dos pasos, si un colaborador o viajero quiere cancelar o abandonar la habitación sin finalizar la reserva, puede retener una habitación individual sin realizar un cargo inmediato y sin incurrir en penalizaciones por cancelación.

Si el colaborador o viajero quiere confirmar la habitación en un plazo determinado, podrá finalizar la reserva como segundo paso. Si se abandona la reserva, esta se revertirá automáticamente y el inventario seleccionado se desbloqueará.

Información general

¿Qué cambios son necesarios?

La función de "retener y reanudar" utiliza API existentes con nuevas marcas de solicitud y nuevos enlaces tokenizados en las respuestas. No es necesario integrar nuevos métodos discretos de la API. Para integrar la función de "retener y reanudar", tendrás que actualizar la gestión de la solicitud o la respuesta para lo siguiente:

1. Gestión de la creación de reservas.
2. Gestión de la recuperación de reservas.
3. Reanudación: nueva gestión del enlace token desde la respuesta de recuperación.
4. Cancelación: nueva gestión del enlace token desde la respuesta de creación.

Para que puedas entender mejor todo el proceso de «Hold» y «Resume», revisa esta página con detenimiento antes de consultar nuestra documentación específica de la API para la integración. Las opciones específicas que se describen en esta página también están disponibles en las Respectivas páginas de documentación específicas de nuestras API actuales de «Booking» y «Manage Booking».

>> Más información sobre la API de reservas
>> Más información sobre la API de gestión de reservas

Bandera que se puede llevar en la mano

No todas las tarifas se pueden mantener. El indicador de «retención» que aparece en la respuesta de Rapid Shop indica si una tarifa concreta puede ser objeto de retención y reanudación. Para que aparezca el indicador de «se puede guardar» en la respuesta de Rapid Shop, los socios deben incluir include=rooms.rates.holdable en su solicitud.

Creación de una reserva retenida

Las solicitudes de reserva ahora tienen un nuevo campo booleano denominado hold. El envío de un valor de true colocará el alojamiento en estado de retención.

Las reservas retenidas solo deberían dejarse en estado de retención durante el tiempo mínimo necesario para realizar la solicitud en cuestión. La reserva se revertirá automáticamente si se deja en estado de retención sin confirmarla.

Una respuesta de reserva retenida realizada correctamente devuelve otro enlace tokenizado que se utiliza para reanudar, confirmar y pagar la reserva retenida. También omite la matriz de habitaciones utilizada normalmente para proporcionar enlaces de cancelación, ya que no hay todavía ninguna habitación que cancelar.

Ejemplo de respuesta para una reserva en on-hold

{
    "itinerary_id": "2667552437552",
    "links": [
        {
            "rel": "retrieve",
            "method": "GET",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "resume",
            "method": "PUT",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "cancel",
            "method": "DELETE",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        }
    ]
}

Si la marca hold (retener) se utiliza para reservar, no se cargará ningún pago por la reserva. La reserva se finaliza y el pago se carga únicamente cuando el enlace del método PUT en la respuesta de la reserva retenida se utiliza dentro de la ventana de retención.

Recuperación de una reserva retenida

Recupera una reserva retenida a través del enlace retrieve (recuperar) que aparece en la respuesta de la reserva retenida. El método para recuperar una reserva en modo «Hold and Resume» es igual que una recuperación normal en la API «Manage Booking» para una reserva de un solo paso y no requiere un cuerpo de solicitud.

Situaciones de respuesta:

• La recuperación de una reserva retenida que sigue retenida devolverá una respuesta con datos limitados, que incluyen enlaces para reanudar inmediatamente y finalizar o para cancelar la reserva.
• La recuperación de una reserva retenida que ha sido cancelada (revertida mediante solicitud) o ha superado el tiempo de espera (revertida automáticamente) devolverá un error de itinerario no encontrado.
• La consulta de una reserva de on-hold que ya se hayareanudado y confirmado funcionará igual que una consulta de itinerario estándar en la API de «Gestionar reserva» y te mostrará todos los detalles de la reserva.

Ejemplo de cómo consultar una reserva en on-hold

{
    "itinerary_id": "8701934321257",
    "creation_date_time": "2027-03-09T14:42:58.159Z",
    "links": {
        "resume": {
            "method": "PUT",
            "href": "/v3/itineraries/8701934321257?token=QldfCGlcUA…{example trimmed for length}="
        },
        "cancel": {
            "method": "DELETE",
            "href": "/v3/itineraries/9700934721257?token=QldfCGlcUA…{example trimmed for length}="
        }
    }
}

Ejemplo de respuesta de consulta para una reserva de on-hold que se ha cancelado o ha caducado

{
    "type": "resource_not_found",
    "message": "Itinerary was not found with provided request."
}

Reanudación de una reserva retenida

Para confirmar una reserva que haya sido retenida y finalizar el pago, es necesario reanudar la reserva.

La reanudación de una reserva retenida se realiza mediante el enlace resume (reanudación) que aparece en la respuesta de la reserva retenida original y no necesita un cuerpo de solicitud.

Situaciones de respuesta:

• Al reanudar una reserva retenida que está todavía retenida, se finalizará la reserva y se devolverá una respuesta HTTP 204 - No content para indicar que se ha finalizado correctamente. Utiliza el enlace GET de la respuesta de la reserva retenida inicial para recuperar todo el itinerario.
• La reanudación de una reserva retenida que ha sido cancelada (revertida mediante solicitud) o ha superado el tiempo de espera (revertida automáticamente) devolverá el mismo error de error de itinerario no encontrado que se ha especificado en la sección de recuperación anterior.
• La reanudación de una reserva retenida que ya se ha reanudado correctamente devolverá un error que indica que ya se ha enviado la reserva.

Ejemplo de respuesta de reanudación de una reserva que ya ha sido reanudada

{
    "type": "resume.already_resumed",
    "message": "Booking has already been resumed."
}

Cancelación de una reserva retenida (reversión)

El enlace tokenizado cancel (cancelación), que aparece en la creación de la reserva y en las respuestas de recuperación, actúa en el nivel del itinerario. Cuando se utiliza, libera el alojamiento solicitado de la retención y revierte el itinerario retenido. Los enlaces para la cancelación del nivel de las habitaciones solo se facilitan en la respuesta de recuperación después de que una reserva se haya reanudado correctamente.

Cuando se realice una operación de cancel (cancelación), se devolverá un código de estado HTTP 204, el mismo que en una respuesta de reanudación correcta. HTTP 204 se utiliza en ambos estados para indicar que el servidor ha realizado correctamente la solicitud y que no hay que enviar ningún contenido adicional en el cuerpo de la carga neta de la respuesta.

La solicitud de cancelación de una reserva retenida genera la misma situación final que cuando se permitió que la reserva se revirtiese automáticamente.

Situaciones de respuesta:

• La cancelación de una reserva que todavía está retenida liberará el inventario de la retención y devolverá un código de estado HTTP 204.
• La cancelación de una reserva retenida que ya ha sido cancelada (revertida mediante solicitud) o ha superado el tiempo de espera (revertida automáticamente) devolverá el error de itinerario no encontrado que se ha documentado anteriormente en esta página.
• La cancelación de una reserva retenida que ya se ha reanudado correctamente devolverá un error de cancelación del nivel de itinerario no admitida. Realiza una llamada de recuperación y utiliza los enlaces de nivel de habitaciones facilitados en la respuesta para cancelar las habitaciones individuales.

Ejemplo de respuesta de cancelación de una reserva que ya se ha reanudado

{
    "type": "resume.itinerary_level_cancel_not_supported",
    "message": "Itinerary level cancel on confirmed booking is not supported."
}