Manual Técnico: Backend Intermedio Spring Boot para VeriFactu

Java 21 Spring Boot 3.2 WSDL & JAXB WS-Security Docker Compose

El Concepto "Proxy Inteligente"

El backend de Novapay opera bajo el patrón de diseño Facade (Fachada) o "Proxy Inteligente". Actúa como un intermediario o diplomático técnico entre la sencillez requerida por las aplicaciones cliente TPV (tablets o terminales con interfaz en Flutter que envían JSON simplificados) y la estricta complejidad formal exigida por la Agencia Tributaria.

Gracias a este diseño, las aplicaciones de cobro en el punto de venta no necesitan gestionar certificados digitales empresariales, lidiar con bibliotecas de criptografía nativa en Android o Windows, ni interpretar esquemas XML de miles de líneas. El servicio Spring Boot centraliza estas responsabilidades, garantizando el cumplimiento normativo sin afectar la velocidad de venta.

📱

Flutter App / TPV

Envía JSON ligero con datos de venta
(Factura DTO)

➔

☕

Spring Boot Middleware

Valida integridad del DTO
Calcula Hash SHA-256 encadenado
Genera XML vía POJOs JAXB/CXF
Firma X.509 con certificado .p12
Transmite paquete SOAP WS-Security

➔

🏛️

Servidores AEAT

Recibe SOAP Firmado
Verifica huella y devuelve CSV

Seguridad de API (Spring Security)

Los endpoints REST expuestos al punto de venta se protegen mediante tokens JWT (JSON Web Tokens) con caducidad corta o claves API Key por dispositivo registrado. Esto impide que terminales no autorizadas o actores maliciosos puedan invocar servicios de facturación a nombre de la empresa.

Resiliencia (Resilience4j Circuit Breaker)

Si la infraestructura de la Agencia Tributaria sufre degradación o caídas de red, la librería Resilience4j abre el circuito para evitar bloquear los hilos del servidor Java. La factura se asienta en la base de datos local y se delega la retransmisión al hilo asíncrono.

Estructura de Carpetas del Proyecto Java

Standard Spring Boot Layout

src/main/java/com/novapay/verifactu
├── config/ // Beans SOAP, WebServiceTemplate y Security
├── controller/ // Endpoints REST que reciben DTO desde Flutter
└── FacturaController.java
├── service/ // Lógica de negocio y encadenamiento SHA-256
└── VeriFactuService.java
├── model/ // Entidades JPA e InvoiceDTO de entrada
├── integration/ // Capa SOAP & CXF
├── aeat.generated/ // POJOS AUTO GENERADOS
└── AeatSoapClient.java
└── utils/ // SHA-256 & Firma Digital X.509
└── SignatureUtil.java
src/main/resources
├── application.yml
├── certs/
└── certificado_aeat.p12
└── wsdl/
└── SuministroFacturas.wsdl

Justificación Arquitectónica de Carpetas

📂 aeat.generated

Aísla los miles de objetos Java autogenerados desde el WSDL de la AEAT. Al mantenerlos en su propio paquete separado, se evita contaminar las clases del dominio de negocio y se facilita la actualización futura del esquema tributario.

📄 AeatSoapClient.java

Implementa la comunicación remota utilizando `WebServiceTemplate` de Spring WS. Inyecta el interceptor `Wss4jSecurityInterceptor` encargado de añadir el encabezado WS-Security firmado antes de la transmisión.

🔑 certs/certificado.p12

Certificado digital en formato PKCS#12 (.p12). Contiene la clave privada RSA legal de la empresa. Por seguridad, este archivo se ignora en .gitignore y se monta dinámicamente mediante volúmenes en producción.

Automatización de Clases Java desde WSDL

Una de las ventajas fundamentales de utilizar Java en el backend es la existencia de herramientas de compilación como cxf-codegen-plugin o jaxb2-maven-plugin. Estos plugins leen directamente los archivos de definición WSDL oficiales proporcionados por la AEAT y los compilan a clases Java POJO fuertemente tipadas durante la fase ./mvnw compile.

Esto elimina por completo la necesidad de concatenar cadenas XML manualmente, previniendo errores de sintaxis en etiquetas o atributos y permitiendo autocompletado y validación de tipos en tiempo de compilación.

Entrada (Definición Oficial)

📄

SuministroFacturas.wsdl

Esquema XML Complejo de AEAT

➔ Compilación `cxf-codegen` ➔

Salida (Código Fuertemente Tipado)

☕

POJOs Java Generados

`SuministroLRFacturasEmitidas.java`

// Uso real de clases autogeneradas en VeriFactuService.java

SuministroLRFacturasEmitidas peticion = new SuministroLRFacturasEmitidas();

CabeceraSuministro cabecera = new CabeceraSuministro();

cabecera.setIDVersionSuministro("1.0");

cabecera.setTitular(new PersonaFisicaJuridicaESType("B12345678", "Novapay S.L."));

peticion.setCabecera(cabecera);

// Spring WS transforma la instancia POJO a XML, inyecta WS-Security X.509 y ejecuta la llamada HTTPS

Object respuesta = webServiceTemplate.marshalSendAndReceive(peticion);

Estrategia de Despliegue en Contenedores (Docker)

Al empaquetar la aplicación en un contenedor estandarizado, se garantiza que el comportamiento de la pila de librerías criptográficas de Java 21 sea exactamente idéntico en el entorno de desarrollo local, en la Raspberry Pi 5 de pruebas y en el servidor de producción.

# docker-compose.yml (Stack de Producción)

services:
  verifactu-backend:
    image: novapay-backend:latest
    ports: "127.0.0.1:8080:8080"
    volumes:
      - ./certs:/app/certs:ro # Lectura segura del certificado digital
    environment:
      - SPRING_PROFILES_ACTIVE=prod

  postgres-db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data

Plan de Mantenimiento Operativo

✓ Logs Centralizados: Rotación diaria mediante Logback. Si la AEAT rechaza un paquete, se almacena el XML completo devuelto para auditoría rápida.
✓ Renovación de Certificados: Los certificados expirados paralizan la facturación. Al estar montados vía volumen, basta sustituir el archivo .p12 en el host y reiniciar el contenedor.

Plan de Recuperación de Desastres

⚠ Cola de Reintentos `@Scheduled`: Ante caídas prolongadas de la Agencia Tributaria, las facturas en estado PENDING se reintentan en segundo plano de forma automática.
⚠ Backups Automáticos PostgreSQL: Copias de seguridad diarias via pg_dump. La base de datos relacional es la única fuente de verdad inalterable del negocio.

← Volver a la portada ↑ Volver arriba