Flujo Completo de Monitoreo de Transacciones

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

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:

{
  "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:

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)
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
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):

{
  "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

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

Metadatos de Conversión:

{
  "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:

{
  "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:

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
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'
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
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
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

{
  "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

{
  "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

{
  "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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

Creación de Alertas: Las reglas con acción create_alert crean alertas individuales
Retraso de 5 Segundos: El sistema espera para recopilar todas las alertas relacionadas
Consolidación: Las alertas relacionadas se consolidan en una sola investigación
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
Notificaciones: Se notifica a los analistas sobre la nueva investigación

Estructura de Investigación:

{
  "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

Siempre Habilite Reglas Automáticas: Establezca executeRules: true (por defecto) para detectar transacciones sospechosas inmediatamente.
Use la API de Lote para Volumen: Para importaciones masivas o escenarios de alto volumen, use /transactions/batch para un mejor rendimiento.
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
Mapeo de ID Externo: Siempre establezca un externalId único para correlación con sus sistemas.
Manejo de Moneda: El sistema maneja la conversión de moneda automáticamente. Asegúrese de que MS_PROVIDERS_URL esté configurado correctamente.
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
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
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:

{
  "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:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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.

Comenzando

Casos de Uso

Webhooks

Workflows

Monitoreo (entidades)

Persona

Mensajería

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Documentos

Enriquecimiento

Integraciones

Tutoriales Interactivos

Documentation Index

​Descripción General

​Diagrama de Flujo

​Paso 1: Crear Transacción

​Paso 2: Conversión de Moneda

​Cómo Funciona la Conversión de Moneda

​Manejo de Fallas de Conversión

​Paso 3: Análisis de Riesgo de Transacciones

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

​Ejemplos de Reglas Específicas de Transacción

​Estructura del Contexto de Transacción

​Paso 4: Creación de Transacciones en Lote

​Paso 5: Análisis Manual de Transacciones

​Paso 6: Consultas y Monitoreo de Transacciones

​Listar Transacciones con Filtrado

​Obtener Detalles de Transacción

​Ver Alertas de Transacción

​Paso 7: Consolidación de Alertas e Investigaciones

​Mejores Prácticas

​Patrones Avanzados

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

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

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

​Manejo de Errores

​Fallas en la Conversión de Moneda

​Fallas en la Ejecución de Reglas

​Fallas Parciales en Lote

​Próximos Pasos