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 (sync, `executeRules: true`, padrão)	Raiz da resposta — summary completo após as regras terminarem
Criar transação (async, `asyncRules=true`)	Raiz — summary placeholder; `asyncRules: true`, `rulesEvaluationStatus: "queued"`
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 da transação quando a ação `updateEntityStatus` define `status` (regras transacionais). Em regras de entidade pode refletir status de entidade quando aplicável.
originEntityStatus	`string`	Opcional. Status da entidade origem quando a regra define `originEntityStatus` em `updateEntityStatus` (regras transacionais). Omitido se não configurado ou não aplicado.
destinationEntityStatus	`string`	Opcional. Status da entidade destino quando a regra define `destinationEntityStatus` em `updateEntityStatus` (regras transacionais). Omitido se não configurado ou não aplicado.
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 da transação quando regras transacionais aplicam `updateEntityStatus.status` (regra vencedora por peso).
originEntityStatus	`string`	Opcional. Status final da entidade origem quando regras aplicam `originEntityStatus` (regras transacionais). Omitido se não aplicado.
destinationEntityStatus	`string`	Opcional. Status final da entidade destino quando regras aplicam `destinationEntityStatus` (regras transacionais). Omitido se não aplicado.
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, created, updated, entre outros conforme o contexto. check_completed foi removido (2026-06-04) — use enrichment_completed para regras pós-screening.
Regras transacionais updateEntityStatus: uma regra pode definir status (transação), originEntityStatus e/ou destinationEntityStatus separadamente. rulesHit[].actions reflete o configurado na regra que deu match (inclui ações de status diferidas). actionsExecuted na raiz agrega o status de transação vencedor e os status de entidade origem/destino aplicados na execução. Clientes que só leem status permanecem compatíveis; os novos campos são opcionais.

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

AML Crypto

Serviços

Integrações

Tutoriais Interativos

Resumo de Execução de Regras

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

​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

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