Skip to content

Latest commit

 

History

History
463 lines (409 loc) · 11.1 KB

AN-Native_DeviceUpdater_Protocol-Spec.md

File metadata and controls

463 lines (409 loc) · 11.1 KB
Raw

ationetlogo

ATIONet - Native Device Updater Protocol Specification v1.0

Document Information
File: AN-Native_DeviceUpdater_Protocol-Spec
Doc Version: 1.0
Release Date: 21, Feb 2019
Author: ATIONet LLC
Change Log
Ver. Date Change Summary

1.0

21/Feb/2019

Initial version.

Contents

Visión General

Introducción

El objetivo de esta documentación es especificar el formato de mensajería de protocolo nativo de la API de mantenimiento de Terminals Management y las funcionalidades requeridas para los sistemas que solicitan integración con la herramienta. Las siguientes secciones proporcionan descripciones de los mensajes y el comportamiento esperado para cada tipo de operación.

Definiciones

Terminal Dispositivo al cual serán aplicadas de forma remota actualizaciones de firmwares, parámetros o recursos descritos en una agenda programada, y del que se llevara un control o monitoreo del estado de operatividad y localización física en la cual se encuentra.

Agenda

Cronograma programado de actualización de terminal, en el que se agrupan terminales para aplicar una actualización requerida por el usuario en una fecha y hora especifica; en ella se encuentra definido los detalles de la actualización a efectuar (tipo, modo, definición de parámetros, recursos necesarios).

Parámetros

Valores necesarios de configuración de la terminal para poder operar satisfactoriamente con la herramienta.

Novedades

Mensaje que contiene la información o donde obtener la información de la actualización a aplicar en la terminal.

Alcance de la Documentación

Los sistemas de terceros se integran con Terminals Mangement a través de una API.

El presente documento del protocolo de la API de Terminals Management especifica el protocolo de interfaz de mantenimiento, el cual lista un conjunto de mensajes para ayudar al mantenimiento y soporte de una red de terminales; por ejemplo, verificar el estado de las terminales mediante un mensaje denominado KeepAlive, obtener novedades para las terminales registradas en la herramienta y el reporte de parámetros actuales.

Detalles del alcance

Protocolo: Protocolo de Interfaz de Mantenimiento Terminals Management Versión: 1.0.0000 API URI: https://terminalsmanagementapi.ationet.com/v1/maintenance

Mensajes

Nombre Versión Protocolo Descripción

Keep-Alive

1.0.0000

Se utiliza para reportar valores de operatividad de la terminal (Código de Terminal, Número de Serie, Sistema Operativo, Modelo del Sistema, Versión del Sistema, IP, Carga de la Batería, Estado del Papel y Fecha de Reporte), además de obtener información de agendas pendientes por aplicación disponible.

GetNews

1.0.0000

Se utiliza para obtener los datos de la próxima actualización disponible por aplicar en la terminal.

ParametersReport

1.0.0000

Utilizado para reportar los valores de los parámetros actuales que posee la terminal activa.

Seguridad de Datos

La interfaz API requiere una conexión SSL entre ambas partes. La conexión SSL se establece para cada par de solicitud / respuesta, utilizando una propiedad de certificado de Terminals Management.

Estructura del Mensaje

Todos los mensajes de la API comparten la misma estructura, lo único que cambia entre mensaje y mensaje es el código de transacción/operación, que indica la función a realizar, y en base al cual se analizan los valores de los campos enviados y recibidos.

La acción HTTP siempre es POST y tanto las solicitudes como las respuestas utilizan un formato JSON.

Solo se acepta una solicitud en cada mensaje.

Formato del Request

Header:

Accept-Encoding: gzip

Body:

{“NombreDeCampo1”:“ValorDeCampo1”,“NombreDeCampo2”:“ValorDeCampo2”,...,“NombreDeCampoNNN”:“ValorDeCampoNNN” }

Formato del Response

Header:

Content-Type: application/json; charset=utf-8

Body:

{“NombreDeCampo1”:“ValorDeCampo1”,“NombreDeCampo2”:“ValorDeCampo2”,...,“NombreDeCampoNNN”:“ValorDeCampoNNN” }

Mensaje KeepAlive

Request

Descripción del cuerpo:

Nombre Tamaño Tipo Condición Descripción

TransactionCode

3

A

Requerido

Código de transacción / operación

TerminalCode

4-20

A/N

Requerido

Código de Terminal

Ip

Var

N

Opcional

Ip de conexión

SystemModel

Var

A/N

Opcional

Modelo del sistema

SystemVersion

Var

A/N

Opcional

Versión del sistema

SerialNumber

Var

A/N

Requerido

Número de serie de terminal

OperatingSystem

Var

A/N

Opcional

Sistema Operativo

BatteryCharge

Var

A/N

Opcional

Cantidad de carga de la batería

PaperStatus

Var

A/N

Opcional

Estado del papel

LastSchedule

36

GUID

Opcional

Id de última agenda aplicada

Ejemplo:

{“TransactionCode”:“600”,“TerminalCode”:“AXN8763542”, “Ip”:“192.168.20.154”, “SystemModel”:“ StandAloneTerminal”,“SystemVersion”:“ 2.0.0150”,“SerialNumber”: “SR937492”,“OperatingSystem”:“ EVO”,“BatteryCharge”:“100%”, “PaperStatus”:“OK”,“LastSchedule”:“ 90BEBD7C-78F8-4711-A304-0E690F2A0466” }

Response

Descripción del Cuerpo:

XXXXXXXXXXXXXXXXXXXXXXXXXXX

Ejemplo:

{“TransactionCode”:“ 601”,“SiteDateTime”:“05-11-18 09:10:00”,“SiteTimeZone”:“Argentina Standard Time”,“HostDateTime”:“ null”,“IdSchedule”:“90BEBD7C-78F8-4711-A304-0E690F2A0466”}

Mensaje GetNews

Request

Descripción del Cuerpo:

XXXXXXXXXXXXXXXXXXXXXXXXXX

Ejemplo:

{“TransactionCode”:“602”,“TerminalCode”:“AXN8763542,“SerialNumber”:“SR937492”,“IdSchedule”:“ 90BEBD7C-78F8-4711-A304-0E690F2A0466”}

Response

Descripción del Cuerpo:

XXXXXXXXXXXXXXXXXXXXXXXXX

Ejemplo:

{“TransactionCode”:“603”,“FirmwareUrl”: “https://storage.blob.net/terminalsmanagment/firmwares/45aa5bd5-7344-f8688c6878a14e42483.zip”, “ResourcesUrl”:“https://storage.blob.net/terminalsmanagment/Resources/45aa5bd5-7344-4f86-88c6-878a14e42483.zip”,“ Configurations”:“{“Parámetro1”:“Valor1”,“Parámetro2”:“Valor2”,…,“ParametroN”: “ValorN”}” ,“ ApplicationMethod”:“0”}

Mensaje ParametersReport

Request

Descripción del Cuerpo:

XXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ejemplo:

{“TransactionCode”:“604”,“TerminalCode”:“AXN8763542”,“SerialNumber”:“SR937492”,“ Configurations”:“{“Parámetro1”:“Valor1”,“Parámetro2”:“Valor2”,…,“ParametroN”: “ValorN”}”}

Response

Descripción del Cuerpo:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ejemplo:

{“TransactionCode”:“605”,“ResponseMessage”:“OK”}

Códigos de Transacción / Operación Se refiere a los códigos con lo cual se indica que tipo de transacción/operación se realizará.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXxxxxx