Como bien es sabido, el KuDE es la representación visual del documento electrónico XML entregada al Receptor que adquiere un producto o servicio, y si bien el SIFEN establece unos parámetros básicos para su formato válido, es normal que algunas emisores quieran adaptarlo, deseando incorporar más datos de los exigidos como obligatorios.
La Facturación Electrónica con FacturaSend, desde sus inicios y de forma nativa, permite al emisor final personalizar el KuDE de manera básica o avanzada, permitiendo adaptar por completo el documento, por ejemplo para obtener las siguientes características:
- Cambio en el encabezado estándar de la Factura, tamaño de Logo, posición de Razón Social, etc.
- Agregar o quitar bordes, añadir un mensaje fijo en la cabecera o pie.
- Dividir el formato de un documento por hoja en 2 o hasta 3 documentos en una sola hoja.
- Agregar información adicional debajo de cada ítem de producto/servicio.
- Agregar lógica de programación para mostrar/ocultar campos de acuerdo a los datos de la Factura.
- Añadir cualquier información adicional, que provenga de ERP, incluso si esa información no se envía en el XML.
Cabe destacar que FacturaSend permite gestionar 3 formatos específicos de impresión, por cada tipo de documento electrónico, lo cual otorga mucha flexibilidad y permite adaptarse a las necesidades de cualquier negocio u organización, entre las que se citan:
- Formato A4: es el formato por defecto, muestra una factura por hoja en tamaño A4, pero se puede personalizar a Oficio u otro tamaño.
- Formato Personalizado(Custom): es un formato auxiliar al por defecto y se puede usar para imprimir datos extras cuando fueren necesarios, por ejemplo para una factura de exportación, donde hay que añadir más datos sobre el destinatario.
- Formato Ticket: es el formato más utilizado para negocios de comercialización de consumo masivo, supermercados, estaciones de servicios, etc. Este formato permite el ahorro en papel.
Para entender a profundidad sobre la personalización del KUDE, a continuación, estaremos viendo los siguientes temas:
- Instalación del Jaspersoft
- Creación del Proyecto
- Agregar Librerías
- Crear un DataSet en base a un archivo XML de ejemplo
- Descargar el Jasper de FacturaSend
- Abrir y modificar Jasper
- Compilar Reporte
- Probar reporte
- Actualizar Jasper en FacturaSend
- Parámetros EXTRAS
1. Instalación Jaspersoft
Todos los KuDES están representados cómo reportes en FacturaSend, entonces, el primer paso consiste en descargar y realizar la instalación de Jaspersoft® Studio . Este es el software que se utiliza para la edición de reportes.
A continuación indicamos la versión y la URL de descarga:
Windows
Linux
http://facturasend.s3.us-east-1.amazonaws.com/binaries/TIB_js-studiocomm_6.19.1_linux.zip
También puede acceder a la URL que se indica en la imagen de abajo, y navegar hasta encontrar la versión correcta, la cual recomendamos que sea la 6.19.1.
Una vez instalado el Jaspersoft, podemos intentar ejecutarlo y verificar si abre la aplicación correctamente. Seguidamente vamos al siguiente paso.
2. Creación del Proyecto
Para trabajar dentro del Jaspersoft y poder crear o editar reportes necesitamos primeramente crear un proyecto donde podamos agrupar todos los reportes de un grupo. Tenga en cuenta que dentro de éste proyecto puede crear carpetas y subcarpetas para organizar los reportes de varias empresas, por ejemplo.
Para crear el nuevo proyecto de Jaspersoft, vamos a dar clic derecho sobre la parte blanca de la vista “Project Explorer” y luego le damos New/Project, o el Wizard con el cual nos abrirá la siguiente pantalla:
luego agregamos un nombre al proyecto, en este caso lo llamamos “Modificaciones-Kude”
Una vez presionado el botón “Finish” y creado el proyecto se podrá ver que el proyecto aparecerá en la vista Project Explorer.
Luego se debe de agregar las librerías *.jar necesarias para poder compilar los reportes, el cual se explica a continuación:
3. Agregar librerías
Para agregar las librerías tenemos este enlace, que nos provee la descarga en zip de las librerías que se utilizarán:
https://facturasend.s3.us-east-1.amazonaws.com/binaries/facturaSend-jasperStudio-libs-20240820.zip
Se tratan de librerías .jar provistas por FacturaSend y que ya se encuentran en el servidor para realizar cambios básicos. Caso se requiera de una librería a parte usted deberá descargarla manualmente e incorporarla a su reporte de la misma manera, pero también necesitará agregar dicha librería a su servidor.
Luego de descargar todo descomprimimos el archivo, Creamos una carpeta llamada lib dentro del proyecto y copiamos allí las librerías
Una vez copiado las librerías le damos click derecho y seleccionamos todas las librerías .jar y elegimos la opción Add to build path
Las librerías quedan en el classpath del proyecto y pueden ser visualizadas a través de la ventana de propiedades.
El siguiente paso será:
- Crear un DataSet en base a un archivo XML de ejemplo
A continuación, vemos como hacerlo.
4. Crear un Dataset en base a un archivo XML de ejemplo
Para poder modificar el JASPER y visualizarlo posteriormente, necesitará contar con un dataset, es decir, un conjunto de datos, donde el origen será el XML del Documento Electrónico que desea probar.
Para ello puede descargar cualquier XML de su cuenta de FacturaSend y almacenarlo dentro del proyecto “Modificaciones KUDE”, por ejemplo bajo una carpeta llamada “xmls”
A continuación, en la imagen puede ver cómo crear una conexión Dataset.
Al seleccionar el DataAdapter le aparecerá una ventana con diferentes opciones para su utilización, en esta de debe de seleccionar “XML Document”
Luego de seleccionar el tipo de “Data Adapter”, aparecerá otra ventana:
En el punto 1 se debe de seleccionar el XML descargado desde FacturaSend y que recomendamos debía guardar dentro de una carpeta “xmls” dentro de su proyecto “Modificaciones KUDE”.
En el punto 2, se debe seleccionar el tipo de PATH, esto para que se puede leer correctamente el xml
Por último se puede hacer un test de conexión y luego dar por finalizada la creación del DATA Adapter.
5. Descargar el Jasper de FacturaSend
Todo proceso de personalización inicia por la edición de un documento ya existente, que sería la base para lo que desea modificar, en éste caso esa base consiste en archivos con la extensión .jasper los cuales ya se encuentran, todos ellos cargados en su cuenta de FacturaSend.
Desde FacturaSend podrá descargar todos los 3 formatos de Jasper por cada tipo de documento, tenga en cuenta de organizarlos adecuadamente en el proyecto del Jaspersoft para no mezclar un formato con otro cuando lo actualiza y evitar problemas.
Para descargar el .jasper del KuDE deseado siga los pasos:
Ir a la ventana de opciones dentro de FacturaSend
Luego ir a la ventana Conf. KUDE como se observa en el punto 1 de la siguiente imagen..
Una vez dentro se selecciona, primero, el Tipo de Documento que se desea modificar/descargar. En este caso se opto por “Factura Electrónica” como se puede observa en el punto 2 de la imagen anterior..
En el punto 3 se selecciona el tipo de formato(Estandar, Custom, Ticket) que se necesita.
En el punto 4 damos clic al botón descargar. Esto nos descarga un archivo .jasper que debe de colocarse dentro del proyecto. Para poder editarlo
6. Abrir y modificar Jasper
Una vez listo el .jasper descargado desde FacturaSend, se debe realizar doble clic al .jasper, esto genera un archivo .jrxml modificable como se observa en la imagen.
En este punto, ya es a consideración del usuario, que necesita agregar, modificar o quitar del KUDE. Tenga en cuenta que siempre debe hacer una copia de seguridad del .jasper al modificar, para no perder la versión que estaba funcionando.
En Youtube encontrará varios videos sobre la edición del Jasper y todas las posibilidades que tendrá una vez que pueda manejar ésta herramienta, a continuación, un curso básico:
7. Compilar Reporte
Tenga en cuenta que el JASPER modificado por usted, debe compilarse en ambiente local, antes de ser enviada a la Plataforma de FacturaSend.
Para compilar siga estos pasos:
Primero darle click al botón que muestra el punto 1 de la imagen.. esto hará una compilación general del archivo.
8. Probar reporte
Si se muestra el archivo como se ve en la imagen, significa que no hubo errores y está listo para ser actualizado en la consola del Facturasend
Al compilarse se creará un archivo .jasper, que estará junto al archivo jrxml editado. Ese archivo .jasper es el que utilizará posteriormente para levantar la actualización al Facturasend.
9. Actualizar Jasper en FacturaSend
Una vez modificado el archivo .jasper localmente, ésta debe subirse de nuevo a la plataforma de FacturaSend. Para ello, basta con ir al apartado de Conf. KUDE nuevamente:
Luego se da click al botón actualizar el Archivo Jasper, este abrira una ventana como se observa en el punto 2 de la imagen.
Allí debemos de buscar el archivo .jasper, una vez seleccionado y enviado saldrá un mensaje como se observa en la siguiente imagen
Luego ir al Listado de documentos y seleccionar el kude como se observa en el punto 1. Si todo se realizó sin inconvenientes.. el FacturaSend abrirá el PDF del Documento Electrónico seleccionado, y podrá ver los campos que usted editó.
Parámetros EXTRAS
Caso desee incorporar los parámetros extras enviados desde el JSON para visualizarlos en el KUDE, entonces debe saber que dichos datos extras son enviados como parámetros al JASPER, en el momento de su ejecución:
Suponiendo, como ejemplo, que envía estos datos extras como cabecera del DE:
“extras” : {
“pedidoCliente” : “2123-1”,
“numeroPresupuesto”: “P/001”,
“posTicketId” : 39271
}
entonces debería de crear los siguientes parámetros en su reporte:
- Parameter: pedidoCliente, tipo: String
- Parameter: numeroPresupuesto, tipo: String
- Parameter: posTicketId, tipo: Integer
Luego, una vez creados esos parámetros en el reporte lo puede mostrar en cualquier parte utilizando un componente textfield, utilizando la expresión $P{numeroPedido}, por ejemplo.
Caso de datos extras en los ítems
Luego, para este otro ejemplo, suponiendo que envíe en el JSON estos datos extras en cada ítem del DE:
“extras” : {
“taxRate” : “15%”,
“barCode“: “7937638273256”,
“storeId” : 3
}
Primero hay que crear el parámetro que recibirá los datos extras de los ítems como el tipo de dato java.util.List. Este parámetro tiene un nombre especial que es “ix_fs”
Luego, se debe crear una variable ITEM_COUNT que servirá como índice para recorrer dicho parámetro creado anteriormente.
Esta nueva variable debe ser inicializada con el valor -1, su expresión debe corresponder a la misma variable + 1, así: $V{ITEM_COUNT} + 1
Luego, para recuperar un valor específico del extra del item, se coloca la siguiente expresión, dentro de cada ítem mostrado.
Esta expresión debe estar dentro del grupo detalle, del reporte.
Nota: En la expresión se puede observar que del parámetro List ix_fs, se selecciona el item actual del array utilizando el índice $V{ITEM_COUNT} y si no es nulo le hacemos un cast a Map para poder acceder a los valores que se requieran.
Sugerencia
La personalización del KUDE es una opción de FacturaSend para que pueda realizar cambios de formato, fuentes, colores, líneas, tamaños, etc. Evite realizar modificaciones complejas, como por ejemplo agregar más campos, parámetros o variables, o realizar cálculos.
Problemas conocidos
Cuando intento ver el KUDE, no se muestra el PDF.
Es un error que puede ser por datos del Extras del JSON o tipo de datos del Jasper, para obtener información del error, puede ver el log del keycloak desde el servidor
docker logs keycloak -f
Video base para creación y modificación de jasper
Mini Curso Jasper Studio 01 Instalación y configuración
Observación
Las fuentes aceptadas por el servidor son: Serif y SanSerif
