Como bien es sabido, el KuDE (Kuatia Documento Electrónico) es la representación visual del documento electrónico XML entregada al Receptor del Documento Electrónico 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
https://www.filehorse.com/download-jaspersoft-studio/71004/download/#google_vignette
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/los archivos .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
Los archivos Jasper se descargan en formato comprimido .zip.
Tenga en cuenta que todos los archivos descomprimidos deben estar en la misma ubicación y ser accesibles desde el Jasper Studio al momento de la compilación
Una vez listo los archivos .jasper descargado y descomprimidos 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 antes de modificar e ir versionando los cambios realizados, 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 parte del archivo XML al reporte, 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
Como los campos ya vienen en el XML, todo lo que tiene que hacer es seguir los siguientes pasos, se muestra desde cero:
- 1. Clic sobre el icono “DataSet and Query editor dialog” mostrado en la pantalla.
- 2. Seleccionar la fuente de datos que contiene el XML con los datos extras que desea mostrar. Si su XML no posee los datos extras, descarguelo de la plataforma con el parmetro ?extras=true. Ver endpoint para obtener XML por CDC AQUI.
- 3. Una vez seleccionado la fuente de datos que contiene el XML, entonces apareceran los campos en el cuadro de lista izquierdo. Debe buscar el atributo de la ruta /DE/extras, segun se ve en la figura de abajo.
- 4. Al expandir el campo extras, apareceran los sub-nodos (atributos) contenidos en el nodo extras del XML. Alli puede seleccionar el campo que desea o seleccionar todos los campos uno a uno y por cada uno seleccionar la opcion Add node as field (Agregar nodo como campo)
- 5. Note que cuando el nodo es agregado como campo ya aparece en el listado inferior de campos. Una vez logrado esto ya se puede utilizar dicho campo en el informe.
- 6. Para mostrar el campo agregado en el informe, entonces en la vista “Outline“, desde la rama “Fields” arrastrar el campo deseado hacia cualquier parte del informe.
Con estos pasos ya se termina la inclusion del campo extra en el informe.
Caso de datos extras en los ítems
Para mostrar un campo extra del item se sigue el mismisimo proceso. A continuacion se muestra paso a paso:
"extras" : {
"taxRate" : "15%",
"barCode": "7937638273256",
"storeId" : 3
}
.
- 1. En la lista de campos buscar el nodo extras para expandirlo y encontrar el nodo especifico que desea utilizar.
El resto de los pasos es exactamente igual al proceso ya mostrado anteriormente.
Problemas conocidos
Cuando intenta 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 -fSerie de Videos – Curso de Personalización de KuDE de Facturasend
https://www.youtube.com/watch?v=3e6WepIhT14
https://www.youtube.com/watch?v=_cNGO-NSzc0
https://www.youtube.com/watch?v=SRhfsnNB4Z4
https://www.youtube.com/watch?v=2DiO9VFKpOQ
Observación
Las fuentes aceptadas por el servidor son: Serif y SanSerif
