> ## 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. # Resumen de Ejecución de Reglas > Estructura completa del objeto rulesExecutionSummary devuelto por el motor de reglas — en la API REST de gu1 para equipos de compliance y riesgo. ## Descripción El objeto **rulesExecutionSummary** se devuelve cada vez que se ejecuta el motor de reglas: en [Crear transacción](/es/api-reference/transactions/create), [Crear persona](/es/api-reference/person/create-automatic), [Crear empresa](/es/api-reference/company/create-automatic), [Crear entidad](/es/api-reference/entities/create-automatic), [Crear evento](/es/api-reference/events/create), y en los payloads de webhooks de [eventos de análisis de riesgo](/es/webhooks/events/risk-analysis-events). 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. ```json theme={null} { "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. ```json theme={null} { "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.