> ## Documentation Index
> Fetch the complete documentation index at: https://alan-ramirez-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ✅ Operaciones y Validación

> Mutaciones financieras, sanitización de payloads y manejo global de excepciones.

Las operaciones financieras requieren un perímetro de seguridad robusto que prevenga el procesamiento de datos inválidos (como montos negativos o valores nulos). La API implementa una barrera de validación estricta a través de **Jakarta Validation** y un manejador global de excepciones.

## 🚨 Saneamiento y Manejo Global de Errores

Para mantener el código de los controladores limpio de bloques `try-catch`, la aplicación utiliza un patrón de diseño centralizado mediante `@ControllerAdvice`.

El `GlobalExceptionHandler` intercepta automáticamente cualquier fallo de validación HTTP o excepción de negocio (`IllegalArgumentException`, `IllegalStateException`), y los transforma en una respuesta JSON estandarizada con soporte para idioma (EN).

```java theme={null}
// Intercepción global de errores en 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);
}
```

## 📑 Contratos de Validación de Datos (DTO Records)

Para asegurar que las restricciones de negocio se cumplan desde el primer instante en que los datos ingresan a la API, el perímetro HTTP utiliza `record` de Java enriquecidos con anotaciones de **Jakarta Validation** (`@NotNull`, `@Positive`).

Esto actúa como un escudo que previene que valores nulos, vacíos o montos financieros negativos alcancen la capa de servicios o la base de datos.

```java theme={null}
// Contrato de validación en 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
) {}
```