Saltar al contenido principal

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 BootQuarkusJakarta EE / MicroProfile
Dependenciaspring-boot-xsenderquarkus-xbuilder, quarkus-xsenderxsender-cdi
Prefijo de propiedadesxsender.*quarkus.xsender.*, quarkus.xbuilder.*xsender.*
SunatClientSíSíSí
FileSenderSolo si defines xsender.company.usernameSí, si defines quarkus.xsender.company.*Sí, si defines xsender.company.*
XBuilderNo (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​

pom.xml
<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.

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-urlFacturas, boletas, notas, resúmenes y bajas
perception-retention-urlPercepciones, retenciones y reversiones
despatch-urlGuías de remisión
username, passwordUsuario y clave SOL
client-id, client-secretCredenciales de la API, solo para guías de remisión
application.properties
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​

InvoiceController.java
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();
}
}

Si falta la configuración​

  • Spring Boot: si no defines xsender.company.username, el bean FileSender simplemente no se crea (el SunatClient sí). Si inyectas FileSender sin esa propiedad, Spring falla al arrancar porque no encuentra el bean. Si defines username pero no password, falla con IllegalStateException.
  • Quarkus: si inyectas FileSender sin quarkus.xsender.company.*, falla con IllegalStateException al crear el bean. Si defines company, username y password son obligatorios.
  • Jakarta EE: si inyectas FileSender sin xsender.company.username o sin xsender.company.password, falla con IllegalStateException.

Reemplazar los beans o usar varias empresas​

Los beans se pueden reemplazar por los tuyos:

  • Spring Boot: declara tu propio @Bean de tipo SunatClient o FileSender y 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​