===================== Funciones de usuarios ===================== A continuación se describen las operaciones que pueden realizar los usuarios en el portal de administración de acuerdo a su rol. Admin Offsite ============= Aquellos usuarios creados con el propósito de efectuar modificaciones sobre propiedades globales del Sistema Arena. También están facultados para llevar a cabo algunas funciones de los otros roles de administración. La propiedad de rol para este usuario es *super*. Gestión de usuarios ------------------- Primer usuario ############## Previo el levantamiento incial del servidor Offsite, debe ser creado un usuario en el seed de la base de datos que contenga los datos del primer súper usuario. De no existir información de dicho usuario, el servidor Offsite debe abortar su levantamiento. Al momento de inicialización del servidor Offsite, se crea un nuevo Access Key para el usuario del seed y se envía un correo con el subject y el secret del mismo, que le permitirá al usuario firmar su petición de establecimiento de contraseña. La fecha de expiración del Access Key será de 3 días a partir de la creación. El establecimiento de contraseña se lleva a cabo mediante la ruta :ref:`establecer-password`. Creación de usuarios #################### Descripción general ^^^^^^^^^^^^^^^^^^^ .. image:: /images/user/user_creation_overview.svg :align: center 1. Un usuario *super admin* solicita la creación en Offsite de un nuevo usuario. 2. Offsite valida la información recibida y, en caso de ser aprobada, crea el usuario y solicita el envío de un correo para el establecimiento de contraseña. 3. El servidor de correo responde con el estado de la operación. 4. Offsite responde al usuario con la creación de la nueva cuenta. Flujo ^^^^^ Se hace uso de la siguiente ruta para dar de alta un nuevo usuario Offsite: ``POST /users`` ************************ **Autorización:** User (*super*) Mediante la cual se solicita la creación de una cuenta *User* con los siguientes valores .. code-block:: yaml role: super locationId: 2 position: Creador de sucursales name: Juan lastName: Pérez Pérez email: juanp@domain.com phone: 5511223344 address: Calzada bonita 93. Colonia Las Flores. Como resultado de la petición, se crea un usuario con la información proporcionada, validando la unicidad del correo electrónico. Además, se establece el creador del nuevo usuario como aquel que lleva a cabo la petición y, en caso de ser un nuevo usuario *onsite*, se liga la nueva cuenta a la sucursal indicada. Finalmente, se crea un nuevo Access Key para el usuario y se envía un correo con el subject y el secret del mismo, que le permitirá al usuario firmar su petición de establecimiento de contraseña. La fecha de expiración del Access Key será de 3 días a partir de la creación. La ruta responde con el estado ``201 Created`` acompañado del usuario recién creado. Si el correo electrónico proporcionado ya se encuentra en uso por cualquiera de los perfiles (Player, User) o si la sucursal a la que se asignará el usuario no es proporcionada (en caso de ser *onsite* el nuevo usuario), o si se intenta establecer la sucursal de un usuario que no es *onsite*, se responde con el estado ``409 Conflict``. Si la sucursal proporcionada no existe, se responde con el estado ``404 Not Found``. Adicional a validaciones de sintaxis de la petición, se responde con el estado ``422 Unprocessable Entity`` bajo cualquiera de los siguientes casos: - El *role* proporcionado no es uno de entre *super*, *onsite*, o *tournament*. - Los campos de nombre, apellido o dirección exceden los 100 caracteres de longitud. - El teléfono presenta algún caracter no numérico, o la longitud es mayor a 13 dígitos. Todos los campos, a excepción de ``locationId`` cuando aplique, son requeridos. El campo ``address`` es requerido para usuarios con rol *super* u *onsite*, y opcional para usuarios *tournament*. La ausencia del campo ``address`` cuando este es requerido resulta en el error``400 Bad Request``. Si el servidor de correos no está disponible, se hace *rollback* de la creación y se responde con el estado ``503 Service Unavailable``. El establecimiento de contraseña se lleva a cabo mediante la siguiente ruta: .. _establecer-password: Offsite: ``POST /users/password`` ********************************* **Autorización:** User (*super*, *onsite*) Mediante esta ruta, se solicita el establecimiento de contraseña del usuario que lleva a cabo la petición. El cuerpo de la petición contiene únicamente el campo de contraseña a establecer. Al recibir esta petición, se marca como expirado el Access Key del usuario cuyo secret se recibe en la petición. Esto con el objetivo de que el Key generado para el restablecimiento de contraseña sea de un solo uso. Adicionalmente, se elimina el campo `requestPasswordRecoveryAt`. La ruta responde con el estado ``200 OK`` como resultado de la modificación de la contraseña. Si el usuario no solicitó restablecimiento de contraseña, se responde con el estado ``403 Forbidden``. Obtención de usuarios ##################### Descripción general ^^^^^^^^^^^^^^^^^^^ .. image:: /images/user/user_fetching_overview.svg :align: center 1. Un usuario solicita la información de los usuarios existentes. 2. Offsite consulta y devuelve la información solicitada. Flujo ^^^^^ Offsite: ``GET /users`` *********************** **Autorización:** User (*super*) Mediante esta ruta se solicita la información de los usuarios no suspendidos de Arena. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml users: - id: 1 email: juanp@domain.com role: onsite position: Encargado de sucursal profile: name: Juan lastName: Pérez Pérez phone: 5567982312 address: Sierra Bonita 49. Col. Unión createdBy: name: Eufrasio lastName: Domínguez email: eufrasio@domain.com phone: 5515678723 belongsTo: Cuernavaca isManagerOf: Cuernavaca createdAt: 1469491719 updatedAt: 1469491345 - id: 5 email: eufrasio@domain.com role: super position: Encargado de sucursales profile: name: Eufrasio lastName: Domínguez phone: 5515678723 address: Paleta 23. Colonia Dulces requestedPasswordRecoveryAt: 1469492345 createdAt: 1469491719 updatedAt: 1469491345 ``id`` Identificador proporcionado por el modelo. ``email`` Correo electrónico / usuario para el administrador. ``role`` Rol del administrador (*super*, *onsite*, *tournament*). ``position`` Cargo del usuario dentro de la empresa. De carácter informativo. ``profile.name`` Nombre del usuario. ``profile.lastName`` Apellido(s) del usuario. ``profile.phone`` Teléfono de contacto. ``profile.address`` Residencia física del usuario. ``createdBy`` Información del usuario creador. La ausencia de valor para este campo indica que el usuario fue creado durante el levantamiento del sistema. ``requestedPasswordRecoveryAt`` Fecha en la que el usuario solicita la recuperación de su contraseña. La presencia de este campo es opcional. ``belongsTo`` En caso de de ser un usuario administrador de un local (*onsite*), este campo opcional indica el nombre de la sucursal para la cual se cuenta con permisos. ``isManagerOf`` En caso de de ser un usuario administrador de un local (*onsite*), este campo opcional indica el nombre de la sucursal en la cual es gerente. ``createdAt`` Fecha de creación del usuario. ``updatedAt`` Fecha de la última modificación. Se tienen los siguientes parámetros de búsqueda para la ruta ============ ======= ===================================== Parámetro Tipo Función ------------ ------- ------------------------------------- role string | Solicita el filtrado de usuarios | por el rol indicado. location string | Filtra la búsqueda por el nombre | de la sucursal para la cual | fue creado el usuario. Este | campo debe devolver únicamente | usuarios con rol *onsite*. location_id integer | Filtra la búsqueda por el id | de la sucursal para la cual | fue creado el usuario. Este | campo debe devolver únicamente | usuarios con rol *onsite*. email string | Busca al usuario cuya dirección | de correo coincida con la | ingresada. ============ ======= ===================================== Cualquier parámetro de búsqueda no reconocido es ignorado. Edición de usuarios ################### El flujo descrito a continuación es llevado a cabo por un usuario con permisos suficientes para editar la información de perfil de su cuenta o de la cuenta de otro administrador. Flujo ^^^^^ Offsite: ``PUT /users/{id}`` **************************** **Autorización:** User (*super*) Mediante esta ruta, es posible actualizar la información de perfil del usuario con el identificador indicado. Un esquema con los campos susceptibles de edición es el siguiente: .. code-block:: yaml phone: 5587234532 address: Sierra Blanca 43. Las Palmas position: Cajero locationId: 2 role: super Sólo en caso de que el usuario sea *onsite* previo a la petición será posible llevar a cabo el cambio de sucursal; esto para señalar que el administrador cambia de locación, lo que también significa renovación de permisos. Por lo tanto, al hacer un cambio de sucursal, el Access Key del usuario debe marcarse como expirado para requerir un nuevo inicio de sesión. Un cambio de rol marca el cambio de nivel de autorización para un usuario. Dicho cambio puede hacerse de *onsite*/*tournament* a *super* y viceversa, mas no puede realizarse entre *onsite* y *tournament* de manera directa. En caso de convertirse en usuario *onsite*, se debe proporcionar también la sucursal a la cual se ligará al administrador. Por otro lado, si un usuario pierde su rol *onsite*, también pierde su relación con una sucursal. La ruta responde con el estado ``200 OK`` acompañado del usuario modificado. Si se desea cambiar el rol del usuario por *onsite*, pero no se indica la sucursal a la que pertenecerá, se responde con el estado ``422 Unprocessable Entity``. Adicional a validaciones de sintaxis de la petición, se responde con el estado ``422 Unprocessable Entity`` bajo cualquiera de los siguientes casos: - El *role* proporcionado no es uno de entre *super*, *onsite*, o *tournament*. - Los campos de cargo o dirección exceden los 100 caracteres de longitud. - El teléfono presenta algún caracter no numérico, o la longitud es mayor a 13 dígitos. Si el usuario intenta editar información propia, se responde con el estado ``403 Forbidden``. Un súper usuario únicamente puede editar información de otros súper usuarios. El campo ``address`` es requerido para usuarios que cambien de rol a *super* u *onsite*, y opcional para usuarios *tournament*. La ausencia del campo ``address`` cuando este es requerido resulta en el error ``400 Bad Request``. Si la sucursal a la que desea reasignarse un usuario *onsite* no existe, se responde con el estado ``404 Not Found``. Si se intenta establecer la sucursal de un usuario que no es *onsite*, o si intenta hacer un cambio de rol entre *onsite* y *tournament*, se responde con el estado ``409 Conflict``. Suspensión de cuenta #################### Un súper usuario tiene el privilegio de suspender cuentas de otros usuarios de igual o menor jerarquía. A continuación se indica la ruta en Offsite para llevar a cabo dicho proceso. Flujo ^^^^^ Offsite: ``DELETE /users/{id}`` ******************************* **Autorización:** User (*super*) Mediante esta ruta se elimina la cuenta del usuario indicado en el parámetro ``id``, imposibilitando la realización de cualquier función que indica su rol. Como recepción de esta petición, se lleva a cabo un *hard delete* del usuario, así como de su respectivo Access Key. La ruta responde con el estado ``200 OK`` acompañado del usuario suspendido. Si el usuario a eliminar coincide con aquel que lleva a cabo la petición, se responde con el estado ``403 Forbidden``. .. _recuperacion-pass-usuario: Recuperación de contraseña ########################## Un usuario solicita la recuperación de su contraseña con el servidor Offsite. Posteriormente, el usuario solicitante recibe el enlace para restablecer su contraseña. El proceso es descrito a continuación. Descripción general ^^^^^^^^^^^^^^^^^^^ .. image:: /images/user/user_password_reset_overview.svg :align: center 1. El usuario solicita al servidor Offsite el restablecimiento de su contraseña. 2. Como consecuencia del punto anterior, Offsite solicita el envío de un correo con instrucciones para el restablecimiento de contraseña del usuario. 3. El servidor de correos responde a Offsite confirmando el encolamiento el correo. 4. Offsite responde al usuario que su autorización de restablecimiento de contraseña fue procesada. Flujo ^^^^^ .. image:: /images/user/user_password_reset_sequence.svg :align: center Se hace uso de la siguiente ruta para el restablecimiento de contraseña Offsite: ``POST /templates/users_password`` ******************************************* Mediante esta ruta se solicita la obtención de una nueva contraseña para el usuario. Al recibir la petición se renueva el Access Key del usuario. Con los valores *subject* y *secret* se envía un correo al usuario con una liga para el restablecimiento. La nueva fecha de expiración del Access Key será de 3 días a partir de la fecha de creación. La ruta responde con el estado ``200 OK`` indicando así que se envió un correo al usuario para que este pueda restablecer su contraseña. Si ya se ha solicitado un restablecimiento de contraseña (la fecha de solicitud es no nula), se establece el campo ``requested_password_recovery_at`` como la fecha de recepción de la última petición. Si no se encuentra el usuario indicado en la petición, se responde con el estado ``404 Not Found``. Finalmente, se renueva el Access Key para el usuario y se envía un correo con el subject y el secret del mismo, que le permitirá al usuario firmar su petición de establecimiento de contraseña. La fecha de expiración del Access Key será de 3 días a partir de la creación. Para finalizar el flujo, el restablecimiento de contraseña se lleva a cabo mediante la ruta :ref:`establecer-password`. Gestión de sucursales --------------------- Creación de sucursales ###################### La creación de una sucursal se lleva a cabo como se indica en el flujo :ref:`dar-de-alta-local`. .. _obtener-sucursales: Obtención de sucursales ####################### A continuación se describe la ruta para obtener la información de las sucursales registradas en Offsite, así como los filtros disponibles para parametrizar la búsqueda. Flujo ^^^^^ Offsite: ``GET /locations`` *************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene el listado de sucursales dadas de alta en el servidor. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml - id: 2 name: Antara prefix: AN imageBucket: arena_onsite_ANkjH67n domain: antara.onsite.arena.mx timezone: America/Mexico_City code: GHuy6 acceptedAt: 1469491719 lastUpdatedBy: name: Juvenal lastName: Urbino email: juve@domain.com phone: 5564390876 manager: name: Juvenal lastName: Urbino email: juve@domain.com phone: 5564390876 users: - name: Miguel lastName: Domínguez email: miguel@domain.com phone: 5543526726 - name: Marcos lastName: Almada email: marcos@domain.com phone: 5528229384 locationInfo: address: Plateros 32. Colonia Metales city: Ciudad de México state: Distrito Federal phone1: 56129726 phone2: 76109234 phone3: 87422932 country: id: 1 name: México currency: Pesos mexicanos isoCode: MXN - id: 5 name: Cuernavaca prefix: CU imageBucket: arena_onsite_CUgj76N domain: cuernavaca.onsite.arena.mx timezone: America/Mexico_City code: fh67G acceptedAt: 1469491732 manager: name: Florentino lastName: Ariza email: ariza@domain.com phone: 5520938325 users: - name: Gustavo lastName: Flores email: gustavo@domain.com phone: 5566273843 - name: Lorena lastName: Yamil email: lorena@domain.com phone: 5562928374 locationInfo: address: Ahuehuetes 45. Col. Santos city: Cuernavaca state: Morelos phone1: 23798777 phone2: 87687665 phone3: 08767657 country: id: 1 name: México currency: Pesos mexicanos isoCode: MXN ``id`` Identificador otorgado a la sucursal por el modelo. ``name`` Nombre asignado a la sucursal. ``prefix`` Prefijo que será antepuesto al nombre de cada dispositivo cliente registrado en la sucursal. ``imageBucket`` Nombre del contenedor de imágenes de la sucursal. ``domain`` Dominio de la sucursal. ``timezone`` Zona horaria de la sucursal. ``code`` Código de verificación para ligar una sucursal física a su correspondiente entidad virtual. ``acceptedAt`` Fecha en la que la sucursal es ligada a su correspondiente entidad virtual. La ausencia de este campo indica que la sucursal ha sido creada por el administrador Offsite, pero no ha habido servidor Onsite que se enlace a la misma. ``lastUpdatedBy`` Información del autor de la última modificación a la información de la sucursal. ``manager`` Información del usuario *onsite* a cargo de la sucursal. ``locationInfo.address`` Dirección física de la sucursal. ``locationInfo.city`` Ciudad a la que pertenece la sucursal. ``locationInfo.state`` Estado de ubicación de la sucursal. ``locationInfo.phoneN`` Teléfono de contacto. ``country`` Información del país de pertenencia de la sucursal. Se tienen los siguientes parámetros de búsqueda para la ruta ========= ====== ====================================== Parámetro Tipo Función --------- ------ -------------------------------------- name string | Solicita el filtrado de sucursales | por nombre. city string | Filtra la búsqueda por la ciudad | de la sucursal. state string | Filtra la búsqueda por el estado | de la sucursal. country string | Realiza búsqueda por país de la | sucursal. ========= ====== ====================================== Si esta ruta es invocada por un usuario *Onsite*, debe devolverse en la respuesta únicamente la sucursal a la que pertenece o de la cual es administrador el usuario. .. _detalles-sucursal: Ver detalles de sucursal ######################## A continuación se define la ruta en el servidor Onsite empleada por un súper usuario para obtener información específica de un local. Flujo ^^^^^ Onsite: ``GET /location_details`` ********************************* **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene la información de la sucursal de acuerdo al siguiente esquema .. code-block:: yaml categories: - id: 1 name: Retro - id: 1 name: Platinum pcCount: 23 screenCount: 35 ``categories`` Listado de categorías de la sucursal. ``pcCount`` Conteo de las PCs existentes. ``screenCount`` Conteo de las estaciones que no son PC, es decir, pantallas. La ruta responde con el estado ``200 OK`` acompañado de la información como en el esquema recién descrito. .. note:: Si no se encuentra registro del usuario en el servidor Onsite, este debe hacer una petición a Offsite para actualizar su registro de llaves. Editar sucursal ############### La ruta descrita a continuación es empleada cuando se desea editar la información registrada de una sucursal. Flujo ^^^^^ Offsite: ``PUT /locations/{id}`` ******************************** **Autorización:** User (*super*) Mediante esta ruta se edita la información registrada de una sucursal. Un ejemplo del esquema con los campos aceptados para edición es el siguiente .. code-block:: yaml email: antara@domain.com address: Calzada de las lomas 23. city: Ciudad de México state: Distrito Federal timezone: America/Mexico_City countryId: 2 phone1: 45654323 phone2: 27872637 phone3: 29826276 managerId: 2 Como parte de las acciones al recibir la petición, se actualiza el último usuario en modificar la sucursal. Adicional a validaciones de sintaxis de la petición, se responde con el estado ``422 Unprocessable Entity`` bajo cualquiera de los siguientes casos: - Los campos de correo, dirección, país o ciudad exceden los 100 caracteres de longitud. - Los teléfonos presentan algún caracter no numérico, o la longitud es mayor a 13 dígitos. Si el identificador del usuario a asignar como gerente no existe, o si no se encuentra la sucursal, o si no se encuentra el país, se responde con el estado ``404 Not Found``. Si el usuario referenciado a ser encargado del local no tiene rol *onsite*, o no pertenece a la sucursal a editar, se responde con el estado ``409 Conflict``. Si se desea actualizar la zona horaria y la sucursal ya cuenta con un servidor vinculado, se responde con el estado ``412 Precondition Failed``. Gestión de países ----------------- Creación de país ################ La ruta descrita a continuación es empleada para dar de alta la información de un país, que incluye el nombre de su divisa y su abreviación Flujo ^^^^^ Offsite: ``POST /countries`` *(Deshabilitada)* ********************************************** **Autorización:** User (*super*) El propósito de esta ruta es dar de alta una divisa de cobro en el sistema Arena, así como su equivalencia en moneda virtual. El cuerpo del mensaje es el siguiente .. code-block:: yaml name: México currency: Peso mexicano isoCode: MXN ``name`` Nombre del país. ``currency`` Nombre la divisa. ``isoCode`` Código de país definido. La ruta responde con el estado ``201 Created`` si la creación del país fue correcta. Si alguno de los campos ``name``, ``currency``, ``isoCode`` ya existe registrado para un país, se responde con el estado ``409 Conflict``. Visualizar lista de países ########################## A continuación se describe la ruta usada para la obtención de países y su información asociada. Flujo ^^^^^ Offsite: ``GET /countries`` *************************** **Autorización:** User (*super*) A través de esta ruta son devueltos los países de los cuales se tiene registro en Offsite. La información devuelta tiene el siguiente esquema .. code-block:: yaml - id: 1 name: México currency: Peso mexicano isoCode: MXN - id: 2 name: Estados Unidos currency: Dólar estadounidense isoCode: USD La ruta responde con el estado ``200 Ok`` acompañado de los países de acuerdo al esquema anterior. De manera adicional, puede llevarse a cabo la búsqueda con uno de los siguientes parámetros ========= ====== ====================================== Parámetro Tipo Función --------- ------ -------------------------------------- name string | Solicita el filtrado de países | por nombre. currency string | Realiza búsqueda por divisa del | país. isoCode string | Filtra la búsqueda por el código | de la divisa del país. ========= ====== ====================================== Gestión de precios de producto ------------------------------ .. _consulta-productos-offsite: Visualizar lista de productos ############################# Se indica a continuación la manera de obtener productos de tiempo y de recarga del servidor, así como su costo en función de la sucursal para la que son efectivos. Flujo ^^^^^ Offsite: ``GET /time_products`` ******************************* **Autorización:** User (*super*), Location Mediante esta ruta se obtiene la lista de productos de tiempo dados de alta en Offsite. La ruta responde con el estado ``200 OK`` siguiendo el siguiente esquema .. code-block:: yaml - id: 1 minutes: 30 category: Retro cost: - id: 1 coins: 100 penaltyCoins: 50 location: id: 2 name: Antara - id: 2 coins: 50 penaltyCoins: 25 location: id: 4 name: Cuernavaca En caso de que esta petición haya sido llevada a cabo por una sucursal, Offsite responde únicamente con los costos asociados al *Location* que lleva a cabo la petición. .. _obtener-recargas: Offsite: ``GET /recharges`` *************************** **Autorización:** User (*super*), Player, Location Mediante esta ruta se obtiene la lista de productos de recarga dados de alta en Offsite. La ruta responde con el estado ``200 OK`` siguiendo el siguiente esquema .. code-block:: yaml - id: 1 coins: 100 cost: - id: 1 amountCents: 10000 locationId: 3 country: México currency: Pesos mexicanos isoCode: MXN - id: 2 amountCents: 5000 locationId: 67 country: Estados Unidos currency: Dólar estadounidense isoCode: USD Es posible hacer uso del parámetro de búsqueda ``isoCode`` para obtener el listado de recargas posibles para un divisa en específico. También puede usarse el parámetro ``locationId`` para obtener los productos de recarga con costos registrados para la sucursal en específico. En caso de que esta petición haya sido llevada a cabo por una sucursal, Offsite responde únicamente con los costos del país al que pertenece el servidor Onsite. Visualizar categorías ##################### Es posible visualizar el listado de categorías de producto de tiempo dadas de alta en el sistema haciendo uso de la siguiente ruta. Flujo ^^^^^ Offsite: ``GET /categories`` **************************** **Autorización:** User (*super*) Mediante este ruta se consulta la información de las categorías de producto de tiempo. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml - id: 1 name: Next Level Zone createdAt: 1469491719 isPcOnly: false - id: 2 name: Retro Room createdAt: 1469491719 isPcOnly: false - id: 3 name: Platinum Room createdAt: 1469491719 isPcOnly: false - id: 4 name: Versus Zone createdAt: 1469491719 isPcOnly: true Gestión de precios de entrada a torneo -------------------------------------- Visualizar lista de productos ############################# Es posible visualizar el listado de precios de entrada a torneo dados de alta en el sistema como se indica a continuación. Flujo ^^^^^ Offsite: ``GET /tournament_products`` ************************************* **Autorización:** User (*super*) Mediante esta ruta se obtiene la información de los productos de entrada a torneo. La ruta admite los siguientes parámetros de consulta: ============ ============================================ Nombre Comportamiento ============ ============================================ location_id | En caso de proporionarse, el servidor | devuelve únicamente los productos de | torneo existentes para la sucursal. ============ ============================================ La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - id: 1 name: TORNEO PRO 150 cost: - id: 1 coins: 150 location: id: 2 name: Antara - id: 2 coins: 150 location: id: 4 name: Cuernavaca - id: 1 name: TORNEO PLUS 140 cost: - id: 1 coins: 140 location: id: 2 name: Antara - id: 2 coins: 140 location: id: 4 name: Cuernavaca Gestión de avatares ------------------- Creación de avatar ################## A continuación se describe el proceso para la carga de un avatar en el bucket dedicado en Offsite. Flujo ^^^^^ Offsite: ``POST /avatars`` ************************** **Autorización:** User (*super*) Mediante esta ruta se solicita el alojamiento de un avatar en formato **jpg** o **png** en el servicio GCS. Offsite definirá el nombre del archivo siguiendo la convención ``a_UUUUUUUUUU_AAAAA.[jpg|png]``, donde *UUUUUUUUUU* corresponde a la fecha UNIX en segundos y *AAAAA* es una cadena alfanumérica aleatoria. Para la comunicación con GCS, el proceso de cargar una imagen es el siguiente: .. code-block:: javascript var bucket = gcs.bucket(bucketName); var filename = 'a_' + new Date().getTime() + "_" + random + '.jpg'; var file = bucket.file(filename); var imageUrl = 'https://www.googleapis.com/storage/v1/b/' + settings.gcp.bucketName + '/o/' + filename; fs.createReadStream(imageData.path) // Path to image resource .pipe(file.createWriteStream({ metadata: { contentType: 'image/jpeg' // O 'png' en función de la extensión } })) .on('error', callback) .on('finish', function() { // On upload success file.makePublic(function(errPublic, apiResponse) { // On make public success }); }); Al lograr almacenar y hacer pública una imagen, se almacenan en la base de datos el nombre del archivo (*filename*) y la URL de consulta que se proporcionará al cliente (*imageURL*). Esta ruta responde con el estado ``201 Created`` acompañado del avatar si su creación y almacenamiento en GCS fueron exitosas. Si el nombre del avatar ya existe, se responde con el estado ``409 Conflict``. Si el formato de imagen es inválido se responderá ``415 Unsupported media type``. En caso de ocurrir un error de comunicación con GCS se responde ``503 Service Unavailable``. Si ocurre un error al alojar el archivo se responde con el estado ``500 Internal Server Error``. .. note:: Los avatares deben ser cargados en el bucket ``arena-offsite-avatars``. Dicho bucket debe ser creado por Offsite al momento del primer levantamiento como se describe en :ref:`creacion-de-contenedor`. Visualización de avatares ######################### Los avatares pueden obtenerse para su visualización siguiendo el comportamiento descrito a continuación. Flujo ^^^^^ .. _obtener-avatares: Offsite: ``GET /avatars`` ************************** **Autorización:** User (*super*), nula Mediante esta ruta se consulta el banco de avatares existentes en Offsite. La petición responde con el estado ``200 OK`` acompañado de los avatares siguiendo el siguiente esquema: .. code-block:: yaml - id: 1 name: Malote fileName: a_1475281867_67gk5.jpg url: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475281865163-0.9304038190748543 createdAt: 1469491719 updatedAt: 1469491267 - id: 2 name: Lady Di fileName: a_1475281299_GH67g.jpg url: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475281865163-0.9304038190748543 createdAt: 1469491254 updatedAt: 1469492673 A partir del campo ``url``, es responsabilidad del cliente obtener la imagen como se describe en :ref:`recuperacion-de-imagen`. Admin Onsite ============ Aquellos usuarios creados con el propósito de efectuar modificaciones sobre propiedades de una sucursal del Sistema Arena. La propiedad de rol para este usuario es *onsite*. Gestión de credenciales ----------------------- Inicio y cierre de sesión ######################### La autenticación de un usuario Onsite se lleva a cabo como se indica en :ref:`autenticacion-usuarios`. Posteriormente, las peticiones autenticadas deben dirigirse al servidor Onsite en particular. Recuperación de contraseña ########################## El proceso de recuperación de contraseña se lleva a cabo como se describe en :ref:`recuperacion-pass-usuario`. Gestión de información general ------------------------------ Consulta de información de sucursal ################################### La información de la sucursal se consulta realizando una consulta al servidor Offsite como se indica en :ref:`obtener-sucursales`. La información sobre la cantidad y tipo de estaciones se obtiene como se indica en :ref:`detalles-sucursal`. Consultar horario de operación ############################## A continuación se indica el comportamiento para consultar el horario de apertura y cierre de un local. Flujo ^^^^^ Onsite: ``GET /timetable`` ************************** **Autorización:** User (*super*, *onsite*), Assistant Mediante esta ruta se consulta el horario de operación del local. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml opening: 0830 closing: 2330 Donde los enteros ``opening`` y ``closing`` se refieren a los horarios de apertura y cierre, respectivamente, del local; ambos expresados en formato de 24 horas. Editar horario de operación ########################### A continuación se indica el comportamiento para establecer el horario de apertuta y cierre del local. Flujo ^^^^^ Onsite: ``PUT /timetable`` ************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se editan los horarios de apertura y cierre del local. El cuerpo de la petición es el siguiente: .. code-block:: yaml opening: 0830 closing: 2330 Donde los enteros ``opening`` y ``closing`` se refieren a los horarios de apertura y cierre, respectivamente, del local; ambos expresados en formato de 24 horas. La ruta responde con el estado ``200 OK`` indicando así que la actualización fue correcta. La actualización de horario tiene efecto inmediato sobre la operación del local. Si los campos de horario no respetan el formato, si los dos enteros más significativos no pertenecen a la secuencia ``[00, ..., 23]``, o si los dos enteros menos significativos no pertenecen a la secuencia ``[00, ..., 59]``, se responde con el estado ``422 Unprocessable Entity``. .. _consulta-productos-onsite: Visualizar lista de productos ############################# Se indica a continuación la manera de obtener productos de tiempo y de recarga de la sucursal. Flujo ^^^^^ .. _obtener-productos-tiempo: Onsite: ``GET /time_products`` ****************************** **Autorización:** User (*super*, *onsite*), Kiosk, Timer, Assistant, Player Mediante esta ruta se obtiene la lista de productos de tiempo dados de alta en Onsite. La ruta responde con el estado ``200 OK`` siguiendo el siguiente esquema .. code-block:: yaml - id: 1 minutes: 30 category: id: 1 name: Retro createdAt: 1469491719 updatedAt: 1469491345 costCoins: 100 penaltyCoins: 50 createdAt: 1469491719 updatedAt: 1469491345 - id: 1 minutes: 30 category: id: 2 name: Platinum createdAt: 1469491719 updatedAt: 1469491345 costCoins: 200 penaltyCoins: 100 createdAt: 1469491719 updatedAt: 1469491345 Se tienen los siguientes parámetros de consulta para la petición: ============ ============================================ Nombre Comportamiento ============ ============================================ force_update | En caso de ser ``true``, solicita la | actualización forzosa de los productos de | tiempo con aquellos existentes en Offsite. | Dicha actualización se lleva a cabo como | se indica en :ref:`actualizar-productos`. | El valor por defecto de este campo es | ``false``. ============ ============================================ Onsite: ``GET /recharges`` ************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene la lista de productos de recarga dados de alta en Onsite. La ruta responde con el estado ``200 OK`` siguiendo el siguiente esquema .. code-block:: yaml - id: 1 coins: 100 amountCents: 10000 createdAt: 1469491719 updatedAt: 1469491345 - id: 2 coins: 300 amountCents: 30000 createdAt: 1469491719 updatedAt: 1469491345 Se tienen los siguientes parámetros de consulta para la petición: ============ ============================================ Nombre Comportamiento ============ ============================================ force_update | En caso de ser ``true``, solicita la | actualización forzosa de los productos de | tiempo con aquellos existentes en Offsite. | Dicha actualización se lleva a cabo como | se indica en :ref:`actualizar-productos`. | El valor por defecto de este parámetro es | ``false``. ============ ============================================ .. _actualizar-productos: Actualizar lista de productos ############################# A continuación se define el proceso para actualizar la información de los productos, tanto de tiempo como de recarga, existentes en la sucursal. Flujo ^^^^^ .. image:: /images/user/product_refresh_sequence.svg :align: center La solicitud de actualización de los productos de tiempo o de recarga en Onsite se lleva a cabo invocando las rutas descritas en :ref:`consulta-productos-onsite`, proporcionando el parámetro de consulta ``forceUpdate``. Al solicitar la actualización forzosa de los productos, el servidor Onsite consultará a Offsite la última versión del listado como se indica en :ref:`consulta-productos-offsite`. Corte del día ############# Al finalizar un día operativo, se solicita al servidor Onsite la realización de un corte. Como consecuencia, se realizarán los cobros de penalizaciones pendientes para el día. A continuación, se describe la ruta que garantiza dicho comportamiento. Flujo ^^^^^ Onsite: ``GET /balancing`` ************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta, se solicita el fin de día operativo en la sucursal. En consecuencia, se efectúa el cobro de las penalizaciones correspondientes a las reservaciones efectuadas durante el día. La ruta responde con el estado ``200 OK`` acompañado de la información de las penalizaciones cobradas del día operativo. De ocurrir un error de comunicación con el WS de Cinemex para procesar las penalizaciones, se responde con el estado ``503 Service Unavailable``. La cancelación de las reservaciones es notificada a los clientes Assistant como en :ref:`broadcast-delete-reservation`. Gestión de zonas arquitectónicas -------------------------------- Una zona arquitectónica corresponde a una sección física de la sucursal, a la cual pertenecen estaciones. A continuación se describen las operaciones permitidas para el manejo de zonas. Crear zona arquitectónica ######################### A continuación de describe el proceso de creación de zona. Flujo ^^^^^ Onsite: ``POST /zones`` *********************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se crea una zona física en la sucursal. El cuerpo de la petición es el siguiente .. code-block:: yaml name: Hexágono Al recibir esta petición, se da de alta la zona con el nombre proporcionado y se responde con el estado ``201 Created``. Si ya existe una zona con el nombre proporcionado, se responde con el estado ``409 Conflict``. Si el nombre de la zona es de longitud menor a 4 o mayor a 30, se responde con el estado ``422 Unprocessable Entity``. Visualizar lista de zonas ######################### El proceso de obtención de las zonas de un local se lleva a cabo como se describe a continuación. Flujo ^^^^^ Onsite: ``GET /zones`` ********************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se solicitan las zonas existentes en el local al servidor Onsite. Esta ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml - id: 1 name: Hexágono - id: 2 name: Panal Eliminar zona arquitectónica ############################ El borrado de una zona arquitectónica se lleva a cabo como se indica a continuación. Flujo ^^^^^ Onsite: ``DELETE /zones/{id}`` ****************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se elimina el registro de la zona referenciada por el parámetro ``id``. Al borrarse la zona, todas las estaciones que pertenezcan a ella se mantienen. El borrado de la zona es *hard delete*. La ruta responde con el estado ``200 OK`` acompañado de la zona recién eliminada. Si la zona a eliminar no se encuentra, se responde con el estado ``404 Not Found``. Gestión de categorías --------------------- .. _consulta-categorias: Consulta de categorías ###################### La consulta de categorías registradas en una sucursal se lleva a cabo como se indica en el siguiente flujo. Flujo ^^^^^ Onsite: ``GET /categories`` *************************** **Autorización:** User (*super*, *onsite*), Kiosk La ruta responde con el estado ``200 OK`` acompañado de las categorías del local como se indica a continuación. .. code-block:: yaml - id: 1 name: Playground isPcOnly: false createdAt: 1469491719 updatedAt: 1469491719 systems: - id: 1 name: PS4 createdAt: 1469491719 updatedAt: 1469491719 - id: 2 name: XBOX createdAt: 1469491719 updatedAt: 1469491719 - id: 3 name: WiiU createdAt: 1469491719 updatedAt: 1469491719 - id: 2 name: Retro Room isPcOnly: false createdAt: 1469491719 updatedAt: 1469491719 systems: - id: 1 name: PS4 createdAt: 1469491719 updatedAt: 1469491719 - id: 2 name: XBOX createdAt: 1469491719 updatedAt: 1469491719 - id: 3 name: WiiU createdAt: 1469491719 updatedAt: 1469491719 - id: 5 name: SEGA createdAt: 1469491719 updatedAt: 1469491719 - id: 3 name: Platinum Room isPcOnly: false createdAt: 1469491719 updatedAt: 1469491719 systems: - id: 1 name: PS4 createdAt: 1469491719 updatedAt: 1469491719 - id: 2 name: XBOX createdAt: 1469491719 updatedAt: 1469491719 - id: 3 name: WiiU createdAt: 1469491719 updatedAt: 1469491719 - id: 4 name: Versus Zone isPcOnly: true createdAt: 1469491719 updatedAt: 1469491719 systems: - id: 4 name: PC createdAt: 1469491719 updatedAt: 1469491719 Gestión de estaciones --------------------- En este partado se define el comportamiento para las operaciones que interactúan con las estaciones del local. Las operaciones abarcan creación, edición, modificación, y borrado. Agregar nueva estación ###################### Flujo ^^^^^ .. image:: /images/user/station/station_creation_sequence.svg :align: center Onsite: ``POST /stations`` ************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se solicita al servidor la creación de una estación en la sucursal. El cuerpo de la petición es el siguiente: .. code-block:: yaml name: 18 screen: Pantalla 2 seats: 2 categoryId: 2 systemIds: - 2 - 4 zoneId: 3 observations: El cable tiene falso ``name`` Nombre de la estación. ``screen`` Nombre de pantalla perteneciente a la estación. Si no es proporcionado este campo, se asume que la estación está en uso por una PC. ``seats`` Capacidad de asientos de la estación. ``categoryId`` Identificador de la categoría a la que pertenece la estación. ``systemIds`` Arreglo con los identificadores de las consolas con las que contará la estación. Dichos identificadores son obtenidos de la consulta indicada en :ref:`consulta-categorias`. ``zoneId`` Identificador de la zona arquitectónica a la que pertenece la estación. ``observations`` Comentarios en particular sobre la estación a registrar. Al recibir la petición, se registra localmente la nueva estación con las consolas proporcionadas, para posteriormente crear la misma estación en el Scheduler como se indica en :ref:`crear-estacion-scheduler`. Si falla el registro de la estación en el calendarizador, la estación local también debe eliminarse. La ruta responde con el estado ``201 Created`` acompañado de la estación recién creada. Si no es proporcionada ninguna consola para la creación de la estación, se reponde con el estado ``400 Bad Request``. Se responde con el estado ``422 Unprocessable Entity`` en cualquiera de los siguientes casos: - El campo de observaciones tiene longitud mayor a 255 caracteres. - Si se proporciona un número de asientos mayor a uno para una PC. - Si la categoría es exclusiva de PCs y es proporcionada una estación con pantalla asociada. - Si la categoría no contiene PCs y se proporciona una estación sin pantalla. - El número de asientos es mayor a 8. Si la zona o la categoría para vincular una estación no existen, o si alguna de las consolas proporcionadas no se encuentra, se responde con el estado ``404 Not Found``. Se responde con el estado ``409 Conflict`` bajo cualquiera de los siguientes escenarios: - Ya existe otra estación con el mismo valor para ``name``. - Ya existe otra estación con el mismo valor para ``screen``. - Alguna de las consolas proporcionadas no es permitida para la categoría. Si no es posible crear la estación en el servicio de calendarización, se responde con el estado ``503 Service Unavailable``. El enlazamiento del Timer se lleva a cabo como se indica en :ref:`alta-dispositivo`. Visualizar lista de estaciones ############################## A continuación se describe la manera de obtener el listado de estaciones dadas de alta en la sucursal. Flujo ^^^^^ La consulta de la información de una estación, así como de la partida que se juega actualmente, se puede consultar como se indica en :ref:`consulta-station-match`. Liberar una estación #################### Una estación ocupada por un grupo de jugadores puede ser liberada de manera forzosa. El comportamiento de esta función se indica a continuación. Flujo ^^^^^ Onsite: ``PUT /stations/standby_status`` **************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta, un usuario solicita al servidor Onsite liberar de manera forzosa una estación. El cuerpo de la petición es el siguiente .. code-block:: yaml name: Estacion 23 Al recibir la petición, se cierra el Match activo de la estación, en caso de existir, trasladando a los jugadores al pool de Check Ins. Posteriormente, se realiza el cambio de señal en la estación a *señal digital*. El cambio en la señal se realiza también si la estación no cuenta con una partida activa. La ruta responde con el estado ``200 OK`` si la solicitud de liberación de estación fue procesada correctamente. Si la estación no se encuentra, se responde con el estado ``404 Not Found``. Editar información de estación ############################## A continuación se describe el proceso para editar la información de una estación. Flujo ^^^^^ .. image:: /images/user/station/station_update_sequence.svg :align: center Onsite: ``PUT /stations/{id}`` ****************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se edita la información de la estación referenciada en el parámetro ``id``. El cuerpo de la petición es el siguiente: .. code-block:: yaml name: 3 screen: 7 categoryId: 2 systemIds: - 7 - 1 - 3 zoneId: 2 observations: Ya no se apaga Al recibir la petición, se actualiza la estación en el Scheduler como se indica en :ref:`actualizar-estacion-scheduler`. Si falla el cambio de la estación en el calendarizador, la estación local tampoco debe actualizarse. La ruta responde con el estado ``200 OK`` acompañado de la información actualizada de la estación. Si no es proporcionada ninguna consola para la creación de la estación, se reponde con el estado ``400 Bad Request``. Si la estación se encuentra en uso, es decir, cuenta con Match activo o se está jugando un torneo, se responde con el estado ``403 Forbidden``. Si no se encuentra la estación a actualizar o alguna de las consolas, se responde con el estado ``404 Not Found``. Se responde con el estado ``422 Unprocessable Entity`` en cualquiera de los siguientes casos: - El campo de observaciones tiene longitud mayor a 255 caracteres. - Si se hace el cambio en categoría de una estación, y la nueva categoría no cuenta con alguno de los *System* que posee la estación. Se responde con el estado ``409 Conflict`` bajo cualquiera de los siguientes escenarios: - Ya existe otra estación con el mismo valor para ``name``. - Ya existe otra estación con el mismo valor para ``screen``. - Se intenta asignar una pantalla a una estación que carecía de ésta. - Alguna de las consolas proporcionadas no es permitida para la categoría. Si no es posible actualizar la estación en el servicio de calendarización, se responde con el estado ``503 Service Unavailable``. .. _eliminar-estacion: Eliminar estación ################# A continuación se indica el proceso para remover una estación del local Arena. Flujo ^^^^^ .. image:: /images/user/station/station_delete_sequence.svg :align: center Onsite: ``DELETE /stations/{id}`` ********************************* **Autorización:** User (*super*, *onsite*) Mediante esta ruta se solicita la remoción de una estación de la lista registrada del local. La estación a borrar es referenciada por el parámetro ``id``, y el tipo de borrado es *hard delete*. Al momento de recibir la petición, debe solicitarse la eliminación en el servidor Offsite como se indica en :ref:`eliminar-timer-offsite`. Si el borrado es exitoso, se elimina la estación, el Timer vinculado a esta, y el Access Key correspondiente al Timer. En caso de no contar con un Timer asociado, la estación igualmente es eliminada. De manera adicional, se elimina la estación en el Scheduler como se indica en :ref:`eliminar-estacion-scheduler`. Si falla el borrado de la estación en el calendarizador, la estación local tampoco debe eliminarse. La ruta responde con el estado ``200 OK`` acompañado de la estación recién eliminada. Si la estación a eliminar no se encuentra, se responde con el estado ``404 Not Found``. Si el Timer asociado a la estación no pudo ser removido en el servidor Offsite o si la estación no pudo ser removida en el calendarizador, se anula la operación y se responde con el estado ``503 Service Unavailable``. Gestión de usuarios asistentes ------------------------------ Un usuario asistente corresponde al personal en cada sucursal encargado de brindar asistencia y servicio a los jugadores. A continuación se describe el proceso llevado a cabo por un usuario para administrar cuentas de asistente. Dar de alta un asistente ######################## El proceso de creación de un asistente es descrito en el apartado :ref:`crear-asistente`. Visualizar asistentes ##################### A continuación se describe el comportamiento llevado a cabo por un usuario para obtener la lista de asistentes del local. Flujo ^^^^^ Offsite: ``GET /assistants`` **************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene el listado de asistentes registrados. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - id: 1 username: ElChico email: juanmanuel@domain.com profile: name: Juan Manuel lastName: Ochoa Reyes phone: 5367874635 position: staff createdAt: 1469491719 updatedAt: 1469491719 - id: 2 username: lalalan email: carlota@domain.com profile: name: Carlota lastName: Piña phone: 5502093648 position: Supervisor createdAt: 1469491672 updatedAt: 1469491672 Editar asistente ################ A continuación se describe el proceso para editar la información permitida de un asistente. Dado que la información de perfil es almacenada únicamente por el servidor Onsite al cual pertenece el personal, no es necesario reportar la edición con el servidor Offsite. Flujo ^^^^^ .. image:: /images/authentication/assistant_update_sequence.svg :align: center Offsite: ``PUT /assistants/{id}`` ********************************* **Autorización:** User (*super*, *onsite*) A través de esta ruta se editan los datos personales de un asistente. El cuerpo de la petición es el siguiente: .. code-block:: yaml phone: 5467879374 Donde cualquier otro campo proporcionado en la petición es ignorado. La ruta responde con el estado ``200 OK`` acompañado del recurso actualizado. Si el asistente a editar no se encuentra, se responde con el estado ``404 Not Found``. Se responde con el estado ``422 Unprocessable Entity`` si el teléfono presenta algún caracter no numérico, o la longitud es mayor a 13 dígitos. Eliminar asistente ################## El proceso de eliminar un asistente, tanto de la sucursal como del registro global en Offsite, se resuelve como se indica en :ref:`borrar-asistente`. Gestión de Kiosk ---------------- A continuación se describen las posibles acciones que tiene un usuario de un local sobre los quioscos de la sucursal. Validar quiosco ############### El proceso de creación de un Kiosk, el cual abarca su validación, es descrito en :ref:`alta-dispositivo`. Visualizar lista de quioscos ############################ La visualización de los clientes Kiosk de la sucursal se lleva a cabo como se indica en la sección :ref:`ver-quioscos`. Eliminar (o rechazar vinculación de) quiosco ############################################ El borrado de un quiosco, lo cual niega las peticiones subsecuentes que provengan de este, se logra como se describe en la sección :ref:`baja-dispositivo`. Esta funcionalidad también se extiende al rechazo en la validación de aceptación de un quiosco. Gestión de Timer ---------------- A continuación se describen las posibles acciones que tiene un usuario de un local sobre los temporizadores de la sucursal. Enlazado de timer a estación ############################ Un Timer solicita registrarse como tal y unirse a una estación **existente** como se indica en :ref:`alta-dispositivo`. Dado que un Timer es débil con respecto a una estación (depende de la existencia de ésta), se requiere como prerrequisito de la operación la presencia una entidad *Station* a la cual vincularse. Validar timer ############# La autorización de vinculación de un Timer a una estación se lleva a cabo como se indica en :ref:`autorizar-timer`. Visualizar lista de timers ########################## La visualización de los clientes Timer de la sucursal se lleva a cabo como se indica en :ref:`ver-timers`. Rechazar vinculación de timer ############################# La negación de vinculación (y autorización) de un Timer hacia una estación se logra invocando a la ruta :ref:`borrar-timer`. Esta operación no es permitida si el dispositivo ya ha sido aceptado como perteneciente a una estación. Eliminar Timer ############## Dada la dependencia de una entidad Timer hacia una estación, es necesario eliminar la entidad *Station* a la que pertenece el dispositivo. Como consecuencia del borrado de una estación, se eliminará el Timer perteneciente a ésta. El borrado de una estación de define en :ref:`eliminar-estacion`. Gestión de juegos ----------------- Una función de los usuarios de un local es la gestión de los juegos disponibles en la sucursal. A continuación de indican las funciones a realizar sobre el catálogo de juegos. Crear juego ########### El proceso de creación de un juego en el local se describe a continuación Flujo ^^^^^ Onsite: ``POST /games`` *********************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se crea el registro de un juego en la sucursal. El cuerpo de la petición será de tipo ``multipart/form-data`` y contendrá los siguientes valores =========== ================================================== Campo Contenido =========== ================================================== name | Nombre del juego. Obligatorio. maxPlayers | Número máximo de jugadores permitidos para | el juego. esrb | Clasificación del juego. description | Descripción del juego. tagIds | Arreglo con los ids de los tags del juego. cover | Imagen correspondiente a la carátuta del juego. | Obligatorio. highlight | Imagen de destacado. Obligatorio screenshotX | Captura de pantalla del juego, donde X en [0, 2] | corresponde al número de captura que se | carga. El máximo permitido de capturas de | pantalla a subir es 3. En caso de ser | proporcionadas más capturas, estas serán | ignoradas. Ninguna de estas imágenes es | requerida. =========== ================================================== Como consecuencia de la recepción de la petición, se registrará el nuevo juego en la sucursal y posteriormente se cargará cada una de las imágenes proporcionadas en el contenedor externo. La carga se lleva a cabo de manera similar a como se describe en :ref:`carga-imagen`. Si la carga de una o más imágenes de juegos falla, la creación del registro de un *Game* no es anulada. La ruta responde con el estado ``201 Created`` acompañado del juego recién creado. Si el nombre del juego no es único, se responde con el estado ``409 Conflict``. Si alguna de las etiquetas proporcionadas para el juego no existe, se responde con ``404 Not Found``. Se responde con el estado ``422 Unprocessable Entity`` bajo cualquiera de los siguientes casos: - El nombre del juego es de longitud mayor a 60 caracteres. - Los campos de texto restantes tienen una longitud mayor a 255 caracteres. - El número de jugadores no está en el rango [1, 4]. - La clasificación ESRB del juego no es una de entre *C, E, E10, T, M, A, RP*. - La extensión de la imagen no es ``.jpg`` ni ``.png``. - La dimensión de alguna de las imágenes excede los 500 kb. .. note:: Onsite definirá el nombre de cada archivo de imagen siguiendo la convención ``UUUUUUUUUU_AAAAA.jpg``, donde *UUUUUUUUUU* corresponde a la fecha UNIX en segundos y *AAAAA* es una cadena alfanumérica aleatoria. Editar juego ############ La edición de la información de un juego comprende las imágenes vinculadas a este. A continuación se describe el proceso llevado a cabo por un usuario para cambiar las imágenes de un juego. Flujo ^^^^^ Onsite: ``PUT /games/{id}`` *************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se editan las imágenes de un juego, ya sea de portada, de destacado, o sus capturas de pantalla. La petición, con tipo de contenido ``multipart/form-data`` recibe uno o más de entre los siguientes campos =========== ================================================== Campo Contenido =========== ================================================== tagIds | Arreglo con los ids de los tags del juego. cover | Imagen correspondiente a la carátuta del juego. | Si esta imagen es proporcionada, se elimina | la versión anterior de la imagen alojada en el | proveedor de almacenamiento. description | Descripción del juego. highlight | Imagen de destacado. | Si esta imagen es proporcionada, se elimina | la versión anterior de la imagen alojada en el | proveedor de almacenamiento. screenshotX | Captura de pantalla del juego, donde X en [0, 2] | corresponde al número de captura que se | carga. El máximo permitido de capturas de | pantalla a subir es 3. En caso de ser | proporcionadas más capturas, estas serán | ignoradas. | Si se proporciona al menos una nueva imagen | de las tres permitidas, toda captura que | exista registrada para el juego debe ser | eliminada; por lo que los nuevos *screenshots* | del juego serán aquellos proporcionados en | la petición. =========== ================================================== Al proporcionar nuevas etiquetas para el juego, se eliminarán las anteriores y se actualizará el *Game* únicamente con los registros proporcionados. La ruta responde con el estado ``200 OK`` acompañado del juego actualizado. Si alguna de las etiquetas no existe, se responde con el estado ``404 Not Found`` y se cancela la actualización de etiquetas. Si la dimensión de alguna de las imágenes excede los 500 kb, se responde con el estado ``422 Unprocessable Entity``. .. note:: Los registros de las imágenes descartadas del juego deben ser eliminados del servidor Onsite. Visualizar listado de juegos ############################ La visualización de los juegos en el local, así como su información por consola, se logra invocando a la ruta descrita a continuación. Flujo ^^^^^ Onsite: ``GET /games`` ********************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene el listado de juegos en la sucursal. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información. .. code-block:: yaml - id: 1 name: Fifa 17 maxPlayers: 4 esrb: M description: Fútbol y más fútbol cover: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475281865163-0.9304038190748543 highlight: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475281865163-0.9304038190748543 screenshots: - https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475281865163-0.9304038190748543 - https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475281865163-0.9304038190748543 tags: - id: 2 name: Fútbol - id: 23 name: Multijugador gameSystems: - id: 23 isHighlight: false isOnHardDrive: true pathToLauncher: C:/Users/Arena/Games/Dota/launcher.exe system: - id: 2 name: PC createdAt: 1469491719 updatedAt: 1469491719 - id: 52 isHighlight: true isOnHardDrive: false system: - id: 1 name: PS4 createdAt: 1469491719 updatedAt: 1469491719 createdAt: 1469491719 updatedAt: 1469491719 Se tienen los siguientes parámetros de búsqueda reconocidos para la consulta: ====== ====================================================== Nombre Comportamiento ====== ====================================================== name Devuelve un arreglo de juegos cuyo nombre contenga como subcadena a ``name`` system Devuelve aquellos juegos que cuenten con el gameSystem cuyo nombre de consola coincida con ``system`` ====== ====================================================== Eliminar juego ############## El proceso de eliminar la información general de un juego se define a continuación. Este proces elimina también los registros de compatibiliada para consolas. Flujo ^^^^^ Onsite: ``DELETE /games/{id}`` ****************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se elimina (*soft delete*) la información existente de un juego de la sucursal. Al recibir la petición, se confirma que ninguno de los ``Game System`` vinculados al juego esté en uso por alguna estación. De confirmarse la validación, se eliminan tanto el ``Game`` como todos los ``Game System`` vinculados a éste. Las imágenes asociadas al juego, tanto carátula como capturas e imágenes destacadas, son eliminadas con el proveedor de almacenamiento. Si el proceso es exitoso, la ruta responde con el estado ``200 OK`` acompañado del juego recién eliminado. Si el identificador proporcionado no hace referencia a ninguna entidad existente, se responde con el estado ``404 Not Found``. Si el juego cuenta con algún ``Game System`` que esté siendo usado por al menos una estación, se responde con el estado ``409 Conflict``. Si el eliminado de imágenes de un juego falla con el proveedor de almacenamiento, de igual manera debe ser eliminado el registro ``Game`` del sistema. Consulta de etiquetas ##################### Para la creación de juego pueden proporcionarse una o más etiquetas, esto con el objetivo de agrupar los juegos. En el siguiente flujo se indica el proceso para consulta de etiquetas. Flujo ^^^^^ Onsite: ``GET /tags`` ********************* **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtienen las categorías registradas. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - id: 1 name: Oldies - id: 2 name: Peleas - id: 3 name: Disparos - id: 4 name: Multiplataforma Creación de etiqueta #################### La creación de nuevas etiquetas se describe en el siguiente flujo. Flujo ^^^^^ Onsite: ``POST /tags`` ********************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se crea una etiqueta en el registro de la sucursal. El cuerpo de la petición es el siguiente .. code-block:: yaml name: Multijugador La ruta responde con el estado ``201 Created`` acompañado de la etiqueta recién creada. Si ya existe registro de una etiqueta con el nombre que se proporcionó, se responde con el estado ``409 Conflict``. Si el nombre de la etiqueta excede los 15 caracteres de longitud o si se encuentra por debajo de los 3 caracteres, o si se usa un caracter no alfanumérico o un caracter de espacio, se responde con el estado ``422 Unprocessable Entity``. Consulta de consolas #################### Es necesario otorgar al usuario la facultad de consultar los tipos de consola de la sucursal; esto con el fin de vincular juegos a estas. El proceso de consulta se indica a continuación. Flujo ^^^^^ Onsite: ``GET /systems`` ************************ **Autorización:** User (*super*, *onsite*) Mediante esta ruta se consultan las consolas existentes en la sucursal. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml - id: 1 name: PC - id: 2 name: XBOX - id: 3 name: PS4 Vincular juego a consola ######################## La creación de un juego no basta para que este pueda ser usado en una partida. Adicional al registro del juego, es necesario habilitarlo para una consola en particular, lo que marca la compatibilidad de un juego con una consola. El comportamiento es descrito a continuación. Flujo ^^^^^ .. _patch-gamesystems: Onsite: ``PATCH /games/{id}/game_systems`` ****************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se llevan a cabo modificaciones sobre los valores de los juegos en consolas vinculados a cierto ``Game``. El cuerpo de la petición es el siguiente: .. code-block:: yaml - op: 'replace' path: 1 value: pathToLauncher: 'C:\\another\\route.exe' - op: 'remove' path: 2 - op: 'add' path: 3 value: stock: 20 isOnHardDrive: false isHighlight: false ``path`` Identificador de la consola con la que se marcará compatibilidad. ``value.stock`` En caso de no ser PC la consola, este campo corresponde con la cantidad de copias disponibles del juego. ``value.pathToLauncher`` En caso de ser PC, indica la ruta donde el ejecutable del juego debe encontrarse en los clientes. ``value.isOnHardDrive`` Indica si el juego se encuentra almacenado en el disco duro de la consola. ``value.isHighlight`` Indica si el juego debe mostrarse a los clientes como destacado. En consecuencia, se actualiza la información existente sobre los ``Game System`` vinculados con únicamente la informaciónn proporcionada. La ruta responde con el estado ``200 OK`` acompañado de los registros actualmente asociados con el juego. Si alguna de las consola no se encuentra se responde con el estado ``404 Not Found``. Si ya existe un Game System con la misma consola para el mismo juego, si se duplica información para una consola, o si el juego está siendo usado por al menos una estación, se responde con el estado ``409 Conflict``. Se responde con el estado ``422 Unprocessable Entity`` si se proporciona ruta al ejecutable de un juego que no se vincula con una PC, o si le es proporcionado stock. En caso de ocurrir error en el procesamiento de alguno de los elementos, debe anularse la operación completa. Editar juego para consola ######################### El registro de compatibilidad entre un juego y una consola es editado como se indica en la ruta :ref:`patch-gamesystems`. Eliminar juego para consola ########################### La acción de desvincular una consola y un juego compatible se da como se indica en :ref:`patch-gamesystems`. Gestión de aplicaciones ----------------------- Las consolas PC pueden ejecutar aplicaciones cuyo uso pueda ser combinado con la ejecución de un juego. A continuación se describe el flujo para dar de alta una nueva aplicación, así como sus comportamientos de consulta, edición y borrado. Crear aplicación ################ A continuación se describe el proceso llevado a cabo por un administrador para dar de alta una aplicación de PC. Flujo ^^^^^ Onsite: ``POST /applications`` ****************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se lleva a cabo el registro de una nueva aplicación a ser usada por consolas PC. El cuerpo de la petición es el siguiente: .. code-block:: yaml name: Chrome pathToLauncher: C:/Users/Arena/Apps/Chrome/launcher.exe pathToIcon: C:/Users/Arena/Apps/Chrome/imgs/icon.png Como acción a la recepción de la petición, se registra la nueva aplicación con los valores proporcionados, para posteriormente responder con el estado ``201 Created``. Si ya existe una aplicación con el nombre o la ruta proporcionados, se responde con el estado ``409 Conflict``. Visualizar aplicaciones ####################### Flujo ^^^^^ Onsite: ``GET /applications`` ***************************** **Autorización:** User (*super*, *onsite*), Timer Mediante esta ruta son consultadas las aplicaciones que pueden ser usadas en la estación. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - id: 1 name: Chrome pathToLauncher: C:/Users/Arena/Apps/Chrome/launcher.exe pathToIcon: C:/Users/Arena/Apps/Chrome/imgs/icon.png createdAt: 1469491719 updatedAt: 1469491345 - id: 2 name: Razr Synapse pathToLauncher: C:/Users/Arena/Apps/Razr/Synapse/launcher.exe pathToIcon: C:/Users/Arena/Apps/Razr/Synapse/imgs/icon.png createdAt: 1469491719 updatedAt: 1469491345 Editar aplicación ################# A continuación se define la ruta de la cual hace uso un administrador para editar la información asociada a una aplicación de PC. Flujo ^^^^^ Onsite: ``PUT /applications/{id}`` ********************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se lleva a cabo la actualización de los valores de una aplicación. El cuerpo de la petición es el siguiente: .. code-block:: yaml name: Chrome pathToLauncher: C:/Users/Arena/Apps/Chrome/launcher.exe pathToIcon: C:/Users/Arena/Apps/Chrome/imgs/icon.png Como acción a la recepción de la petición, se actualizan los campos proporcionados, para responder con el estado ``200 OK``. Si la aplicación no pudo ser encontrada, se responde con el estado ``404 Not Found``. Si ya existe una aplicación con el nombre o la ruta proporcionados, se responde con el estado ``409 Conflict``. Eliminar aplicación ################### Flujo ^^^^^ Onsite: ``DELETE /applications/{id}`` ************************************* **Autorización:** User (*super*, *onsite*) Mediante esta ruta se lleva a cabo un *hard delete* de la aplicación referenciada por su identificador. La ruta responde con el estado ``200 OK`` acompañado del registro de la aplicación recién eliminada. Si la aplicación no pudo ser encontrada, se responde con el estado ``404 Not Found``. Generación de reportes ---------------------- Es una funcionalidad de un servidor Onsite la generación de reportes sobre la operación de la sucursal en un período de tiempo dado por el usuario que lo requiere. A continuación, se definen los reportes que el servidor es capaz de generar, así como la entrada y salida esperada de los mismos. Redenciones de productos de tiempo ################################## Flujo ^^^^^ Onsite: ``GET /statistics/time_purchases`` ****************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene el reporte de productos de tiempo adquiridos en la sucursal durante el intervalo de tiempo proporcionado. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - timeProduct: 3 horas station: TV023 category: Platinum Room purchasedAt: 21-11-2017 14:25:28 - timeProduct: 1 día station: PC004 category: Versus Zone purchasedAt: 21-11-2017 10:49:31 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. .. hint:: Para devolver este reporte, se incluyen también las compras de productos de tiempo para partidas grupales. Horarios de mayor consumo ######################### Flujo ^^^^^ Onsite: ``GET /statistics/purchase_count`` ****************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene un desglose por hora del día sobre el número de compras de productos de tiempo llevadas a cabo en la sucursal en el intervalo de tiempo proporcionado. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== Al recibir la petición, se contabiliza por intervalos de una hora, desde la fecha de apertura hasta la fecha de cierre de la sucursal, el número de compras de productos de tiempo llevadas a cabo en el intervalo de fecha proporcionado en la petición. Se incluyen también las compras de productos de tiempo correspondientes a partidas grupales. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - interval: 10:00 - 11:00 usageCount: 23 - interval: 11:00 - 12:00 usageCount: 0 - interval: 12:00 - 13:00 usageCount: 4 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Estación más jugada ################### Flujo ^^^^^ Onsite: ``GET /statistics/top_stations`` **************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se solicita un reporte del número de usos por estación en la sucursal, dentro del intervalo de tiempo proporcionado. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== Como acción a la recepción de la petición, se contabiliza el número de partidas jugadas en cada una de las estaciones, incluyendo también partidas grupales. La ruta responde con el estado ``200 OK`` acompañado de la siguiente estructura: .. code-block:: yaml - station: PC001 usageCount: 3 - station: TV052 usageCount: 10 - station: TV055 usageCount: 8 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Tiempo extra más requerido ########################## Flujo ^^^^^ Onsite: ``GET /statistics/extra_time_purchases`` ************************************************ **Autorización:** User (*super*, *onsite*) Mediante esta ruta se consultan los *Time Product* más solicitados al momento de renovar tiempo en la sucursal dentro del intervalo de tiempo proporcionado. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== Para servir esta petición, se llevan a cabo los siguientes pasos: 1. Obtener los Check Ins creados dentro del intervalo de tiempo proporcionado. 2. Para cada Check In, obtener las compras de productos de tiempo del segundo al último, los cuales corresponden a solicitudes de tiempo adicional. 3. Agrupar los registros por producto de tiempo y contarlos. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - timeProduct: 1 día category: Versus Zone usageCount: 8 - timeProduct: 3 horas category: Next Level Zone usageCount: 8 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Juegos más solicitados ###################### Flujo ^^^^^ Onsite: ``GET /statistics/top_game_systems`` ******************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtienen los juegos más usados en la sucursal dentro del intervalo de tiempo proporcionado. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== Para servir esta petición, se consultan los Match creados dentro del intervalo de tiempo, se obtienen sus Game System asociados, se agrupan y se contabilizan. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - name: Super Smash Bros system: WiiU usageCount: 67 - name: Mortal Kombat X system: XBOX usageCount: 20 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Categorías más jugadas ###################### Flujo ^^^^^ Onsite: ``GET /statistics/top_categories`` ****************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtienen las categorías de producto de tiempo más usadas dentro de la sucursal en el intervalo de tiempo proporcionado. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== Para servir esta petición, se obtienen los Match y Match Groups creados dentro del intervalo de tiempo proporcionado, para posteriormente obtener las categorías de las estaciones donde las partidas fueron jugadas. Estos registros son agrupados y contabilizados por categoría. La ruta responde con el estado ``200 OK`` acompañado la siguiente información: .. code-block:: yaml - category: Next Level Zone usageCount: 202 - category: Platinum Room usageCount: 156 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Producto de tiempo más contratado ################################# Flujo ^^^^^ Onsite: ``GET /statistics/top_time_purchases`` ********************************************** **Autorización:** User (*super*, *onsite*) A través de esta ruta son obtenidos los productos de tiempo más contratados en la sucursal dentro del período proporcionado por el usuario. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== Al recibir la petición se contabilizan todos los productos de tiempo adquiridos dentro de las fechas proporcionadas en la consulta. Esta consulta incluye los productos de tiempo adquiridos para partidas grupales. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - timeProduct: 2 horas category: Next Level Zone usageCount: 89 - timeProduct: 1 día category: Platinum Room usageCount: 13 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Consolas más usadas ################### Flujo ^^^^^ Onsite: ``GET /statistics/top_systems`` *************************************** **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene el reporte de las consolas más usadas dentro del período de tiempo proporcionado. Se tienen los siguientes parámetros de consulta: ====== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ====== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ====== ============ ======================================== ============== Al recibir la petición, se toman las partidas creadas dentro de la ventana de tiempo proporcionada. Posteriormente, se toman las consolas compatibles con los juegos creados en dichas partidas y se agrupan. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - system: XBOX usageCount: 89 - system: PS4 usageCount: 13 - system: WiiU usageCount: 13 - system: Atari usageCount: 23 - system: Sega usageCount: 79 Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Juegos usados ############# Flujo ^^^^^ Onsite: ``GET /statistics/games/by_system`` ******************************************* **Autorización:** User (*super*, *onsite*) Mediante esta ruta se obtiene el reporte de juegos usados en la sucursal, así como la información de los asistentes que operaron con los ejemplares de los juegos. Se tienen los siguientes parámetros de consulta: ======== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ======== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). gameId Integer | Identificador del ``Game`` para el 34 cual se desean obtener coincidencias. systemId Integer | Identificador de la consola con la 2 cual deben ser compatibles los | registros. ======== ============ ======================================== ============== Al recibir la petición, se obtienen los ``GameSystem`` usados dentro de la fecha proporcionada, para posteriormente filtrar por juego y y consola compatibles. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - id: 2 system: id: 3 name: PS4 stock: 37 availableCopies: 3 operations: - stationName: TV002 assignedAt: 1479867892 assignedBy: Lorena removedAt: 1479867990 removedBy: Shoshana - stationName: TV018 assignedAt: 1479889093 assignedBy: Lorena removedAt: 1479894728 removedBy: Shoshana ``id`` Identificador del Game System. ``system.id`` Identificador de la consola con la cual es compatible la copia del juego. ``system.name`` Nombre de la consola con la cual es compatible la copia del juego. ``stock`` Copias en existencia del juego. ``available_copies`` Copias disponibles del juego, es decir, aquellas que no están en uso al momento de la petición. ``operations`` Listado de operaciones efectuadas sobre las copias de los juegos dentro del rango de tiempo proporcionado. ``operations[].stationName`` Nombre de la estación en la que fue asignado el ejemplar del juego. ``operations[].assignedAt`` Fecha en que el juego fue asignado a la estación indicada. ``operations[].assignedBy`` Nombre del asistente que asignó la copia del juego a la estación. ``operations[].removedAt`` Fecha en que el ejemplar del juego fue removido de la estación. ``operations[].removedBy`` Nombre del asistente que retiró la copia del juego de la estación. Únicamente disponible en caso de transacciones de cambio de mesa o cambio de juego. Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un mes, o si el día en la fecha ``to`` es mayor al día actual, se responde con el estado ``400 Bad Request``. Eventos ####### Flujo ^^^^^ Onsite: ``GET /statistics/group_matches`` ***************************************** **Autorización:** User (*super*, *onsite*) Obtiene el listado de partidas grupales llevadas a cabo en el intervalo de tiempo proporcionado. ======== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ======== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ======== ============ ======================================== ============== Se obtienen los registros de partidas grupales creadas en el rango de fecha proporcionado. Se contabilizan y se responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - date: 17-02-2018 playerGroupMatches: count: 1 breakdown: - createdAt: 1479867891 minutes: 60 numberOfPlayers: 5 categories: - Next Level Zone - Versus Zone guestGroupMatches: count: 1 breakdown: - createdAt: 1479867888 minutes: 180 numberOfPlayers: 7 categories: - Versus Zone - Retro Room ``date`` Fecha para la cual existe registro de al menos un evento en la sucursal. ``[player | guest]GroupMatches`` Partidas grupales donde el anfitrión es un jugador / invitado. ``[player | guest]GroupMatches.count`` Número de sesiones grupales contabilizadas durante el día. ``[player | guest]GroupMatches.breakdown[].createdAt`` Fecha de creación de la partida. ``[player | guest]GroupMatches.breakdown[].minutes`` Cantidad de minutos que tomó la partida grupal. ``[player | guest]GroupMatches.breakdown[].numberOfPlayers`` Número de jugadores, contando al anfitrión, que jugaron en el evento. ``[player | guest]GroupMatches.breakdown[].categories[]`` Nombres de las categorías empleadas en el evento. Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Offsite: ``GET /statistics/coin_expirations`` ********************************************* **Autorización:** User (*super*) Obtiene la información de aquellos jugadores cuyo balance en monedas expiró por falta de uso. ======== ============ ======================================== ============== Nombre Tipo Descripción Ejemplo ======== ============ ======================================== ============== from * Integer | Fecha a partir de la cual debe 1479862013 devolverse el reporte (inclusivo). to * Integer | Fecha hasta la cual debe 1479867892 devolverse el reporte (inclusivo). ======== ============ ======================================== ============== En consecuencia, se obtiene a los jugadores no invitados a quienes se les haya efectuado una transacción negativa y no reportada a Vista, siempre y cuando la transacción haya sido efectuada dentro del rango de fechas proporcionado. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información: .. code-block:: yaml - nick: aleexkj name: Alejandra lastName: Ochoa email: ale@domain.com expiredCoinAmount: 100 expiredAt: 1479867891 - nick: ratrabbit name: Francisco lastName: Díaz email: paco@domain.com expiredCoinAmount: 75 expiredAt: 1479867538 ``nick`` Nick del jugador. ``name`` Nombre del jugador. ``lastName`` Apellidos del jugador. ``email`` Dirección de correo del jugador. ``expiredCoinAmount`` Cantidad de monedas que expiraron. ``expiredAt`` Fecha de expiración del balance en ares. Si el campo ``to`` es previo a ``from``, si el intervalo de tiempo es mayor a un año, o si el día en la fecha ``to`` es mayor o igual al día actual, se responde con el estado ``400 Bad Request``. Admin torneos ============= Aquellos usuarios creados con el propósito de efectuar modificaciones sobre plantillas de torneo a efectuarse en sucursales de Arena. La propiedad de rol para este usuario es *tournament*. Gestión de atributos de plantilla --------------------------------- Al crear o modificar una plantilla, le son asociados criterios de evaluación, modo de juego, y título de juego. A continuación se indican los flujos seguidos para consulta y actualización de dichos atributos. Creación de criterios de evaluación ################################### Flujo ^^^^^ Offsite: ``POST /criteria`` *************************** **Autorización:** User (*super*, *tournament*) Mediante esta ruta se dan de alta criterios de evaluación para ser tomados en cuenta durante un torneo. El formato de la petición es el siguiente: .. code-block:: yaml name: Precisión isPercentage: false maxValue: 500 // No se incluye en criterios porcentuales indicando así que se desea contabilizar la precisión de un equipo y que la cantidad a medir es numérica. De darse de alta correctamente, Offsite responde con el estado ``201 Created`` acompañado del criterio recién creado. Si ya existe un criterio con el nombre proporcionado, se responde con el estado ``409 Conflict``. Si se intenta configurar un valor máximo para un criterio porcentual, o si dicho valor es mayor a 1000, o si el nombre del criterio es de longitud menor a 3 caracteres o mayor a 25, se responde con el estado ``422 Unprocessable Entity``. Consulta de criterios de evaluación ################################### Flujo ^^^^^ Offsite: ``GET /criteria`` ************************** **Autorización:** User (*super*, *tournament*) Mediante esta ruta se obtienen los criterios de desempate que se encuentran registrados. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml criteria: - id: 2 name: Tiros a la cabeza isPercentage: false maxValue: 100 createdAt: 1480642412 - id: 5 name: Relación de goles isPercentage: true maxValue: null createdAt: 1480645412 En caso de dar de alta nombres de juegos o de modos, se hace uso de las siguientes rutas Creación de juegos ################## Flujo ^^^^^ Offsite: ``POST /games`` ************************ **Autorización:** User (*super*, *tournament*) Mediante esta ruta es posible dar de alta nombres de juego para ser usados en las plantillas de torneo. El cuerpo de la petición es el siguiente: .. code-block:: yaml name: Fifa 2017 El sistema comprueba que no exista ningún juego con el mismo nombre que el proporcionado y procede a la creación del juego; para posteriormente responder con el estado ``201 Created``. Si ya existe un juego con el nombre que se proporcionó, se responde con el estado ``409 Conflict``. Consulta de juegos ################## Flujo ^^^^^ Offsite: ``GET /games`` *********************** **Autorización:** User (*super*, *tournament*) Mediante esta ruta se obtienen los nombres de los juegos que se encuentran registrados en el local. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml games: - id: 2 name: Fifa 2017 createdAt: 1480642412 - id: 5 name: Mortal Kombat X createdAt: 1480645412 Creación de modos de juego ########################## Flujo ^^^^^ Offsite: ``POST /modes`` ************************ **Autorización:** User (*super*, *tournament*) Mediante esta ruta es posible dar de alta modos de juego en el sistema Offsite, mismos que pueden ser usados al momento de elegir una plantilla. La petición lleva por cuerpo: .. code-block:: yaml name: 1 vs 1 El sistema comprueba que no exista ningún modo con el mismo nombre que el proporcionado y procede a la creación del modo; para posteriormente responder con el estado ``201 Created``. Si ya existe un modo con el nombre que se proporcionó, se responde con el estado ``409 Conflict``. Consulta de modos de juego ########################## Flujo ^^^^^ Offsite: ``GET /modes`` *********************** **Autorización:** User (*super*, *tournament*) Mediante esta ruta se obtienen los nombres de los modos de juego que se encuentran registrados en el local. La ruta responde con el estado ``200 OK`` acompañado de la siguiente información .. code-block:: yaml modes: - id: 2 name: 1 vs 1 createdAt: 1480642412 - id: 5 name: 2 vs 2 createdAt: 1480645412 Gestión de plantillas de torneo ------------------------------- Una plantilla de torneo contiene la información de todo torneo que deba instanciarse a partir de ésta. Al momento de crear un torneo en una sucursal, éste contará con aquella información que se haya definido para la plantilla. .. _crear-plantilla: Crear una plantilla ################### Flujo ^^^^^ Offsite: ``POST /tournament_templates`` *************************************** **Autorización:** User (*super*, *tournament*) Mediante esta ruta se da de alta la información de la plantilla de un torneo con los siguientes valores: .. code-block:: yaml name: Fifa 2017 Otoño maxPlayersPerTeam: 3 minPlayersPerTeam: 1 gameId: 3 modeId: 6 criteriaIds: - 1 - 6 - 34 - 3 Al recibir la petición, Offsite crea la plantilla y confirma la creación de la misma respondiendo con el estado ``201 Created``. Si alguno de los criterios de evaluación, el juego, o la modalidad no existen, se responde con el estado ``404 Not Found``. Si ya existe en el sistema un torneo con el nombre ``name``, la ruta responde con ``409 Conflict``. Si el número máximo de jugadores por equipo se encuentra fuera del rango [1, 4], si el mínimo de jugadores por equipo es menor a 1, si el mínimo es mayor que el máximo, o si la longitud del nombre del torneo queda fuera del intervalo ``[4, 60]``, se responde con el estado ``422 Unprocessable Entity``. .. _consultar-plantillas: Ver lista de plantillas ####################### Flujo ^^^^^ Offsite: ``GET /tournament_templates`` ************************************** **Autorización:** User (*super*, *tournament*), Location Mediante esta ruta se consultan las plantillas de torneo existentes en Offsite. La ruta responde con el estado ``200 OK`` acompañado de la información devuelta como en el siguiente esquema .. code-block:: yaml tournaments: - id: 1 name: Fifa 2017 Otoño maxPlayersPerTeam: 3 minPlayersPerTeam: 1 gameName: Fifa 2017 modeName: 1 vs 1 criteria: - id: 3 name: Precisión isPercentage: true maxValue: null - id: 5 name: Cantidad de goles isPercentage: false maxValue: 10 - id: 2 name: Apertura de Mario Kart maxPlayersPerTeam: 4 minPlayersPerTeam: 4 gameName: Mario Kart 8 modeName: Grand Prix criteria: - id: 5 name: Carreras ganadas isPercentage: false maxValue: 25 Adicionalmente, es posible hacer una búsqueda con el parámetro ``id`` para limitar la obtención de resultados a aquella plantilla de torneo cuyo identificador coincida con el proporcionado en la petición. Editar una plantilla #################### Flujo ^^^^^ Offsite: ``PUT /tournament_templates/{id}`` ******************************************* **Autorización:** User (*super*, *tournament*) Modifica la información de la plantilla indicada. Los campos admitidos en la petición son los siguientes: .. code-block:: yaml name: Fifa 2017 Otoño maxPlayersPerTeam: 3 minPlayersPerTeam: 1 gameId: 3 modeId: 6 criteriaIds: - 1 - 6 - 34 - 3 Al recibir la petición, Offsite actualiza los campos de la plantilla con aquellos que fueron proporcionados. La ruta responde con el estado ``200 OK`` acompañado de la plantilla actualizada. Si la plantilla se encuentra en uso por algún torneo, independientemente de su estado, se responde con el estado ``403 Forbidden``. Si alguno de los criterios de evaluación, el juego, o la modalidad no existen, se responde con el estado ``404 Not Found``. Si ya existe en el sistema un torneo con el nombre ``name``, la ruta responde con ``409 Conflict``. Si el número máximo de jugadores por equipo se encuentra fuera del rango [1, 4], si el mínimo de jugadores por equipo es menor a 1, si el mínimo es mayor que el máximo, o si la longitud del nombre del torneo queda fuera del intervalo ``[4, 60]``, se responde con el estado ``422 Unprocessable Entity``. Eliminar una plantilla ###################### Flujo ^^^^^ Offsite: ``DELETE /tournament_templates/{id}`` ********************************************** **Autorización:** User (*super*, *tournament*) Elimina la plantilla de torneo indicada por el identificador. La ruta responde con el estado ``200 OK`` acompañado de la plantilla recién eliminada. Si la plantilla se encuentra en uso por algún torneo, independientemente de su estado, se responde con el estado ``403 Forbidden``. Si la plantilla no se encuentra, se responde con el estado ``404 Not Found``.