Flujo de reserva

El flujo típico de un motor de reservas: obtener un token, listar las habitaciones para las fechas y la ocupación que buscó el huésped, aplicar la tarifa elegida y el cupón si lo hay, completar el paso de pago y registrar la reserva en HMS con BookingPushRQ. Esta guía recorre cada paso con solicitudes y respuestas reales.

1Inicio de sesión/external/public/login
2Lista de habitaciones/external/online/roomType
3Cupón · Paquetescoupon/search · stock/packages
4Pagopayment/type/{type}
5Envíochannel/booking

1. Obtén un token#

Inicia sesión una vez al arrancar tu servidor o cuando caduque el token, y guarda el token junto con el ID del hotel. Detalles: Autenticación.

2. Lista las habitaciones#

Solicita la lista de habitaciones con los valores del formulario de búsqueda del huésped. Si viajan niños, envía sus edades; el precio para niños se calcula según la edad.

Terminal
curl "https://test.hms.gen.tr/external/online/roomType" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "startDate=2026-08-18" -d "endDate=2026-08-20" \
  -d "adultCount=2" -d "childCount=1" -d "childAges[]=7" -d "language=en"

Qué mostrar para cada tipo de habitación de la respuesta:

CampoEn pantalla
name, images[], detail, roomFeatures[]Tarjeta de la habitación
roomCountHabitaciones restantes. 0 significa “no está a la venta”; el motivo figura en roomRestrictionMessage.
accommodationTypes[].titleOpción de régimen (Alojamiento y desayuno, Media pensión…)
accommodationTypes[].prices{}Opciones de tarifa: estándar y no reembolsable

Las claves del objeto prices tienen la forma "<persons>-<1|0>". El sufijo 1 corresponde a la tarifa estándar (reembolsable) y 0, a la tarifa no reembolsable; la opción no reembolsable lleva nonRefundable: "[NR]". Con precios por habitación (priceType: 1), la clave es 1-1 / 1-0, sea cual sea la ocupación.

accommodationTypes[0].prices
{
    "2-1": {
        "total": 2,
        "title": 2,
        "nonRefundable": "",
        "price": "1930.00",
        "currency": "TRY",
        "id": "2/2",
        "prices": [
            {
                "price": "965.00",
                "tarih": "18.08.2026"
            },
            {
                "price": "965.00",
                "tarih": "19.08.2026"
            }
        ]
    },
    "2-0": {
        "total": 2,
        "title": 2,
        "nonRefundable": "[NR]",
        "price": "1737.00",
        "currency": "TRY",
        "id": "2-0/2",
        "prices": [
            {
                "price": "868.50",
                "tarih": "18.08.2026"
            },
            {
                "price": "868.50",
                "tarih": "19.08.2026"
            }
        ]
    }
}

3. Cupones y paquetes#

Si el huésped introduce un cupón, valídalo y aplica el descuento en tu sistema:

Terminal
curl "https://test.hms.gen.tr/external/online/coupon/search" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "coupon=SUMMER2026"
Respuesta · 200
{
    "success": true,
    "cupon": {
        "id": 12,
        "change": 0,
        "rate": "10.00"
    }
}

Con change 0, rate es un descuento porcentual (10 %); con 1, es un importe fijo (10.00 en la moneda del hotel). Aplica el descuento al importe de la habitación y envía los totales con descuento en la reserva.

Para vender extras, muestra la lista de paquetes. Los paquetes seleccionados se incluyen en la reserva como extras[], con el id del paquete en stockID. Los totales tras aplicar cupones y paquetes se escriben en el Total de la reserva.

4. Paso de pago#

Lista los tipos de pago que acepta el hotel y continúa según la elección del huésped. Con el tipo 10 (pago online) se inicia una sesión de pago y el huésped pasa al proveedor; tras el pago, vuelve a tu returnUrl. Todos los tipos se explican en la guía Flujo de pago.

5. Envía la reserva#

Cuando conozcas el resultado del pago, registra la reserva en HMS. ID es el código único que generas tú; da ese mismo código al huésped. Los IDs de tipo de habitación y de régimen proceden de la lista de habitaciones.

Solicitud
curl -X POST "https://test.hms.gen.tr/external/online/channel/booking" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @booking.json
Respuesta · 200
{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}

HMS_ID es el ID de la reserva en HMS; guárdalo junto con tu propio registro. La reserva aparece en el panel bajo el canal “Online” y HMS envía al huésped un correo de confirmación según la configuración del hotel.

Varias habitaciones#

Cuando se venden varias habitaciones del mismo tipo de habitación y régimen, cada habitación es un elemento RoomStays independiente; NumberOfUnits es "1" para la primera, "2" para la segunda, y así sucesivamente. Los distintos tipos de habitación también son elementos independientes. El Total de la reserva es la suma de todas las habitaciones y extras.

Modificaciones y cancelaciones#

Vuelve a enviar la reserva al mismo endpoint con el mismo ID:

  • type: "Modify" — han cambiado las fechas, las habitaciones o los datos del huésped. Envía la reserva completa en su estado actual; HMS sustituye el registro existente por ella.
  • type: "Cancel" — la reserva se ha cancelado. Las habitaciones también llevan type: "Cancel".

Errores frecuentes#

  • Guardar en caché la lista de habitaciones durante mucho tiempo. La disponibilidad y las tarifas cambian constantemente; actualiza la lista antes de que el huésped pase al paso de pago.
  • Enviar un childCount distinto de la longitud de childAges[]: el servidor se fía de la lista de edades y cambia el número de niños sin avisar.
  • Enviar tus propios IDs como roomTypeID / ratePlanID en lugar de los IDs de la lista de habitaciones: se devuelve Could not register.
  • Enviar PaymentCard con tipos de pago distintos del 9: los datos de la tarjeta se transmiten a HMS sin necesidad.
  • Reintentar tras un error de red con un ID diferente: se crea una reserva duplicada. Reintenta con el mismo ID.
Última actualización: 21 de septiembre de 2026¿Has encontrado un error? Avísanos