project-openubl · muglerman · Jan 12, 2026 · Jan 12, 2026
diff --git a/.gitignore b/.gitignore
@@ -54,4 +54,5 @@ target
 *dependency-reduced-pom.xml
 
 /lsp/
-bin/
+bin/
+.vscode/*
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,3 +1,4 @@
 {
-    "java.configuration.updateBuildConfiguration": "interactive"
+    "java.configuration.updateBuildConfiguration": "interactive",
+    "java.compile.nullAnalysis.mode": "automatic"
 }
diff --git a/README.md b/README.md
@@ -1,48 +1,95 @@
+# XHandler Java
+
 [![License](https://img.shields.io/github/license/project-openubl/xhandler?logo=apache)](https://www.apache.org/licenses/LICENSE-2.0)
 [![CI](https://github.com/project-openubl/xhandler/actions/workflows/ci.yml/badge.svg)](https://github.com/project-openubl/xhandler/actions/workflows/ci.yml)
-
 [![Project Chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg?style=for-the-badge&logo=zulip)](https://projectopenubl.zulipchat.com/)
 [![Supported JVM Versions](https://img.shields.io/badge/JVM--17-brightgreen.svg?style=for-the-badge&logo=Java)](https://github.com/project-openubl/xhandler/actions/)
 
-| Artifact                      | Version                                                                                                                                                                              |
-|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| XBuilder                      | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/xbuilder)](https://search.maven.org/artifact/io.github.project-openubl/xbuilder/)                 |
-| XBuilder Quarkus extension    | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/quarkus-xbuilder)](https://search.maven.org/artifact/io.github.project-openubl/quarkus-xbuilder/) |
-| XSender                       | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/xsender)](https://search.maven.org/artifact/io.github.project-openubl/xsender/)                   |
-| XSender Quarkus extension     | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/quarkus-xsender)](https://search.maven.org/artifact/io.github.project-openubl/quarkus-xsender/)   |
-| XSender Spring Boot extension | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/spring-boot-xsender)](https://search.maven.org/artifact/io.github.project-openubl/spring-boot-xsender/)   |
+**XHandler Java** es una suite de herramientas diseñada para facilitar la integración de **Facturación Electrónica en Perú (SUNAT)** en aplicaciones Java. Este repositorio es un "monorepo" que alberga las librerías `XBuilder` y `XSender`, proporcionando una solución integral para crear, firmar y enviar comprobantes de pago electrónicos.
+
+> [!TIP]
+> Si buscas integrar facturación electrónica de manera rápida y estándar, estás en el lugar correcto.
+
+---
+
+## 📦 Ecosistema
 
-# XBuilder
+El proyecto se divide en módulos principales y extensiones para frameworks populares:
 
-Librería Java para crear XMLs basados en UBL y los estándares de la SUNAT respecto a la facturación electrónica.
+| Componente | Descripción | Maven Central |
+|------------|-------------|---------------|
+| **XBuilder** | Creación y firma de XMLs (UBL 2.1) | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/xbuilder)](https://search.maven.org/artifact/io.github.project-openubl/xbuilder/) |
+| **XSender** | Envío de comprobantes a SUNAT/OSE | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/xsender)](https://search.maven.org/artifact/io.github.project-openubl/xsender/) |
+| **Quarkus XBuilder** | Extensión XBuilder para Quarkus | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/quarkus-xbuilder)](https://search.maven.org/artifact/io.github.project-openubl/quarkus-xbuilder/) |
+| **Quarkus XSender** | Extensión XSender para Quarkus | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/quarkus-xsender)](https://search.maven.org/artifact/io.github.project-openubl/quarkus-xsender/) |
+| **Spring Boot XSender** | Starter XSender para Spring Boot | [![Maven Central](https://img.shields.io/maven-central/v/io.github.project-openubl/spring-boot-xsender)](https://search.maven.org/artifact/io.github.project-openubl/spring-boot-xsender/) |
 
-XBuilder esta diseñado para que puedas crear XMLs fácilmente.
+---
 
-- Crea XMLs sin que necesites conocer nada sobre manejo de archivos XMLs.
-- Hace cálculos internos por ti.
-- Requiere solamente datos mínimos.
+## 🛠️ XBuilder
 
-## ¿Qué puedes hacer con XBuilder?
+XBuilder abstrae la complejidad de los estándares UBL y XML, permitiéndote construir documentos tributarios válidos escribiendo código Java simple.
 
-- Crear XMLs
-- Firmar XMLs
+### Características
+- **Simple**: No necesitas manipular XML directamente ni conciliar namespaces complejos.
+- **Completo**: Soporte para Facturas, Boletas, Notas de Crédito/Débito, Guías de Remisión y Percepciones/Retenciones.
+- **Validado**: Realiza cálculos automáticos y validaciones básicas según normativa SUNAT.
 
-### Update snapshots
+### Ejemplo de Uso
 
-```shell
-mvn clean test -Dxbuilder.snapshot.update
+```java
+// Ejemplo simplificado de creación de factura
+Invoice invoice = Invoice.builder()
+    .serie("F001")
+    .numero(1)
+    .proveedor(proveedor)
+    .cliente(cliente)
+    .detalle(detalle)
+    .build();
+
+XMLInvoice xml = new InvoiceXMLBuilder().build(invoice);
 ```
 
-# XSender
+> [!NOTE]
+> Para actualizar los snapshots de prueba en desarrollo local, ejecuta:
+> `mvn clean test -Dxbuilder.snapshot.update`
+
+---
+
+## 🚀 XSender
+
+XSender se encarga de la comunicación con los servicios SOAP de la SUNAT o de los Operadores de Servicios Electrónicos (OSE).
+
+### Características
+- **Compatible**: Soporta los diversos endpoints de SUNAT (Beta/Producción) y OSEs.
+- **Resiliente**: Gestiona el envío de archivos ZIP y el procesamiento de respuestas (CDR, Tickets).
+- **Flexible**: Fácil integración con frameworks modernos como Quarkus y Spring Boot.
+
+---
+
+## 💻 Ejemplos
+
+Explora la carpeta `examples/` para ver implementaciones de referencia:
+
+- [**Spring Boot**](./examples/springbot): Ejemplo de integración completa usando Spring Boot.
+- [**Wildfly**](./examples/wildfly): Ejemplo para servidores de aplicaciones Jakarta EE.
+- [**Tomcat**](./examples/tomcat): Ejemplo ligero desplegable en Tomcat.
+- [**XBuilder/XSender**](./examples): Ejemplos "standalone" de uso de las librerías.
+
+---
+
+## 📚 Documentación
+
+Para guías detalladas, referencia de API y tutoriales, consulta nuestra documentación oficial.
 
-Libreria para realizar envíos de comprobantes electrónicos a los servicios web de la SUNAT y/o OSCE de acuerdo a lo
-especificado por la SUNAT.
+- 📖 **Sitio Web**: [project-openubl.github.io](https://project-openubl.github.io)
+- 💬 **Comunidad**: [Únete al chat en Zulip](https://projectopenubl.zulipchat.com/)
+- 🐛 **Soporte**: [Reportar un problema o discutir mejoras](https://github.com/project-openubl/xsender/discussions)
 
-# Getting started
+---
 
-- [Documentación](https://project-openubl.github.io)
-- [Discusiones](https://github.com/project-openubl/xsender/discussions)
+## 📄 Licencia
 
-## License
+Este proyecto se distribuye bajo la licencia **Apache 2.0**. Consulta el archivo [LICENSE](LICENSE) para más detalles.
 
-- [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+Copyright © Project OpenUBL.
diff --git a/examples/pom.xml b/examples/pom.xml
@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.github.project-openubl</groupId>
         <artifactId>xhandler-parent</artifactId>
-        <version>5.0.3-SNAPSHOT</version>
+        <version>6.0.0-SNAPSHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

diff --git a/examples/springbot/pom.xml b/examples/springbot/pom.xml
@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.github.project-openubl</groupId>
         <artifactId>examples-parent</artifactId>
-        <version>5.0.3-SNAPSHOT</version>
+        <version>6.0.0-SNAPSHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 
@@ -47,7 +47,7 @@
         <dependency>
             <groupId>io.github.project-openubl</groupId>
             <artifactId>spring-boot-xsender</artifactId>
-            <version>4.1.4</version>
+            <version>6.0.0-SNAPSHOT</version>
         </dependency>
 
         <!-- Spring minimum libraries -->
-Original file line number
+Diff line change
@@ Expand Up / @@ -54,4 +54,5 @@ target @@
     *dependency-reduced-pom.xml
     /lsp/
-    bin/
+    bin/
+    .vscode/*