Resumen de Ejecución de Reglas

Descripción

El objeto rulesExecutionSummary se devuelve cada vez que se ejecuta el motor de reglas: en Crear transacción, Crear persona, Crear empresa, Crear entidad, Crear evento, y en los payloads de webhooks de eventos de análisis de riesgo. Resume qué reglas hicieron match (hit), cuáles no (no hit), las acciones ejecutadas y metadatos de puntuación.

Dónde aparece

Contexto	Ubicación
Crear transacción (con `executeRules: true`)	Raíz de la respuesta (`rulesExecutionSummary`)
Crear persona/empresa/entidad (cuando corre la matriz de riesgo)	Raíz de la respuesta y `rulesResult.rulesExecutionSummary`
Crear evento (cuando se ejecutan reglas)	Raíz de la respuesta y `rulesResult.rulesExecutionSummary`
Webhooks de análisis de riesgo	`payload.rulesExecutionSummary`

Campos

Campo	Tipo	Descripción
rulesHit	`array`	Reglas cuyas condiciones se cumplieron. Cada elemento incluye `ruleId`, `ruleExternalId` (si está configurado), `riskMatrixId` / `riskMatrixName` cuando la regla pertenece a una matriz (multi-matriz y trazabilidad en auditoría), más `name`, `description`, `score`, `priority`, `category`, `status`, `conditions` y opcionalmente `actions`.
rulesNoHit	`array`	Reglas evaluadas pero cuyas condiciones no se cumplieron. Misma estructura que cada elemento de rulesHit.
actionsExecuted	`object`	Presente solo cuando se ejecutó al menos una acción. Acciones agregadas de todas las reglas que hicieron hit.
totalScore	`number`	Suma del score de todas las reglas que hicieron hit (excluyendo reglas shadow).
scoreResult	`object`	Score normalizado y etiqueta: `rawScore`, `normalizedScore` y opcionalmente `label` (name, range, minScore, maxScore).
riskMatrixName	`string`	Nombre de la matriz de riesgo ejecutada.
executionTimeMs	`number`	Tiempo de ejecución del motor de reglas en milisegundos.
trigger	`string`	Evento que disparó la evaluación (ej. `manual_evaluation`, `entity_created`, `enrichment_completed`, `created`).
matchedRulesCount	`number`	Cantidad de reglas que hicieron match (equivalente a `rulesHit.length`).
riskMatricesExecuted	`array`	Opcional. Una entrada por cada matriz de riesgo que aportó reglas evaluadas en esta corrida: score bruto, cantidad de reglas con hit y metadatos de etiqueta por matriz. Se añade cuando la API enriquece el resumen tras la evaluación (por ejemplo flujos con varias matrices o análisis persistido). Se omite si no aplica o viene vacío.

Elemento de rulesHit / rulesNoHit

Campo	Tipo	Descripción
ruleId	`string`	UUID de la regla (fila persistida).
ruleExternalId	`string \| null`	Código de negocio de la regla cuando está configurado (ej. `RG-ENTITY-1`).
riskMatrixId	`string \| null`	UUID de la matriz de riesgo a la que pertenece la regla, o `null` si no está asociada a una matriz.
riskMatrixName	`string \| null`	Nombre visible de la matriz cuando el contexto de ejecución incluye etiquetas de matrices.
name	`string`	Nombre de la regla.
description	`string`	Descripción de la regla.
score	`number \| null`	Puntos de la regla cuando hace hit.
priority	`number \| null`	Prioridad de la regla.
category	`string`	Categoría de la regla.
status	`string`	Estado de la regla (ej. `active`, `shadow`).
conditions	`array`	Condiciones evaluadas: cada `{ field, value, operator? }`.
actions	`object`	En rulesHit: acciones ejecutadas. En rulesNoHit: acciones configuradas. Ver abajo.

actions (dentro de cada regla)

Campo	Tipo	Descripción
alerts	`array`	Definiciones de alertas: `name`, `type`, `severity`, `description`.
suggestion	`string`	Tipo de sugerencia: `BLOCK`, `SUSPEND` o `FLAG`.
status	`string`	Estado definido por la regla.
assignedUser	`object`	`{ userId: string }` si la regla asigna un usuario.
customKeys	`array`	Claves de acciones personalizadas (ej. para workflows).

actionsExecuted (raíz)

Campo	Tipo	Descripción
alerts	`array`	Todas las alertas de las reglas que hicieron hit. Cada alerta puede incluir `ruleId`, `ruleExternalId` e `investigationId` (asignado tras la consolidación; null en la respuesta inmediata).
suggestion	`string`	Sugerencia ganadora por peso: `BLOCK`, `SUSPEND` o `FLAG`.
status	`string`	Estado final aplicado (de la regla de mayor peso).
assignedUser	`object`	`{ userId: string }` si alguna regla asignó un usuario.
customKeys	`array`	Todas las claves de acciones personalizadas de las reglas que hicieron hit.

riskMatricesExecuted (cada elemento del array)

Campo	Tipo	Descripción
riskMatrixId	`string \| null`	UUID de la matriz, o `null` para reglas no asociadas a una fila de matriz.
riskMatrixName	`string \| null`	Nombre visible de la matriz (resuelto en la corrida o desde metadatos de la organización).
rawScore	`number`	Suma de scores de reglas con hit en esa matriz (hits no shadow), misma base que el desglose por matriz en auditorías.
matchedRules	`number`	Cantidad de reglas con hit para esa matriz en esta ejecución.
labelName	`string \| null`	Nombre de la etiqueta de riesgo aplicada al aporte de esa matriz (cuando hubo resolución de etiquetas).
labelColor	`string \| null`	Color hex o token para UI cuando existe.
labelSeverity	`string \| null`	Severidad: `low`, `medium`, `high` o `critical`, cuando se resolvió.
matrixNormalizedScore	`number \| null`	Score normalizado 0–100 de esa matriz cuando está disponible.

Ejemplo completo

El siguiente ejemplo muestra rulesExecutionSummary con todos los campos poblados como llegarían en una respuesta de API o en un webhook.

{
  "rulesHit": [
    {
      "ruleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ruleExternalId": "RG-ENTITY-1",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Matriz de entidades por defecto",
      "name": "País de alto riesgo",
      "description": "Marca entidades o transacciones vinculadas a jurisdicciones de alto riesgo.",
      "score": 30,
      "priority": 1,
      "category": "compliance",
      "status": "active",
      "conditions": [
        { "field": "entity.countryCode", "value": ["IR", "KP", "SY"], "operator": "in" },
        { "field": "entity.type", "value": "person" }
      ],
      "actions": {
        "alerts": [
          {
            "name": "Alerta país alto riesgo",
            "type": "create_alert",
            "severity": "high",
            "description": "La entidad está vinculada a una jurisdicción de alto riesgo."
          }
        ],
        "suggestion": "FLAG",
        "status": "PENDING_REVIEW"
      }
    }
  ],
  "rulesNoHit": [
    {
      "ruleId": "f6a7b8c9-d0e1-2345-f678-901234567890",
      "ruleExternalId": "RG-ENTITY-2",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Matriz de entidades por defecto",
      "name": "Match PEP",
      "description": "Marca cuando el screening PEP devuelve coincidencia.",
      "score": 25,
      "priority": 2,
      "category": "compliance",
      "status": "active",
      "conditions": [
        { "field": "enrichment.complyadvantage_pep_enrichment.isPep", "value": true }
      ],
      "actions": {
        "alerts": [
          {
            "name": "Match PEP",
            "type": "create_alert",
            "severity": "medium",
            "description": "El screening PEP devolvió una coincidencia."
          }
        ],
        "suggestion": "SUSPEND"
      }
    }
  ],
  "actionsExecuted": {
    "alerts": [
      {
        "name": "Alerta país alto riesgo",
        "type": "create_alert",
        "severity": "high",
        "description": "La entidad está vinculada a una jurisdicción de alto riesgo.",
        "ruleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "ruleExternalId": "RG-ENTITY-1",
        "investigationId": null
      }
    ],
    "suggestion": "FLAG",
    "status": "PENDING_REVIEW",
    "customKeys": ["required_kyc"]
  },
  "totalScore": 30,
  "scoreResult": {
    "rawScore": 30,
    "normalizedScore": 42,
    "label": {
      "name": "Medio",
      "range": "30-80",
      "minScore": 30,
      "maxScore": 80
    }
  },
  "riskMatrixName": "Matriz de entidades por defecto",
  "executionTimeMs": 156,
  "trigger": "entity_created",
  "matchedRulesCount": 1,
  "riskMatricesExecuted": [
    {
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Matriz de entidades por defecto",
      "rawScore": 30,
      "matchedRules": 1,
      "labelName": "Medio",
      "labelColor": "#f5a623",
      "labelSeverity": "medium",
      "matrixNormalizedScore": 42
    }
  ]
}

Ejemplo mínimo (ninguna regla hace hit)

Cuando ninguna regla hace match, igualmente se devuelven rulesHit, rulesNoHit, totalScore y metadatos; actionsExecuted se omite cuando está vacío.

{
  "rulesHit": [],
  "rulesNoHit": [
    {
      "ruleId": "f6a7b8c9-d0e1-2345-f678-901234567890",
      "ruleExternalId": "RG-ENTITY-2",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Matriz de entidades por defecto",
      "name": "Match PEP",
      "description": "Marca cuando el screening PEP devuelve coincidencia.",
      "score": 25,
      "priority": 2,
      "category": "compliance",
      "status": "active",
      "conditions": [
        { "field": "enrichment.complyadvantage_pep_enrichment.isPep", "value": true }
      ],
      "actions": {
        "alerts": [
          {
            "name": "Match PEP",
            "type": "create_alert",
            "severity": "medium",
            "description": "El screening PEP devolvió una coincidencia."
          }
        ],
        "suggestion": "SUSPEND"
      }
    }
  ],
  "totalScore": 0,
  "scoreResult": {
    "rawScore": 0,
    "normalizedScore": 0,
    "label": {
      "name": "Bajo",
      "range": "0-30",
      "minScore": 0,
      "maxScore": 30
    }
  },
  "riskMatrixName": "Matriz de entidades por defecto",
  "executionTimeMs": 98,
  "trigger": "manual_evaluation",
  "matchedRulesCount": 0
}

Notas

riskMatricesExecuted no lo genera solo el motor de reglas; la API lo fusiona en rulesExecutionSummary cuando existe un desglose de score por matriz. En respuestas con una sola matriz puede bastar riskMatrixName en la raíz sin este array.
investigationId en actionsExecuted.alerts se asigna de forma asíncrona tras la consolidación de alertas; en la respuesta inmediata de la API es null.
scoreResult.normalizedScore es el valor 0–100 que se persiste en la entidad o en el audit; totalScore (y scoreResult.rawScore) es la suma cruda de los scores de las reglas.
Los valores de trigger incluyen: manual_evaluation, entity_created, enrichment_completed, check_completed, created, updated, entre otros según el contexto.

Documentation Index

​Descripción

​Dónde aparece

​Campos

​Elemento de rulesHit / rulesNoHit

​actions (dentro de cada regla)

​actionsExecuted (raíz)

​riskMatricesExecuted (cada elemento del array)

​Ejemplo completo

​Ejemplo mínimo (ninguna regla hace hit)

​Notas