Integrar con Spring Boot, Quarkus o Jakarta EE
En Java hay integraciones para Spring Boot, Quarkus y Jakarta EE (CDI con MicroProfile Config). Configuras la empresa en tus propiedades y luego inyectas un SunatClient compartido y un FileSender listo para enviar. Quarkus, además, te da un XBuilder configurable.
Qué te da cada integración
| Spring Boot | Quarkus | Jakarta EE / MicroProfile | |
|---|---|---|---|
| Dependencia | spring-boot-xsender | quarkus-xbuilder, quarkus-xsender | xsender-cdi |
| Prefijo de propiedades | xsender.* | quarkus.xsender.*, quarkus.xbuilder.* | xsender.* |
SunatClient | Sí | Sí | Sí |
FileSender | Solo si defines xsender.company.username | Sí, si defines quarkus.xsender.company.* | Sí, si defines xsender.company.* |
XBuilder | No (créalo con new XBuilder()) | Sí | No (créalo con new XBuilder()) |
Los beans son singletons: un único SunatClient (conexiones y tokens) y un FileSender para la empresa configurada, que usa ese mismo SunatClient. XBuilder y XSigner son seguros para usar desde varios hilos, así que puedes tenerlos como campos.
Dependencias
- Spring Boot
- Quarkus
- Jakarta EE
<dependency>
<groupId>io.github.project-openubl</groupId>
<artifactId>spring-boot-xsender</artifactId>
<version>6.0.0-alpha.1</version>
</dependency>
<!-- Para crear y firmar: no hay integración de xbuilder para Spring -->
<dependency>
<groupId>io.github.project-openubl</groupId>
<artifactId>xbuilder</artifactId>
<version>6.0.0-alpha.1</version>
</dependency>
La configuración se carga sola (autoconfiguración de Spring Boot); no necesitas @ComponentScan ni @Import.
<dependency>
<groupId>io.github.project-openubl</groupId>
<artifactId>quarkus-xbuilder</artifactId>
<version>6.0.0-alpha.1</version>
</dependency>
<dependency>
<groupId>io.github.project-openubl</groupId>
<artifactId>quarkus-xsender</artifactId>
<version>6.0.0-alpha.1</version>
</dependency>
Las extensiones funcionan también en compilación nativa.
<dependency>
<groupId>io.github.project-openubl</groupId>
<artifactId>xsender-cdi</artifactId>
<version>6.0.0-alpha.1</version>
</dependency>
<dependency>
<groupId>io.github.project-openubl</groupId>
<artifactId>xbuilder</artifactId>
<version>6.0.0-alpha.1</version>
</dependency>
xsender-cdi necesita CDI y MicroProfile Config, pero no los incluye: los aporta tu servidor de aplicaciones (por ejemplo, WildFly).
Configuración
Las claves son las mismas en los tres frameworks; solo cambia el prefijo. Los ejemplos usan el entorno beta.
Propiedad (company.*) | Para qué sirve |
|---|---|
invoice-url | Facturas, boletas, notas, resúmenes y bajas |
perception-retention-url | Percepciones, retenciones y reversiones |
despatch-url | Guías de remisión |
username, password | Usuario y clave SOL |
client-id, client-secret | Credenciales de la API, solo para guías de remisión |
- Spring Boot
- Quarkus
- Jakarta EE
xsender.company.invoice-url=https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billService
xsender.company.perception-retention-url=https://e-beta.sunat.gob.pe/ol-ti-itemision-otroscpe-gem-beta/billService
xsender.company.username=12345678959MODDATOS
xsender.company.password=MODDATOS
# Solo para guías de remisión (la SUNAT no tiene beta para ellas):
# xsender.company.despatch-url=https://api-cpe.sunat.gob.pe/v1/contribuyente/gem
# xsender.company.client-id=...
# xsender.company.client-secret=...
quarkus.xsender.company.invoice-url=https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billService
quarkus.xsender.company.perception-retention-url=https://e-beta.sunat.gob.pe/ol-ti-itemision-otroscpe-gem-beta/billService
quarkus.xsender.company.username=12345678959MODDATOS
quarkus.xsender.company.password=MODDATOS
# Solo para guías de remisión (la SUNAT no tiene beta para ellas):
# quarkus.xsender.company.despatch-url=https://api-cpe.sunat.gob.pe/v1/contribuyente/gem
# quarkus.xsender.company.client-id=...
# quarkus.xsender.company.client-secret=...
# Opcional: tasas por defecto del XBuilder inyectado (por defecto, las vigentes)
# quarkus.xbuilder.igv-tasa=0.18
# quarkus.xbuilder.icb-tasa=...
# quarkus.xbuilder.ivap-tasa=...
Usa cualquier fuente de MicroProfile Config, por ejemplo:
xsender.company.invoice-url=https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billService
xsender.company.perception-retention-url=https://e-beta.sunat.gob.pe/ol-ti-itemision-otroscpe-gem-beta/billService
xsender.company.username=12345678959MODDATOS
xsender.company.password=MODDATOS
# Solo para guías de remisión (la SUNAT no tiene beta para ellas):
# xsender.company.despatch-url=https://api-cpe.sunat.gob.pe/v1/contribuyente/gem
# xsender.company.client-id=...
# xsender.company.client-secret=...
Hay una propiedad más, fuera de company: security-api-url (xsender.security-api-url o quarkus.xsender.security-api-url), que indica dónde se piden los tokens de las guías. Por defecto es el de la SUNAT (https://api-seguridad.sunat.gob.pe); normalmente no necesitas cambiarla.
Inyectar y usar
- Spring Boot
- Quarkus
- Jakarta EE
import io.github.project.openubl.xbuilder.XBuilder;
import io.github.project.openubl.xsender.FileSender;
import io.github.project.openubl.xsender.sunat.SunatClient;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import java.io.IOException;
@RestController
public class InvoiceController {
private final FileSender xsender; // la empresa de xsender.company.*
private final SunatClient sunatClient; // compartido
private final XBuilder xbuilder = new XBuilder();
public InvoiceController(FileSender xsender, SunatClient sunatClient) {
this.xsender = xsender;
this.sunatClient = sunatClient;
}
@PostMapping("/api/file/upload")
public String upload(@RequestParam("file") MultipartFile file) throws IOException {
// Recibe un XML ya firmado y lo envía
return xsender.sendFile(file.getBytes()).getStatus().toString();
}
}
import io.github.project.openubl.xbuilder.XBuilder;
import io.github.project.openubl.xbuilder.models.Invoice;
import io.github.project.openubl.xsigner.SigningKey;
import io.github.project.openubl.xsigner.XSigner;
import io.github.project.openubl.xsender.FileSender;
import io.github.project.openubl.xsender.sunat.SunatClient;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
@Path("/invoices")
@ApplicationScoped
public class InvoiceResource {
@Inject
XBuilder xbuilder; // con las tasas de quarkus.xbuilder.*
@Inject
FileSender xsender; // la empresa de quarkus.xsender.company.*
@Inject
SunatClient sunatClient; // compartido
private final XSigner xsigner = new XSigner();
private final SigningKey key;
public InvoiceResource() throws IOException {
key = SigningKey.fromPkcs12(Files.readAllBytes(Paths.get("certificado.pfx")), "password");
}
@POST
public String send(Invoice invoice) {
String xml = xbuilder.build(invoice);
byte[] signed = xsigner.sign(xml.getBytes(StandardCharsets.UTF_8), key);
return xsender.sendFile(signed).getStatus().toString();
}
}
import io.github.project.openubl.xsender.FileSender;
import io.github.project.openubl.xsender.sunat.SunatClient;
import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
@Path("/ubl")
@RequestScoped
public class UBLResource {
@Inject
FileSender xsender; // la empresa de xsender.company.*
@Inject
SunatClient sunatClient; // compartido
@POST
public String send(byte[] signedXml) {
return xsender.sendFile(signedXml).getStatus().toString();
}
}
Si falta la configuración
- Spring Boot: si no defines
xsender.company.username, el beanFileSendersimplemente no se crea (elSunatClientsí). Si inyectasFileSendersin esa propiedad, Spring falla al arrancar porque no encuentra el bean. Si definesusernamepero nopassword, falla conIllegalStateException. - Quarkus: si inyectas
FileSendersinquarkus.xsender.company.*, falla conIllegalStateExceptional crear el bean. Si definescompany,usernameypasswordson obligatorios. - Jakarta EE: si inyectas
FileSendersinxsender.company.usernameo sinxsender.company.password, falla conIllegalStateException.
Reemplazar los beans o usar varias empresas
Los beans se pueden reemplazar por los tuyos:
- Spring Boot: declara tu propio
@Beande tipoSunatClientoFileSendery el de xhandler no se crea. - Quarkus: los beans de xhandler son beans por defecto; un bean tuyo del mismo tipo los reemplaza.
- Jakarta EE: produce el tuyo como
@Alternative @Priority(1).
El bean FileSender envía para una empresa. Si emites para varias, inyecta el SunatClient compartido y crea un FileSender por empresa:
FileSender sender = new FileSender(URLs.production(), credencialesDeLaEmpresa, sunatClient);
Revisa Facturar para varias empresas.
Ver también
- Instalación
- Consultar y validar comprobantes: los servicios de consulta están en el
SunatClientinyectado. - Firma digital