Índice

Este módulo implementa la integración con el sistema Opera ‘on premise’ de las siguientes funcionalidades:

Este módulo agrega una nueva forma de pago al sistema con el nombre “(OPERA) Cargos a habitación”. Se ha agregado entre paréntesis la palabra ‘OPERA’ para distinguirlo de otra forma de pago que también se llama “cargos a habitación” y que se corresponde con la integración con ORACLE OHIP.

Este módulo requiere de la instalación adicional del ejecutable del servicio local de OPERA-GM que es quien realmente tramitará las peticiones hacia el servidor final de OPERA.

Volver arriba 👆🏼

Para poder autorizar la integración entre la empresa y el sistema a través de una API, previamente tendrás que enviar el documento cumplimentado y firmado por ambas partes a Golfmanager. Para más información, dirígete al siguiente link.

Volver arriba 👆🏼

Los pasos a seguir son los siguientes:

Volver arriba 👆🏼

Tenemos sólo dos opciones relevantes, la opción de forma de pago está en discusión si
eliminarla o no. La primera es la dirección ip del servidor de ópera. Normalmente será
​http://127.0.0.1:8081 pero puede ser cualquier dirección IP LOCAL (ojo con lo de local) que
apunte a un terminal con el servidor de Opera Local ejecutándose. El puerto de nuestro servidor local opera es el 8081.

Es OBLIGATORIO incluir el encabezado "HTTP://" o de lo contrario la conexión fallará.
La otra opción determina si enviamos los impuestos desglosados a Opera, o si enviamos
directamente los totales con impuestos incluidos.

Debemos crear un usuario API con permisos de administrador desde la sección de usuarios en la configuración y generarle una API key. Una vez generada esta clave, debemos copiarla y pegarla en el archivo de configuración más abajo descrito, en la propiedad "apiKey". Esto no es necesario en el caso de que no se vaya a utilizar la funcionalidad de envío masivo de la facturación.

El módulo extiende un nuevo campo a la tabla de subfamilias llamado "operaSubtotalGroupId" de tipo número entero. Opera permite usar hasta 16 subtotales distintos. Como ejemplo, podríamos tener las subfamilias "Restauración-Bebidas" y "Restauración-Comidas" asociada al subtotal "1" y las subfamilias "Tienda-Accesorios" y "Tienda-Textil" asociadas al subtotal "2" para que Ópera reciba los subtotales agrupados del modo que el club considere conveniente.

Volver arriba 👆🏼

Dentro del directorio de instalación del servidor local de ópera encontramos el archivo
config.json. Un ejemplo de este es:

"opera": {
"address": "127.0.0.1:5001",
"apiUrl": "http://localhost:8080/demo",
"apiKey": "4E22FwC9JGytFZF0KFP1G2HypS65YMY2ADfYbEzacQ5CQYQbkcaBJ7vQzZPujqBV",
"mockAddress": "127.0.0.1:5001",
"sendPaymentsTimer": 600,
"sequence": {
"date": "2023-10-17T16:24:48+02:00",
"value": 4
},
"startingId": 1,
"timeout": 30
}

​Address: Es la dirección IP del servidor OFICIAL de ópera al que nuestro servidor local
tramitará las peticiones finales, es decir, esta NO es la IP donde nuestro programa local está instalado.

​ApiURL: Es la URL del tenant del club al que se enviarán las peticiones automatizadas y
manuales de envío de pagos. Este tenant debe tener instalado el módulo Opera, obviamente.

​ApiKEY: La key generada del usuario API con permisos de administrador que configuramos más arriba. Sólo es necesaria en caso de que se vaya a configurar la sincronización.

​SendPaymentsTimer: Cada cuántos segundos el servidor local intentará obtener la facturación no enviada a Opera y remitirla al servidor final. Sólo es necesaria en caso de que se vaya a configurar la sincronización.

​Sequence: Requerido por opera. Se usa para serializar en secuencia las ventas enviadas.

​StartingId: Id de la tabla Sales a partir de la cual el servidor comenzará a buscar las líneas no enviadas. Sólo es necesaria en caso de que se vaya a configurar la sincronización.

​Timeout: Tiempo máximo de espera para las peticiones en segundos. Sólo es necesaria en caso de que se vaya a configurar la sincronización.

Volver arriba 👆🏼

El módulo agrega la tabla "OperaTransaction" dónde se irán recogiendo los resultados de las transacciones. El modelo es el siguiente:

​OperaTransaction:

{
posCart: int, //ID del carrito de la línea de venta
reservationID: string, //OPERA ID de la reserva
roomID: string, //OPERA ID de la habitación
success: boolean, //Verdadero o falso según si la transacción fue ok o no
type: int, // (1 -> "payment"; 2-> "refund"; 3->"rejected")*
request: json, //OBJETO JSON de la petición que se envío a Opera
response: json, //OBJETO JSON con la respuesta recibida, si se recibió alguna
error: string, //Almacena una descripción del error si se produjo alguno.
}

* A nivel interno el tipo del campo es número entero; no obstante, al ser una lista de opciones, lo que se mostrará en pantalla será la etiqueta traducible. En el caso del castellano, veríamos "Pago", "Devolución" o "Rechazada" según proceda.
Pago y devolución son tipos autodescriptivos. El tipo "Rechazada" se emplea para los casos en que la comunicación con los servidores local y remoto ha sido satisfactoria y técnicamente correcta, pero el servidor final de Opera nos rechaza la operación por algún motivo. Debido al funcionamiento del patrón "on premise", en estos casos deshacemos la operación de nuestro lado y no guardamos dos transacciones de Opera (una cancelando la otra) porque realmente sólo se ha producido una; en estos casos la transacción se guardará con el tipo "Rechazada".

Es conveniente remarcar, sobre todo a efectos de detección de posibles errores o depuración, que los cargos a habitación desde el TPV se realizan usando una forma de pago como cualquier otra, de tal modo que en la línea de pago (tabla payment) quedará reflejado cuál es el modelo de transacción (en nuestro caso, la tabla OperaTransaction) y cual es la ID dentro de esa tabla que apunta a la línea de OperaTransaction descriptiva de la transacción.

Volver arriba 👆🏼

En cuanto a la funcionalidad de envío masivo de facturación se ha agregado el campo
"operaSent", de tipo verdadero o falso, a los modelos (tablas) "invoiceLine" y "sale".
Recordemos que en v3 "sale" no agrupa líneas de venta, sino que es en si misma la línea de venta, que se relaciona y agrupa con la id del carrito, o de la factura asociada.
​

Como ya se ha mencionado anteriormente, se ha agregado el campo "operaSubtotalGroupId" a la tabla subFamilia. Su razón de ser y su funcionalidad están explicadas más arriba.

Volver arriba 👆🏼

Una vez instalado el servidor local de Opera en el directorio por defecto o aquel que hayamos escogido, podemos usar los dos siguientes comandos para levantar y tumbar el servicio respectivamente: start y stop.

Para hacerlo, debemos abrir una consola de comandos de Windows en MODO
ADMINISTRADOR, situarnos dentro del directorio de instalación y escribir "start.bat" o
"stop.bat" según lo necesitemos en cada momento.

Conviene apuntar que el comando start no "reinicia" el servicio sino que siempre va a intentar instalarlo como si fuera la primera vez y no existiese. El comando stop, consecuentemente, no sólo detiene el servicio, sino que lo desinstala y elimina de la lista de servicios de Windows.

Una vez configurado el servidor local y ejecutado satisfactoriamente el comando start, podemos acudir al gestor de servicios de Windows y localizar el servicio "OperaLocalServer" para comprobar su estado actual. Una vez instalado correctamente el servicio, desde dicho gestor se puede configurar para que su inicio se automático al iniciar sesión en Windows o, por el contrario, manual. Salvo para usuarios o soluciones avanzadas, es recomendable dejarlo en inicio automático.

Conviene resaltar también aquí la importancia de tener bien configurado el cortafuegos de
Windows o cualquier otro software de vigilancia del tráfico del red para permitir las conexiones entrantes y salientes al PC donde esté instalado el servidor local. Lo más habitual es que durante el primer intento de conexión, se nos muestre una ventana del cortafuegos de Windows preguntándonos qué queremos hacer. Si es el caso, hay que autorizar el tráfico entrante y saliente tanto a nivel interno de red (que suele estar habilitado) como remoto (para que el servidor local pueda comunicarse a través de Internet con el servidor final de Opera).

Volver arriba 👆🏼

El funcionamiento de los cargos a habitación es esencialmente idéntico en concepto al de
cualquier otra forma de pago. Una vez el módulo esté correctamente instalado y configurado, cuando acudamos al TPV y finalicemos una venta habremos de escoger la forma de pago "(OPERA) Cargo habitación".

Escogida dicha forma de pago, el sistema intentará conectarse al servidor de local de Opera, para solicitar de éste que obtenga la lista de habitaciones con su ocupante principal. Si este proceso se ha resuelto sin incidencias, se nos mostrará una ventana modal con un desplegable para escoger la habitación a la que queremos realizar el cargo.
En este preciso momento, pueden ocurrir dos posibles situaciones de error: que la conexión con el servidor local falle, en cuyo caso habría que revisar lo siguiente:
- El estado del servicio. Debe aparecer en la lista de servicios de Windows y figurar
como "en ejecución". Si no es así, se debe reinstalar el servicio como más arriba se
explicó.
- La configuración del módulo del lado de GMV3. Esta configuración es relativa AL SERVIDOR LOCAL. La relativa al servidor remoto final está en el archivo config.json del servidor local. Recordemos que hay que encabezar la ip del servidor local siempre con "http://".

Hay que destacar, que si se produce un error en este momento, no se generará
transacción alguna en la tabla de transacciones del módulo. El error más habitual
en estos casos será un error de tipo TIMEOUT para los casos de que la configuración esté
formalmente correcta pero apuntando a una URL errónea, por ejemplo, o de malas formaciones de la URL (olvidar el encabezado, direcciones IP mal escritas, etc..). En cualquiera de los casos, conviene revisar lo dicho.

Si la conexión con el servidor local se realizó satisfactoriamente, aún pueden ocurrir incidencias en cuanto a la comunicación con el servidor final de Opera. Estas se puede clasificar en dos grandes grupos.

La comunicación ha sido satisfactoria, pero el servidor final de Opera nos ha
contestado rechazando la operación por algún motivo, ya sea por existir un defecto
o error en los datos o en su forma, o por cualesquiera políticas propias del servidor
final de Opera que impidan que los datos, aunque correctos en forma y tipo, se
puedan consolidar.
En este caso, debería mostrársenos el correspondiente pop-up rojo alertando del
error, conteniendo la descripción corta del ERROR INTERNO DE OPERA que ha
impedido la consolidación del cargo (o de la devolución). En estos casos, el
contexto de la transacción y su información se guardará en la tabla de transacciones
del módulo con el tipo "Rechazada" que ya vimos más arriba.
Debido al esquema "on premise", en este punto, la operación ya se habrá realizado
de nuestro lado, así que el sistema se encargará de cancelar los pagos hechos y no
aceptados finalmente por Opera dejando las líneas no aceptadas como "pendientes
de pago".

Puede ocurrir que la comunicación de GM con el servidor local sea buena pero que
la comunicación entre el servidor local y el remoto de Opera falle por alguna razón.
Lo primero que hay que revisar es que la dirección URL del servidor remoto de
Opera sea la correcta y que cualesquiera configuraciones de Opera del lado del
club/cliente que sean necesarias estén correctamente realizadas.
No obstante, si todo parece correcto, y tenemos claro que el problema radica en el
momento de comunicacón del servidor local con el remoto, podemos hacer lo
siguiente para depurar:
a) Abrir en modo administrador una consola de comandos de Windows.
b) Acudir al directorio de instalación del servidor local. Ejecutar el comando
"stop.bat". Esto parará y desinstalará el servicio de Windows.
c) Ejecutar el siguiente comando "sim opera.bin"
De este modo, habremos levantado el servidor de nuevo, pero no como servicio, de
tal manera que los errores y sus trazas se mostrarán en la ventana de consola lo cual
puede ayudar a "acotar" o a "precisar" la situación de error a soporte para los casos
que finalmente representen un bug y deban ser revisados.

La devolución se realiza como habitualmente se realiza en el TPV. Veremos la
ventana modal que nos pregunta si queremos devolver a la misma forma de pago,
seleccionaremos obviamente que sí, y si queremos cancelar definitivamente las
líneas o dejarlas pendientes de pago tal y como se viene haciendo con cualquier
otra forma de pago.
En lo relativo al registro de transacciones de Opera y al funcionamiento interno,
éste es muy similar al de cargos. Cabe destacar que en los casos en que el servidor
de Opera rechaza la operación, aún siendo ya válida de nuestro lado, se generará un
pago negativo de nuestro lado, pero no se reflejará como "devolución" en la tabla
de transacciones de Opera, sino como "rechazada".

Volver arriba 👆🏼

Para que esta funcionalidad opere correctamente, es necesario que el archivo de
configuración del servidor esté correctamente configurado tal como se detalla más
arriba.
​

Comprobado lo anterior, en la vista de la tabla sale (ventas) se habrán
agregado dos botones a continuación de los genéricos y/o que ya
tuviere la vista. El que ahora nos interesa es el botón de "Enviar a
Opera", de momento no está implementada la automatización de esta
tarea.
La operativa no tiene misterio, pulsamos el botón y las ventas no
marcadas ya como enviadas (a través del campo extendido
"operaSent") se intentan enviar al servidor local de Opera, para que
este las remita finalmente al servidor remoto de Opera.

Si no queremos usar el envío automático, debemos editar el archivo de
configuración del servidor, config.json, en el directorio de instalación
y cambiar el valor de la propiedad sendPaymentsTimer a cero.
En cualquier otro caso, si el valor de dicha propiedad en el archivo de
configuración es distinto de cero, el ciclo de envío automatizado
simplemente comenzará de acuerdo a los parámetros indicados en la
misma configuración.

Volver arriba 👆🏼

Asimismo, para que el servidor local de ópera pueda obtener la facturación ya sea mediante el flujo manual o el automático se han implementado múltiples endpoints del lado del servidor.

Los que aquí conviene mencionar son los que emplea el servidor local:
- opera/getPayments.json (GET)
- opera/setSalesAsSent.json (POST)
​

Estos dos endpoints se autentican mediante la clave API de usuario que se generó en el
momento de la configuración y que debe estar debidamente copiada en el archivo de
configuración del servidor.

En el escenario de depuración donde ejecutamos el servidor desde la línea de comandos, puede comprobarse si efectivamente el servidor está pasando la autenticación o no, ya que con cada ciclo se mostrará en consola el resultado de la operación.

Volver arriba 👆🏼