✅ Operations and Validation

Financial mutations, payload sanitization, and global exception handling.

Financial operations require a robust security perimeter that prevents the processing of invalid data (such as negative amounts or null values). The API implements a strict validation barrier through Jakarta Validation and a global exception handler.

🚨 Sanitization and Global Error Handling

To keep the controller code clean from try-catch blocks, the application uses a centralized design pattern via @ControllerAdvice.

The GlobalExceptionHandler automatically intercepts any HTTP validation failure or business exception (IllegalArgumentException, IllegalStateException), and transforms them into a standardized JSON response with language support (EN).

// Global error interception in GlobalExceptionHandler.java
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, String>> handleValidationExceptions(
        MethodArgumentNotValidException ex,
        HttpServletRequest request) {

    Map<String, String> errorResponse = new HashMap<>();
    boolean isEn = "en".equals(request.getHeader("Accept-Language"));

    FieldError fieldError = ex.getBindingResult().getFieldError();
    String fallbackMsg = isEn
            ? "Validation error in input data"
            : "Error de validación en los datos de entrada";

    String mensajeDefault = fieldError != null ? fieldError.getDefaultMessage() : fallbackMsg;
    errorResponse.put("error", mensajeDefault);

    return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
}

📑 Data Validation Contracts (DTO Records)

To ensure that business constraints are met from the very moment data enters the API, the HTTP perimeter uses Java records enriched with Jakarta Validation annotations (@NotNull, @Positive).

This acts as a shield that prevents null, empty, or negative financial amounts from reaching the service layer or the database.

// Validation contract in CompraUsdcRequest.java
public record CompraUsdcRequest(
        @NotNull(message = "{compra.montoMxn.notnull}")
        @Positive(message = "{compra.montoMxn.positive}")
        BigDecimal montoMxn,

        @NotNull(message = "{compra.tipoCambio.notnull}")
        @Positive(message = "{compra.tipoCambio.positive}")
        BigDecimal tipoCambio
) {}