Informe Backend API: Novapay Spring Boot

@RestController InvoiceController

Punto de entrada de peticiones REST HTTP. Desacopla la interfaz de usuario de las reglas tributarias del servidor. Recibe el DTO firmado por la sesión del cajero y delega la ejecución al servicio transaccional.

@PostMapping("/api/v1/invoices")
public ResponseEntity<InvoiceResult> create(@Valid @RequestBody InvoiceDTO invoice) {
    // 1. Recepción y validación estricta del Payload JSON
    // 2. Delegación síncrona al motor transaccional
    InvoiceResult result = invoiceService.processInvoice(invoice);
    return ResponseEntity.status(HttpStatus.CREATED).body(result);
}

@Service InvoiceService

Orquestador de lógica de negocio y transaccionalidad `@Transactional`. Obtiene el último hash guardado en base de datos para garantizar la secuencia ininterrumpida, genera la huella criptográfica actual y registra la factura en estado `PENDING`.

@Transactional
public InvoiceResult processInvoice(InvoiceDTO data) {
    // 1. Obtención del hash inmediatamente anterior en el libro registro
    String prevHash = repository.findTopByOrderByIdDesc()
                                .map(InvoiceEntity::getChainHash)
                                .orElse("00000000000000000000000000000000");
    
    // 2. Cálculo de la nueva huella SHA-256 encadenada
    String newHash = hashGenerator.calculateHash(data, prevHash);
    
    // 3. Firma digital utilizando la clave privada RSA
    String signature = signer.sign(newHash, keyManager.getPrivateKey());
    
    // 4. Inserción obligatoria en PostgreSQL en estado PENDING
    InvoiceEntity entity = repository.save(new InvoiceEntity(data, newHash, signature, "PENDING"));
    
    // 5. Publicación de evento asíncrono para transmisión a Hacienda
    eventPublisher.publishEvent(new FiscalSendEvent(entity.getId()));
    return new InvoiceResult(entity.getInvoiceNumber(), newHash, "ACCEPTED_LOCAL");
}

Componentes Criptográficos (`HashGenerator` & `Signer`)

Módulo encargado del cumplimiento estricto del algoritmo SHA-256 de VeriFactu y la firma PKCS#1 v1.5 / XAdES.

• HashGenerator.java: Concatena NIF emisor, número de serie, fecha/hora ISO, importe total y hash anterior.
• Signer.java: Aplica algoritmo SHA256withRSA sobre los datos normalizados.
• KeyManager.java: Carga dinámica del almacén PKCS#12 (.p12) montado como volumen Docker.

Estrategia de Transporte (`FiscalSender`)

Patrón de diseño Strategy (`FiscalSender`). Permite que el backend intercambie el cliente de transporte según la sede tributaria del contribuyente sin alterar el servicio de facturación.

public interface FiscalSender {
    FiscalResponse send(InvoiceEntity invoice);
}

// Adaptador para el territorio nacional (AEAT)
@Component("aeatSender")
public class VerifactuSoapSender implements FiscalSender { ... }

// Adaptador para las haciendas forales vascas (TicketBAI)
@Component("ticketBaiSender")
public class TicketBaiRestSender implements FiscalSender { ... }

Persistencia Relacional (PostgreSQL)

Definición DDL del esquema relacional. Almacena las facturas emitidas, los identificadores de cadena criptográfica y la respuesta (CSV) devuelta por la Agencia Tributaria.

CREATE TABLE invoices (
    id BIGSERIAL PRIMARY KEY,
    invoice_number VARCHAR(50) NOT NULL UNIQUE,
    issue_date TIMESTAMP NOT NULL,
    total_amount NUMERIC(12, 2) NOT NULL,
    chain_hash VARCHAR(64) NOT NULL,       -- Huella SHA-256 actual
    prev_hash VARCHAR(64) NOT NULL,        -- Huella del registro inmediatamente anterior
    signature_data TEXT NOT NULL,          -- Bloque de firma digital X.509
    status VARCHAR(20) DEFAULT 'PENDING',  -- PENDING, SENT, REJECTED
    aeat_csv VARCHAR(100),                 -- Código Seguro de Verificación oficial
    retry_count INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);