THE FACTORY HKA

Soporte e Integración

Aplicación Tfinulx
Manual de Integración
 SOPORTE E INTEGRACIÓN

Manual de Integración

Revision 1.0

 The Factory HKA

La California Norte, Callejón Gutiérrez
Edif. Riva, PB Ofic. 2-1
Caracas - Venezuela
Teléfono (212) 237.4112 • Fax (212) 239.8176
Historial de Revisiones
Paginas
Revisión Fecha Comentario
Afectadas
1.o 08/09/14 Todas Versión inicial
Índice
Capitulo 1 .......................................................................................................... 1
Introducción .............................................................................................................. 1
Resumen .................................................................................................................... 1
Requerimientos de Hardware ................................................................................. 2
Requerimientos de Software ................................................................................... 2
Capitulo 2 .......................................................................................................... 3
Instalación y Configuracion ............................. Error! Bookmark not defined.
Uso de Covertidor USB a Puerto Serial ……………………………………4
Alcance de la librería ................................................................................................ 5
Capitulo 3 .......................................................................................................... 6
Funciones de la Aplicación Tfinulx ....................................................................... 6
CheckFprinter ............................................................................................. 8
ReadFpStatus ............................................................................................... 9
SendCmd .................................................................................................... 10
SendFileCmd ............................................................................................. 11
UploadReportCmd ................................................................................... 12
UploadStatusCmd ..................................................................................... 14
Anexos ..................................................................................................................... 17
ANEXO 1: Lista de códigos de Status ................................................ 177
ANEXO 2: Lista de códigos de Error ................................................. 188
ANEXO 3: Ejemplo básico de emisión de Factura para Consumidor
Final .......................................................................................................... 199
 1
Capítulo
T H E F A C T O R Y H K A

Introducción
La aplicación Tfinulx está pensada para dar soporte a sistemas administrativos
basados en Linux/Unix/QNX que no puedan hacer uso directamente del puerto
serie.

Resumen

E n las siguientes páginas se describen los detalles de la interfaz de aplicación

Tfinulx, desde los requerimientos de hardware, la referencia a de las funciones
que están disponibles para ser usadas y los procedimientos de instalación y
configuración de la aplicación para poder hacer uso de ella.

1
T H E F A C T O R Y H K A

Requerimientos de Hardware
 Procesador de 1Ghz o superior

 Memoria RAM de 512MB o superior

 Puerto Serial físico o USB 2.0

 Espacio en Disco de al menos 50 MB

Requerimientos de Software
 Sistema Operativo Linux/Unix/QNX

2
T H E F A C T O R Y H K A

2
Capítulo

Generalidades
La aplicación “tfinulx” utiliza lenguaje C como lenguaje de programación y puede ser
invocada directamente en consola o desde una aplicación secundaria – remota.

La aplicación “tfinulx” está destinada a dar una solución a las aplicaciones desarrolladas
bajo sistemas UNIX, LINUX y QNX que no pueden hacer uso del puerto de
comunicación directamente, su función es controlar la apertura del puerto, gestionar las
comunicaciones y cerrar el puerto.

Aplicación tfinulx Impresora

Remota Fiscal

Ilustración 1. Interacción de la aplicación “tfinulx”.

Una aplicación remota, puede ser cualquier desarrollo que pueda acceder al Prompt y/o
consola del sistema.

Desde dicha aplicación remota, se escribe en el Prompt de la consola del sistema

llamando a la aplicación “tfinulx” la cual se encarga de la interacción con la impresora
fiscal.

La aplicación es proporcionada en una carpeta que contiene los siguientes archivos:

 Aplicación “tfinulx”.
 Guía de uso de la Aplicación.
 Archivo de configuración del puerto de comunicaciones
“Puerto.txt”

En el Archivo “Puerto.txt”, se indica la información del nombre del Puerto de

comunicaciones a emplear para establecer la comunicación con la impresora fiscal.
Ejemplo “/dev/ttyS0”. Éste archivo es modificable para permitir reconfigurar el
nombre del puerto a emplear.

Dentro de esta carpeta se generaran los siguientes archivos por medio de la

aplicación:
 Archivo de Status y Error identificado con el nombre pasado
por parámetro al llamar la aplicación.

3
T H E F A C T O R Y H K A

 Archivo de Reportes (X, Z) identificado con el nombre

pasado por parámetro al llamar la aplicación.
 Archivo de Status (S1, S2, S3, S4, S5) identificado con el
nombre pasado por parámetro al llamar la aplicación.
 Archivo de Retorno de la aplicación “Retorno.txt”.

NOTA: La aplicación “tfinulx” y el archivo de configuración “Puerto.txt”, deben ser

copiados en la misma carpeta donde se encuentre la aplicación remota.

Instalación y Configuración
Para instalar la aplicación tfinulx solamente copie los archivos correspondientes a la
versión del Sistema Operativo que esté usando (32 o 64 bits) en una nueva carpeta,
digamos /home/usuario/tfinulx. Los archivos a copiar deben ser tfinulx (la aplicación),
puerto.txt (el archivo de configuración del puerto) y retorno.txt (donde la aplicación
devuelve los valores que se obtienen al ejecutar la función).

Use el comando chmod 777 /home/usuario/tfinulx para dar permiso a la carpeta donde
copió los archivos de la aplicación.

Ejecute todos los comandos expuestos en la siguiente sección como SUDO.

Uso de Convertidor USB a Puerto

Serial
Es probable que la interface con que pretenda usar la impresora sea puerto serie RS-232,
y hoy día es muy común usarlas con convertidor USB a Puerto Serie. En este caso el
puerto a usar (que debe colocarse en el archivo Puerto.txt) seria /dev/ttyUSB0.

Durante las pruebas aquí realizadas se usó el conversor Prolific PL2303, que es muy
común conseguir en el mercado. El Sistema Operativo Ubuntu 13 instala los drivers de
este convertidor automáticamente. En cualquier otro sistema operativo deberá chequear
si los drivers están instalados antes de usar la impresora, use el comando lsusb para
visualizar los dispositivos instalados y verifique que el que está usando aparece.

4
T H E F A C T O R Y H K A

Alcance de la librería
La aplicación Tfinulx es compatible con cualquier distribución de Linux.

5
T H E F A C T O R Y H K A

3
Capítulo

Funciones de la Aplicación Tfinulx

Las funciones poseen una Cabecera y el parámetro de entrada de la función que
puede ser un Comando o una Ruta, algunas funciones no requieren de parámetro
de entrada por lo que se pueden presentar los casos mostrados a continuación:

Cabecera
Cabecera Comando
Cabecera Ruta
Cabecera Comando Ruta

El retorno del llamado y ejecución de las funciones son generados en

archivos .txt de forma automática y son colocados en la misma ubicación en que se
encuentre la aplicación, la aplicación remota podrá hacer uso de dicho archivo para
el control interno.

La llamada de la aplicación directamente desde el Prompt, está dada por la

siguiente estructura:

Ruta de la Aplicación + Nombre de la Aplicación + Cabecera Parámetros

Ej: >/home/did/tfinulx/tfinulx SendCmd I0X

En los casos en que en el prompt se encuentren ubicados en la carpeta que

contiene el ejecutable o que la llamada se haga desde la aplicación remota se debe
preceder al nombre de la aplicación con los caracteres “./” sin colocar la ruta de la
aplicación, como se describe continuación:

6
T H E F A C T O R Y H K A

Ej: >./tfinulx SendCmd I0X

La descripción de las funciones y comandos empleados, se encuentran

detallados en el manual de protocolos y comandos para impresoras fiscales “The
Factory HKA”

La aplicación tfinulx retorna un valor que se almacena en la variable de

entorno “?” y se puede visualizar con la siguiente línea de comando inmediatamente
después de la ejecución o llamada al tfinulx:

Ej: >echo $?

Los posibles retornos se especifican en la siguiente tabla:

Función Solicitada Retorno Casos
Error en la apertura del puerto
255
Todas Error en los parámetros enviados
0 Sin respuesta de la impresora
CheckFprinter
1 Impresora en línea
0 Error al cargar o guardar el Status&Error
ReadFpStatus
1 Status&Error cargado y guardado
0 Error al cargar o guardar el reporte
UploadReportCmd
1 Reporte cargado y guardado correctamente
0 Error al cargar o guardar el reporte de estado
UploadStatusCmd Reporte de estado cargado y guardado
1
correctamente
0 Error en la recepción del comando enviado
SendCmd
1 Comando recibido por la impresora
Número
Número de Comandos contenidos en el
SendFileCmd a partir
archivo que se enviaron correctamente
de 0

7
 T H E F A C T O R Y H K A

CheckFprinter

BOOLEAN CheckFprinter()

Permite verificar si la impresora está conectada al PC.

Retorno:

True: impresora conectada.

False: impresora no detectada.

Ej: >./tfinulx CheckFprinter

Ilustración 2. Llamada de la función CheckFprinter.

RETORNO LA IMPRESORA SE ENCUENTRA CONECTADA = TRUE

LA IMPRESORA NO SE ENCUENTRA CONECTADA = FALSE

La ejecución de todas las funciones crea de forma automática un archivo

“Retorno.txt”, en donde se almacena el retorno de la función, en caso de error de
comunicación o error en los parámetros el retorno tiene un valor de “-1”.

Ilustración 3. Archivo de texto “Retorno.txt”

8
 T H E F A C T O R Y H K A

ReadFpStatus

BOOLEAN ReadFpStatus()

Permite leer las variables de estado y error de la impresora. Al ejecutar

este método se establece el valor de la variable tipo String Estado. (Ver
Anexos 1 y 2)

Retorno:

True: Método ejecutado exitosamente

False: Error en ejecución del método

Ej: >./tfinulx ReadFpStatus archivo_destino

Ilustración 4. Llamada de la función ReadFpStatus.

RETORNO LECTURA CO RRECTA DEL STATUS & ERROR = TRUE

LECTURA ER RÓNEA DEL STATUS & ERROR = FALSE
VER ANE XO 1 -> TABLA DE ESTADOS
VER ANE XO 2 -> TABLA DE ERRORES

La ejecución de esta función crea de forma automática un archivo de texto con el

nombre pasado por parámetro, en donde se almacena la información referente al
Status y Error durante la invocación de la función, adicionalmente se crea el archivo
“Retorno.txt” con la información del retorno de la función.

9
T H E F A C T O R Y H K A

Ilustración 5. Archivo de salida “Status_Error.txt”

SendCmd

VOID SendCmd(String Cmd)

Permite realizar el envío de comandos hacia la impresora, en forma de

tramas de caracteres ASCII, tal como es descrito en los manuales de
integración de las respectivas impresoras, y en el manual general de
protocolos y comandos del protocolo TFHKA.

Parámetros:

String cmd: trama de comando en ASCII que se enviara a la impresora.

Retorno:

True: Método ejecutado exitosamente.

False: Error en ejecución del método.

Ej: >./tfinulx SendCmd I0X  Comando que realiza un reporte

X e imprime un ticket.

Ej: >./tfinulx SendCmd 0  Comando para la apertura de la

Gaveta e imprimir un ticket.

10
 T H E F A C T O R Y H K A

Ilustración 6. Llamada de la función SendCmd.

R E T O R N EOL C O M A N D O F U E R E C I B I D O C O R R E C T A M E N T E = T R U E
EL COMANDO NO SE REC IBIÓ CORRECTAMENTE = FALSE

La ejecución de ésta función crea el archivo “Retorno.txt” con la

información de retorno.

SendFileCmd

INT SendFileCmd(String file)

Permite realizar el envío de un archivo de lotes de comando hacia la

impresora.

Parámetros:

String rutaFile: ruta en la cual se encuentra el archivo de comandos

por lote que se enviará a la impresora.

Retorno:

(int) Número de líneas del archivo de lotes de comandos ejecutadas

exitosamente.

Ej: >./tfinulx SendfileCmd /home/archivo.txt -> El archivo se

encuentra en otra ubicación

Ej: >./tfinulx SendfileCmd archivo.txt -> El archivo se encuentra

en la misma ubicación de la aplicación “tfinulx”

11
 T H E F A C T O R Y H K A

Ilustración 7. Llamada de la función SendFileCmd

Ilustración 8. Archivo de comandos

RETORNO NÚMERO DE COMANDOS ENVIADOS

CORRECTAMENTE

La ejecución de ésta función crea el archivo “Retorno.txt” con la

información de retorno.

UploadReportCmd

BOOLEAN UploadReportCmd(String cmd)

12
 T H E F A C T O R Y H K A

Ésta función se encarga de cargar un reporte de datos y almacenarlos en

un archivo de texto con el nombre indicado por el parámetro Ruta, el
cual se crea de forma automática en la ruta indicada, en el caso en que la
Ruta solo contenga el nombre del archivo se guarda en la misma
ubicación de la aplicación, si el archivo ya existe se borra su contenido
anterior. Para armar el comando se mantiene lo establecido en el
“Manual de Protocolos y Comandos”.

Parámetros:

String cmd: tipo de reporte a solicitar. Los reportes que pueden ser
solicitados son los siguientes (consultar manual general de integración
de las respectivas impresoras):

- U0X - U1Z
- U0Z - U1X
Retorno:

True: Método ejecutado exitosamente.

False: Error en ejecución del método.

Ej: >./tfinulx UploadReportCmd U0X archivo_destino 

Comando que carga un reporte X y genera un archivo con la data
referente al reporte solicitado.

Ilustración 9. Llamada de la función UploadReportCmd.

R E T O R NE
OL R E P O R T E S E H A C A R G A D O C O R R E C T A M E N T E = TRUE
ERROR AL CARGAR EL REPORTE = FALSE

13
T H E F A C T O R Y H K A

Ilustración 10. Archivo de salida Reporte.txt

La ejecución de ésta función crea el archivo “Retorno.txt” con la

información de retorno.

UploadStatusCmd

BOOLEAN UploadStatusCmd(String cmd)

Ésta función se encarga de cargar los status de la impresora (S1, S2, S3,
S4, S5) y almacenar la información en un archivo de texto con el
nombre indicado por el parámetro Ruta, el cual se crea de forma
automática en la ruta indicada, en el caso en que la Ruta solo contenga
el nombre del archivo se guarda en la misma ubicación de la aplicación,
si el archivo ya existe se borra su contenido anterior. Para armar el
comando se mantendrá lo establecido en el “Manual de Protocolos y
Comandos”.

Parámetros:

String cmd: tipo de Status a solicitar. Los Status que pueden ser
solicitados son los siguientes:

- S1 - S4 - S8P
- S2 - S5
- S3 - S8E

Retorno:

14
 T H E F A C T O R Y H K A

True: Método ejecutado exitosamente.

False: Error en ejecución del método.

Ej: ./tfinulx UploadReportCmd S1 archivo_destino 

Comando que carga el status S1 y genera un archivo con la data
referente al status solicitado.

Ilustración 11. Llamada de la función UploadStatusCmd.

R E T O R N OE L S T A T U S S E H A C A R G A D O C O R R E C T A M E N T E = TRUE
ERROR AL CARGAR EL STATUS = FALSE

Ilustración 12. Archivo de salida Status.txt

15
T H E F A C T O R Y H K A

La ejecución de ésta función crea el archivo “Retorno.txt” con la

información de retorno.

16
T H E F A C T O R Y H K A

Anexos
ANEXO 1: Lista de códigos de Status

STATUS
Retorno Retorno
Comentario
(Hex) (Decimal)
0 0 Estado desconocido.
1 1 En modo prueba y en espera.
2 2 En modo prueba y emisión de documentos fiscales.
3 3 En modo prueba y emisión de documentos no fiscales.
4 4 En modo fiscal y en espera.
5 5 En modo fiscal y emisión de documentos fiscales.
6 6 En modo fiscal y emisión de documentos no fiscales.
En modo fiscal, cercana carga completa de la memoria fiscal y
7 7
en espera.
En modo fiscal, cercana carga completa de la memoria fiscal y
8 8
en emisión de documentos fiscales.
En modo fiscal, cercana carga completa de la memoria fiscal y
9 9
en emisión de documentos no fiscales.
En modo fiscal, carga completa de la memoria fiscal y en
0A 10
espera.
En modo fiscal, carga completa de la memoria fiscal y en
0B 11
emisión de documentos fiscales.
En modo fiscal, carga completa de la memoria fiscal y en
0C 12
emisión de documentos no fiscales.

17
T H E F A C T O R Y H K A

ANEXO 2: Lista de códigos de Error

ERROR
Retorno Retorno
Comentario
(Hex) (Decimal)
00 0 No hay error.
01 1 Fin en la entrega de papel.
02 2 Error de índole mecánico en la entrega de papel.
03 3 Fin en la entrega de papel y error mecánico.
50 80 Comando invalido o valor invalido.
54 84 Tasa invalida.
58 88 No hay asignadas directivas.
5C 92 Comando invalido.
60 96 Error fiscal.
64 100 Error de la memoria fiscal.
6C 108 Memoria fiscal llena.
70 112 Buffer completo. (debe enviar el comando de reinicio)
80 128 Error en la comunicación.
89 137 No hay respuesta.
90 144 Error LRC.
91 145 Error interno api.
99 153 Error en la apertura del archivo.

18
T H E F A C T O R Y H K A

ANEXO 3: Ejemplo básico de emisión de Factura

sudo ./tfinulx SendCmd !000000100000001000Item 1

sudo ./tfinulx SendCmd 101

19