> ## 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. # Resumo de Execução de Regras > Estrutura completa do objeto rulesExecutionSummary retornado pelo motor de regras — na API REST da gu1 para equipes de compliance e risco. ## Visão geral O objeto **rulesExecutionSummary** é retornado sempre que o motor de regras é executado: em [Criar transação](/pt/api-reference/transactions/create), [Criar pessoa](/pt/api-reference/person/create-automatic), [Criar empresa](/pt/api-reference/company/create-automatic), [Criar entidade](/pt/api-reference/entities/create-automatic), [Criar evento](/pt/api-reference/events/create) e nos payloads de webhooks de [eventos de análise de risco](/pt/webhooks/events/risk-analysis-events). 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. ```json theme={null} { "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. ```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 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.