FacturaSend Off-line es una herramienta poderosa para la generación de documentos electrónicos sin necesidad de conexión a Internet. Ideal para aplicaciones de escritorio o web que requieren una emisión rápida y local de facturas electrónicas. En esta guía, te explicamos paso a paso su funcionamiento, configuración y beneficios.

Debido a que se trata de una guía bien detallada estaremos explicando el concepto en las siguientes secciones:

Contenido

• ¿En qué consiste?
• Conexión con FacturaSend
• Instalación y Configuración
• Funcionamiento
• Imagen para QR
• Generación directa de PDF
• Generación de PDF a pedido
• Envíos de documentos a FacturaSend – Sincronización
• Error al enviar documento a FacturaSend

¿En qué consiste?

Se trata de una aplicación ejecutable para Windows/Linux, que funciona como un servicio de HTTP y que permite la generación de documentos XML firmados desde el equipo local del cliente, sin necesitar conexión a Internet o que el servidor donde está instalado el FacturaSend se encuentre respondiendo.

La generación de documentos electrónicos es realizada mediante la invocación a una API REST local, al cual se le pasa datos de los documentos que se desea generar en formato JSON, similar a cómo lo haría en una llamada normal a la API lote/create de FacturaSend, siendo de ésta forma compatible su uso con la plataforma en la nube o cualquier instalación de FacturaSend y requiriendo cambios mínimos a una aplicación que ya se conecta con FacturaSend.

Gracias a eso, las aplicaciones de escritorio o aplicaciones Web que funcionan de manera local pueden obtener de manera directa y rápida el CDC de cualquier tipo de documento electrónico, como así también el valor de la Cadena QR e imagen de QR para incorporarlo en sus impresiones de comprobantes actual, haciendo que la espera de emisión de documentos electrónicos sea la mínima para el emisor y receptor.

Opcionalmente también puede obtener inmediatamente el KUDE del documento electrónico (Ver apartado Generación directa de PDFs), el cual quedará guardado en la carpeta de la aplicación en formato PDF.

Conexión con FacturaSend

La aplicación off-line mantiene información sobre el servidor de FacturaSend donde hay que enviar los documentos electrónicos, sea éste el que se encuentra bajo el dominio https://console.facturasend.com.py u otro servidor local o en la nube instalado de manera particular para el cliente.

De esa forma, cada cierto tiempo, parametrizable, se intentará enviar los datos de los documentos recibidos en formato JSON a FacturaSend, para que éste último lo gestione en su plataforma y luego, intente enviar a la SET.

Todo éste proceso es realizado de manera transparente para el emisor.

Instalación y Configuración

Para  empezar a utilizar la aplicación offl-ine, basta con acceder a la pestaña Off-line entrando en el menú de Contribuyente Emisor, como se muestra a continuación:

A la derecha, al lado de API Key, acceder a la opción Off-line

Primeramente debe descargar la Aplicación off-line (Paso 1), de acuerdo a su sistema operativo. Luego de la descarga, cree una carpeta donde colocará el ejecutable, de manera a mantener organizados los archivos que serán generados una vez que empiece a utilizar la aplicación.  

Luego, descargue el archivo de configuración de la empresa, con la cual desea utilizar la aplicación off-line (Paso 2) y guarde el archivo en la misma carpeta donde guardó el ejecutable. A continuación se muestra un ejemplo:

Listo…!!. Ya puede ejecutar la aplicación.

Funcionamiento

Ejecute la aplicación y acepte la alerta de Windows que aparecerá la primera vez, en el fondo, puede verse algunas instrucciones acerca de la aplicación.

Texto que aparece en el servidor HTTP:

Servidor de FacturaSend corriendo y en espera de nuevos lotes para (off-line) con el RUC “80005484-9“

Para la creación nuevos lotes de documentos electrónicos utilice:

(POST) http://localhost:3010/lote/create

Note que la palabra off-line en negrita y subrayado corresponde al tenantId e FacturaSend, y el RUC es el RUC del Emisor, el cual se obtiene del archivo facturasend-config.json.

Luego también se informa el ENDPOINT e la API, donde debe enviar sus documentos, la API no requiere de autenticación, el cual es:

(POST) http://localhost:3010/lote/create

El puerto 3010 puede ser modificado si lo desea, mediante el archivo .env

A modo de ejemplo se muestra una llamada realizada mediante POSTMAN:

Puede notar que la llamada a la API es realizada de la misma manera como lo haría con FacturaSend, con la diferencia de que en éste caso el envío se realiza en localhost.

La respuesta de la petición también se obtiene de la misma forma como lo haría Facturasend, cuando se envía un lote.

En la respuesta se obtiene el XML, cdc, qr, número de la Factura y fecha de la Firma Digital.

Imagen para código QR

En la carpeta de la aplicación también se crean las imágenes QR de cada documento que es generado, utilizando el número de la factura, como nombre del PNG, cómo se muestra a continuación:

Las imágenes QR se eliminarán una vez que el documento es enviado a FacturaSend, por parte de la aplicación off-line, para optimizar el espacio en disco.

Si lo indica, mediante configuración, también se guardará el archivo XML del documento generado.

Personalización

Algunos cambios de funcionamiento pueden ser realizados mediante parámetros de configuración, establecidos en un archivo .env, el cual debe estar ubicado dentro de la misma carpeta del ejecutable, por ejemplo:

Archivo .env

facturasend.sendLote.time=60000

facturasend.saveResponseXML=true

facturasend.preventDeleteQR=false

port=3011

Clave	Valor
facturasend.sendLote.time	Intervalo de tiempo en milisegundos, en el cual la aplicación enviará los documentos recibidos a FacturaSend. Predeterminado 1Hr.
facturasend.saveResponseXML	Si existe y es igual a true, se guarda una copia del XML de cada documento recibido en la carpeta ./xml
facturasend.preventDeleteQR	Si existe y es igual a true, no se borrarán los códigos QR de documentos recibidos
facturasend.showJarOutput	Si existe y es igual a true, muestra la salida de la ejecución de la generación de archivos PDFs.
port=3011	Puerta del Servidor HTTP para escuchar peticiones

Generación directa de PDFs

Para que el PDF sea generado automáticamente al momento de la emisión off-line, y que el mismo sea almacenado en la carpeta ./pdf, se requiere tener instalado el jdk8 en el equipo del cliente. La instalación deberá ser realizada de manera independiente.

También se requiere una aplicación independiente con extensión .jar (Java ARchive) llamada kude-offline.jar.

Esta aplicación está contenida dentro de un archivo ZIP y debe ser descargada desde el siguiente enlace:

http://facturasend.s3.us-east-1.amazonaws.com/binaries/kude-offline.zip

Dentro de donde instaló la aplicación off-line, debe crear una carpeta llamada kude-offline y dentro de esa carpeta descomprimir el archivo ZIP. 

Por ejemplo:

c:\facturasend-offline\kude-offline\kude-offline.jar
La aplicación off-line generará automáticamente el PDF si el archivo kude-offline.jar se encuentra en la ubicación correcta.

Generación de PDF a pedido

Caso desee generar un documento PDF, luego de que ya se hayan creado el documento y el PDF, el mismo se puede realizar mediante la llamada al endpoint de/pdf de la API.

El endpoint funciona de la misma forma cómo funciona el endpoint de FacturaSend en la nube, incluso se pueden generar más de un documento al mismo tiempo, informando el CDC del documento correspondiente.

Ejemplo postman:

Para utilizar éste endpoint, el documento tuvo que haber sido generado previamente con la aplicación, es decir, ya tiene que existir el archivo JSON en la carpeta ./json y el XML en la carpeta ./xml.

Envíos de documentos a FacturaSend – Sincronización

Todos los documentos que se envían a la aplicación off-line, son almacenados dentro de la carpeta ./data/ con la estructura de nombre siguiente “json-{fechaHora}.json” para su posterior proceso y se quedan allí hasta que sean enviados al servidor final de FacturaSend.

El archivo .json, puede estar compuesto por 3 atributos principales:

envio_lote Contiene el JSON que el off-line recibió por API REST

respuesta Contiene la respuesta que la aplicación off-line respondió a quien
invocó la API REST.

envio_error Ocurre cuando el retorno del envío del documento a FacturaSend online
tuvo algún error y no se creó el documento en la plataforma.
Generalmente va encontrar éste atributo en los archivos con
sufijo “json.error”

Cada cierto tiempo, establecido en un valor de milisegundos por la variables de entorno “facturasend.sendLote.time” del archivo .env, se tomarán todos los archivos .json que están pendientes de envío y se enviarán a FacturaSend. El valor por defecto de la variable de entorno “facturasend.sendLote.time” es de 1 (una) hora (3600000 ms), pero por ejemplo si desea cambiar ésta propiedad a 10 segundos debe especificar (10000 ms).

Una vez procesados, los archivos enviados cambian su sufijo a .json.processed, por ejemplo “json-{fechaHora}.json.procesed” y ya no son tomados en el próximo intervalo del envío del lote.

Los archivos .json.processed, contienen información importante en formato JSON sobre los datos enviados y el proceso resultante del envío del lote. Para ver el resultado del envío puede abrir el contenido de éste archivo, y examinar la respuesta que se ve en el atributo “respuesta”

Error al enviar el documento a FacturaSend

En ocasiones, puede ser que un determinado documento tenga algún error que no permita generarse el documento en FacturaSend, algunos ejemplos de éstos casos pueden ser por:

Error Documento (Tipo 1) 001-001-1007434  ya existe

Puede ser que la aplicación off-line permitió sin ningún tipo de validación crear el documento localmente, pero cuando se envía a FacturaSend, no se obtiene el mismo resultado, ya que en FacturaSend ya existía.

Otros errores comunes pueden darse por la validación de RUC que puede estar activado en FacturaSend y que como en el modo off-line no se tiene en cuenta, no permite generar el documento en FacturaSend. También se tienen los casos cuando se verifican los documentos asociados antes de enviar, los cuales también podrían ser motivos de errores.

Para éstos caso cuando no se genera el documento en FacturaSend, debe tener en cuenta que los archivos .json, cambian de nombre a .json.error, por ejemplo “json-{fechaHora}.json.error”

Para volver a enviar los JSON de los cuales tuvo error tiene 2 opciones, una es volviendo a enviar el JSON a la API off-line y la otra es retirando manualmente el sufijo .error del nombre del archivo “json-{fechaHora}.json.error”
Los archivos .json.processed que son procesados con éxito en FacturaSend, se eliminarán de la carpeta ./data/. En cambio los archivos .json.error que tuvieron falla quedarán como histórico en la carpeta ./data/ para su análisis respectivo

Recomendaciones

• Se recomienda empezar a implementar la solución off-line una vez que haya pasado un tiempo desde que ha logrado la integración con el modo on-line (modo normal) de facturasend, para que sea más sencillo su funcionamiento, es decir, entienda bien el modo on-line primero para luego pasar a implementar la opción off-line.
• No realice cambios y no haga pruebas de integración desde su sistema, para con el modo off-line ni para con el modo on-line, en ambiente de producción. Utilice para ello siempre el ambiente de PRUEBAS SIFEN.
• Debido a que la integración utilizando el on/off-line son idénticas (parámetros y respuestas), mantenga un parámetro en su sistema, que indique si la integración es de una forma u otra , de forma que pueda ser fácil cambiar utilizando uno u otro en el momento de necesidad.

Conclusión

FacturaSend Off-line es una solución práctica y robusta para la generación de documentos electrónicos en entornos sin conexión a Internet. Permite emitir facturas electrónicas desde aplicaciones locales de escritorio o sistemas propios, generando el XML firmado, el CDC, el código QR y el PDF del KUDE sin depender de la nube. Además, mantiene la sincronización automática con la plataforma en línea de FacturaSend cuando la conexión está disponible, asegurando cumplimiento fiscal y trazabilidad.

Con una configuración sencilla, compatibilidad multiplataforma y una API local fácil de integrar, es la herramienta ideal para desarrolladores, empresas y contadores que necesitan operar en modo off-line sin sacrificar eficiencia ni seguridad.