> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flujo Completo de Monitoreo de Transacciones

> Guía de extremo a extremo para crear, analizar y monitorear transacciones con puntuación automática de riesgo — en el producto de monitoreo transaccional gu1.

## Descripción General

Esta guía cubre el flujo completo para el monitoreo de transacciones, desde la creación hasta el análisis automático de riesgo y la generación de alertas. Las transacciones se evalúan según reglas específicas para detectar patrones sospechosos, montos inusuales, jurisdicciones de alto riesgo y otras señales de alerta.

## Diagrama de Flujo

```mermaid theme={null}
graph TD
    A[Crear Transacción] --> B[POST /transactions]
    B --> C{¿Se Necesita Conversión de Moneda?}

    C -->|Sí| D[Convertir a USD]
    C -->|No| E[Transacción Creada]

    D --> F{¿Conversión Exitosa?}
    F -->|Sí| G[Almacenar Monto en USD]
    F -->|No| H[Almacenar Sin USD]

    G --> E
    H --> E

    E --> I{¿executeRules = true?}
    I -->|Sí| J[Análisis de Riesgo Automático]
    I -->|No| K[Retornar Transacción]

    J --> L[Cargar Contexto de Transacción]
    L --> M[Seleccionar Reglas de Transacción]
    M --> N[Ejecutar Motor de Reglas]

    N --> O[Calcular Puntuación de Riesgo]
    O --> P{¿Puntuación > Umbral?}

    P -->|Sí| Q[Marcar Transacción]
    P -->|No| R[Aprobar Transacción]

    Q --> S[Crear Alertas]
    R --> T[Actualizar Puntuación de Riesgo]

    S --> U[Consolidar Alertas]
    T --> V[Retornar Resultado]

    U --> W[Crear Investigación]
    W --> X[Enviar Notificaciones]
    X --> V
```

## Paso 1: Crear Transacción

Las transacciones se crean a través de la API de transacciones con conversión automática de moneda y ejecución opcional de reglas.

**Endpoint**: `POST /transactions`

**Solicitud**:

```json theme={null}
{
  "externalId": "TXN-2024-00001",
  "type": "TRANSFER",
  "status": "PENDING",
  "amount": 50000,
  "currency": "EUR",
  "paymentMethod": "bank_transfer",
  "originEntityId": "sender-entity-uuid",
  "originName": "John Doe",
  "originCountry": "FR",
  "destinationEntityId": "receiver-entity-uuid",
  "destinationName": "Acme Corporation",
  "destinationCountry": "US",
  "description": "Business payment for services",
  "category": "B2B",
  "transactedAt": "2025-12-24T10:30:00Z",
  "executeRules": true,
  "metadata": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "sessionId": "sess_abc123"
  }
}
```

**Descripción de Campos**:

| Campo                 | Tipo     | Requerido | Descripción                                                                                                       |
| --------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| externalId            | string   | Sí        | Su identificador único para esta transacción                                                                      |
| type                  | enum     | Sí        | Tipo de transacción: PAYMENT, TRANSFER, WITHDRAWAL, DEPOSIT, REFUND, CHARGEBACK, REVERSAL, FEE, ADJUSTMENT, OTHER |
| status                | enum     | No        | Estado de la transacción (por defecto: PENDING)                                                                   |
| amount                | number   | Sí        | Monto de la transacción en la moneda original                                                                     |
| currency              | string   | Sí        | Código de moneda ISO 4217 (ej., USD, EUR, GBP)                                                                    |
| paymentMethod         | enum     | No        | Método de pago utilizado                                                                                          |
| originEntityId        | uuid     | No        | ID de la entidad emisora (si la entidad existe en el sistema)                                                     |
| originExternalId      | string   | No        | Identificador externo del emisor                                                                                  |
| originName            | string   | No        | Nombre del emisor                                                                                                 |
| originCountry         | string   | No        | País del emisor (ISO 3166-1 alpha-2)                                                                              |
| destinationEntityId   | uuid     | No        | ID de la entidad receptora (si la entidad existe en el sistema)                                                   |
| destinationExternalId | string   | No        | Identificador externo del receptor                                                                                |
| destinationName       | string   | No        | Nombre del receptor                                                                                               |
| destinationCountry    | string   | No        | País del receptor (ISO 3166-1 alpha-2)                                                                            |
| description           | string   | No        | Descripción de la transacción                                                                                     |
| category              | string   | No        | Categoría de la transacción                                                                                       |
| transactedAt          | datetime | No        | Cuándo ocurrió la transacción (por defecto: ahora)                                                                |
| executeRules          | boolean  | No        | Ejecutar reglas automáticamente (por defecto: true)                                                               |
| metadata              | object   | No        | Metadatos personalizados adicionales                                                                              |

**Lo que sucede automáticamente**:

1. **Conversión de Moneda**:
   * Si la moneda no es USD, convierte el monto a USD usando tasas de cambio en tiempo real
   * Almacena: `amountInUsd`, `exchangeRate`, `rateSource`, `rateTimestamp`
   * En caso de falla de conversión, la transacción aún se crea (sin monto en USD)

2. **Creación de Transacción**:
   * Se crea el registro de transacción en la base de datos
   * Se genera un ID único
   * Se vincula a las entidades de origen/destino si se proporcionan

3. **Análisis Automático de Riesgo** (si `executeRules: true`):
   * Ejecuta reglas específicas de transacción
   * Calcula la puntuación de riesgo
   * Crea alertas para las reglas que coinciden
   * Actualiza el estado de la transacción si es necesario

**Respuesta (con análisis de riesgo)**:

```json theme={null}
{
  "transaction": {
    "id": "txn-uuid",
    "organizationId": "org-uuid",
    "externalId": "TXN-2024-00001",
    "type": "TRANSFER",
    "status": "PENDING",
    "amount": "50000.00",
    "currency": "EUR",
    "amountInUsd": "54500.00",
    "exchangeRate": "1.09",
    "rateSource": "fixer.io",
    "rateTimestamp": "2025-12-24T10:30:00Z",
    "convertedAt": "2025-12-24T10:30:01Z",
    "originEntityId": "sender-entity-uuid",
    "originName": "John Doe",
    "originCountry": "FR",
    "destinationEntityId": "receiver-entity-uuid",
    "destinationName": "Acme Corporation",
    "destinationCountry": "US",
    "riskScore": "68.00",
    "flagged": true,
    "riskFactors": [
      "Large transaction amount detected",
      "Cross-border transaction to high-risk jurisdiction"
    ],
    "transactedAt": "2025-12-24T10:30:00Z",
    "createdAt": "2025-12-24T10:30:02Z"
  },
  "rulesExecutionSummary": {
    "rulesHit": [
      {
        "name": "Large Transaction Amount",
        "description": "Flags transfers above threshold",
        "score": 30,
        "priority": 10,
        "category": "transaction-monitoring",
        "status": "active",
        "conditions": [{ "field": "amount", "operator": "gte", "value": "50000" }],
        "actions": [{ "type": "add_risk_score", "value": 30 }]
      },
      {
        "name": "High-Risk Jurisdiction Transfer",
        "description": "Cross-border high-risk corridor",
        "score": 38,
        "priority": 20,
        "category": "transaction-monitoring",
        "status": "active",
        "conditions": [],
        "actions": [
          { "type": "add_risk_score", "value": 38 },
          { "type": "create_alert", "result": { "alertId": "alert-uuid" } }
        ]
      }
    ],
    "rulesNoHit": [],
    "actionsExecuted": {
      "alerts": [{ "ruleId": "rule-uuid-2", "severity": "critical" }]
    },
    "totalScore": 68,
    "matchedRulesCount": 2,
    "executionTimeMs": 850,
    "trigger": "created",
    "riskMatrixName": "Default Transaction Matrix"
  }
}
```

## Paso 2: Conversión de Moneda

### Cómo Funciona la Conversión de Moneda

1. **Conversión Automática**: Si `currency !== 'USD'`, el sistema automáticamente convierte a USD
2. **Proveedor**: Usa el servicio `ms-providers` (configurado vía `MS_PROVIDERS_URL`)
3. **Caché**: Las tasas de cambio se almacenan en caché por 1 minuto (TTL)
4. **Resiliencia**: Patrón de circuit breaker con respaldo a caché obsoleto
5. **Degradación Controlada**: Si la conversión falla, la transacción aún se crea (sin monto en USD)

**Metadatos de Conversión**:

```json theme={null}
{
  "amountInUsd": "54500.00",
  "exchangeRate": "1.09",
  "rateSource": "fixer.io",
  "rateTimestamp": "2025-12-24T10:30:00Z",
  "convertedAt": "2025-12-24T10:30:01Z"
}
```

**Transacciones en USD**:

* Si `currency: 'USD'`, no se necesita conversión
* `amountInUsd = amount`
* `exchangeRate = 1`
* `rateSource = 'no-conversion'`

### Manejo de Fallas de Conversión

Si el servicio de moneda no está disponible:

```json theme={null}
{
  "transaction": {
    "amount": "50000.00",
    "currency": "EUR",
    "amountInUsd": null,
    "exchangeRate": null,
    "rateSource": null
  }
}
```

La transacción se crea exitosamente, pero el monto en USD no está disponible. Las reglas que dependen de montos en USD usarán el monto original en su lugar.

## Paso 3: Análisis de Riesgo de Transacciones

### Cómo Funciona el Análisis de Riesgo de Transacciones

El **RulesExecutionService** evalúa las transacciones usando reglas específicas de transacción:

1. **Carga de Contexto**:
   * Carga los datos de la transacción
   * Carga las entidades vinculadas (origen/destino) con datos de enriquecimiento
   * Prepara el contexto de ejecución

2. **Selección de Reglas**:
   * Filtra reglas por `targetEntityTypes: ['transaction']`
   * Filtra por disparador: `'created'` (para automático) o `'manual_evaluation'`
   * Filtra por estado: `enabled: true` y `status: 'active'`

3. **Ejecución de Reglas**:
   * Evalúa las condiciones de reglas contra el contexto de transacción
   * Ejecuta acciones para reglas coincidentes (agregar puntuación, crear alertas, actualizar estado)
   * Acumula la puntuación de riesgo

4. **Actualización de Puntuación**:
   * Actualiza el `riskScore` de la transacción
   * Establece `flagged: true` si la puntuación > 50
   * Almacena el array `riskFactors` con razones

5. **Creación de Alertas**:
   * Las reglas con acción `create_alert` generan alertas
   * Las alertas se vinculan a la transacción
   * Las alertas se consolidan en investigaciones después de un retraso de 5 segundos

### Ejemplos de Reglas Específicas de Transacción

**Regla 1: Monto de Transacción Grande**

```json theme={null}
{
  "name": "Large Transaction Amount",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "greater_than",
        "value": 50000
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 30
    }
  ]
}
```

**Regla 2: Transferencia a Jurisdicción de Alto Riesgo**

```json theme={null}
{
  "name": "High-Risk Jurisdiction Transfer",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originCountry",
        "operator": "in_list",
        "value": ["AF", "IR", "KP", "SY"]
      },
      {
        "field": "destinationCountry",
        "operator": "in_list",
        "value": ["AF", "IR", "KP", "SY"]
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 50
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Transaction involves high-risk jurisdiction"
    }
  ]
}
```

**Regla 3: Velocidad Rápida de Transacciones**

```json theme={null}
{
  "name": "Rapid Transaction Velocity",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originEntityId",
        "operator": "historical_count",
        "timeWindow": "1h",
        "comparison": "greater_than",
        "value": 10
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 40
    },
    {
      "type": "create_alert",
      "severity": "warning",
      "description": "Unusual transaction velocity detected"
    }
  ]
}
```

**Regla 4: Transacción con Entidad Sancionada**

```json theme={null}
{
  "name": "Sanctioned Entity Transaction",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      },
      {
        "field": "destinationEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 100
    },
    {
      "type": "update_status",
      "status": "blocked"
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Transaction involves sanctioned entity"
    }
  ]
}
```

### Estructura del Contexto de Transacción

El motor de reglas recibe este contexto:

```json theme={null}
{
  "transaction": {
    "id": "txn-uuid",
    "type": "TRANSFER",
    "amount": 50000,
    "currency": "EUR",
    "amountInUsd": 54500,
    "originEntityId": "sender-uuid",
    "originName": "John Doe",
    "originCountry": "FR",
    "destinationEntityId": "receiver-uuid",
    "destinationName": "Acme Corp",
    "destinationCountry": "US",
    "transactedAt": "2025-12-24T10:30:00Z"
  },
  "originEntity": {
    "id": "sender-uuid",
    "type": "person",
    "name": "John Doe",
    "enrichmentData": {
      "isPep": false,
      "sanctionsMatch": false,
      "riskScore": 25
    }
  },
  "destinationEntity": {
    "id": "receiver-uuid",
    "type": "company",
    "name": "Acme Corp",
    "enrichmentData": {
      "sanctionsMatch": false,
      "riskScore": 42
    }
  }
}
```

## Paso 4: Creación de Transacciones en Lote

Para escenarios de alto volumen, use el endpoint de lote para crear múltiples transacciones eficientemente.

**Endpoint**: `POST /transactions/batch`

**Solicitud**:

```json theme={null}
{
  "transactions": [
    {
      "externalId": "TXN-001",
      "type": "PAYMENT",
      "amount": 1000,
      "currency": "USD",
      "originName": "Customer A",
      "destinationName": "Merchant X"
    },
    {
      "externalId": "TXN-002",
      "type": "PAYMENT",
      "amount": 2500,
      "currency": "EUR",
      "originName": "Customer B",
      "destinationName": "Merchant X"
    }
  ],
  "executeRules": true,
  "skipDuplicates": true
}
```

**Características**:

* Inserción masiva para mejor rendimiento
* Conversión de moneda optimizada (almacena en caché las tasas para la misma moneda)
* Detección automática de duplicados (por externalId)
* Ejecución opcional de reglas en todas las transacciones
* Máximo 1000 transacciones por lote
* Tiempo de espera de 2 minutos

**Respuesta**:

```json theme={null}
{
  "summary": {
    "total": 2,
    "created": 2,
    "duplicates": 0,
    "failed": 0,
    "flagged": 0,
    "totalCost": 150
  },
  "transactions": [
    {
      "id": "txn-uuid-1",
      "externalId": "TXN-001",
      "riskScore": "15.00",
      "flagged": false
    },
    {
      "id": "txn-uuid-2",
      "externalId": "TXN-002",
      "riskScore": "22.00",
      "flagged": false
    }
  ],
  "executionTimeMs": 3200
}
```

## Paso 5: Análisis Manual de Transacciones

Si creó una transacción con `executeRules: false`, puede activar manualmente el análisis de riesgo más tarde.

**Endpoint**: `POST /entities/:transactionId/analyze`

**Solicitud**:

```json theme={null}
{
  "entityType": "transaction",
  "enrichIfNeeded": false
}
```

**Casos de Uso**:

* Re-analizar la transacción después del enriquecimiento de la entidad
* Analizar la transacción después de actualizaciones de reglas
* Re-puntuación periódica de transacciones pendientes

**Respuesta**: Igual que el resultado del análisis de riesgo automático

## Paso 6: Consultas y Monitoreo de Transacciones

### Listar Transacciones con Filtrado

**Endpoint**: `GET /transactions`

**Parámetros de Consulta**:

```
GET /transactions?flagged=true&minAmount=10000&sortBy=risk_score&sortOrder=desc&limit=50
```

**Filtros Disponibles**:

* `flagged`: Filtrar por estado marcado (true, false, all)
* `minAmount` / `maxAmount`: Filtro de rango de monto (en moneda original)
* `currency`: Filtrar por moneda
* `type`: Filtrar por tipo de transacción
* `status`: Filtrar por estado de transacción
* `entityId`: Filtrar por entidad de origen o destino
* `startDate` / `endDate`: Filtro de rango de fechas
* `search`: Búsqueda de texto libre (externalId, description, names)
* `sortBy`: Campo de ordenamiento (transacted\_at, amount, risk\_score, created\_at)
* `sortOrder`: Dirección de ordenamiento (asc, desc)

**Respuesta**:

```json theme={null}
{
  "transactions": [
    {
      "id": "txn-uuid",
      "externalId": "TXN-2024-00001",
      "type": "TRANSFER",
      "amount": "50000.00",
      "currency": "EUR",
      "amountInUsd": "54500.00",
      "riskScore": "68.00",
      "flagged": true,
      "originName": "John Doe",
      "destinationName": "Acme Corp",
      "transactedAt": "2025-12-24T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}
```

### Obtener Detalles de Transacción

**Endpoint**: `GET /transactions/:transactionId`

**Respuesta**: Objeto completo de transacción con detalles de análisis de riesgo

### Ver Alertas de Transacción

**Endpoint**: `GET /alerts?transactionId=:transactionId`

**Respuesta**: Todas las alertas generadas para la transacción

## Paso 7: Consolidación de Alertas e Investigaciones

Después del análisis de riesgo, las alertas se consolidan automáticamente en investigaciones:

1. **Creación de Alertas**: Las reglas con acción `create_alert` crean alertas individuales
2. **Retraso de 5 Segundos**: El sistema espera para recopilar todas las alertas relacionadas
3. **Consolidación**: Las alertas relacionadas se consolidan en una sola investigación
4. **Creación de Investigación**: Se crea la investigación con:
   * Prioridad basada en la severidad de alerta más alta
   * Estado: "open"
   * Todas las alertas relacionadas vinculadas
5. **Notificaciones**: Se notifica a los analistas sobre la nueva investigación

**Estructura de Investigación**:

```json theme={null}
{
  "id": "investigation-uuid",
  "organizationId": "org-uuid",
  "title": "High-Risk Transaction: TXN-2024-00001",
  "priority": "critical",
  "status": "open",
  "relatedTransactions": ["txn-uuid"],
  "relatedEntities": ["sender-uuid", "receiver-uuid"],
  "alerts": [
    {
      "id": "alert-uuid-1",
      "severity": "critical",
      "type": "HIGH_RISK_JURISDICTION",
      "description": "Transaction involves high-risk jurisdiction"
    },
    {
      "id": "alert-uuid-2",
      "severity": "warning",
      "type": "LARGE_AMOUNT",
      "description": "Transaction amount exceeds threshold"
    }
  ],
  "createdAt": "2025-12-24T10:30:07Z"
}
```

## Mejores Prácticas

1. **Siempre Habilite Reglas Automáticas**: Establezca `executeRules: true` (por defecto) para detectar transacciones sospechosas inmediatamente.

2. **Use la API de Lote para Volumen**: Para importaciones masivas o escenarios de alto volumen, use `/transactions/batch` para un mejor rendimiento.

3. **Vincule Entidades**: Siempre proporcione `originEntityId` y `destinationEntityId` cuando estén disponibles. Esto habilita:
   * Datos de enriquecimiento de entidad en la evaluación de reglas
   * Mejor agregación de riesgo
   * Patrones de transacción a nivel de entidad

4. **Mapeo de ID Externo**: Siempre establezca un `externalId` único para correlación con sus sistemas.

5. **Manejo de Moneda**: El sistema maneja la conversión de moneda automáticamente. Asegúrese de que `MS_PROVIDERS_URL` esté configurado correctamente.

6. **Configuración de Reglas**: Configure las reglas de transacción para su apetito de riesgo:
   * Umbrales de monto apropiados para su negocio
   * Jurisdicciones de alto riesgo basadas en sus requisitos de cumplimiento
   * Reglas de velocidad basadas en patrones normales de transacción

7. **Gestión de Estado**: Use el campo `status` de la transacción para rastrear el ciclo de vida:
   * PENDING → APPROVED/REJECTED/CANCELLED
   * Actualice el estado basado en revisión manual o validación externa

8. **Monitoreo**: Configure dashboards para monitorear:
   * Tasa de transacciones marcadas
   * Puntuaciones de riesgo promedio
   * Volumen de alertas por tipo
   * Tiempo de resolución de investigaciones

## Patrones Avanzados

### Patrón 1: El Riesgo de Entidad Afecta el Riesgo de Transacción

Configure reglas que consideren el riesgo de la entidad:

```json theme={null}
{
  "name": "High-Risk Entity Transaction",
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.riskScore",
        "operator": "greater_than",
        "value": 70
      },
      {
        "field": "destinationEntity.riskScore",
        "operator": "greater_than",
        "value": 70
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 35
    }
  ]
}
```

### Patrón 2: Detección de Velocidad y Patrones

Use consultas históricas en reglas:

```json theme={null}
{
  "name": "Unusual Transaction Pattern",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originEntityId",
        "operator": "historical_sum",
        "aggregateField": "amountInUsd",
        "timeWindow": "24h",
        "comparison": "greater_than",
        "value": 100000
      }
    ]
  }
}
```

### Patrón 3: Verificación de Sanciones en Transacción

```json theme={null}
{
  "name": "Transaction Sanctions Check",
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      },
      {
        "field": "destinationEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "actions": [
    {
      "type": "update_status",
      "status": "blocked"
    },
    {
      "type": "add_risk_score",
      "value": 100
    }
  ]
}
```

## Manejo de Errores

### Fallas en la Conversión de Moneda

```json theme={null}
{
  "transaction": {
    "amountInUsd": null,
    "exchangeRate": null
  },
  "warnings": [
    "Currency conversion failed: fixer.io service unavailable"
  ]
}
```

La transacción se crea exitosamente, las reglas usan el monto original.

### Fallas en la Ejecución de Reglas

```json theme={null}
{
  "rulesExecutionSummary": null,
  "warnings": [
    "Rules engine timeout after 30000ms"
  ]
}
```

La transacción se crea, pero el riesgo no se calcula. Active el análisis manualmente más tarde.

### Fallas Parciales en Lote

```json theme={null}
{
  "summary": {
    "total": 100,
    "created": 95,
    "failed": 5
  },
  "failures": [
    {
      "externalId": "TXN-042",
      "error": "Validation failed: invalid currency code"
    }
  ]
}
```

Las transacciones exitosas se crean, las fallas se reportan por separado.

## Próximos Pasos

* [Configurar Reglas de Transacción](/en/use-cases/transaction-monitoring/rules-configuration)
* [Configurar Reglas de Velocidad](/en/use-cases/transaction-monitoring/fraud-detection)
* [Flujo de Trabajo de Investigación de Alertas](/en/workflows/overview)
* [Dashboard de Análisis de Transacciones](/es/use-cases/transaction-monitoring/overview)