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 (sync, `executeRules: true`, default)	Raíz de la respuesta — summary completo tras terminar las reglas
Crear transacción (async, `asyncRules=true`)	Raíz — summary placeholder; `asyncRules: true`, `rulesEvaluationStatus: "queued"`
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 de la transacción cuando la acción `updateEntityStatus` define `status` (reglas transaccionales). En reglas de entidad puede reflejar el estado de entidad cuando aplica.
originEntityStatus	`string`	Opcional. Estado de la entidad origen cuando la regla define `originEntityStatus` en `updateEntityStatus` (reglas transaccionales). Se omite si no está configurado o no se aplicó.
destinationEntityStatus	`string`	Opcional. Estado de la entidad destino cuando la regla define `destinationEntityStatus` en `updateEntityStatus` (reglas transaccionales). Se omite si no está configurado o no se aplicó.
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 de la transacción cuando reglas transaccionales aplican `updateEntityStatus.status` (regla ganadora por peso).
originEntityStatus	`string`	Opcional. Estado final de la entidad origen cuando las reglas aplican `originEntityStatus` (reglas transaccionales). Se omite si no se aplicó.
destinationEntityStatus	`string`	Opcional. Estado final de la entidad destino cuando las reglas aplican `destinationEntityStatus` (reglas transaccionales). Se omite si no se aplicó.
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, created, updated, entre otros según el contexto. check_completed fue eliminado (2026-06-04) — usá enrichment_completed para reglas post-screening.
Reglas transaccionales updateEntityStatus: una regla puede definir status (transacción), originEntityStatus y/o destinationEntityStatus por separado. rulesHit[].actions refleja lo configurado en la regla que hizo match (incluye acciones de estado diferidas). actionsExecuted en la raíz agrega el estado de transacción ganador y los estados de entidad origen/destino aplicados en esa corrida. Los clientes que solo leen status siguen siendo compatibles; los campos nuevos son opcionales.

Comenzando

SDK

Casos de Uso

Webhooks

Workflows

Monitoreo (entidades)

Persona

Mensajería

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Listas personalizadas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Importaciones masivas

Documentos

Enriquecimiento

AML Crypto

Servicios

Integraciones

Tutoriales Interactivos

Resumen de Ejecución de Reglas

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

​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

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