Protocolos de mensajería

-La comunicación entre el EPOS y la Nube se basa en:

● API REST sobre HTTPS.
● MQTT.

-API REST

Mediante API REST, la aplicación EPOS se vincula (bind) con un terminal de pago (POS) y obtiene los parámetros para enviar mensajes y realizar transacciones usando MQTT. La vinculación entre el EPOS y el POS se realiza una única vez solamente.

-Autenticación básica

Para consumir la API REST, se utiliza el mecanismo de autenticación básica de HTTPS, que consiste en concatenar el valor de APP ID con el valor de APP Secret, codificar el resultado en Base64 y agregarlo a la cabecera Authorization de las solicitudes HTTPS:

APP ID = 600045
APP Secret = appsecret
APP ID:APP Secret = 600045:appsecret
Base64(APP ID:APP Secret) = NjAwMxsdqDQ1OmFwcHNlY3JldA==
Luego en cada solicitud HTTPS, se agrega la siguiente cabecera:
Authorization: Basic NjAwMxsdqDQ1OmFwcHNlY3JldA==

-Vinculación / Binding

Antes de intentar procesar transacciones con el terminal de pago, es necesario vincularlo (bind) con el EPOS. Esto se realiza mediante el consumo de la API pos-binding que se muestra a continuación.

Solicitud HTTPS

Endpoint	/nebula-acs/api/v1/pos-binding
Cabecera (Header)	Authorization: Basic `{Authinfo}`	Permite usar el mecanismo de autenticación básica de HTTPS para acceder a la API REST de la Nube. Vea el punto "Autenticación básica" para generar esta cabecera.
Tipo de contenido (Content-Type)	application/json
Método (Method)	POST
Cuerpo (Body)	`{ "code":"xxxx" }`	El valor xxxxx corresponde al código numérico generado por la aplicación Launcher en el terminal de pago al iniciar la vinculación / binding.

Respuesta HTTPS


Código de respuesta (Status)	200 OK
Cuerpo (Body)	`{ "sn": "99999999" }`	El valor 99999999 corresponde al número de serie del terminal de pago.

-Obtener los parámetros MQTT

Una vez realizada exitosamente la vinculación entre el terminal de pago y el EPOS, y antes de enviar transacciones o mensajes, es necesario obtener los parámetros para comunicarse con la Nube mediante MQTT.

La API que permite obtener estos parámetros se llama mqtt-access-applying y tiene los siguientes campos:

Solicitud HTTPS

Endpoint	/nebula-acs/api/v1/mqtt-access-ap plying
Cabecera (Header)	Authorization: Basic `{Authinfo}`	Permite usar el mecanismo de autenticación básica de HTTPS para acceder a la API REST de la Nube. Vea el punto 3.1.1 para generar esta cabecera.
Tipo de contenido (Content-Type)	application/json
Método (Method)	POST
Cuerpo (Body)	`{ "eid": "${EID}", "sn": [ "${SN1}", "${SN2}", … ], "isWebsocket": false }`	El valor de `${EID}` corresponde al identificador único asociado al EPOS. Los valores de `${SN1}, ${SN2}`, … corresponden a los números de serie de los terminales de pago (POS) con los que se ha vinculado el EPOS especificado por epos-id. El valor isWebsocket debe tener el valor true si MQTT está funcionando sobre WebSockets.
Status	200 OK
Body	`{ "host": "${HOST}", "clientId": "${CLIENTID}", "username": "${USERNAME}", "password": "${PASSWORD}" }`	El valor de `${HOST}` contiene la dirección IP del servidor MQTT. El valor de `${CLIENTID}` contiene el ID de cliente para MQTT. El valor de `${USERNAME}` corresponde al nombre del usuario de la conexión MQTT. El valor de `${PASSWORD}` es una contraseña de un solo uso para establecer la conexión MQTT. Esta conexión dura solamente un par de horas, por lo que es necesario invocar a esta API con cierta frecuencia, para evitar que la contraseña suministrada caduque.

-MQTT

Una vez realizada la vinculación entre el EPOS y el terminal de pago y obtenidos los parámetros de conexión para MQTT, la aplicación EPOS puede enviar mensajes y transacciones usando el mecanismo de publicación / subscripción de mensajes de MQTT.

-Publicación de mensajes

Para que el EPOS envíe una transacción o mensaje, debe publicarlo en un tópico MQTT como sigue:


tópico	`/ecr-req/${APPID}/${CLIENTID}`	El valor de `${APPID}` corresponde al valor de APP ID devuelto inicialmente al crear la aplicación. El valor de `${CLIENTID}` corresponde al valor devuelto al solicitar los parámetros MQTT con la API mqtt-access-applying. Si APPID es 600045 y CLIENTID es ecr100742, entonces el tópico será: /ecr-req/600045/ecr100742
qos	1	QoS (Calidad de Servicio o garantía de entrega) Sus valores posibles son los siguientes: 0 = El mensaje será entregado a lo más una vez. 1 = El mensaje será entregado al menos una vez. 2 = El mensaje será entregado exactamente una vez.
payload	Mensaje JSON con la solicitud

-Suscripción de mensajes

Para recibir la respuesta, la aplicación EPOS debe suscribirse al siguiente tópico en MQTT:


tópico	`/ecr-res/${APPID}/${CLIENTID}`	El valor de `${APPID}` corresponde al valor de APP ID devuelto inicialmente al crear la aplicación. El valor de `${CLIENTID}` debe ser reemplazado por el valor devuelto al solicitar los parámetros MQTT con la API mqtt-access-applying. Si APPID es 600045 y CLIENTID es ecr100742, entonces el tópico será: /ecr-res/600045/ecr100742
qos	1	QoS (Calidad de Servicio o garantía de entrega) Sus valores posibles son los siguientes: 0 = El mensaje será entregado a lo más una vez. 1 = El mensaje será entregado al menos una vez. 2 = El mensaje será entregado exactamente una vez.
payload	Mensaje JSON con la respuesta

El campo payload de los mensajes consiste en una estructura de múltiples capas anidadas: transferencia, control y parámetros.

-Capa de transferencia

Es la capa más externa y gestiona los parámetros relacionados con la transmisión de la comunicación. A continuación, se muestran los campos de esta capa.

Parámetro	Tipo	Requerido	Comentario
sdkVersion	int	Sí	Versión SDK
appId	String	Sí	ID de la aplicación EPOS generado durante la creación de esta.
id	String	Sí	UUID, donde los ID de la solicitud y de la respuesta deben ser iguales, permitiendo la correlación entre ambas.
eid	String	No	Identificador del EPOS que envía el mensaje.
sn	String	Sí	Número de serie del terminal de pago.
time	long	Sí	Timestamp en milisegundos de cuando el requerimiento fue enviado.
type	String	Sí	Tipo del mensaje
jsonData	String	Sí	String con la Capa de Control.

Capa de control

Gestiona el control de la lógica de negocio. Es un string correspondiente al valor del campo jsonData de la capa de transferencia. Este mensaje contiene los campos: packageName, category y jsonData (este último es un string con el mensaje de la capa de parámetros). A continuación se muestran los campos de esta capa.

Parámetro	Tipo	Comentario
packageName	String	Nombre del paquete de la aplicación de pago.
category	String	Categoría de la transacción
jsonData	String	Mensaje con los parámetros.

Capa de parámetros

Define los parámetros de la transacción, con campos específicos definidos por el EPOS y el terminal de pago. En esta capa viajan, por ejemplo: monto, código de moneda, propina, etc. Solicitud de capa de parámetros

Parámetro	Tipo	Comentario
packageName	String	Nombre del paquete de la aplicación de pago
category	String	Categoría de la transacción.
jsonData	String	Parámetros requeridos por cada transacción.

Tipos de Mensaje

-com.pax.nebula.message.Payment El Mensaje de Pago es un tipo de mensaje enviado por el sistema EPOS para iniciar una transacción

-com.pax.nebula.message.Cancel El Mensaje de Cancelación es un tipo de mensaje enviado por el sistema EPOS para cancelar una transacción (Cierre, Devolución, Venta, etc)

Categoría de transacción

En la capa de parámetros de un mensaje se especifica la categoría de la transacción según la tabla siguiente.

Propietario	Categoría de transacción	Descripción
Transformapp	cl.transformapp.payment.cashClosing	Cierre
Transformapp	cl.transformapp.payment.return	Devolución
Transformapp	cl.transformapp.payment.sale	Venta
Transformapp	cl.transformapp.payment.void	Cancelación