Está en la página 1de 9

ESPECIFICACIONES

CashlogyTickets
V1.2

1
1 INTRODUCCIÓN.
Este documento va a definir la especificación técnica para que los desarrolladores de
aplicaciones TPV puedan llevar a cabo una integración con la aplicación
CashlogyTickets desarrollada por Azkoyen para poder integrar el cajón automático
Cashlogy. Esta aplicación tiene diferentes modos de integración.
En este documento únicamente se va a describir la Micro-Integración.

2 MICRO-INTEGRACIÓN.
Este modo de integración se basa en el utilizar la técnica de intercambio de ficheros
para intercambiar información entre la aplicación TPV y CashlogyTickets.
Con el fin de reducir la integración a la mínima expresión, se ha definido un fichero que
contiene los datos mínimos necesarios para poder tener el control total de la gestión
de efectivo. Con esta información debemos ser capaces de cuadrar las ventas que se
registran en la propia aplicación TPV con las que registran en CashlogyTickets.
Este módulo será capaz de ofrecer un sistema de intercambio de ficheros para que un
software exterior integre Cashlogy.

2
2.1 Modos de trabajo
Existen dos posibles formas de trabajo:

• Con respuesta
• Sin respuesta
El funcionamiento de ambos modos se detalla en el aparado 2.3
En ambos casos se utilizará un único directorio donde se compartirán los ficheros. Este
directorio se fijará en el menú herramientas - Carpetas – Peticiones en la aplicación
CashlogyTickets.

2.2 Formato de los ficheros.


Todos los ficheros que se utilizarán en el intercambio entre la aplicación de TPV y
CashlogyTickets, tendrán un formato tipo JSON simple. Por otra parte, la extensión de
estos ficheros será “.azk” para los ficheros de venta y abono y “.OK” / ”.NOK” para las
respuestas.
Los parámetros definidos en estos ficheros variarán según se trate de un proceso de
venta, una respuesta a la venta, un proceso de abono o una respuesta al abono, y
serán los que se describen a continuación:

3
PROCESO DE VENTA
Nombre: Comenzará por la letra ‘C’. Extensión: “azk”. Formato: JSON
{
“VentaRequest”:
[
{
“NumeroTicket”:”NumeroTicket”,
➢ “Número del ticket de la aplicación TPV. Debe coincidir con el nombre del fichero sin
extensión ni letra inicial”
➢ Se trata como un valor alfanumérico.
“ImporteTransaccion”:ImporteTransaccion,
➢ “El importe en céntimos de la venta.”
➢ Dato numérico y decimal.
“CodigoCaja”:”CodigoCaja”,
➢ “El código de la caja en la que se va a realizar la venta”
➢ Se trata como un valor alfanumérico.
“CodigoUsuario”:”CodigoUsuario”,
➢ “El código del usuario que realiza la venta”
➢ Se trata como un valor alfanumérico.
“ModoWork”:ModoWork,
➢ “Indica si se trabaja con modo fichero respuesta”
➢ El dato enviado es numérico y decimal.
➢ 0 :sin respuesta
➢ 1: con respuesta
}
]
}
RESPUESTA A LA VENTA
Nombre: Comenzará por la letra ‘C’. Extensión: “OK” o “NOK” Formato: JSON
{
“VentaResponse”:
[
{
“NumeroTicket”:”NumeroTicket”,
➢ “Número del ticket de la aplicación TPV. Debe coincidir con el nombre del fichero sin
extensión ni letra inicial”
➢ Se trata como un valor alfanumérico.
“ImporteTransaccion”:ImporteTransaccion,
➢ “El importe en céntimos de la venta.”
➢ Dato numérico y decimal.
“ImporteCobrado”:ImporteCobrado,
➢ “El importe en céntimos que se introduce para realizar la venta.”
➢ Dato numérico y decimal.
“ImportePagado”:ImportePagado,
➢ “El importe en céntimos dispensado como cambios.”
➢ Dato numérico y decimal.
“MensajeError”:”CadenaError”,
➢ CadError tendrá los siguientes valores:
RESP:OK, indicando OK. (solo para ficheros .OK)
RESP:CANCEL, indicando que el usuario ha pulsado el botón “Cancel” de la ventana de
Cobro. (solo para ficheros .NOK)
RESP:ERROR, indicando Error (solo para ficheros .NOK).

4
➢ Se trata como un valor alfanumérico.
}
]
}

PROCESO DE ABONO
Nombre: Comenzará por la letra ‘A’. Extensión: “azk”. Formato: JSON
{
“AbonoRequest”:
[
{
“NumeroAbono”:”NumeroAbono”,
➢ “Número del ticket de abono de la aplicación TPV. Debe coincidir con el nombre del
fichero sin extensión ni letra inicial”
➢ Se trata como un valor alfanumérico.
“NumeroTicketRelacionado”:”NumeroTicketRelacionado”
➢ “Número del ticket de venta original sobre el que se va a realizar el abono”
➢ Se trata como un valor alfanumérico
“ImporteTransaccion”:ImporteTransaccion,
➢ “El importe en céntimos del abono.”
➢ Dato numérico y decimal.
“CodigoCaja”: ”CodigoCaja”,
➢ “El código de la caja en la que se va a realizar el abono”
➢ Se trata como un valor alfanumérico.
“CodigoUsuario”:”CodigoUsuario”,
➢ “El código del usuario que realiza la venta”
➢ Se trata como un valor alfanumérico.
“ModoWork”:ModoWork,
➢ “Indica si se trabaja con modo fichero respuesta”
➢ El dato enviado es numérico y decimal.
➢ 0 :sin respuesta
➢ 1: con respuesta
}
]
}
RESPUESTA AL ABONO
Nombre: Comenzará por la letra ‘A’. Extensión: “OK” o “NOK” Formato: JSON
{
“AbonoResponse”:
[
{
“NumeroAbono”:”NumeroAbono”,
➢ “Número del ticket de abono de la aplicación TPV. Debe coincidir con el nombre del
fichero sin extensión ni letra inicial”
➢ Se trata como un valor alfanumérico.
“NumeroTicketRelacionado”:”NumeroTicketRelacionado”
➢ “Número del ticket de venta original sobre el que se va a realizar el abono”
➢ Se trata como un valor alfanumérico
“ImporteTransaccion”:ImporteTransaccion,
➢ “El importe en céntimos del abono”

5
➢ Dato numérico y decimal.
“ImportePagado”:ImportePagado,
➢ “El importe en céntimos dispensado como abono.”
➢ Dato numérico y decimal.
“MensajeError”:”CadenaError”,
➢ CadError tendrá los siguientes valores:
RESP:OK, indicando OK. (solo para ficheros .OK)
RESP:CANCEL, indicando que el usuario ha pulsado el botón “Cancel” de la ventana de
Cobro. (solo para ficheros .NOK)
RESP:ERROR, indicando Error (solo para ficheros .NOK).
➢ Se trata como un valor alfanumérico.
}
]
}

2.3 Procedimiento
Para realizar la Micro integración se deben seguir los siguientes pasos, referidos tanto al
proceso de venta, como al proceso de abono/devolución:

1. El software que integra, (aplicación TPV), debe crear un fichero del tipo
<NombreFichero>.<azk> en el directorio de peticiones indicando, de esta forma, el inicio
de una operación (ver detalles de nombre y extensión en el apartado 2.2).
2. CashlogyTickets está continuamente revisando si hay un nuevo fichero en este directorio.
Cuando comprueba que se ha creado el fichero, lo captura, analiza y realiza el proceso de
venta/abono.
3. Una vez que la operación ha terminado, CashlogyTickets borra el fichero .azk del mismo y
realizará las siguientes acciones dependiendo de si se está trabajando con respuesta o no.
a. En caso de trabajar con respuestas:
i. CashlogyTickets genera los ficheros .OK/NOK en el directorio de peticiones.
El nombre de estos archivos será el mismo que el del fichero que inicia la
operación (NombreFichero.azk) pero en este caso con la extensión
correspondiente según haya terminado la operación.
ii. El encargado de borrar el fichero respuesta es la aplicación TPV, de tal
forma que en el directorio de intercambio solo puede haber un único
fichero en el mismo instante. La existencia de un fichero previo, indicaría
que el sistema está ocupado.
b. En caso de no trabajar con respuesta, no se deberá realizar ninguna otra acción.

2.4 Ejemplos:
Ejemplo 1: Supongamos que vamos a solicitar el cobro del ticket de venta y que
trabajamos en modo sin respuesta:

• Nº ticket – 385069
• Importe de venta - 4,98€
• Caja – Barra 2
• Usuario – Carlos Ruiz
• Trabajaremos sin respuesta - 0

6
Los pasos a realizar son:

1. La aplicación TPV debe generar un fichero al que nombrará C385069.azk y lo creará


en el directorio asignado en la configuración (por defecto será
“C:\Cashlogy\CashlogyTickets\Files\RequestsDir\” )
El contenido del fichero, según el formato definido sería:
{
"VentaRequest":
[
{
"NumeroTicket":"385069",
"ImporteTransaccion":498,
"CodigoCaja":"Barra 2",
"CodigoUsuario":"Carlos Ruiz",
"ModoWork": 0
}
]
}

2. Cuando CashlogyTicket detecta que hay un nuevo fichero, lo lee y comprueba que
el formato es correcto. Si el formato es correcto ejecuta la venta y debe aparecer
una ventana similar a la que se muestra.

3. Una vez finalizada la venta, CashlogyTicket registra la transacción en su BD y borra


el fichero del directorio para que se pueda iniciar otro proceso de venta.

7
Ejemplo 2: Supongamos que vamos a solicitar el abono/devolución de un ticket de venta
y que trabajamos en modo con respuesta:

• Nº Abono : 000001
• Nº ticket relacionado : 385069
• Importe de la transacción a abonar : 4,98€
• Caja : Barra 2
• Usuario : Carlos Ruiz
• Trabajaremos con respuesta : 1

Los pasos a realizar son:

1. La aplicación TPV debe generar un fichero al que nombrará A000001.azk y lo creará


en el directorio asignado en la configuración (por defecto será
“C:\Cashlogy\CashlogyTickets\Files\RequestsDir\” )

El contenido del fichero, según el formato definido sería:

{
"AbonoRequest":
[
{
"NumeroAbono":"000001",
"NumeroTicketRelacionado":"385069",
"TransactionAmount":498,
"CodigoCaja":"Counter 2",
"CodigoUsuario":"Carlos Ruiz",
"ModoWork": 1
}
]
}

2. Cuando CashlogyTicket detecta que hay un nuevo fichero, lo lee y comprueba que el
formato es correcto. Si el formato es correcto ejecuta la devolución y debe aparecer
una ventana similar a la que se muestra.

8
3. Una vez finalizado el abono, CashlogyTicket registra la transacción en su BD y borra el
fichero del directorio.

4. Adicionalmente, como en este ejemplo trabajamos con respuesta, CashlogyTicket


creará el fichero respuesta A000001.OK en el directorio de peticiones (por defecto
será “C:\Cashlogy\CashlogyTickets\Files\RequestsDir\” ), con el siguiente contenido:
{

“AbonoResponse”:
[
{
"NumeroAbono":"1",
"NumeroTicketRelacionado":"385069",
“ImporteTransaccion”:498,
“ImportePagado”:498,
“MensajeError”:”OK”
}

]
}
5. Por último, la aplicación de TPV deberá borrar el archivo A000001.OK