Reservaciones

El sistema de reservaciones permite agendar y pagar por adelantado la compra de un producto de tiempo y su redención en una mesa indicada también con anterioridad.

Consulta de disponibilidad

Dado que la disponibilidad de reservación es variable, debe efectuarse una consulta de horarios disponibles por categoría.

Descripción general

1. Se consultan las categorías de productos de tiempo en el local.
2. El servidor devuelve las categorías existentes.
3. Una vez elegida la categoría, se procede a consultar la disponibilidad de horario de estaciones que permitan redimir un producto de tiempo de dicha categoría.
4. El servidor devuelve los intervalos de media hora que se encuentran disponibles para reservar en la categoría especificada.

Flujo

Se requieren las siguientes rutas para la consulta de horarios disponibles:

Onsite: GET /categories/time_products

Autorización: Player

Mediante la cual se obtienen las categorías del lugar y los productos de tiempo que pueden adquirirse en las mismas. Esta ruta devuelve el estado 200 OK acompañada de la información de acuerdo a la siguiente estructura

categories:
  - id: 2
    name: Arena
    isPcOnly: false
    timeProducts:
      - id: 2
        minutes: 30
        costCoins: 200
        penaltyCoins: 100
      - id: 4
        minutes: 60
        costCoins: 500
        penaltyCoins: 250
  - id: 4
    name: Retro
    isPcOnly: false
    timeProducts:
      - id: 3
        minutes: 180
        costCoins: 300
        penaltyCoins: 150
      - id: 4
        minutes: 30
        costCoins: 600
        penaltyCoins: 300

Donde los atributos de la categoría corresponden a

id

El identificador

name

El nombre otorgado

isPcOnly

Indica si una categoría cuenta únicamente con PCs.

y los atributos del producto de tiempo corresponden a

id

El identificador

minutes

La cantidad de minutos que abarca el producto de tiempo

costCoins

El costo en moneda Arena del producto

penaltyCoins

El costo en moneda Arena del monto de retención por reservación

Onsite: GET /categories/{id}/available_timetable

Autorización: Player

Mediante la cual se consultan los horarios disponibles de estaciones pertenecientes a una categoría para la fecha solicitada en el parámetro date, el cual corresponde a una fecha UNIX en segundos.

El sistema ignora campos inferiores a los días en la búsqueda. Es decir, cualquier fecha entre el tiempo 1478304000 y el 1478390399 corresponde a una consulta por el día 5/11/2016.

Si la consulta de disponibilidad se lleva a cabo para el mismo día, los horarios disponibles abarcan desde el día operativo en curso en la sucursal hasta el cierre del local, en intervalos de media hora. No son devueltos los horarios abarcados por una reservación.

Por ejemplo, si en un local el horario es de 9 a 19 horas y no se cuenta con disponibilidad en los horarios 11 - 14 y 16 - 17 en una categoría dada el día 5/11/2016, esta ruta responde con el estado 200 OK acompañado de la siguiente información de la categoría

id: 2
name: Retro
timetable:
  - start: 1478336400
    end: 1478338200
  - start: 1478338200
    end: 1478340000
  - start: 1478340000
    end: 1478341800
  - start: 1478341800
    end: 1478343600
  - start: 1478354400
    end: 1478356200
  - start: 1478356200
    end: 1478358000
  - start: 1478358000
    end: 1478359800
  - start: 1478359800
    end: 1478361600
  - start: 1478365200
    end: 1478367000
  - start: 1478367000
    end: 1478368800
  - start: 1478368800
    end: 1478370600
  - start: 1478370600
    end: 1478372400

Esta ruta responde con el estado 200 OK acompañado de los horarios disponibles del día para reservar. Si la fecha de consulta no está en el futuro o no corresponde a una fecha bien formada, se responde con el estado 422 Unprocessable Entity.

Creación de reservación

Descripción general

1. El cliente solicita la creación de una reservación.
2. El sistema comprueba la disponibilidad de horario en la categoría, solicitada, agenda la reservación, y solicita a Offsite el envío de un correo de confirmación de la misma.
3. Offsite encola el correo de reservación con el servidor de correos.
4. El servidor de correos confirma la recepción de la petición.
5. Offsite responde con el resultado de encolar la petción de envío de correo.
6. Onsite confirma al cliente la creación de la reservación.

Flujo

La creación de una reservación en el local se crea invocando la siguiente ruta

Onsite: POST /reservations

Autorización: Player, Assistant

Mediante la cual se solicita la creación de una reservación en el sistema con los siguientes valores:

nick: pianoMan
categoryId: 2
isPC: false
numberOfPlayers: 2
reservationAt: 1478336400
timeProductId: 7

Donde

• nick corresponde al nombre del usuario para el que se realiza la reservación. Este campo es ignorado cuando la solicitud proviene de un jugador; pero es requerido cuando la petición es realizada por un asistente.
• categoryId es el identificador de la categoría a reservar.
• isPC indica si se desea reservar una PC.
• numberOfPlayers es el número de jugadores que atenderán la reservación.
• reservationAt corresponde a la fecha y hora cerrada en la que el jugador planea acudir a jugar.
• timeProductId es el identificador del producto de tiempo que se adquiere para la reservación.

El sistema verifica la disponibilidad de la categoría de estaciones para tantos minutos como especifique el producto de tiempo a comprar, el cual debe ser compatible con la categoría indicada.

Posterior a la verificación de disponibilidad, el servidor Onsite solicita a Offsite la autorización por una retención del 50% del monto del producto de tiempo contratado como se indica en Redención de un producto de tiempo. Si Offsite autoriza la retención por la mitad del costo del producto de tiempo, se agenda la reservación. Después, Onsite solicita el envío de correo de confirmación como se indica en la siguiente ruta.

La ruta responde con el estado 201 Created si la reservación pudo ser agendada para la fecha que se solicitó. Si la reservación fue llevada a cabo por un asistente y no fue proporcionado el nick del jugador, se responde con el estado 400 Bad Request. Si la referencia a la categoría o al producto de tiempo corresponden a instancias inválidas, o si el nick del jugador no existe, se responde con el estado 404 Not Found.

La ruta responde con el estado 409 Conflict para cualquiera de los siguientes casos:

• Si la categoría no se encuentra disponible para cubrir el tiempo solicitado en su totalidad.
• Si el producto de tiempo a adquirir no es compatible con la categoría donde se ubica la estación.
• Si se solicita reservar una PC con una cantidad de jugadores distinta a 1.
• Si el jugador ya cuenta con una reservación no redimida para el día proporcionado.
• Si el jugador no cuenta con moneda Arena suficiente para contratar la reservación.

Si el jugador para el cual se desea hacer una reservación es de tipo Guest, el sistema responde con el estado 412 Precondition Failed.

Si la fecha en la que se solicita crear una reservación no corresponde a una fecha en el futuro o el campo de los minutos no es divisible por 30, si se desea reservar para una fecha mayor a tres meses a partir de la fecha de la petición, o si el número de jugadores en la reservación es mayor a 8, se responde con el estado 422 Unprocessable Entity.

La reservación es creada y confirmada al usuario inclusive si Onsite recibe de Offsite una respuesta de error durante el envío de la plantilla.

Offsite: POST /templates/reservation

Autorización: Location

Mediante esta ruta se solicita el envío de un correo de confirmación de reservación al jugador indicado en la petición. El cuerpo del mensaje es el siguiente

nick: pianoMan
categoryId: Retro
isPC: false
numberOfPlayers: 2
reservationAt: 1478336400
timeProductSeconds: 3600

Como consecuencia, Offsite encola el envío de la plantilla en el servidor de correos. De agendarse el correo de manera exitosa, se responde con el estado 200 OK. Si la comunicación con el servidor de correo falla, se responde con el estado 503 Service Unavailable.

Notificación de reservación creada

Si una reservación es creada el mismo día que va a redimirse, se debe notificar la creación a todos los clientes Assistant del local. Lo anterior se lleva a cabo mediante la difusión del mensaje Onsite broadcast: create_reservation.

Preparación de reservación

Un asistente prepara una estación para la redención de un producto de tiempo reservado por un jugador. Con el objetivo de que un varios asistentes preparen múltiples estaciones para satisfacer la misma reservación, se tiene la facultad de marcar las reservaciones como preparadas. A continuación se describe el proceso.

Flujo

Se hace uso de la siguiente ruta para actualizar la fecha de preparación de una reservación.

Onsite: PUT /reservations/{id}/prepared_at

Autorización: Assistant

Al recibir esta petición, Onsite marca la fecha de preparación de la reservación.

La ruta responde con el estado 200 OK, acompañado de la reservación actualizada. Si la reservación no pudo ser localizada, se responde con el estado 404 Not Found.

La fecha de preparación de una reservación se establece únicamente con la primera petición. Si una reservación ha sido cancelada o redimida previo a la petición, o si la estación ya cuenta con la estación preparada, se responde con el estado 403 Forbidden.

Como consecuencia de la actualización de la reservación, se hace uso de la siguiente propagación del mensaje Onsite broadcast: update_reservation.

Cancelación de reservación

Flujo

Se hace uso de la siguiente ruta para cancelar una reservación existente en el local.

Onsite: DELETE /reservations/{id}

Autorización: Assistant, Player

Mediante esta ruta se solicita cancelar la reservación indicada en el parámetro id. Al recibir esta petición, debe eliminarse la reservación del sistema.

Como acción posterior, se comprueba si la fecha de recepción de la petición es mayor a 24 horas previo al campo reservationAt. De ser así, se libera el monto retenido por el Sistema Arena. En caso contrario, se solicita que dicho monto retenido por la reservación a cancelar sea cobrado efectivamente. Este comportamiento se indica en Redención de un producto de tiempo.

El sistema responde con el estado 200 OK acompañado de la reservación cancelada. Si la reservación indicada a cancelar no existe, se responde con el estado 404 Not Found. Si el campo reservationAt se encuentra en el pasado, o si la reservación ha sido redimida, se responde con el estado 409 Conflict.

Si un jugador intenta cancelar una reservación ajena, se responde con el estado 403 Conflict.

Como acción posterior a la cancelación exitosa, el proceso debe ser notificado a los clientes Assistant como se indica en la siguiente sección.

Notificación de reservación cancelada

Las reservaciones canceladas deben ser notificadas a los clientes Assistant con el objetivo de que estos sean capaces de actualizar su registro local. Esto se lleva a cabo mediante el broadcast Onsite broadcast: delete_reservation.

Como acción a esta difusión, los clientes deben garantizar que la reservación ya no será mostrada en sus registros.

Disponibilidad de horario

Para toda categoría del local y en cualquier intervalo de tiempo, la cantidad de estaciones disponibles para ser reservadas corresponde a 3/5 de aquellas que no se encuentren en uso.

Al realizar una reservación para un día distinto al actual, basta con verificar que la cantidad de estaciones reservadas para el intervalo de tiempo deseado sea menor a 3/5. Si esto se cumple, se permite la reservación.

Por otro lado, si se desea realizar una reservación para el mismo día, se considera como capacidad de la categoría al número de estaciones que no estén siendo empleadas en la redención de un producto de tiempo. Posteriormente, en el subconjunto de estaciones obtenido se determina si la cantidad de estaciones reservadas es menor a 3/5. Sólo en este caso procede la reservación.

Nota: En caso de que 3/5 de la capacidad de una categoría no sea un número entero, este se redondeará hacia arriba si la fracción decimal es mayor o igual a 0.5. En caso contrario, el entero será redondeado hacia abajo.

Reglas para redención de reservación

Un jugador tiene oportunidad de redimir una reservación desde 15 minutos antes del comienzo programado de la misma hasta el final del día. Dependiendo del momento en que la reservación sea redimida se lleva a cabo uno de los siguientes comportamientos:

1. El reservante llega a tiempo Se considera como redención a tiempo aquella que se efectúa en el intervalo [h - 15, h + 15], donde h es la hora a la que el usuario se comprometió a hacer uso de su reserva. En este caso, para cada jugador con reservación dentro del Match por asignar a una estación se aplican los citerios en la nota al pie.
2. El reservante llega a destiempo Si el reservante llega antes del intervalo permitido para redimir la reservación, no puede hacer uso de la misma. Por otro lado, si el reservante llega después del intervalo definido en el punto 1, su reservación es considerada como bonificable durante el transcurso del día. Las reglas para hacer uso de la bonificación se definen en la nota al pie de la sección.

Nota

Si el producto que se desea redimir es de costo mayor o igual que el anticipo del producto de tiempo reservado, se libera la retención de la reservación y se hace el cargo por el 100% del nuevo producto solicitado. Por el contrario, si el producto que se desea redimir es de costo menor que el anticipo del producto de tiempo reservado, se cobra la retención llevada a cabo al reservar. Acto seguido, se otorga al jugador el producto de tiempo que solicitó, no el que reservó.

Expiración de reservaciones

Al final del día, cada reservación no redimida existente en la sucursal debe ser cancelada en el servidor Offsite. Para esto, se envía la solicitud de cobro de la retención como se indica en Redención de un producto de tiempo.

Observaciones

• Los horarios disponibles para reservar un equipo ocurren en intervalos de media hora.
• Los horarios de apertura y cierre del local son especificados durante la configuración del sistema.