vtol client java - manual librería 1.1
TRANSCRIPT
VTOL CLIENT JAVA - Manual librería 1.1.10
Manual de referencia técnica
Manual librería VTOLClient Java
Cambios por Revisiones
Fecha Revisión Observaciones
24/01/2005 1.0 Generación del documento
24/11/2005 1.1 Inclusión campo 74,75
21/03/2006 1.2 Encriptacion
19/07/2006 1.3 Agregado campos para transacciones de debito
22/09/2006 1.4 Libreria para vb
02/10/2006 1.5 Agregado y actualización de información de la librería JAVA.
14/05/2007 1.6 Reestructuración del documento. Incorporación de información del protocolo VTOL (llavecitas)
05/10/2010 1.7 Agregado de parámetro de configuración librería dinámica TOTALNODESNUMBER y INITIALNODENUMBER
19/04/2012 1.8 Agregado de mayor flexibilidad para configurar los archivos de configuración. Agregado de logeo nativo de Java.
01/09/2014 1.9 Revisión de parámetros de configuración de la librería.
10/02/2015 1.10 Agregado de la modalidad VirtualVTOLClient para locales virtuales donde VTOL Server gestionará la asignación de nodos.
01/12/2016 1.11 Agregado de comunicación sobre protocolo SSL. Detalle de los nuevos parámetros de configuración disponibles para SSL.
28/03/2018 1.12 Modificación en las revisiones del documento.
Índice
1. Introducción1.1 Introducción1.2 Protocolo de comunicación POS - VTOL
1.2.1 Header1.2.2 Mensaje1.2.3 Escape de caracteres
1.3 Tipos de mensajes1.4 Estructura de los mensajes1.5 Mecanismo de "Tercer Mensaje"
1.5.1 Descripción1.5.2 Control de operaciones pendientes (mensaje "CheckPending")1.5.3 Tercer Mensaje con múltiples operaciones
2. Uso de la librería2.1 Implementación2.2 Modalidades
2.2.1 Pasos para el uso2.2.2 Parámetros posibles de inicialización2.2.3 Métodos de VTOLClient2.2.4 Métodos de VTOLNode2.2.5 Interface VTOLClientFinder2.2.6 Manejo de errores2.2.7 Encriptación2.2.8 Campos Pre-configurados2.2.9 Parámetros Pre-configurados
2.2.10 Logging3. Ejemplos de uso de la librería
3.1 Acceso a VTOL Server desde Java3.1.1 Ejemplos de modo de uso Static3.1.2 Ejemplos de modo de uso Dinámico3.1.3 Ejemplos de modo de uso Virtual
1. Introducción
1.1 Introducción
VTOL cuenta con una librería desarrollada en Java la cual provee las funciones necesarias para realizar autorizaciones de diversos tipos de transacciones, además de las transacciones de control propio y común a cualquier implementación de VTOL Server.La librería es en realidad un módulo cliente que se comunica vía TCP/IP con el servidor de transacciones (VTOL).A continuación se hará una descripción de los contenidos de la librería que ayudarán a comprender su funcionamiento. Antes se hará una introducción a la .Mensajería de VTOL
1.2 Protocolo de comunicación POS - VTOL
Se establece un protocolo de comunicación para la interacción POS - VTOL, el cual se denomina "Protocolo VTOL" o "llavecitas". Dicho protocolo se basa en un esquema recursivo compuesto por campos y separadores. A continuación se provee una especificación detallada de su estructura junto con los consecuentes diagramas para un mejor entendimiento.Para implementar esta mensajería, VTOL provee una librería en el cual se encuentra la declaración de funciones y las definiciones de constantes y tipos necesarias. La librería es en realidad un módulo cliente que se comunica vía TCP/IP con el servidor de transacciones VTOL. El cliente podrá implementar esta mensajería sin utilizar la librería, pero deberá respetar el formato de la misma.
El formato del protocolo VTOL se basa en la siguiente estructura:
Header Mensaje
Longitud del mensaje (4 bytes) Indica si el mensaje requiere respuesta o no (2 bytes) Ejemplo: {25:20020426172836;1:5;2:1;27:00;26:ISO8583;28:Aprobado}
La estructura posee dos partes separadas que son el Header y el Mensaje propiamente dicho.
1.2.1 Header
Dentro del Header viaja información específica del mensaje que se encuentra a continuación del mismo, como ser su longitud y si requiere o no una respuesta. Para ello fueron destinados 6 bytes que se distribuyen de la siguiente manera: los primeros 4 bytes son destinados a la longitud (expresado en hexadecimal, con el último byte como el más significativo) y los últimos 2 indican la necesidad de recibir o no una respuesta (expresado en hexadecimal, con el último byte como el más significativo) Un ejemplo de lo explicado anteriormente podría ser el siguiente:
1.
HEADER
Longitud del mensaje Requiere respuesta
A101 01
En este ejemplo la longitud del mensaje será:
0001 0000 0001 1010= 2 + 2 + 2 + 2 = 1 0 1 A 12 4 3 1 4122
1.2.2 Mensaje
A continuación del Header se encuentra el Mensaje propiamente dicho, el cual contiene la información que el emisor desea transmitirle al sistema receptor. La estructura de los mensajes son que se muestra en la siguiente ilustración:
Simple
El mensaje viajará encerrado entre " " (llaves). Cada campo del mismo se compondrá de la siguiente manera: los primeros dígitos indicarán el número de campo y a partir de los " " (dos puntos) se encontrará { } :el valor del campo. Los campos viajan separados por " " (punto y coma).;
Ejemplo:
{1:5;2:1;26:ISO8583;27:00;28:Aprobado}
El mensaje anterior posee 5 campos, los cuales se identifican con los números 1, 2, 26, 27 y 28. A continuación de cada uno de ellos (luego del separador " ") se encuentra el valor de cada campo. En el :ejemplo presentado, para el campo 1 el valor es "5", para el campo 2 el valor es "1" y así sucesivamente.
1.2.3 Escape de caracteres
Para realizar el escape de un caracter especial se deberá usar " " inmediatamente antes del carácter a escapar.\
Nota: Se ordena la longitud A101colocando el byte más significativo a la izquierda, con lo cual resulta: 101A.
Ejemplo:
A continuación se presenta un campo cuyo valor incluye el carácter y se muestra como escapar el mismo:;
{1:14 56} \;
1.3 Tipos de mensajes
Solicitud de Autorización, este mensaje lo genera el punto de venta cada vez que se requiere autorizar una operación. Se envían los datos requeridos de acuerdo al tipo de operación. Adicionalmente se envía información de control de mensajes.Respuesta de Autorización, este mensaje lo genera VTOL para el punto de venta, en respuesta a cada Solicitud de Autorización y contiene información tanto de resultado de la operación como de control.Confirmación (Tercer mensaje), este mensaje lo genera el punto de venta para informar como ha terminado de procesar la respuesta de una operación. No se genera respuesta para este mensaje.Solicitud de Control de Pendientes, este mensaje lo genera el punto de venta, para asegurar que ha confirmado el estado de todas las operaciones.Respuesta de Control de Pendientes, este mensaje lo genera VTOL para el punto de venta, en respuesta a cada Solicitud de Control de Pendientes e informa si existen operaciones pendientes de confirmación.
1.4 Estructura de los mensajes
Para referencia sobre la estructura de cada uno de los tipos de mensajes mencionados con antelación, consultar el documento ubicado en el repositorio del producto VTOL."Mensajería POS – VTOL"
1.5 Mecanismo de "Tercer Mensaje"
1.5.1 Descripción
El tercer mensaje es un mecanismo para asegurar la consistencia y concordancia de las transacciones realizadas que son registradas en VTOL.
El flujo de mensajes es el siguiente:Se envía un requerimiento de autorización a VTOL. Si el requerimiento es autorizado, el POS guarda el ID de la trx recibido en la respuesta.Una vez conocido el estado final de la trx en el POS (es decir si la misma se procesa o bien se anula), el POS envía el 3er Msg con el CIT correspondiente, informando a VTOL el destino que tuvo la trx en cuestión. Las posibilidades en este caso son COMMIT o ROLLBACK.
Cada transacción aprobada debe ser confirmada o reversada con un tercer mensaje. Si se envía una transacción y no se confirma o reversa, a la próxima transacción que se envíe VTOL responderá que aún existe una transacción pendiente y hasta que no se envíe el tercer mensaje correspondiente no se podrá tratar la misma.
El tercer mensaje puede enviarse "embebido" en un requerimiento. Así en una misma transacción se enviará un requerimiento y la confirmación o reverso de una transacción pendiente. Una operación de venta en el POS podrá tener una o más transacciones de pago electrónico validadas por intermedio de VTOL (trx VTOL). Importante:
Para el envío del 3er Msg debe establecerse una condición por la que se da por finalizada la venta en el POS. Esta condición podría ser el registro de la transacción o la impresión del comprobante, pero se deberá tener en cuenta que para confirmar una trx VTOL, se tiene que asegurar que la venta que contiene esa trx sea procesada por el POS, que se emitan los comprobantes correspondientes, etc. Por otro lado, si la venta en el POS se registra como anulada o directamente no se registra (ya sea por pedido del operador, por un error del Controlador Fiscal, etc) debemos estar seguros de que en el 3er Msg de las trx correspondientes vaya la orden de ROLLBACK para esta trx.
1. 2. 3.
4.
1.5.2 Control de operaciones pendientes (mensaje "CheckPending")
Los mensajes de confirmación no son respondidos por VTOL Server. Además estos mensajes pueden ser embebidos en futuros mensajes de pedido de autorización esto da lugar a que algunas operaciones queden pendientes de confirmación entre dos transacciones distintas. La última transacción antes de el cierre o caída del punto de venta podría ocasionar dicha contingencia ya que no existiría un futuro mensaje de confirmación o pedido de autorización con la confirmación embebida. Para asegurar que ninguna transacción quedó pendiente de confirmación en VTOL se deberán aplicar los siguientes pasos:
El punto de venta enviara un mensaje de chequeo de pendientes "CheckPending" a VTOL.VTOL Server verificará la existencia de transacciones pendientes en su base, en caso de existir responderá el mensaje con el identificador (ID) de la transacción pendiente.El punto de venta deberá confirmar dicha transacción (Commit/Rollback) y enviar un nuevo mensaje de chequeo de pendientes. Nótese que esto se podría realizar en un solo paso, enviando un mensaje de chequeo de pendientes con la confirmación embebida.Se deberá repetir el proceso hasta tanto existan transacciones pendientes en VTOL. Cuando ya no existan VTOL responderá APROBADA.
1.5.3 Tercer Mensaje con múltiples operaciones
También existe la posibilidad de deshabilitar el chequeo de pendientes. Esto permite realizar un conjunto de transacciones que podrán ser confirmadas o reversadas posteriormente. Por ejemplo:
La implementación del Tercer Mensaje y Mensajes de Control de Pendientes, dependerá del tipo de integración que se realiza en el Punto de Venta, y quedará a elección del cliente utilizar algunos, o todos los Mensajes descriptos.
Los campos que debe contener el tercer mensaje son los siguientes:
TransactionTypeFieldId debe tener el valor UnSyncCompletionDateTimeFieldIdNodeFieldId (debe ser el valor recibido en este mismo campo en el mensaje de respuesta de la transacción original que se intenta completar)TrxIdFieldId (debe ser el valor recibido en este mismo campo en el mensaje de respuesta de la transacción original que se intenta completar)TrxActionFieldId (este campo define si lo que se quiere hacer es confirmar la transacción ( ), o bien reversarla ( ))UnSyncCommit Rollback
2. Uso de la librería
2.1 Implementación
Se pueden adoptar diferentes políticas al momento de implementar la librería cliente. Una de ellas es implementarla en cada punto de venta, por lo cual se le deberá incorporar la lógica suficiente a cada uno para que puedan manejar la librería y mediante la misma comunicarse con VTOL Server.
Incorporándola en cada punto de venta
Un ejemplo de este uso sería una línea de cajas de un supermercado. Otra forma sería centralizar todo en un módulo cliente al cual se le incorporaría la lógica para usar la librería y mediante la misma comunicarse con VTOL Server. De esta manera la implementación no impactaría en los puntos de venta.
Implementándola en un módulo cliente
1. 1.
2. 1.
3. 1.
1. 2. 3. 4. 5. 6. 7.
Un ejemplo de esta modalidad sería el uso de la librería en un sitio WEB donde no necesariamente existen nodos estáticos.
2.2 Modalidades
Como se explicó con anterioridad la librería cuenta con dos modalidades, por lo tanto, en Java existen dos implementaciones:
StaticVTOLClientEsta implementación está orientada a ser utilizada por cada punto de venta donde el Originador y el Nodo sean fijos.
DinamicVTOLClientEsta implementación está orientada a concentrar varios puntos de venta donde el Originador sea fijo y el nodo se obtenga de forma dinámica entre la librería y VTOL (Se hace por medio de un mensaje ).HandShake
VirtualVTOLClientEsta implementación está orientada a ser utilizada por varios puntos de venta o en un ambiente de e-commerce donde el Originador sea fijo y VTOL gestione la asignación de nodos (Locales virtuales).
2.2.1 Pasos para el uso
Para utilizar la librería java hay que seguir los siguientes pasos:
crear una instancia de VTOLClient.cargarle los parámetros correspondientes.inicializar el clientetomar un nodoconstruir una transacción.enviar el mensaje.devolver el nodo.
2.2.2 Parámetros posibles de inicialización
Las siguientes constantes deben ser inicializadas para hacer uso de la librería:
Nombre constante Descripción
HOSTIP
Identifica el parámetro que se usa para determinar la IP de VTOL Server
HOSTPORT
Identifica el port TCP al cual se tiene que conectar con VTOL Server
RESPONSETIMEOUT [Opcional]
Tiempo máximo en (milisegundos) de espera para un respuesta de VTOL server antes de salir por timeout. Superado este tiempo se lanza la excepción TimeoutClientException.
Valor por defecto 30000.
TIMEOUTCONNECTIONHOST [Opcional]
Tiempo máximo de conexión a VTOL Server expresado en milisegundos. Superado este valor y no lograda la conexión, se arroja la excepción VtolClientException
Un valor de cero significa infinito.
Valor por defecto 20000.
TIMEOUTOBTAINNODE
Tiempo máximo en milisegundos a esperará antes de arrojar una excepción al tratar de obtener un nodo.
TIMEOUTEXPIRATIONNODE
Identifica el parámetro utilizado para indicar el tiempo en liberar un nodo. En caso de no liberarse dentro de ese tiempo, será liberado por la aplicación.
USEVTOLCLIENTFINDER
Establece la utilización o no del VTOLClientFinder. El VTOL CLIENT FINDER es una manera de determinar qué acción tomar en caso de existir una transacción pendiente al momento de intentar autorizar una transacción. Si éste parámetro está desactivado, entonces ante una respuesta de transacción pendiente, se le devolverá el control al código de la aplicación integradora. Si éste parámetro está activado, entonces se tomará la acción (Commit o Rollback) que es determinado por el método configurado en el parámetro CLIENTFINDERValores posible:
True
False (valor por defecto)
CLIENTFINDER [Opcional]
Este parámetro será utilizado si está activo el parámetro . USEVTOLCLIENTFINDERValores posible:
R (siempre determinada realizar un Rollback de la transacción pendiente)
C (siempre determinada realizar un Commit de la transacción pendiente, valor por defecto)
Nota: Existe la posibilidad de definir una implementación propia de la estrategia a utilizar para determinar la acción ante una transacción pendiente. La manera de hacerlo consiste en implementar la interfaz
ar.com.synthesis.vtol.client.VtolClientFinder
y configurarla antes de inicializar la librería, por ejemplo:
vtolClientLib.setVtolClientFinder(new MyTrxFinder());
vtolClientLib.init();
USEENCRYPTEDDATA Establece la utilización de encriptación en los mensajes. Valores posible:
TrueFalse (valor por defecto)
ENCRYPTER [Opcional]Tipo de encriptación (este parámetro es utilizado si está activo el parámetro USEENCRYPTEDDATA) Valores posible:
DES (valor por defecto)
DESede
ENCRYPTKEY [Opcional]Clave a utilizar en la encriptacion. En el caso del algoritmo DES, su largo debe ser de minimo 8 caracteres, En el caso del triple DES debe ser mas de minimo 24 caracteres. (este parametro es opcional si está activo el parámetro )USEENCRYPTEDDATA
USEPENDINGAUTOMATIC
[Opcional]Si está activo, cuando la librería envía una transaccion y VTOL responde con transaccion pendiente (incluye el trxId de la pendiente), si el trxId coincide con el trxId de la última transacción enviada, entonces hace un commit automático. Si no coincide hace un rollback automático. Este parámetro no debe usarse en conjunto con el parámetro USEVTOLCLIENTFINDERValores posible:
True
False (valor por defecto)
TOTALNODESNUMBER
[Opcional]Representa el número de nodos que estarán disponibles para el cliente de VTOL dinámico. Para garantizar un adecuado funcionamiento del parámetro es necesario que éste esté fijado al número de terminales + 1 que se tengan configuradas en VTOL. Este parámetro es necesario únicamente para versiones distintas a VTOL NT. Si este parámetro se encuentra declarado ya sea en inicialización o en el archivo de parámetros preconfigurados (ver sección 2.2.6) entonces no se hace el hadshake. Si por el contrario no se encuentra este parámetro en ninguna de las declaraciones antes mencionadas, la librería enviará el handshake. Si este parámetro es nulo o es cero entonces se utilizará el handshake para inicializar los nodos dinámicos.
DEFAULTTRANSACTIONSTATUS
[Opcional]Indica el estado por defecto de las transacciones cuando se está utilzando el parámetro TOTALNOD
ya sea a través de la inicialización de la librería o bien a través de los parámetros ESNUMBERpreconfigurados. Si el parámetro de no está configurado, entonces el TOTALNODESNUMERtransactionStatus se pasa por alto (emula el estado de la última transaccion procesada por el nodo informado por el HandShake, uso por compatiblidad hacia atrás). Nota: Es recomendable no utilizar éste parámetro salvo por recomendación de un especialista Valores posible:
C (valor por defecto)
R
INITIALNODENUMBER
[Opcional]Indica el numero de nodo desde donde se comenzará a crear los nodos (si no se usa el HandShake). Este parámetro es opcional, y si no se configura se tomará el valor por defecto 1. Este valor debe ser > 0. Por último este parámetro solo tiene sentido para el uso de la librería dinámica.
VTOLCLIENTLIBCONFIGPATH
[Opcional]Directorio donde se encuentra la configuracion de la librería. Si éste parámetro no está seteado, entonces se usuará la configuración base.
PRECONFIGUREDFIELDSFILENAME
[Opcional]Nombre del archivo (sin PATH) XML que contiene la configuracion de los campos pre-configurados. Por defecto es vtol-client-preconfigured-fields.xml
PRECONFIGUREDFIELD
[Opcional]Proporciona la funcionalidad adicional de indicar campos previamente configurados que se enviarán directamente en los mensajes a VTOL. El valor del parámetro está compuesto por 4 valores separados por comas, a continuación se detallan los mismos:
Posición Definición Valores disponibles
1 Número de campo Representa el número de campo que debe estar dado de alta en la mensajería de VTOL con el POS.
2 Valor del campo Es el valor que se enviará en la mensajería de VTOL con el POS
3 Tienda para el que aplica Se puede indicar alguno de los siguientes valores:
( * ) que indica que se aplica para todas las tiendas o bien el número específico de la tienda.
4 Nodo para el que aplica Se puede indicar alguno de los siguientes valores:
( * ) que indica que se aplica para todos los nodos o bien el número específico del nodo que enviará el parámetro indicado.
SSLENABLED Indica cuando la comunicación con VTOL está sobre SSL:
TrueFalse (valor por defecto)
SSLKEYSTORE Ruta del archivo que contiene los certificados que se usaran para la validación. OBLIGATORIO cuando el parámetro SSLENABLED es True.
SSLKEYSTOREPASSWORD Contraseña del archivo que contiene los certificados que se usaran para la validación. OBLIGATORIO cuando el parámetro SSLENABLED es True. Valor por defecto: .nosotros
SSLPROTOCOL Versión de protocolo SSL/TLS. OBLIGATORIO cuando el parámetro SSLENABLED es True. Valores posibles:
SSL: Supports some version of SSL; may support other versions.SSLv2: Supports SSL version 2 or later; may support other versions.SSLv3: Supports SSL version 3; may support other versions.TLS: Supports some version of TLS; may support other versions.TLSv1: Supports RFC 2246: TLS version 1.0; may support other versions.TLSv1.1: Supports RFC 4346: TLS version 1.1; may support other versions.TLSv1.2: Supports RFC 5246: TLS version 1.2; may support other versions.
2.2.3 Métodos de VTOLClient
Method Summary
ConnectionManager ()createConnectionManager Devuelve una instancia de la clase, con los valores de las constantes 2, 3 y 10.
TransactionFormat ()createTransactionFormat Devuelve una nueva instancia del objeto .VtolClientTransactionFormat
static VtolClient (java.lang.String _originator)getDynamicVtolClient Devuelve una unica instancia del objeto seteandole como originador a DinamicVtolClient _or
.iginator
java.lang.String ()getOriginator Devuelve el originador actual
java.lang.String (java.lang.String _nameString)getParameter Devuelve el parámetro cuyo nombre es pasado como parámetro del método.
static VtolClient ()getStaticVtolClient Devuelve una unica instancia del objeto .StaticVtolClient
static VtolClient (java.lang.String _originator)getStaticVtolClient Devuelve una unica instancia del objeto seteandole como originador a StaticVtolClient _origi
.nator
static VtolClient ()getUniqueInstanceOfVtolClient Devuelve una instancia del objeto .unica DinamicVtolClient
VtolClientFinder ()getVtolClientFinder
java.util.Vector ()getVtolNodesVector Retorna un vector de nodos.
void ()init Inicializa la clase
boolean ()isInitialized Retorna verdadero en caso de haber sido inicializado en caso contrario retorna falso.
void (boolean newInitialized)setInitialized Setea la variable de inicialización en verdadero o falso según lo indique el parámetro newInitialized
void (java.lang.String newOriginator)setOriginator Setea un nuevo originador.
void (java.lang.String _nameString, java.lang.String _valueString)setParameter Setea el parámetro de nombre _nameString, con el valor _valueString.
void ( vtolClientFinder)setVtolClientFinder VtolClientFinder
void (java.util.Vector newVtolNodesVector)setVtolNodesVector Setea un nuevo vector de nodos, según el parámetro
2.2.4 Métodos de VTOLNode
Method Summary
void (int _iFieldNumber, java.lang.String _valueString)addField Agregado el campo identificado por _iFieldNumber con el valor _valueString a la transacción previamente creada.
void ()createTransaction Crea una transacción nueva para el proceso de un requerimiento de autorización
ConnectionManager ()getConnectionManager Devuelve el connectionManager
Transaction ()getCurrentTransaction Devuelve la transaccion actual asociada al nodo.
DES ()getEncrypter Obtencion del encriptador
java.lang.String (int _iFieldNumber)getField Devuelve el valor del campo asociado al numero del campo ._iFieldNumber
Transaction ()getLastTransaction Devuelve la transaccion anterior a la actual.
java.lang.String ()getNodeId Devuelve el identificador del nodo o idetificador de Terminal(POS).
java.util.Date ()getObtainedDate Devuelve la fecha obtenida por el nodo.
java.lang.String ()getOriginator Devuelve el identificador del Originador o Tienda.
java.util.Collection ()getPreconfiguredFields
NodeStatus ()getStatus Devuelve el estado del nodo.
TransactionFormat ()getTransactionFormat Devuelve el objeto encargado de darle formato al transaccion asociada al nodo.
VtolClientFinder ()getVtolClientFinder Devuelve el objeto VtolClientFinder
boolean ()isUseVtolAutomaticPending
boolean ()isUseVtolClientFinder Indica si se esta utilizando un VtolClientFinder
void ()sendTransaction Envia a VTOL la transaccion asociada al nodo.
void ()sendTransactionWithoutResponse Envia la transaccion asociada al nodo a VTOL.
void setConnectionManager(ConnectionManager newConnectionManager) Setter del connectionManager
void ( newCurrentTransaction)setCurrentTransaction Transaction Seteo de la transaccion actual.
void ( encrypter)setEncrypter DES seteo de un encriptador
void ( newLastTransaction)setLastTransaction Transaction Setea la transaccion anterior.
void (java.lang.String newNodeId)setNodeId Seteo del identificador del nodo.
void (java.util.Date newObtainedDate)setObtainedDate seteo de la fecha obtenida.
void (java.lang.String newOriginator)setOriginator seteo de un nuevo originador.
void setPreconfiguredFields(java.util.Collection preconfiguredFields)
void ( newStatus)setStatus NodeStatus Seteo de un nuevo estado.
void ( newTransactionFormat)setTransactionFormat TransactionFormat Seteo de un nuevo formateador.
void (boolean useVtolAutomaticPending)setUseVtolAutomaticPending
void (boolean b)setUseVtolClientFinder Forma de indicar que se usa un VtolClientFinder
void ( newVtolClientFinder)setVtolClientFinder VtolClientFinder Seteo de un vtolClientFinder
2.2.5 Interface VTOLClientFinder
Esta interface la debe implementar una clase para poder setearse como el de la librería. Esta clase cumple con la función de determinar qué hacer si existe una transacción para cual VTOL VTOLClientFinderServer no conoce su estado. Cuando VTOL Server contesta un requerimiento indicando que una transacción está pendiente, librería llama al método getTransaction() para determinar qué acción debe tomar con esta transacción. La clase seteada por default para esta función devuelve siempre . La clase que se setee como tal, deberá buscar en la base de datos de la aplicación cual es el estado de la "Commit"misma y devolverlo para su correspondiente proceso.
2.2.6 Manejo de errores
public class VtolClientException extends java.lang.Exception
Esta clase identifica cualquier excepción ocurrida en la librería e indica la misma a través de su mensaje.
Constructor Summary
VtolClientException()
VtolClientException(java.lang.String _messageString)
VtolClientException(java.lang.String _codeString, java.lang.String _messageString)
Method Summary
java.lang.String getCode()
2.2.7 Encriptación
La librería brinda la posibilidad de encriptar los mensajes con el algoritmo DES y Triple DES utilizando la clase DES.
Para la utilización de la encriptación se deberá configurar las siguientes constantes:
USEENCRYPTEDDATAENCRYPTKEYENCRYPTER
(Ejemplo, ver 3.3 Acceso a VTOL/Server desde Java con encriptación de mensajes)
2.2.8 Campos Pre-configurados
La librería de Java proporciona la funcionalidad adicional de indicar campos previamente configurados que se enviarán directamente en los mensajes a VTOL. Existen formalmente dos maneras de realizar esta configuración, ya sea a través de los parámetros de inicialización o bien a través de un archivo xml (proporcionado con la aplicación). A continuación se detalla cada uno de estos casos.
InicializaciónLa desventaja que tiene esta manera de configurar es que solamente se puede proporcionar un campo pre-configurado. Por este motivo se recomienda que si se requiere tener más de uno de estos campos, se utilice el enfoque de la configuración vía XML. Los parámetros configurados previamente se pueden agregar al proceso de inicialización del cliente de VTOL que se decida utilizar (estático o dinámico). A continuación se muestra un ejemplo de inicialización de un cliente estático indicando el bloque de inicialización
…//seteo de parmatros, como ser conexión, timeout, encriptacion, etc.staticVTOLClient.setParameter("HOSTIP","127.0.0.1");staticVTOLClient.setParameter("HOSTPORT","3000");staticVTOLClient.setParameter("TIMEOUTCONNECTIONHOST","3000");staticVtolClient.setParameter("RESPONSETIMEOUT","30000");staticVTOLClient.setParameter("TIMEOUTEXPIRATIONNODE","10000");staticVTOLClient.setParameter("TIMEOUTOBTAINNODE","10000");staticVTOLClient.setParameter("USEVTOLCLIENTFINDER","");staticVTOLClient.setParameter("USEENCRYPTEDDATA","False");staticVTOLClient.setParameter("ENCRYPTKEY","");staticVTOLClient.setParameter("ENCRYPTER","");//Inicialización del campo previamente configurado.staticVtolClient.setParameter("PRECONFIGUREDFIELD","115,2,1,1");…
El nombre del parámetro necesariamente es PRECONFIGUREDFIELDEl valor del parámetro está compuesto por 4 valores separados por comas, a continuación se detallan los mismos:
Posición Definición Valores disponibles
1 Número de campo Representa el número de campo que debe estar dado de alta en la mensajería de VTOL con el POS.
2 Valor del campo Es el valor que se enviará en la mensajería de VTOL con el POS
3 Tienda para el que aplica Se puede indicar alguno de los siguientes valores: ( * ) que indica que se aplica para todas las tiendas o bien el número específico de la tienda.
4 Nodo para el que aplica Se puede indicar alguno de los siguientes valores: ( * ) que indica que se aplica para todos los nodos o bien el número específico del nodo que enviará el parámetro indicado.
Con esto podemos tener 4 combinaciones
Enviar el parámetro para todas las tiendas y todos los nodos.Enviar el parámetro para todas las tiendas y un nodo.Enviar el parámetro para una tienda y todos los nodos.Enviar el parámetro para una tienda y un nodo.
Como se puede ver esta manera de configurar parámetros da cierta flexibilidad en caso de tener bien identificado un campo que se quiera manejar como constante y que aplique para una de las combinaciones anteriormente descritas. Sin embargo si se desea tener mayor flexibilidad es conveniente utilizar la configuración por XML que se detalla a continuación.
Configuración vía XMLPara las configuraciones a través de archivos XML tenemos más flexibilidad. Además no requiere de modificación alguna en la implementación de la librería por parte del cliente, ya que toda la configuración se hace por fuera. La parte fundamental de este enfoque es el archivo XML, a continuación se muestra la estructura del mismo:
<?xml version="1.0" encoding="UTF-8"?><fields-configuration> <preconfiguredField> <!-- This field is the originIndicator --> <originator> <originatorId>*</originatorId> <node> <nodeId>*</nodeId> </node> </originator> </preconfiguredField></fields-configuration>
El archivo está compuesto por un tag principal llamado este tag contendrá cada uno de los campos previamente configurados que serán identificados con el tag La fields-configuration preconfiguredField.estructura de cada campo se muestra a continuación:
Nombre del Tag Definición Valores disponibles
fieldNumber Representa el número del campo que se mandará a VTOL Se debe incluir un número entero de acuerdo a las especificaciones del manual así como los campos disponibles para su recepción en VTOL.
fieldValue Representa el valor del campo que se manda a VTOL Cualquier valor que coincida con el tipo de dato y tamaño definidos en VTOL.
Originador Es un tag que representa al originador junto con los nodos que enviarán este campo.
Este tag representa como tal a un originador, que incluye tanto si ID como uno o más nodos. Los tags válidos son: originatorId, node.
originatorId Es el id del originador que enviará este campo. Se puede indicar alguno de los siguientes valores:
( * ) que indica que se aplica para todas las tiendas o bien el número específico de la tienda.
Puede existir solo un elemento de este tipo por originador.
Node Representa a un nodo como tal. Pueden existir uno o más de estos elementos dentro del Nodo. Los tags váidos son: nodeId
nodeId Nodo para Se puede indicar alguno de los siguientes valores: ( * ) que indica que se aplica para todos los nodos o bien el número específico del nodo. Puede existir solo un elemento de este tipo por nodo.
Si se requiere el comportamiento de que todos los nodos del originador seleccionado, envíen el campo definido, entonces se deberá poner únicamente un tag con su respectivo con ( * ). Los tags Node nodeId n que se encuentren posteriormente a éste, serán ignorados. ode
ConfiguraciónEs necesario que el archivo de configuración de los campos se encuentre al mismo nivel que el JAR que contiene las clases de la librería, es este el lugar en donde se buscará. El nombre del archivo utilizado es
vtol-client-preconfigured-fields.xmlEn caso de que dicha configuración esté situada en otro directorio, se puede hacer uso del parámetro de configuración VTOLCLIENTLIBCONFIGPATH para indicar el directorio raíz. Por ejemplo:
vtolClient.setParameter( ,"D:/client-lib/config/");VtolClientConstants.VTOLCLIENTLIBCONFIGPATHComo se puede observar, solamente se indica el PATH absoluto donde reside tal archivo de configuración.
Librerías requeridasEntre las librerías requeridas se encuentran los siguientes JAR:
commons-beanutils.jarcommons-collections-3.2.jarcommons-digester-1.8.jarcommons-logging-1.1.jar
Estas librerías serán proporcionadas como parte del paquete de instalación entregado al cliente y deberán ser depositadas en el mismo lugar donde se deposita el JAR con la instalación de la librería.
Nota: Si se requiere el comportamiento de que todos los originadores envíen el campo definido, entonces se deberá poner únicamente un tag , con su respectivo con ( *** ). Los Originator originatorIdtags que se encuentren posteriormente a éste, serán ignorados.originador
Nota: Es muy importante verificar que en el mismo directorio donde se están depositando tanto estas librerías como la del cliente de VTOL, no exista un JAR con una versión anterior a las provistas aquí.
2.2.9 Parámetros Pre-configurados
Los parámetros configurados se utilizan para proporcionar a VTOL una inicialización a través de un archivo de configuración que se encuentra en la misma ruta donde se encuentra la librería como tal.
A continuación se muestran los detalles para acceder a esta funcionalidad:
Requisitos Para que esta funcionalidad esté disponible es necesario contar con el archivo de propiedades donde se pueden incluir cualquiera de los parámetros de inicialización
El nombre del archivo es: vtol-client-preconfigured-parameters.properties
El archive de propiedades que es provisto con la instalación deberá ser depositado en la misma ruta donde se encuentre la librería de vtol. En caso de que este archivo no exista, se recurrirá a la inicialización por código que se tendrá que hacer en el punto de venta, tal como se indica en los ejemplos de este documento.
Archivo PropertiesEl archivo de propiedades que se muestra a continuación incluye la un ejemplo de configuración tomando como referencia el ejemplo de inicialización de este documento.
HOSTIP = 127.0.0.1HOSTPORT = 3000TIMEOUTCONNECTIONHOST = 3000RESPONSETIMEOUT = 3000TIMEOUTEXPIRATIONNODE = 10000TIMEOUTOBTAINNODE = 10000USEVTOLCLIENTFINDER = USEENCRYPTEDDATA = FalseENCRYPTKEY = ENCRYPTER = #Parameters for DynamicVtolClient initializationTOTALNODESNUMBER = 5DEFAULTTRANSACTIONSTATUS = C
Nota si se utiliza inicialización por archivo y por código, siempre se tomará en cuenta la del código antes que la del archivo externo. En caso de que dicha configuración esté situada en otro directorio, se puede hacer uso del parámetro de configuración VTOLCLIENTLIBCONFIGPATH para indicar el directorio raíz. Por ejemplo: vtolClient.setParameter( ,"D:/client-lib/config/");VtolClientConstants.VTOLCLIENTLIBCONFIGPATHComo se puede observar, solamente se indica el PATH absoluto donde reside tal archivo de configuración.
2.2.10 Logging
La librería Java genera trazas para poder evaluar posibles comportamientos o errores.
De forma nativa no generará ninguna, por lo tanto, si es requerido obtener éste tipo de información, hay que proceder a la habilitación y configuración de dicha funcionalidad.
Para no generar dependencias a otras librerías, éste componente hace uso de la API de logeo nativo de JAVA.
Para habilitar el logeo es necesario incluir en las opciones de la máquina virtual de JAVA la siguiente opción:
-Djava.util.logging.config.file=[PATH_ABSOLUTO_ARCHIVO_CONFIGURACION]
Dónde:
[PATH_ABSOLUTO_ARCHIVO_CONFIGURACION] corresponde al path y nombre de archivo completos de donde se encuentra el archivo de configuración del logeo.
3. Ejemplos de uso de la librería
3.1 Acceso a VTOL Server desde Java
3.1.1 Ejemplos de modo de uso Static
StaticVtolClient staticVtolClient = (StaticVtolClient)VtolClient.getStaticVtolClient("12345");
/** * a) Seteo de parámetros: Como primer paso se deberán setear los parámetros correspondientes por * medio del método setParameter, y setear el originador que se utilizará para tomar * correctamente la configuración de Vtol Server. */staticVtolClient.setParameter(VtolClientConstants.HOSTIP,"127.0.0.1");staticVtolClient.setParameter(VtolClientConstants.HOSTPORT,"3000");
staticVtolClient.setParameter(VtolClientConstants.RESPONSETIMEOUT,"5000");staticVtolClient.setParameter(VtolClientConstants.TIMEOUTCONNECTIONHOST,"0");staticVtolClient.setParameter(VtolClientConstants.USEVTOLCLIENTFINDER,"False");
staticVtolClient.setParameter(VtolClientConstants.CLIENTFINDER,VtolClient.COMMITSTATUS);staticVtolClient.setParameter(VtolClientConstants.USEENCRYPTEDDATA,"False");staticVtolClient.setParameter(VtolClientConstants.ENCRYPTKEY,"synthesissynthesissynth");staticVtolClient.setParameter(VtolClientConstants.ENCRYPTER,"DESede");
/** * b) Inicialización: Se deberá llamar al método init, el cual realizará la inicialización de la librería * tomando los parámetros configurados en Vtol Server.*/staticVtolClient.init();
/** * c) Nodo: se deben setear los campos correspondientes a la transacción según el nodo/caja * correspondiente. */String nodeId = "2";
try{ SimpleDateFormat dateFormat = new SimpleDateFormat("yyyyMMddHHmmss"); String dateTime = dateFormat.format(new java.util.Date()); VtolNode vtolNode = staticVtolClient.createNode(nodeId); vtolNode.setStatus(NodeStatus.INUSE); vtolNode.createTransaction();
vtolNode.addField(3, "VTOL"); vtolNode.addField(4, "DATA"); vtolNode.addField(11, "Sale");//tipo de transaccion vtolNode.addField(25, dateTime); vtolNode.addField(6, "5294948333925257");//PAN vtolNode.addField(9 , "5294948333925257=101210100000212"); //Track2FieldId vtolNode.addField(10, "MSR");//modo de ingreso vtolNode.addField(12, "15000");//importe vtolNode.addField(13, "$");//moneda
vtolNode.addField(14, "1");//cuotas vtolNode.addField(15, "0");//plan //se envia a VTOL SERVER System.out.println("Envio de transaccion a VTOL SERVER"); vtolNode.sendTransaction();
//Obtención de la respuesta al requerimiento enviada por VTOL. Message responseMessage = vtolNode.getCurrentTransaction().getResponseMessage(); //forma de obtener un campo de la respuesta. String _responseCodeString = responseMessage.getField(26).getValue();
if ( _responseCodeString.equalsIgnoreCase("ISO8583")) { String _isoResponseCodeString = responseMessage.getField(27).getValue(); if ("00".equals(_isoResponseCodeString)) {//aprobada System.out.println("Transaccion aprobada."); System.out.println("Codigo de autorizacion: " + responseMessage.getField(22).getValue());
//como fue aprobada entonces hay un id de transaccion que sirve para enviar el tercer mensaje (confirmacion) String transactionIdString = responseMessage.getField(24).getValue(); vtolNode.createTransaction(); vtolNode.addField(3, "VTOL"); vtolNode.addField(4, "Data"); vtolNode.addField(11, "UnSyncCompletion"); vtolNode.addField(25, dateTime); vtolNode.addField(24, transactionIdString); vtolNode.addField(19, "Commit");
System.out.println("Confirmacion de trxId: " + transactionIdString); vtolNode.sendTransactionWithoutResponse();
}else{ System.out.println("Transaccion rechazada: " + responseMessage.getField(28).getValue()); } }else{ System.out.println("Transaccion con error: " + responseMessage.getField(28).getValue()); } vtolNode.setStatus(NodeStatus.AVAILABLE); }catch (Exception e) { e.printStackTrace();}
3.1.2 Ejemplos de modo de uso Dinámico
SimpleDateFormat dateFormat = new SimpleDateFormat("yyyyMMddHHmmss");
DinamicVtolClient dinamicVtolClient = (DinamicVtolClient)VtolClient.getUniqueInstanceOfVtolClient();
try{
/* * a) Seteo de parámetros: Como primer paso se deberán setear los parámetros correspondientes por * medio del método setParameter, y setear el originador que se utilizará para tomar * correctamente la configuración de Vtol Server. */ dinamicVtolClient.setOriginator("1");//Tienda dinamicVtolClient.setParameter(VtolClientConstants.HOSTIP,"127.0.0.1"); dinamicVtolClient.setParameter(VtolClientConstants.HOSTPORT,"3000"); dinamicVtolClient.setParameter(VtolClientConstants.RESPONSETIMEOUT,"3000"); dinamicVtolClient.setParameter(VtolClientConstants.TIMEOUTEXPIRATIONNODE,"10000"); dinamicVtolClient.setParameter(VtolClientConstants.TIMEOUTOBTAINNODE,"10000");
dinamicVtolClient.setParameter(VtolClientConstants.USEVTOLCLIENTFINDER,"False"); dinamicVtolClient.setParameter(VtolClientConstants.CLIENTFINDER,""); dinamicVtolClient.setParameter(VtolClientConstants.USEPENDINGAUTOMATIC,"True"); dinamicVtolClient.setParameter(VtolClientConstants.USEENCRYPTEDDATA,"False"); dinamicVtolClient.setParameter(VtolClientConstants.ENCRYPTKEY,""); dinamicVtolClient.setParameter(VtolClientConstants.ENCRYPTER,""); //si la variable TOTALNODESNUMBER no es especificada se usara el HandShake para obtener la lista de nodos de VTOL dinamicVtolClient.setParameter(VtolClientConstants.TOTALNODESNUMBER,"5"); dinamicVtolClient.setParameter(VtolClientConstants.DEFAULTTRANSACTIONSTATUS,"C"); //dinamicVtolClient.setParameter(VtolClientConstants.CLIENTFINDER,VtolClient.COMMITSTATUS); //dinamicVtolClient.setParameter(VtolClientConstants.USEPENDINGAUTOMATIC,"True"); dinamicVtolClient.setParameter(VtolClientConstants.PRECONFIGUREDFIELDSFILENAME,"D:/svn/vtol-client/dev/client-core/src/main/resources/vtol-client-preconfigured-fields.xml");
/* * b) Inicialización: Se deberá llamar al método init, el cual realizará la inicialización de la librería * tomando los parámetros configurados en Vtol Server. */ dinamicVtolClient.init();
/* * c) Nodo: se deben setear los campos correspondientes a la transacción según el nodo * correspondiente. */ String dateTime = dateFormat.format(new java.util.Date()); //se obtiene la caja/terminal VtolNode vtolNode = dinamicVtolClient.getNode(); vtolNode.createTransaction();
vtolNode.addField(3, "VTOL");
vtolNode.addField(4, "DATA"); vtolNode.addField(11, "Sale");//tipo de transaccion vtolNode.addField(25, dateTime); vtolNode.addField(10, "Manual");//modo de ingreso vtolNode.addField(6, "5432219380000102");//PAN vtolNode.addField(7, "2010");//fecha de vencimiento vtolNode.addField(8, "123"); //cvc vtolNode.addField(12, "1000");//monto vtolNode.addField(13, "$");//moneda vtolNode.addField(14, "1");//cuotas vtolNode.addField(15, "0");//plan
//envio de transaccion System.out.println("Envio de transaccion a VTOL SERVER"); vtolNode.sendTransaction(); System.out.println(""); Message responseMessage = vtolNode.getCurrentTransaction().getResponseMessage(); String responseCodeString = responseMessage.getField(26).getValue(); if (responseCodeString.equalsIgnoreCase("ISO8583")) { String isoResponseCodeString = responseMessage.getField(27).getValue(); if ("00".equals(isoResponseCodeString)) {//aprobada System.out.println("Transaccion aprobada."); System.out.println("Codigo de autorizacion: " + responseMessage.getField(22).getValue());
//como fue aprobada entonces hay un id de transaccion que sirve para enviar el tercer mensaje (confirmacion) String transactionIdString = responseMessage.getField(24).getValue(); vtolNode.createTransaction(); vtolNode.addField(3, "VTOL"); vtolNode.addField(4, "Data"); vtolNode.addField(11, "UnSyncCompletion");
vtolNode.addField(25, dateTime); vtolNode.addField(24, transactionIdString); vtolNode.addField(19, "Commit"); System.out.println("Confirmacion de trxId: " + transactionIdString); vtolNode.sendTransactionWithoutResponse(); }else{ System.out.println("Transaccion rechazada: " + responseMessage.getField(28).getValue()); } }else{ System.out.println("Transaccion con error: " + responseMessage.getField(28).getValue()); } dinamicVtolClient.freeNode(vtolNode); }catch (Exception e) { e.printStackTrace();}
3.1.3 Ejemplos de modo de uso Virtual
try{ VirtualVtolClient virtualVtolClient = new VirtualVtolClient();
//inicializacion de parametros generales virtualVtolClient.setParameter(VtolClientConstants.HOSTIP,"IP_VTOL"); //IP de VTOL SERVER virtualVtolClient.setParameter(VtolClientConstants.HOSTPORT,"3000"); //PUERTO de VTOL SERVER virtualVtolClient.setParameter(VtolClientConstants.TIMEOUTCONNECTIONHOST,"3000"); virtualVtolClient.setParameter(VtolClientConstants.RESPONSETIMEOUT,"15000"); virtualVtolClient.setParameter(VtolClientConstants.USEVTOLCLIENTFINDER,"False"); virtualVtolClient.setParameter(VtolClientConstants.CLIENTFINDER,""); virtualVtolClient.setParameter(VtolClientConstants.USEENCRYPTEDDATA,"False");
virtualVtolClient.setParameter(VtolClientConstants.ENCRYPTKEY,""); virtualVtolClient.setParameter(VtolClientConstants.ENCRYPTER,"");
//seteo de numero de tienda virtualVtolClient.setOriginator("CODIGO_TIENDA");
//Inicialización: Se deberá llamar al método init, el cual realizará la inicialización de la librería //tomando los parámetros configurados en Vtol Server. virtualVtolClient.init();
//se obtiene una caja/terminal de forma dinamica VtolNode vtolNode = virtualVtolClient.getNode(); //se crea una transaccion vtolNode.createTransaction(); //se agregan los datos de la transaccion vtolNode.addField(11, "Sale");//tipo de transaccion vtolNode.addField(3, "VTOL"); vtolNode.addField(4, "DATA"); vtolNode.addField(25, VtolNode.DATEFORMAT.format(new java.util.Date()));//fecha vtolNode.addField(10, "Manual");//Modo de ingreso vtolNode.addField(6, "5432219380000102");//PAN vtolNode.addField(7, "2010");//fecha de expiracion vtolNode.addField(8, "123");//CVC vtolNode.addField(12, "10000");//monto vtolNode.addField(13, "$");//moneda vtolNode.addField(14, "1");//cuotas vtolNode.addField(15, "0");//plan //se envia a VTOL SERVER System.out.println("Envio de transaccion a VTOL SERVER"); vtolNode.sendTransaction(); //se obtiene la repsuesta Message responseMessage = vtolNode.getCurrentTransaction().getResponseMessage(); //se analiza el campo 26
String responseCodeString = responseMessage.getField(26).getValue(); if (responseCodeString.equalsIgnoreCase("ISO8583")) { //se obtiene el campo 27, codigo de repsuesta String _isoResponseCodeString = responseMessage.getField(27).getValue(); if ("00".equals(_isoResponseCodeString)) {//aprobada System.out.println("Transaccion aprobada."); System.out.println("Codigo de autorizacion: " + responseMessage.getField(22).getValue()); //como fue aprobada entonces hay un id de transaccion que sirve para enviar el tercer mensaje (confirmacion) String _transactionIdString = responseMessage.getField(24).getValue(); vtolNode.createTransaction(); vtolNode.addField(3, "VTOL"); vtolNode.addField(4, "Data"); vtolNode.addField(11, "UnSyncCompletion"); vtolNode.addField(25, VtolNode.DATEFORMAT.format(new java.util.Date())); vtolNode.addField(24, _transactionIdString); vtolNode.addField(19, "Commit"); System.out.println("Confirmacion de trxId: " + _transactionIdString); //se envia tercer mensaje sin esperar respuesta vtolNode.sendTransactionWithoutResponse();
}else{ System.out.println("Transaccion rechazada: " + responseMessage.getField(28).getValue()); } }else{ System.out.println("Transaccion con error: " + responseMessage.getField(28).getValue()); } }catch (Exception e) { e.printStackTrace();
}