Resumo de Execução de Regras

Visão geral

O objeto rulesExecutionSummary é retornado sempre que o motor de regras é executado: em Criar transação, Criar pessoa, Criar empresa, Criar entidade, Criar evento e nos payloads de webhooks de eventos de análise de risco. Ele resume quais regras deram match (hit), quais não (no hit), as ações executadas e metadados de pontuação.

Onde aparece

Contexto	Local
Criar transação (com `executeRules: true`)	Raiz da resposta (`rulesExecutionSummary`)
Criar pessoa/empresa/entidade (quando a matriz de risco roda)	Raiz da resposta e `rulesResult.rulesExecutionSummary`
Criar evento (quando as regras rodam)	Raiz da resposta e `rulesResult.rulesExecutionSummary`
Webhooks de análise de risco	`payload.rulesExecutionSummary`

Campos

Campo	Tipo	Descrição
rulesHit	`array`	Regras cujas condições foram atendidas. Cada item inclui `ruleId`, `ruleExternalId` (quando configurado), `riskMatrixId` / `riskMatrixName` quando a regra pertence a uma matriz (multi-matriz e rastreabilidade em auditoria), além de `name`, `description`, `score`, `priority`, `category`, `status`, `conditions` e opcionalmente `actions`.
rulesNoHit	`array`	Regras avaliadas mas cujas condições não foram atendidas. Mesma estrutura de cada item de rulesHit.
actionsExecuted	`object`	Presente apenas quando pelo menos uma ação foi executada. Ações agregadas de todas as regras que deram hit.
totalScore	`number`	Soma do score de todas as regras que deram hit (excluindo regras shadow).
scoreResult	`object`	Score normalizado e label: `rawScore`, `normalizedScore` e opcionalmente `label` (name, range, minScore, maxScore).
riskMatrixName	`string`	Nome da matriz de risco executada.
executionTimeMs	`number`	Tempo de execução do motor de regras em milissegundos.
trigger	`string`	Evento que disparou a avaliação (ex.: `manual_evaluation`, `entity_created`, `enrichment_completed`, `created`).
matchedRulesCount	`number`	Número de regras que deram match (equivalente a `rulesHit.length`).
riskMatricesExecuted	`array`	Opcional. Uma entrada por matriz de risco que contribuiu com regras avaliadas nesta execução: score bruto, contagem de regras com hit e metadados de label por matriz. É adicionado quando a API enriquece o resumo após a avaliação (por exemplo fluxos com várias matrizes ou análise persistida). Omitido quando não se aplica ou vem vazio.

Item de rulesHit / rulesNoHit

Campo	Tipo	Descrição
ruleId	`string`	UUID da regra (linha persistida).
ruleExternalId	`string \| null`	Código de negócio da regra quando configurado (ex.: `RG-ENTITY-1`).
riskMatrixId	`string \| null`	UUID da matriz de risco à qual a regra pertence, ou `null` se não estiver associada a uma matriz.
riskMatrixName	`string \| null`	Nome de exibição da matriz quando o contexto de execução inclui labels das matrizes.
name	`string`	Nome da regra.
description	`string`	Descrição da regra.
score	`number \| null`	Pontos da regra quando dá hit.
priority	`number \| null`	Prioridade da regra.
category	`string`	Categoria da regra.
status	`string`	Status da regra (ex.: `active`, `shadow`).
conditions	`array`	Condições avaliadas: cada `{ field, value, operator? }`.
actions	`object`	Em rulesHit: ações executadas. Em rulesNoHit: ações configuradas. Ver abaixo.

actions (dentro de cada regra)

Campo	Tipo	Descrição
alerts	`array`	Definições de alertas: `name`, `type`, `severity`, `description`.
suggestion	`string`	Tipo de sugestão: `BLOCK`, `SUSPEND` ou `FLAG`.
status	`string`	Status definido pela regra.
assignedUser	`object`	`{ userId: string }` se a regra atribui um usuário.
customKeys	`array`	Chaves de ações personalizadas (ex.: para workflows).

actionsExecuted (raiz)

Campo	Tipo	Descrição
alerts	`array`	Todas as alertas das regras que deram hit. Cada alerta pode incluir `ruleId`, `ruleExternalId` e `investigationId` (atribuído após a consolidação; null na resposta imediata).
suggestion	`string`	Sugestão vencedora por peso: `BLOCK`, `SUSPEND` ou `FLAG`.
status	`string`	Status final aplicado (da regra de maior peso).
assignedUser	`object`	`{ userId: string }` se alguma regra atribuiu um usuário.
customKeys	`array`	Todas as chaves de ações personalizadas das regras que deram hit.

riskMatricesExecuted (cada item do array)

Campo	Tipo	Descrição
riskMatrixId	`string \| null`	UUID da matriz, ou `null` para regras não vinculadas a uma linha de matriz.
riskMatrixName	`string \| null`	Nome de exibição da matriz (resolvido na execução ou a partir de metadados da organização).
rawScore	`number`	Soma dos scores das regras com hit nessa matriz (hits não shadow), mesma base do desdobramento por matriz em auditorias.
matchedRules	`number`	Quantidade de regras com hit para essa matriz nesta execução.
labelName	`string \| null`	Nome do rótulo de risco aplicado à contribuição dessa matriz (quando houve resolução de rótulos).
labelColor	`string \| null`	Cor em hex ou token para UI quando existir.
labelSeverity	`string \| null`	Severidade: `low`, `medium`, `high` ou `critical`, quando resolvida.
matrixNormalizedScore	`number \| null`	Score normalizado 0–100 dessa matriz quando disponível.

Exemplo completo

O exemplo a seguir mostra rulesExecutionSummary com todos os campos preenchidos como viriam em uma resposta da API ou em um webhook.

{
  "rulesHit": [
    {
      "ruleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ruleExternalId": "RG-ENTITY-1",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Matriz de entidades padrão",
      "name": "País de alto risco",
      "description": "Sinaliza entidades ou transações vinculadas a jurisdições de alto risco.",
      "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 risco",
            "type": "create_alert",
            "severity": "high",
            "description": "A entidade está vinculada a uma jurisdição de alto risco."
          }
        ],
        "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 padrão",
      "name": "Match PEP",
      "description": "Sinaliza quando o screening PEP retorna correspondência.",
      "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": "O screening PEP retornou uma correspondência."
          }
        ],
        "suggestion": "SUSPEND"
      }
    }
  ],
  "actionsExecuted": {
    "alerts": [
      {
        "name": "Alerta país alto risco",
        "type": "create_alert",
        "severity": "high",
        "description": "A entidade está vinculada a uma jurisdição de alto risco.",
        "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": "Médio",
      "range": "30-80",
      "minScore": 30,
      "maxScore": 80
    }
  },
  "riskMatrixName": "Matriz de entidades padrão",
  "executionTimeMs": 156,
  "trigger": "entity_created",
  "matchedRulesCount": 1,
  "riskMatricesExecuted": [
    {
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Matriz de entidades padrão",
      "rawScore": 30,
      "matchedRules": 1,
      "labelName": "Médio",
      "labelColor": "#f5a623",
      "labelSeverity": "medium",
      "matrixNormalizedScore": 42
    }
  ]
}

Exemplo mínimo (nenhuma regra dá hit)

Quando nenhuma regra dá match, ainda assim são retornados rulesHit, rulesNoHit, totalScore e metadados; actionsExecuted é omitido quando vazio.

{
  "rulesHit": [],
  "rulesNoHit": [
    {
      "ruleId": "f6a7b8c9-d0e1-2345-f678-901234567890",
      "ruleExternalId": "RG-ENTITY-2",
      "riskMatrixId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "riskMatrixName": "Matriz de entidades padrão",
      "name": "Match PEP",
      "description": "Sinaliza quando o screening PEP retorna correspondência.",
      "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": "O screening PEP retornou uma correspondência."
          }
        ],
        "suggestion": "SUSPEND"
      }
    }
  ],
  "totalScore": 0,
  "scoreResult": {
    "rawScore": 0,
    "normalizedScore": 0,
    "label": {
      "name": "Baixo",
      "range": "0-30",
      "minScore": 0,
      "maxScore": 30
    }
  },
  "riskMatrixName": "Matriz de entidades padrão",
  "executionTimeMs": 98,
  "trigger": "manual_evaluation",
  "matchedRulesCount": 0
}

Notas

riskMatricesExecuted não é produzido apenas pelo motor de regras; a API mescla no rulesExecutionSummary quando existe um desdobramento de score por matriz. Em respostas com uma única matriz pode bastar riskMatrixName na raiz sem este array.
investigationId em actionsExecuted.alerts é atribuído de forma assíncrona após a consolidação de alertas; na resposta imediata da API é null.
scoreResult.normalizedScore é o valor 0–100 persistido na entidade ou no audit; totalScore (e scoreResult.rawScore) é a soma bruta dos scores das regras.
Os valores de trigger incluem: manual_evaluation, entity_created, enrichment_completed, check_completed, created, updated, entre outros conforme o contexto.

Documentation Index

​Visão geral

​Onde aparece

​Campos

​Item de rulesHit / rulesNoHit

​actions (dentro de cada regra)

​actionsExecuted (raiz)

​riskMatricesExecuted (cada item do array)

​Exemplo completo

​Exemplo mínimo (nenhuma regra dá hit)

​Notas