Dman esp eirs_inter-prog

EIR

Manual de Interfaces de
Programación

Versión 3.0.9

Manual de Interfaces de
Programación
Versión C 14
Última modificación: 18/02/2005

Derechos reservados. Prohibida su reproducción, transmisión, transcripción o
traducción a otro idioma, en forma total o parcial, sin el permiso por escrito de
ATS advanced technology solutions. El presente documento es únicamente informativo y está sujeto a
cambios.
Copyright © 2004 ATS advanced technology solutions

www.ats-connection.com

SensIT-EIR Versión 3.0.9
Interfaces de Programación

Índice General

1. Introducción ......................................................................................................................1
2. Módulo SensIT-EIR API....................................................................................................3
Consideraciones Generales..............................................................................................3
2.1 Conexión física .......................................................................................................4
2.2 Servidor Activo y Pasivo .........................................................................................4
2.3 Lenguaje de comandos...........................................................................................4
2.4 Comandos...............................................................................................................6
2.4.1 Validar Usuario ..................................................................................................6
2.4.2 Cambiar clave ....................................................................................................6
2.4.3 Agregar un IMEI y/o un IMSI a una lista............................................................7
2.4.4 Modificar datos de un IMEI y/o un IMSI de una lista .........................................8
2.4.5 Borrar un IMEI y/o un IMSI de una lista...........................................................10
2.4.6 Mover un IMEI y/o un IMSI de una lista a otra ................................................11
2.4.7 Copiar un IMEI o un IMSI de una lista a otra...................................................12
2.4.8 Consultar datos de un IMEI o de un IMSI en una lista ....................................14
2.4.9 Consultar lista de eventos de un IMEI o un IMSI ............................................15
2.4.10 Pasar a Emergencia ........................................................................................17
2.4.11 Simular un CheckIMEI .....................................................................................18
2.4.12 Alta de IMEI o IMSI con verificación de unicidad ............................................19
2.4.13 Respuesta al cliente ........................................................................................21
3. Módulo SensIT-EIR Batch ..............................................................................................22
3.1 Introducción ..........................................................................................................22
3.1.1 Proceso File Transfer ......................................................................................24
3.1.2 Proceso de Altas y Bajas.................................................................................24
3.1.3 Proceso de Consultas......................................................................................24
3.1.4 Proceso de exportación de Eventos................................................................24
3.1.5 Proceso de exportación de Listas ...................................................................24
3.2 Archivos ................................................................................................................24
3.2.1 Nomenclatura de los archivos .........................................................................25
3.2.2 Archivo de entrada del proceso de altas y bajas.............................................26
3.2.3 Archivo de salida del proceso de altas y bajas................................................27
3.2.4 Archivo de entrada del proceso de Consultas.................................................28
3.2.5 Archivo de salida del proceso de Consulta .....................................................29

© ATS – Para uso confidencial del Cliente i

Interfaces de Programación

3.2.6 Archivo de Eventos..........................................................................................31
3.2.7 Archivo de Listas .............................................................................................31
4. Glosario...........................................................................................................................33

© ATS – Para uso confidencial del Cliente ii

Interfaces de Programación Introducción

1
1. Introducción

Este documento describe los mecanismos de intercambio de información entre
SensIT-EIR y el Sistema de Gestión del Cliente.
Uno de ellos consiste en la comunicación a través de un protocolo (SensIT-EIR
API), utilizado entre la plataforma SensIT-EIR y el Sistema de Gestión del
Cliente.
El otro consiste en un módulo llamado SensIT-EIR Batch que es empleado por
las aplicaciones externas a la plataforma para interactuar con el producto
SensIT-EIR a través de procesamiento por lotes.

Figura 1: Comunicación con Sistemas Externos: Comandos APIs y Procesos Batch

Para facilitar la lectura de este material, se ha definido una serie de
convenciones que permiten identificar elementos de características especiales
en el contexto de esta descripción.

Itálica Se utiliza para referir a elementos de hardware y
software, nombres de comandos, nombres de
aplicaciones, nombres de tecnologías y protocolos,
términos en otro idioma.

Negrita Se utiliza para identificar los nombres de entidades y
campos de datos.

Tipo Courier Se utiliza para presentar código de la aplicación,
nombres de archivos, clases y/o tablas de BD.

Nota: Se utiliza para identificar que el texto que sigue es una

© ATS – Para uso confidencial del Cliente 1

Interfaces de Programación Introducción

anotación o explicación adicional.

<Tecla> Se utiliza para referir a una tecla específica.

Ver Documento Referencia a otro documento.

Negrita cursiva Se utiliza para referir a valores de campos.

Para facilitar la comprensión de los comandos este documento incluye algunos
ejemplos, cuyos datos no deben ser tomados como reales.
Además es importante aclarar que para favorecer la lectura de algunos
comandos se insertó el carácter <Enter>. En la realidad los comandos no
contienen este separador.
Los comandos a los cuales se hace referencia en la sección del módulo SensIT-
EIR Batch, se encuentran detallados en la sección de Comandos del módulo
SensIT-EIR API.


Interfaces de Programación Módulo SensIT-EIR API

2
2. Módulo SensIT-EIR API
La conexión entre el Servidor de SensIT y el Sistema de Gestión del Cliente se
realizará a través una Interface de Programación de Aplicaciones (en adelante
SensIT-EIR API).
Se presenta la especificación de la conexión física requerida y del lenguaje de
comandos utilizado para el intercambio de información con el Sistema de
Gestión del Cliente.

Consideraciones Generales
Mientras se encuentre levantado el servicio de API, la conexión TCP/IP se
encontrará disponible y accesible, incluso cuando la base de datos no esté
levantada. En este ultimo caso, el API permitirá que se conecten los
clientes y devolverá el código de error 906 (Error – Sin conexión a Base de
Datos)

En todo comando cuando aparezca IMEI o IMSI se debe considerar que
ambos campos no son obligatorios; se debe enviar uno de los dos o ambos,
dependiendo del tipo de lista que se trate

Cuando un campo no es obligatorio, en el caso de no querer enviar
información, no se debe enviar.

Cuando se envíe una fecha en formato corto, al almacenarse en la base, la
fecha será completada con la hora con el formato: 00:00:00.

En el caso de la respuesta de los comandos se deberá tener en cuenta:

KEY: representa la clave del registro modificado

COUNT: es la cantidad modificada de registros

SensIT-EIR API tiene métodos de sincronización que comparte con el
SensIT-EIR Batch y con la Consola Administrativa WEB. Por lo tanto es
necesario considerar que, cuando SensIT-EIR Batch o la Consola
Administrativa WEB estén realizando operaciones de actualización
importantes, puede ocurrir que SensIT-EIR API tenga ciertas demoras que
surgen de la sincronización de estos procesos o viceversa.



2.1 Conexión física
La conexión entre el Servidor de SensIT y el Sistema de Gestión del Cliente se
realizará a través de una API (SensIT-EIR API) utilizando el protocolo TCP/IP.
Para establecer la comunicación entre los sockets deben definirse los
parámetros:

Dirección IP

Port

2.2 Servidor Activo y Pasivo
SensIT-EIR API trabajará en uno de estos dos modos: Activo o Pasivo,
dependiendo del estado del servidor al cual se encuentre conectado:

Activo: representa que el servidor y, por lo tanto, SensIT-EIR API se
encuentra en estado Normal y con posibilidad de recibir y procesar las
transacciones que le sean enviadas.

Pasivo: SensIT-EIR API permitirá recibir conexiones, aunque sólo admitirá
loggearse sin procesar ninguna otra transacción.

Para informar en qué modo se encuentra SensIT-EIR API, toda transacción que
se ejecute contra SensIT-EIR API, retornará un código de error indicando que se
encuentra en modo Pasivo, exceptuando el comando LOGIN que devolverá un
campo indicando el modo en que se encuentra el servidor. Es importante aclarar
que el sistema continúa conectado, es decir no se desconecta, sólo que
cualquier otra transacción que se realice después de loguearse, SensIT-EIR API
retornará un código de error indicando que el servidor se encuentra en modo
Pasivo. En el modo Activo no hay transacciones con error, sino, las respuestas
correspondientes a las transacciones solicitadas.

2.3 Lenguaje de comandos
Las siguientes reglas especifican las convenciones y restricciones aplicables al
lenguaje de comandos provisto por SensIT-EIR API.

Los comandos son strings de texto que expresan campos de datos
separados por el carácter ‘;’.

El orden de los campos de un comando no afecta al normal funcionamiento
del mismo.

Cada campo está compuesto por: un Label y el/los valor/es a asignar
separados por el carácter ‘=’. En el caso de los campos multivalor, se utiliza
el separador ‘,’.

El separador de mensajes de entrada es configurable. El carácter nueva
línea (0xA) es el sugerido. El string para la terminación de respuestas es
configurable.



Permite el uso de los siguientes wildcards:

Wildcard Especificación
Se traslada a la funcionalidad del sistema.
Funcional (%) Los valores se almacenan en la base tal
cual llegan.
Es utilizado para SensIT-EIR API al
De carga (*)
momento de la carga de datos.

Restricciones:

No utilizar el carácter ‘;’ como dato, ya que será interpretado como
separador de campos

No utilizar el carácter ‘,’ como dato, ya que será interpretado como
separador de valores

Resumen de separadores:

Separadores Uso
; Entre campos
= Entre el label identificador y su valor
, Entre valores
0xA (configurable) Entre mensajes de entrada al API
String configurable Entre mensajes de salida del API

Los comandos que modifiquen de alguna manera los datos de la plataforma
serán registrados en el log de auditoría.
Las primeras acciones que deberá realizar un cliente que se conecta con la
aplicación SensIT-EIR API es establecer conexión con el servidor vía el
protocolo TCP/IP y luego efectuar una transacción de Login. Toda vez que
ocurra una desconexión del protocolo TCP/IP, deben realizarse nuevamente las
acciones anteriormente mencionadas.
Luego de la validación correspondiente el cliente podrá llevar a cabo el resto de
las transacciones, siempre y cuando su perfil sea válido para realizar la
operación deseada y el servidor se encuentre en modo ACTIVO.
El protocolo no requiere transacción de Logoff. Para realizar una desconexión
con el sistema, solamente se debe cerrar la sesión TCP/IP. Si se cierra la sesión
de TCP/IP, habiendo realizado previamente la transacción de Login, la operación
de desconexión quedará grabada como Logoff del usuario que se había
registrado.
Las claves que deban ser enviadas al Sistema no deberán estar encriptadas; sin
embargo el Sistema almacena las claves en la Base de Datos en forma
encriptada.



2.4 Comandos
2.4.1 Validar Usuario
Descripción: es el comando que abre la sesión de transacciones. Corrobora el
nombre de usuario y clave en el inicio de una sesión. Este comando es el
primero que debe ejecutar un cliente cuando se conecta a la aplicación.
LOGIN;UserName=<Value>;Password=<Value>

Campo Obligatorio Default Tipo Descripción
Nombre de usuario dado de alta con la consola
UserName SI String
de seguridad
Password SI String Clave del usuario. No se debe enviar encriptada

Respuesta:
OK;LOGIN;KEY=<UserName>;Version=<protocol_version>;Mode=<ACTIVE|PASIVE>

Donde:
Version: indica el número de versión del protocolo que cumple SensIT-EIR API

Errores posibles del comando Login:

Código Detalle
101 Falta un campo obligatorio
800 Usuario no existe
801 Clave inválida
903 Error de Base de Datos
904 Error interno del sistema
906 Error - Sin conexión a Base de datos

2.4.2 Cambiar clave
Descripción: modifica la clave de un usuario de la aplicación.
Este comando permite modificar únicamente la clave del usuario que ejecutó el
comando.
CHANGE_PASSWORD;UserName=<Value>;Password=<Value>;NewPassword=<Val
ue>

Nombre de usuario dado de alta con la consola
UserName SI String
WEB



Clave del usuario. No se debe enviar
Password SI String
encriptada
Nueva clave del usuario. No se debe enviar
NewPassword SI String
encriptada

Respuesta:
OK;CHANGE_PASSWORD;KEY=<UserName>

Errores posibles del comando CHANGE_PASSWORD:

Código Detalle
106 Server en modo pasivo
800 Usuario no existe
801 Clave inválida

2.4.3 Agregar un IMEI y/o un IMSI a una lista
Descripción: realiza el alta de un IMEI o de un IMSI en una lista determinada.
Permite los siguientes wildcards:

El alta se realiza en modo normal y el % será interpretado por los procesos
Funcional (%)
internos del sistema receptor
Indica que se debe completar el largo del IMEI o IMSI para todos los valores
De carga (*)
posibles, esto permite un alta masiva. Retorna la cantidad que pudo agregar

ADD_IN_LIST;IMEI=<Value>;IMSI=<Value>;List=<Value>;Motive=<Value>;
Origin=<Value>;Description=<Value>

Ejemplo:
ADD_IN_LIST;IMEI=1234567890ABCDEF;List=BLACK;Motive=Robo;Origin=
Argentina;Description=JLOPEZ

IMEI a ingresar. Este campo es
IMEI - String requerido sólo si la lista lo
contempla
IMSI a ingresar. Este campo es
IMSI - String requerido sólo si la lista lo
contempla



Lista a la cual se agregarán los
móviles. Este valor deberá ser el
List SI String
indicador de una lista definida en el
sistema
Detalle del motivo por el cual se
Motive NO Null String
agrega en la lista indicada
Normalmente se usa para indicar el
origen de la información. Ej: zona
Origin NO Null String
geográfica, país, nombre de
operador, etc.
Texto libre que será impactado en
Description NO Null String
el log de auditoría.

Respuesta:
OK;ADD_IN_LIST;KEY=<IMEI Value|IMSI Value|IMEI Value,IMSI Value>;
Count=<Value>

Ejemplo:
OK;ADD_IN_LIST;KEY=1234567890ABCDEF;Count=1

Errores posibles del comando ADD_IN_LIST:

Código Detalle
100 Campo inválido
102 Operación no permitida al usuario
103 Usuario no logueado
104 Dato Inválido
105 Lista incompatible con los datos enviados
901 Ya existe el registro en la base de datos

2.4.4 Modificar datos de un IMEI y/o un IMSI de una lista
Descripción: permite cambiar los datos de un IMEI o de un IMSI en una lista
determinada.
Permite wildcards:

Funcional (%) Modifica los datos del registro que tenga el mismo valor en el sistema
De carga (*) posibles, esto permite una modificación masiva. Retorna la cantidad que pudo
modificar



UPDATE_IN_LIST;IMEI=<Value>;IMSI=<Value>;List=<Value>;Motive=<Valu
e>;
Origin=<Value>;Description=<Value>

Restricción: los datos que se pueden modificar son los correspondientes al
Motive y al Origin.

IMEI a modificar en la lista. Este
IMEI - String campo es requerido sólo si la lista
lo contempla
IMSI a modificar en la lista. Este
IMSI - String campo es requerido sólo si la lista
lo contempla.
Lista a la que pertenecen los
List SI String
móviles que se quieren modificar.
Motive NO Actual String
modifica en la lista indicada
Origin NO Actual String
operador, etc.
el log de auditoría

Ejemplo:
UPDATE_IN_LIST;IMEI=1234567890ABCDEF;List=BLACK;Motive=Extraviado;
Description=JLOPEZ

Respuesta:
OK;UPDATE_IN_LIST;KEY=<IMEI Value|IMSI Value|IMEI Value,IMSI
Value>;
Count=<Value>

Ejemplo:
OK;UPDATE_IN_LIST;KEY=1234567890ABCDEF;Count=1

Errores posibles del comando UPDATE_IN_LIST:

Código Detalle
100 Campo inválido
104 Dato Inválido
902 NO existe el registro en la base de datos



Código Detalle

2.4.5 Borrar un IMEI y/o un IMSI de una lista
Descripción: realiza la baja de un IMEI o de un IMSI de una lista determinada.


Funcional (%) Dará de baja el registro que tiene este valor en el sistema
De carga (*) posibles, esto permite una baja masiva. Retorna la cantidad que se pudo dar de
baja.

DELETE_FROM_LIST;IMEI=<Value>;IMSI=<Value>;List=<Value>;Descriptio
n=<Value>

IMEI a dar de baja en la lista. Este
campo es requerido sólo si la lista
IMEI - String
en la que se desea dar de baja lo
contempla
IMSI a dar de baja en la lista. Este
campo es requerido sólo si la lista
IMSI - String
en la que se desea dar de baja lo
contempla
Lista desde la cual se darán de baja
List SI String
los IMEI o IMSI

Ejemplo:
DELETE_FROM_LIST;IMEI=1234567890ABCDEF;List=BLACK;Description=JLOP
EZ

Respuesta:
OK;DELETE_FROM_LIST;KEY=<IMEI Value|IMSI Value|IMEI Value,
IMSI Value>;Count=<Value>

Ejemplo:
OK;DELETE_FROM_LIST;KEY=1234567890ABCDEF;Count=1



Errores posibles del comando DELETE_FROM_LIST:

Código Detalle
100 Campo inválido
104 Dato Inválido
905 Tiene registros relacionados
907 NO existe el elemento en la lista

2.4.6 Mover un IMEI y/o un IMSI de una lista a otra
Descripción: mueve los datos del registro solicitado de una lista a otra.


Funcional (%) Moverá el registro que tiene este valor en el sistema
De carga (*) posibles, esto permite un movimiento masivo. Retorna la cantidad que se pudo
mover

MOVE_TO_LIST;IMEI=<Value>;IMSI=<Value>;ListSource=<Value>;ListTarg
et=
<Value>;Description=<Value>

IMEI que se desea mover de lista.
IMEI - String Este campo es requerido sólo si las
listas origen y destino lo contemplan
IMSI que se desea mover de lista.
IMSI - String Este campo es requerido sólo si las
ListSource SI String Lista origen
ListTarget SI String Lista destino
Texto libre que será impactado en el
log de auditoría.

Ejemplo:



MOVE_TO_LIST;IMEI=1234567890ABCDEF;ListSource=BLACK;ListTarget=WHI
TE;
Description=JLOPEZ

Respuesta:
OK;MOVE_TO_LIST;KEY=<IMEI Value|IMSI Value|IMEI Value,IMSI Value>;
Count=<Value>

Ejemplo:
OK;MOVE_TO_LIST;KEY=1234567890ABCDEF;Count=1

Errores posibles del comando MOVE_TO_LIST:

Código Detalle
100 Campo inválido
104 Dato Inválido

2.4.7 Copiar un IMEI o un IMSI de una lista a otra
Descripción: copia un IMEI o un IMSI de una lista a otra.


Funcional (%) Copiará el registro que tiene este valor en el sistema
De carga (*)
posibles, esto permite una copia masiva. Retorna la cantidad que se pudo copiar

COPY_TO_LIST;IMEI=<Value>;IMSI=<Value>;ListSource=<Value>;ListTarg
et=
<Value>;Description=<Value>



IMEI que se desea copiar de lista.
IMEI - String Este campo es requerido sólo si las
IMSI que se desea copiar de lista.
IMSI - String Este campo es requerido sólo si las
ListSource SI String Lista origen
ListTarget SI String Lista destino
log de auditoría

Ejemplo:
COPY_TO_LIST;IMEI=1234567890ABCDEF;ListSource=BLACK;ListTarget=WHI
TE;
Description=JLOPEZ

Respuesta:
OK;COPY_TO_LIST;KEY=<IMEI Value|IMSI Value|IMEI Value,IMSI Value>;
Count=<Value>

Ejemplo:
OK,COPY_TO_LIST;KEY=1234567890ABCDEF;Count=1

Errores posibles del comando COPY_TO_LIST:

Código Detalle
100 Campo inválido
104 Dato Inválido



2.4.8 Consultar datos de un IMEI o de un IMSI en una lista
Descripción: obtiene los datos de un IMEI o de un IMSI cargado en una lista.


Funcional (%) Consultará por el registro que tiene este valor en el sistema
De carga (*)
posibles; esto permite una consulta masiva

GET_DATA_IN_LIST;IMEI=<Value>;IMSI=<Value>;List=<Value>;OrderBy=
<Value>;LastIndexRecord=<Value>

IMEI que se desea consultar en una
IMEI - String lista. Este campo es requerido sólo si
la lista a consultar lo contempla
IMSI que se desea consultar en una
IMSI - String lista. Este campo es requerido sólo si
la lista a consultar lo contempla
Lista en la cual se encuentran el IMEI
List SI String
o IMSI
Campo por el cual se ordenará la
consulta. Los valores posibles son:
IMEI| ‘IMEI’, ‘IMSI’, ‘LIST’, ‘MOTIVE’,
IMSI| ‘ORIGIN’.
OrderBy NO String Dependiendo del tipo de lista que
IMEI,
IMSI sea, el default es:
- Por el IMEI o el IMSI
- Por el IMEI y el IMSI
Índice a partir del cual se desea
consultar. Este índice es referente al
LastIndexRecord NO 0 Number campo OrderBy y va desde 0 a
RecordTotal. Para iniciar la consulta
se debe enviar 0

Ejemplo:
GET_DATA_IN_LIST;IMEI=1234567890ABCDEF;List=BLACK;OrderBy=IMEI;Las
tIndexRecord=0

Respuesta:
OK;GET_DATA_IN_LIST;KEY=<IMEI Value|IMSI Value|IMEI Value,IMSI
Value>;RecordTotal=<Value>;
RecordCount=<N>;Record1=<Index,IMEI,IMSI,List,Motive,Origin>;Recor
d2=
<Index,IMEI,IMSI,List,Motive,Origin>;…;RecordN=<Index,IMEI,IMSI,Li
st,
Motive,Origin>



Campo Tipo Descripción
Cantidad de registros que cumplen con la condición de
RecordTotal Number
búsqueda
Cantidad de registros que se devuelven en la actual
RecordCount Number
transacción
Indica el orden del registro en la consulta, tomando como
Index Number referencia para ordenar el valor del campo OrderBy; el
index se refiere a RecordTotal
IMEI String Número de IMEI
IMSI String Número de IMSI
List String Lista en la cual se encuentran en IMEI o IMSI
Detalle del motivo por el cual se agregó en la lista
Motive String
indicada
Origin String Origen desde el cual se agregó en la lista

Ejemplo:
OK;GET_DATA_IN_LIST;KEY1234567890ABCDE*;RecordTotal=3;
RecordCount=3;Record1=1,1234567890ABCDED,,BLACK,Robo,Argentina;
Record2=2,1234567890ABCDEE,,BLACK,Extraviado,Argentina;
Record3=3,1234567890ABCDEF,,BLACK,Robo,Argentina

Errores posibles del comando GET_DATA_IN_LIST:

Código Detalle
100 Campo inválido
104 Dato Inválido

2.4.9 Consultar lista de eventos de un IMEI o un IMSI
Descripción: obtiene los datos de una lista de eventos asociados a un IMEI o a
un IMSI, dentro de un rango de fechas determinado. Es importante tener en
cuenta que las fechas y horas están en GMT en el sistema: Por lo tanto la
recepción y el envío de las fechas y horas deben estar dentro de esta modalidad.
La consulta puede efectuarse mediante alguno de los dos campos (IMEI o IMSI):

Campo Descripción
IMEI Se toma este campo como clave
Si el IMEI no se encuentra en la consulta y se envía el IMSI, se toma este último
IMSI
como clave



GET_EVENTS;IMEI=<Value>;IMSI=<Value>;DateFrom=<Value>;DateTo=
<Value>;OrderBy=<Value>;LastIndexRecord=<Value>;Description=
<Value>

Número de IMEI acerca del cual
se consultarán los eventos. Si
IMEI - String este campo NO forma parte de
la consulta, debe estar indicado
el campo IMSI
Número de IMSI acerca del cual
se consultarán los eventos. Si
IMSI - String este campo no forma parte de la
consulta, debe estar indicado el
campo IMEI
En formato yyyy/mm/dd o bien
1901/01/01
DateFrom NO Date en formato yyyy/mm/dd hh:mi:ss
00:00:00
(GMT)
En formato yyyy/mm/dd o bien
3000/01/01
DateTo NO Date en formato yyyy/mm/dd hh:mi:ss
00:00:00
(GMT)
campo por el cual ordenará la
consulta. Los valores posibles
son: ‘IMEI’, ‘IMSI’,’DATE’. Por
IMEI|IMSI|
OrderBy NO String default es por el IMEI o el IMSI,
IMEI,IMSI
o por el IMEI y el IMSI,
dependiendo del tipo de lista
que sea
Indice que indica a partir de
dónde se desea consultar. Este
índice se refiere al campo
LastIndexRecord NO 0 Number OrderBy y está comprendido
entre 0 y RecordTotal. Para
iniciar la consulta se debe
enviar 0

Ejemplo:
GET_EVENTS;IMEI=1234567890ABCDEF;DateFrom=2004/12/01;DateTo=2005/0
1/01;OrderBy=DATE_FROM;LastIndexRecord=0

Respuesta:
OK;GET_EVENTS;KEY=<IMEI Value|IMSI Value>;RecordTotal=<Value>;
RecordCount=<N>;
Event1=<Index,IMEI,IMSI,Result,Date>;Event2=<…>;…;EventN=
<Index,IMEI,IMSI,Result,Date>

Cantidad de registros que cumplen con la condición de
RecordTotal Number
búsqueda
Cantidad de registros que se devuelven en la actual
RecordCount Number
transacción
Indica el orden del registro en la consulta, tomando como
Index Number referencia para ordenar lo que vino en OrderBy; el index
es en relación a RecordTotal
IMEI String IMEI que generó el evento



IMSI String IMSI que generó el evento
Resultado devuelto. Valores posibles: ‘U’: Unknown, ‘W’:
Result String
White List, ‘G’: Gray List o ‘B’: Black List
Date Date Formato yyyy/mm/dd hh:mi:ss (GMT)

Ejemplo:
OK;GET_EVENTS;KEY=1234567890ABCDEF;RecordTotal=2;RecordCount=2;Eve
nt1=1,1234567890ABCDEF,,'B',2004/12/01
10:02:45;Event2=2,123456789ABCDEF,,'G',2004/12/05 23:34:23

Errores posibles del comando GET_EVENTS:

Código Detalle
100 Campo inválido
104 Dato Inválido
105 Formato de fecha inválido

2.4.10 Pasar a Emergencia
Descripción: modifica el estado del sistema, pasándolo de funcionamiento
"normal" a "emergencia" o viceversa. En el caso del pasaje a "emergencia", se
debe indicar además el resultado que retornará a la red celular.

SET_SYSTEM_STATE;State=<Value>;Result=<Value>;Description=<Value>

Valor que actualizará el estado
State SI String actual del sistema. Valores Posibles:
‘N’: Normal o ‘E’: Emergency
Resultado que devolverá si un
ChekIMEI se encuentra en estado
Result NO W String de Emergencia. Valores Posibles:
‘U’: Unknown, ‘W’: White List, ‘G’:
Gray List o ‘B’: Black List
Texto Libre que será impactado en



Ejemplo:
SET_SYSTEM_STATE;State=E,Result=W

Respuesta:
OK;SET_SYSTEM_STATE;KEY=<State>

Ejemplo:
OK;SET_SYSTEM_STATE;KEY=E

Errores posibles del comando SET_SYSTEM_STATE:

Código Detalle
100 Campo inválido
104 Dato Inválido

2.4.11 Simular un CheckIMEI
Descripción: simula la ejecución de la función de red CheckIMEI.

CHECK_IMEI;IMEI=<Value>;IMSI=<Value>;Description=<Value>

IMEI - String IMEI cuyo perfil se desa verificar
IMSI - String IMSI cuyo perfil se desa verificar
Description N Null String
log de auditoría.

Ejemplo:
CHECK_IMEI;IMEI=1234567890ABCDEF;Description=JLOPEZ

Respuesta:



OK;CHECK_IMEI;KEY=<IMEI Value|IMSI Value|IMEI Value,IMSI
Value>;Lists=
<list1,list2..listn>;
Result=<Value>;SMS=<Value>;Trace=<Value>;File=<Valuel>;
CKD=<Value>;email=<Value>

Retorna una serie de listas en las que fue encontrado el
Lists String
IMEI o el IMSI
Valores posibles: ‘B’: Black List, ‘G’: Gray List, ‘W’: White
Result String
List, ‘U’: Unknown
SMS String Indica si debe enviar SMS. Valores Posibles: ‘YES’, ‘NO’
Indica si se debe trazar la llamada. Valores Posibles:
Trace String
‘YES’, ‘NO’
Indica si se registra en archivo. Valores Posibles: ‘YES’,
FILE String
‘NO’
CKD String Indica si se guarda el CKD. Valores Posibles: ‘YES’, ‘NO’
Email String Indica si se envía un e-mail. Valores posibles: ‘YES’, ‘NO’

Ejemplo:
OK;CHECK_IMEI;KEY=1234567890ABCDEF;Lists=BLACK,GRAY;Result=B;SMS=N
O;
Trace=NO;File=YES;CKD=NO;Email=NO

Errores posibles del comando CHECK_IMEI:

Código Detalle
100 Campo inválido
104 Dato Inválido
105 Formato de fecha inválido

2.4.12 Alta de IMEI o IMSI con verificación de unicidad
Descripción: realiza el alta de un IMEI o un IMSI en una lista determinada,
verificando la existencia previa del IMEI o del IMSI en cualquier otra lista,
teniendo en cuenta las siguientes condiciones:



IMEI/IMSI
existe en otra Procedimiento a realizar
lista
El alta se realiza en modo normal en la lista indicada como parámetro de la
NO
función
Se da de baja el IMEI o el IMSI en la lista donde existe actualmente y se lo inserta
SI
en la lista parámetro de la función


El alta se realiza en modo normal y el % será interpretado por los procesos
Funcional (%)
internos del sistema receptor
De carga (*) posibles; esto permite un alta con verificación de pre-existencia masiva. Retorna
la cantidad que se pudo dar de alta

ADD_MOVE_IN_LIST;IMEI=<Value>;IMSI=<Value>;List=<Value>;Motive=<Va
lue>;Origin=<Value>;Description=<Value>

IMEI a ingresar. Este campo es
IMEI - String requerido sólo si la lista lo
contempla
IMSI a ingresar. Este campo es
IMSI - String requerido sólo si la lista lo
contempla
Lista en la cual se insertarán los
IMEI o IMSI. Este valor deberá ser
List SI String
el indicador de una lista definida en
el sistema
Motive NO Null String
inserta en la lista indicada
Origin NO Null String
operador, etc.
el log de auditoría.

Ejemplo:
ADD_MOVE_IN_LIST;IMEI=1234567890ABCDEF;List=BLACK;Motive=Robo;
Origin=Argentina;Description=JLOPEZ

Respuesta:
OK;ADD_MOVE_IN_LIST;KEY=<IMEI Value|IMSI Value|IMEI Value,IMSI
Value>;
Count=<Value>



Ejemplo:
OK,ADD_MOVE_IN_LIST;KEY=1234567890ABCDEF;Count=1

Errores posibles del comando ADD_MOVE_IN_LIST:

Código Detalle
100 Campo inválido
104 Dato Inválido

2.4.13 Respuesta al cliente
2.4.13.1 Comandos erróneos
Cuando se produzca un error al procesar el comando se enviará la siguiente
respuesta:
ERR;<command>;KEY=<key>;CODE=<error code>;
DESCRIPTION=<error’s description>

Ejemplo:
ERR;ADD_IN_LIST;KEY=1234567890ABCDEF;CODE=1234;
DESCRIPTION=ERROR 1234


Interfaces de Programación Módulo SensIT-EIR Batch

3
3. Módulo SensIT-EIR Batch
3.1 Introducción

El módulo SensIT-EIR Batch puede ser utilizado por las aplicaciones externas a
la plataforma para interactuar con el producto SensIT-EIR mediante el
procesamiento por lotes.
A diferencia del módulo SensIT-EIR API, donde las transacciones se realizan en
línea a través de una conexión TCP/IP, el módulo SensIT-EIR Batch recibe
archivos con comandos a ejecutar y devuelve en forma asincrónica, archivos con
respuestas a los comandos enunciados.
Además de estos archivos creados en forma reactiva, el módulo genera y envía
proactivamente algunos archivos.
El modo de intercambiar archivos, es enviándolos a un directorio del servidor
donde se encuentra el módulo SensIT-EIR Batch, que previamente fue
designado a tal efecto. Los archivos de respuestas, archivos de listas y archivos
de eventos son almacenados en otro directorio del mismo servidor. Existe la
posibilidad de configurar el envío de estos archivos por FTP.
El módulo SensIT-EIR Batch cuenta con varios procesos. Cada uno de ellos
tiene una funcionalidad y una configuración propia.
Es importante señalar que las consideraciones generales detalladas en el
módulo SensIT-EIR API aplican a este módulo.

En el siguiente diagrama se grafican estos procesos:



Figura 2: Funcionalidad del módulo SensIT EIR Batch



3.1.1 Proceso File Transfer
Es el proceso que envía los archivos de respuestas, listas y eventos a un
servidor FTP configurado.

3.1.2 Proceso de Altas y Bajas
Este proceso lee y ejecuta comandos de altas y bajas de lista, que se
encuentran almacenados en un archivo de entrada. Por cada archivo de entrada
se generan dos archivos de salida: uno con el resultado de las operaciones y el
otro con los errores ocurridos.
El procesamiento de cada archivo tiene dos modalidades:

No atómica: esta modalidad procesa cada registro de manera separada
devolviendo en el archivo de respuesta si la operación fue exitosa o no. El
procesamiento no se detiene frente a un resultado erróneo.

Atómica: esta modalidad procesa las transacciones si su resultado es
exitoso. Frente al primer resultado erróneo detiene el procesamiento y
deshace todo lo ejecutado hasta esa instancia. En el archivo de resultado
quedarán registradas todas las operaciones exitosas a excepción de la
última, que tendrá resultado erróneo.

3.1.3 Proceso de Consultas
Este proceso toma las consultas de un archivo de entrada y genera un archivo
de salida con las respuestas.

3.1.4 Proceso de exportación de Eventos
Este proceso genera un archivo con los eventos ocurridos en intervalos
configurables.

3.1.5 Proceso de exportación de Listas
Este proceso genera un archivo con las listas en intervalos configurables.

3.2 Archivos
Los archivos, tanto de entrada como de salida, tienen formato ASCII. Los
registros estarán separados por 0xa.
Existe un potencial problema referido a la transferencia o generación de
archivos, que consiste en el intento de lectura del mismo antes de la generación
del archivo de respuesta.
La solución consiste en generar un archivo con el mismo nombre que el archivo
de datos, localizado en el mismo directorio y con extensión *.FLG.



Existen diferentes tipos de archivos:

Archivo de entrada del proceso de altas y bajas

Archivo de salida del proceso de altas y bajas

Archivo de entrada del proceso de consulta

Archivo de salida del proceso de consulta

Archivo de eventos

Archivo de listas

3.2.1 Nomenclatura de los archivos
Los nombres de los archivos tienen la siguiente estructura:
EIR_BATCH_<identificador de proceso>_<Fecha>_<Seq>.txt
Donde:

Identificador del proceso: debe reemplazarse por:

Identificador del Proceso Descripción
AB_REQ Requerimiento de altas y bajas.
AB_RES Respuesta al requerimiento de altas y bajas.
CON_REQ Requerimiento de consulta.
CON_RES Respuesta al requerimiento de consulta.
EVENT Archivo de Eventos.
LIST Archivo de Lista.

Fecha: debe reemplazarse por el formato YYYYMMDDHHMMSS (fecha y
hora) de generación de archivo.

Seq: número de secuencia distinguible para la misma fecha y hora. Posee
tres dígitos elegidos por el usuario. Por Ejemplo: 001, 002, 003, …etc.



3.2.2 Archivo de entrada del proceso de altas y bajas
El formato del archivo consiste en un registro de cabecera y N registros.

Campo de cabecera Tipo Valor
Versión String Versión 3.0.3
FieldSeparator String ;
ProcessingMode String [ATOMIC | NONATOMIC]
RecordSeparator String 0xa

En el archivo de datos pueden existir los siguientes comandos:

Alta de un IMEI o de un IMSI en una lista. Cada registro de este tipo tiene el
siguiente formato:

Campo de Alta Obligatorio Tipo Valor Descripción
Ver la sección de
TransactionCode SI String ADD_IN_LIST
Comandos EIR API
FieldSeparator SI String ; Separador de campo
IMEI a insertar en una
IMEI NO String <IMEI>
lista
IMSI a insertar en una
IMSI NO String <IMSI>
lista.
Lista a la cual se insertará
List SI String <Lista>
un IMSI o un IMEI
Detalle del motivo por el
Motive SI String <Motivo> cual se agrega a la lista
indicada
Normalmente se utiliza
para indicar el origen de
la información. Por
Origin SI String <Origen>
ejemplo: zona geográfica,
país, nombre de
operador, etc.
RecordSeparator SI Char 0xa Separador de mensajes

Alta con verificación de un IMEI o de un IMSI en una lista. Cada registro de
este tipo tiene el siguiente formato:

Campo de
Obligatorio Tipo Descripción
Alta
TransactionCod Ver la sección de
SI String ADD_MOVE_IN_LIST
e Comandos EIR API.
IMEI a insertar en una
lista



Campo de
Obligatorio Tipo Descripción
Alta
IMSI a insertar en una
lista
Lista a la cual se insertará
un IMSI o un IMEI
Detalle del motivo por el
Motive SI String <Motivo> cual se agrega a la lista
indicada
Normalmente se utiliza
para indicar el origen de
la información. Por
Origin SI String <Origen>
ejemplo: zona geográfica,
país, nombre de
operador, etc.
Descripción que será
Description SI String <Descripción> grabada en el log de
operaciones
RecordSeparato
SI Char 0xa Separador de mensajes
r

Baja de un IMEI o de un IMSI de una lista. Cada registro tiene el siguiente
formato:

Campo de
Obligatorio Tipo Valor Descripción
Baja
Ver la sección de
TransactionCode SI String DELETE_FROM_LIST
Comandos EIR APIs
IMEI NO String <IMEI> IMEI a eliminar de una lista
IMSI NO String <IMSI> IMSI a eliminar de una lista
Lista desde la cual se
borrará el IMSI o el IMEI

3.2.3 Archivo de salida del proceso de altas y bajas
En este archivo, se devuelven los resultados de las operaciones requeridas en el
archivo de entrada de altas y bajas.
El primer registro, es de cabecera e indica la modalidad de procesamiento. El
mismo tiene el siguiente formato:

Campo de Cabecera Tipo Valor

FieldSeparator String Separador de campo



Tiene el mismo valor que el encabezado del
ProcessingMode String
archivo de entrada

RecordSeparator Char 0xa

Para cada registro de alta o baja se retorna un registro con el siguiente formato:

Campo de Salida Valor Descripción
Número de registro que se
InputRecordNumber ; corresponde con el archivo de
entrada
FieldSeparator ; Separador de campo
Result [ OK|ERROR] Resultado del proceso
ErrorCode <Código> Código de error interno
ErrorDescription <Error> Información acerca del error
IMEI <IMEI> IMEI a enviar a una lista
IMSI <IMSI> IMSI a enviar a una lista
FieldSeparator ; Separador de Campo
Lista desde la cual se borraron los
ListDel <Lista>
IMEI o IMSI
Lista desde la cual se agregaron
ListAdd <Lista>
los IMEI o IMSI
RecordSeparator 0xa Separador de mensajes

3.2.4 Archivo de entrada del proceso de Consultas
El registro de cabecera tiene el siguiente formato:

Campo de cabecera Tipo Valor

En el contenido de este tipo de archivo pueden visualizarse los siguientes
comandos:

Consultar datos de un IMEI o de un IMSI en una lista. Los registros de este
tipo tienen el siguiente formato:

Campo de
Entrada
Ver sección de
TransactionCode SI String GET_DATA_IN_LIST
Comandos EIR APIs



Campo de
Entrada
Este campo es requerido
IMEI NO String <IMEI> sólo si la lista lo
contempla
Este campo es requerido
IMSI NO String <IMSI> sólo si la lista lo
contempla
List SI String <Lista> Lista a consultar
Campo por el cual se
ordenará la consulta.
Dependiendo del tipo de
[IMEI | IMSI | LIST | lista que sea, el default
OrderBy NO String
MOTIVE | ORIGIN] es:
- Por el IMEI o el IMSI
- Por el IMEI y el IMSI

Consultar eventos de un IMEI o de un IMSI. Los registros de este tipo
tienen el siguiente formato:

Campo de Obligatori
Tipo Valor Descripción
Entrada o
Ver sección de
TransactionCode SI String GET_EVENTS
Comandos EIR APIs
FieldSeparator SI String ; Separador de campos
IMEI a consultar de una
lista
IMSI a consultar de una
lista
[yyyy/mm/dd |
DateFrom SI Date Formato de fecha
yyyy/mm/dd hh:mi:ss]
[yyyy/mm/dd |
DateTo SI Date Formato de fecha
yyyy/mm/dd hh:mi:ss]

3.2.5 Archivo de salida del proceso de Consulta
El registro de cabecera tiene el siguiente formato:




Para cada registro del archivo de entrada, existen uno o más registros en el
archivo de salida. El primer campo del archivo de salida indica el registro del
archivo de entrada correspondiente.
Los registros de este archivo tienen el siguiente formato, de acuerdo a la
operación solicitada en el archivo de entrada.

Consultar datos de un IMEI o de un IMSI en una lista

Campo de
Salida
InputRecordNumber Number <Número> corresponde con el archivo
de entrada
FieldSeparator String ; Separador de campo
Result String [OK | ERROR] Resultado de la consulta
ErrorCode String <Código> Código de error interno
ErrorDescription String <descripción error> Información acerca del error
IMEI String <IMEI> IMEI a consultar de una lista
IMSI String <IMSI> IMSI a consultar de una lista
Lista en la cual se encuentra
List String <Lista>
el IMSI o el IMEI
Detalle del motivo por el cual
Motive String <Motivo>
se consulta la lista
Normalmente se utiliza para
indicar el origen de la
Origin String <Origen> información. Por ejemplo:
zona geográfica, país,
nombre de operador

RecordSeparator Char 0xa Separador de mensajes

Consulta de eventos de un IMEI o un IMSI.

Campo de
Salida
InputRecordNumber Number <Número> corresponde con el archivo
de entrada
Result String [OK | ERROR] Resultado del evento
ErrorCode String <Código> Código de error interno
ErrorDescription String <Descripción error> Texto informativo del error


Dman esp eirs_inter-prog

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie Dman esp eirs_inter-prog

Ähnlich wie Dman esp eirs_inter-prog (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Dman esp eirs_inter-prog