> ## 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.

# Configuración de Reglas

> Cómo crear y configurar reglas síncronas y asíncronas para monitoreo transaccional — en el producto de monitoreo transaccional gu1 para fraude y AML.

## Tipos de Reglas

El sistema de monitoreo transaccional soporta dos tipos de reglas que se comportan de manera diferente:

### 🔴 Reglas Síncronas (SYNC)

Las reglas síncronas se ejecutan **en tiempo real** durante el análisis de la transacción y **afectan directamente** la decisión final.

**Características:**

* Se ejecutan antes de retornar la respuesta al cliente
* Pueden cambiar el estado de la transacción (APPROVE → REJECT)
* Bloquean el flujo hasta completar la evaluación
* Tiempo de ejecución incluido en los \~500ms de respuesta
* Ideales para decisiones críticas inmediatas

**Cuándo usar SYNC:**

* Bloquear transacciones de alto riesgo
* Validar límites operacionales
* Prevenir fraude en tiempo real
* Cumplimiento regulatorio crítico
* Autenticación adicional requerida

### 🟢 Reglas Asíncronas (ASYNC)

Las reglas asíncronas se ejecutan **en paralelo** sin afectar el tiempo de respuesta ni la decisión de la transacción.

**Características:**

* Se ejecutan después de retornar la respuesta
* No afectan la decisión de la transacción
* No bloquean el flujo de pago
* Generan alertas para revisión posterior
* Aparecen solo en el tablero de Intelligence

**Cuándo usar ASYNC:**

* Monitoreo de patrones a largo plazo
* Análisis de comportamiento acumulativo
* Alertas informativas
* Auditoría y reportes
* Detección de fraude no urgente

## Estructura de una Regla

```json theme={null}
{
  "name": "High Amount Transaction Check",
  "description": "Blocks transactions above $10,000",
  "category": "risk",
  "priority": 100,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 10000
      },
      {
        "field": "currency",
        "operator": "EQUALS",
        "value": "USD"
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "message": "Transaction exceeds $10,000 limit"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "HOLD"
      }
    }
  ]
}
```

## Campos de Configuración

### Campos Básicos

<ParamField path="name" type="string" required>
  Nombre descriptivo de la regla (máx. 255 caracteres)
</ParamField>

<ParamField path="description" type="string">
  Descripción detallada del propósito de la regla
</ParamField>

<ParamField path="category" type="enum" required>
  Categoría de la regla:

  * `risk` - Gestión de riesgo
  * `compliance` - Cumplimiento regulatorio
  * `fraud` - Detección de fraude
  * `aml` - Anti-lavado de dinero
  * `operational` - Controles operacionales
  * `custom` - Personalizada
</ParamField>

<ParamField path="priority" type="number" required>
  Prioridad de ejecución (0-1000, mayor = mayor prioridad)

  **Recomendaciones:**

  * 900-1000: Reglas críticas de seguridad
  * 700-899: Cumplimiento regulatorio
  * 400-699: Detección de fraude
  * 100-399: Monitoreo operacional
  * 0-99: Análisis y reportes
</ParamField>

<ParamField path="enabled" type="boolean" required>
  Si la regla está activa (`true`) o inactiva (`false`)
</ParamField>

<ParamField path="evaluationMode" type="enum" required>
  Modo de evaluación:

  * `sync` - Síncrona (afecta decisión en tiempo real)
  * `async` - Asíncrona (solo alertas en background)
</ParamField>

<ParamField path="targetEntityTypes" type="array" required>
  Tipos de entidades a las que aplica. Para transacciones: `["transaction"]`
</ParamField>

### Condiciones

Las condiciones determinan cuándo se activa la regla. Soportan operadores lógicos anidados.

<ParamField path="conditions.operator" type="enum" required>
  Operador lógico:

  * `AND` - Todas las condiciones deben cumplirse
  * `OR` - Al menos una condición debe cumplirse
</ParamField>

<ParamField path="conditions.conditions" type="array" required>
  Array de condiciones individuales o grupos anidados
</ParamField>

#### Operadores de Comparación

* `EQUALS` - Igualdad exacta
* `NOT_EQUALS` - Diferente de
* `GREATER_THAN` - Mayor que
* `GREATER_THAN_OR_EQUAL` - Mayor o igual que
* `LESS_THAN` - Menor que
* `LESS_THAN_OR_EQUAL` - Menor o igual que
* `CONTAINS` - Contiene (para strings y arrays)
* `NOT_CONTAINS` - No contiene
* `IN` - Está en lista
* `NOT_IN` - No está en lista
* `MATCHES_REGEX` - Coincide con expresión regular
* `IS_NULL` - Es nulo
* `IS_NOT_NULL` - No es nulo

#### Campos Disponibles para Transacciones

```javascript theme={null}
// Campos principales
"amount"                    // Monto
"currency"                  // Moneda
"amountInUsd"               // Monto convertido a USD
"type"                      // Tipo de transacción
"timestamp"                 // Fecha/hora

// Entidades
"originEntityId"            // ID entidad origen
"destinationEntityId"       // ID entidad destino

// Métodos de pago
"origin.paymentMethod"      // Método de pago origen
"origin.accountType"        // Tipo de cuenta origen
"origin.cardLast4"          // Últimos 4 dígitos tarjeta
"origin.cardBrand"          // Marca de tarjeta
"destination.paymentMethod" // Método de pago destino

// Datos de dispositivo
"deviceData.ipAddress"      // IP
"deviceData.country"        // País del dispositivo
"deviceData.city"           // Ciudad
"deviceData.platform"       // Plataforma (web/ios/android)

// Otros
"mccCode"                   // Código MCC
"tags"                      // Tags personalizados
"metadata.*"                // Cualquier campo en metadata
```

### Acciones

Las acciones se ejecutan cuando las condiciones se cumplen.

#### generate\_alert

Genera una alerta en el sistema.

```json theme={null}
{
  "type": "generate_alert",
  "config": {
    "severity": "high",
    "type": "high_amount",
    "message": "Transaction amount exceeds threshold"
  }
}
```

**Severidades disponibles:**

* `info` - Informativa
* `low` - Baja
* `medium` - Media
* `high` - Alta
* `critical` - Crítica

#### set\_decision

Cambia la decisión de la transacción (solo SYNC).

```json theme={null}
{
  "type": "set_decision",
  "config": {
    "decision": "REJECT",
    "reason": "High risk transaction"
  }
}
```

**Decisiones disponibles:**

* `APPROVE` - Aprobar
* `REJECT` - Rechazar
* `HOLD` - En espera
* `REVIEW_REQUIRED` - Requiere revisión
* `ADDITIONAL_AUTH_REQUIRED` - Requiere autenticación adicional

#### create\_investigation

Crea una investigación inmediata (disponible en SYNC y ASYNC).

```json theme={null}
{
  "type": "create_investigation",
  "config": {
    "priority": "high",
    "assignToTeam": "fraud_team"
  }
}
```

## Ejemplos de Reglas

### 1. Límite de Monto Diario (SYNC)

Rechaza transacciones que excedan \$10,000 USD.

```json theme={null}
{
  "name": "Daily Limit - $10K",
  "category": "operational",
  "priority": 800,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "GREATER_THAN",
        "value": 10000
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "amount_limit_exceeded",
        "message": "Transaction exceeds daily limit of $10,000"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Amount exceeds daily limit"
      }
    }
  ]
}
```

### 2. Velocidad de Transacciones (ASYNC)

Alerta cuando un usuario hace más de 5 transacciones en 10 minutos.

```json theme={null}
{
  "name": "Transaction Velocity Alert",
  "category": "fraud",
  "priority": 500,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.transactionCount10m",
        "operator": "GREATER_THAN",
        "value": 5
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "velocity_pattern",
        "message": "Unusual transaction velocity detected"
      }
    }
  ]
}
```

### 3. País de Alto Riesgo (SYNC)

Bloquea transacciones desde países de alto riesgo.

```json theme={null}
{
  "name": "High-Risk Country Block",
  "category": "compliance",
  "priority": 900,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "deviceData.location.country",
        "operator": "IN",
        "value": ["KP", "IR", "SY", "CU"]
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "critical",
        "type": "sanctioned_country",
        "message": "Transaction originated from sanctioned country"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Transaction from restricted country"
      }
    }
  ]
}
```

### 4. Patrón de Estructuración AML (ASYNC)

Detecta posible estructuración (múltiples transacciones justo debajo del límite de reporte).

```json theme={null}
{
  "name": "Structuring Pattern Detection",
  "category": "aml",
  "priority": 700,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "GREATER_THAN",
        "value": 9000
      },
      {
        "field": "amountInUsd",
        "operator": "LESS_THAN",
        "value": 10000
      },
      {
        "field": "metadata.transactionsLast24h",
        "operator": "GREATER_THAN",
        "value": 3
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "possible_structuring",
        "message": "Possible structuring: Multiple transactions near reporting threshold"
      }
    },
    {
      "type": "create_investigation",
      "config": {
        "priority": "high",
        "assignToTeam": "aml_team"
      }
    }
  ]
}
```

### 5. Nueva Tarjeta con Monto Alto (SYNC)

Requiere autenticación adicional para tarjetas nuevas con montos altos.

```json theme={null}
{
  "name": "New Card High Amount",
  "category": "fraud",
  "priority": 850,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.isFirstTransactionWithCard",
        "operator": "EQUALS",
        "value": true
      },
      {
        "field": "amountInUsd",
        "operator": "GREATER_THAN",
        "value": 500
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "new_card_high_amount",
        "message": "First transaction with new card exceeds $500"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "ADDITIONAL_AUTH_REQUIRED",
        "reason": "Additional verification required for new card"
      }
    }
  ]
}
```

### 6. Horario Inusual (ASYNC)

Monitorea transacciones fuera del horario habitual del usuario.

```json theme={null}
{
  "name": "Unusual Time Pattern",
  "category": "fraud",
  "priority": 400,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "metadata.hourOfDay",
        "operator": "LESS_THAN",
        "value": 6
      },
      {
        "field": "metadata.hourOfDay",
        "operator": "GREATER_THAN",
        "value": 23
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "low",
        "type": "unusual_time",
        "message": "Transaction outside of normal hours"
      }
    }
  ]
}
```

## Condiciones Avanzadas

### Condiciones Anidadas

Puedes anidar múltiples niveles de AND/OR:

```json theme={null}
{
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "GREATER_THAN",
        "value": 1000
      },
      {
        "operator": "OR",
        "conditions": [
          {
            "field": "origin.paymentMethod",
            "operator": "EQUALS",
            "value": "CREDIT_CARD"
          },
          {
            "field": "origin.paymentMethod",
            "operator": "EQUALS",
            "value": "DEBIT_CARD"
          }
        ]
      },
      {
        "operator": "NOT",
        "condition": {
          "field": "deviceData.location.country",
          "operator": "EQUALS",
          "value": "US"
        }
      }
    ]
  }
}
```

### Expresiones Regulares

Útil para patrones de texto complejos:

```json theme={null}
{
  "field": "metadata.customerEmail",
  "operator": "MATCHES_REGEX",
  "value": "^[a-zA-Z0-9._%+-]+@tempmail\\.(com|net|org)$"
}
```

### Agregaciones Temporales

Usa metadata para agregar datos históricos:

```json theme={null}
{
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.totalAmountLast24h",
        "operator": "GREATER_THAN",
        "value": 50000
      },
      {
        "field": "metadata.transactionCountLast24h",
        "operator": "GREATER_THAN",
        "value": 10
      }
    ]
  }
}
```

## Best Practices

### ✅ DO

1. **Usa SYNC solo cuando sea necesario**
   * Cada regla SYNC añade latencia
   * Reserva para decisiones críticas

2. **Prioriza correctamente**
   * Reglas de bloqueo primero (alta prioridad)
   * Reglas informativas al final (baja prioridad)

3. **Agrupa condiciones eficientemente**
   * Condiciones más restrictivas primero
   * Usa AND para requisitos estrictos

4. **Documenta tus reglas**
   * Descripción clara del propósito
   * Razón de negocio para la regla

5. **Monitorea el rendimiento**
   * Revisa tiempos de ejecución
   * Optimiza reglas lentas

### ❌ DON'T

1. **No uses SYNC para análisis histórico**
   * Usa ASYNC para patrones a largo plazo

2. **No crees reglas demasiado amplias**
   * Genera falsos positivos
   * Frustra a usuarios legítimos

3. **No ignores la prioridad**
   * Puede causar decisiones inconsistentes

4. **No uses demasiadas reglas SYNC**
   * Impacta el rendimiento
   * Consolida reglas similares

## Testing de Reglas

Antes de activar una regla en producción:

1. **Test en ambiente de desarrollo**
   * Valida la lógica con transacciones de prueba

2. **Modo dry-run**
   * Configura la regla como ASYNC temporalmente
   * Monitorea cuántas alertas genera

3. **A/B Testing**
   * Activa para un % de tráfico primero
   * Mide impacto en conversión

4. **Monitoreo continuo**
   * Revisa falsos positivos/negativos
   * Ajusta umbrales según necesidad

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Casos de Uso: Fraude" icon="shield" href="/es/use-cases/transaction-monitoring/fraud-detection">
    Ejemplos de reglas para detectar fraude en tiempo real
  </Card>

  <Card title="Casos de Uso: AML" icon="scale-balanced" href="/es/use-cases/transaction-monitoring/aml-monitoring">
    Reglas para cumplimiento AML y detección de lavado de dinero
  </Card>

  <Card title="Referencia API" icon="code" href="/es/use-cases/transaction-monitoring/api-reference">
    Documentación del endpoint de creación de transacciones
  </Card>

  <Card title="Listas personalizadas (API)" icon="list" href="/es/api-reference/data-lists/overview">
    Crear listas e ítems para operadores `in_custom_list` y relacionados
  </Card>
</CardGroup>