> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de regras e MCP - Gestão programática de regras KYT

> Crie, ajuste, teste e migre regras KYT com a Didit por API: endpoints da Management API, ferramentas MCP e o fluxo criar - backtest - ativar.

Cada funcionalidade de regras da Consola Empresarial está também disponível por via programática: através da **Management API** com a sua chave de API da aplicação, e através do **Didit MCP** para agentes de IA que atuam como utilizador da consola com sessão iniciada. Use-as para gerir regras a partir do código, manter conjuntos de regras em controlo de versões ou deixar um assistente de IA criar e migrar regras por si.

## Quando usar cada superfície

| Superfície | Autenticação | Ideal para |
| - | - | - |
| **Consola Empresarial** | Início de sessão na consola | Revisão humana de cada alteração; criação visual de regras e backtesting |
| **Management API** | `x-api-key` | Automatização a partir do seu backend, conjuntos de regras em código, implementações de regras geridas por CI |
| **Didit MCP** | Iniciar sessão com a Didit (OAuth) | Assistentes e agentes de IA: o Copilot da consola da Didit, o Claude, o Cursor ou qualquer cliente MCP |

## Os endpoints

| Endpoint | Finalidade |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/pt/management-api/transactions/rules-list) | Listar regras com filtros e ordenação por desempenho |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/pt/management-api/transactions/rules-create) | Criar uma regra personalizada |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/pt/management-api/transactions/rules-get) | Ler uma regra com os contadores de execução |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/pt/management-api/transactions/rules-update) | Atualizar uma regra personalizada; alterar o modo de qualquer regra |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/pt/management-api/transactions/rules-delete) | Eliminar uma regra personalizada (permanente) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/pt/management-api/transactions/rules-backtest) | Avaliar uma regra hipotética contra o seu histórico |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/pt/management-api/transactions/rules-library) | Explorar a biblioteca de 150+ predefinições, com o estado de instalação |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/pt/management-api/transactions/rules-install) | Instalar predefinições por chave, pacote ou pela interseção de ambos |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/pt/management-api/transactions/rules-uninstall) | Desinstalar predefinições por chave, pacote ou pela interseção de ambos |

As ferramentas MCP correspondentes são `didit_transaction_rule_list`, `didit_transaction_rule_get`, `didit_transaction_rule_create`, `didit_transaction_rule_update`, `didit_transaction_rule_delete`, `didit_transaction_rule_backtest`, `didit_transaction_rule_library_list`, `didit_transaction_rule_install` e `didit_transaction_rule_uninstall` - consulte a [referência das ferramentas MCP](https://docs.didit.me/pt/integration/mcp/tools.md).

O esquema completo - o catálogo de campos, os 19 operadores de condição, as janelas temporais de análise de velocidade, as condições agrupadas e os seis tipos de ação - está documentado na página [Regras e pontuação](https://docs.didit.me/pt/transaction-monitoring/rules.md) e incorporado na referência da API.

## Criar, fazer backtest e ativar

O padrão seguro para lançar qualquer regra nova:

**1. Criar a regra no modo TEST**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Structuring - inbound (custom)",
    "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days",
    "category": "finance",
    "mode": "TEST",
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "actions": [{"type": "add_score", "value": 35}]
  }'
```

Leia o payload em duas partes. `scope` e `conditions` descrevem **a transação avaliada**: uma transação financeira de entrada em EUR com um `amount` bruto inferior a 10 000. As entradas de `aggregation` descrevem **a janela de 30 dias para o mesmo sujeito**: pelo menos 20 transações financeiras de entrada em EUR, e nenhuma delas de 10 000 EUR ou mais. Ambas as entradas de agregação têm de se verificar, independentemente do valor de `evaluation_mode`; essa definição rege apenas as condições.

Este exemplo usa o `amount` bruto e fixa `currency` em EUR nas duas partes, pelo que não depende da normalização cambial. Para fazer backtest com os dados de teste do sandbox, submeta pelo menos 20 transações financeiras de entrada em EUR para o mesmo sujeito nos 30 dias, cada uma com `amount` inferior a 10 000. Nem `preferred_currency_amount` nem `amount_in_default_currency` são obrigatórios. A ingestão no sandbox guarda estas transações; execute o backtest explicitamente.

Uma regra `TEST` avalia cada nova transação e regista as correspondências que teria produzido, mas nunca altera a pontuação nem o estado da transação.

> [!NOTE]
>
> **Um filtro de agregação não é uma condição.** Uma condição lê apenas a transação avaliada; um filtro de agregação restringe apenas a janela histórica, e compara por igualdade ou por pertença a uma lista - não existe um filtro `lt`, por isso não é possível contar *apenas as transferências abaixo de 10 000*.
>
> A entrada `max ... lt 10000` é a forma suportada de impor um teto à janela: exige que **todas** as transações da janela sejam inferiores a 10 000, o que é mais restritivo do que contar apenas as pequenas - uma transferência de 12 000 entre as vinte impede a regra de disparar. Remova essa entrada se preferir que a contagem seja independente, e indique-o então no título: sem ela, a regra conta transferências de entrada de qualquer valor, e dezanove transferências de 50 000 seguidas de uma pequena fazem com que a regra seja acionada.

**2. Fazer backtest contra o seu histórico**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "period_days": 90
  }'
```

```json theme={null}
{ "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 }
```

Um número surpreendente de correspondências em `matched` significa que os limiares precisam de ser ajustados antes de a regra poder ser aplicada.

> [!WARNING]
>
> Faça o backtest da configuração **exata** que vai ativar: os mesmos `conditions`, `aggregation`, `evaluation_mode` e `scope`. Omitir `conditions`, `aggregation` e `scope` não acrescenta restrições próprias; remover o scope pode incluir direções ou tipos de transação que a regra guardada ignora. Omitir `evaluation_mode` assume o valor `ALL`, pelo que omiti-lo numa regra `ANY` pode reduzir as correspondências. Omitir `period_days` assume 90 dias; não seleciona histórico ilimitado.

**3. Ativar**

```bash theme={null}
curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "ACTIVE"}'
```

A regra aplica-se imediatamente a todas as novas transações de uma aplicação **de produção**.

> [!WARNING]
>
> As aplicações sandbox nunca avaliam regras. Uma transação sandbox é apenas guardada, sem mais nada, pelo que ativar uma regra numa aplicação sandbox não altera nada que possa observar. O backtest é a forma suportada de testar uma regra antes de entrar em produção - veja [Monitorização de transações no sandbox](https://docs.didit.me/pt/integration/sandbox-testing.md#monitorização-de-transações-no-sandbox).

## Migração de regras de outro fornecedor

Como a criação de regras é uma simples chamada de API com um esquema totalmente documentado, um assistente de IA pode traduzir a exportação de regras de outro fornecedor para regras da Didit por si.

1. **Exportar** as suas regras do fornecedor atual - a maioria das ferramentas exporta para CSV ou Excel.
2. **Coloque o ficheiro** no assistente da consola da Didit (ou em qualquer agente ligado ao MCP, como o Claude, com o [MCP da Didit](https://docs.didit.me/pt/integration/mcp/overview.md) associado). As folhas de cálculo são convertidas automaticamente para texto.
3. O assistente **mapeia cada linha** para o esquema da Didit - condições, janelas de velocidade, ações - e mostra-lhe o mapeamento, assinalando tudo o que não tenha equivalente na Didit, antes de criar seja o que for.
4. Após a sua confirmação, **cria as regras em modo TEST**, faz testes retrospetivos com o seu próprio histórico de transações e indica as linhas criadas, falhadas e não mapeáveis.
5. **Analise os números e ative** as regras que lhe parecerem corretas, na consola ou com um `PATCH {"mode": "ACTIVE"}`.

Uma exportação de um fornecedor como esta:

```csv theme={null}
Rule Name,Condition,Threshold,Window (days),Action
Structuring - Small Transfers,count of outbound transfers under amount,20 transfers under 10000 EUR,30,Flag for review
High Value Wire,single transaction amount,> 50000 USD,,Decline
```

transforma-se em regras como estas:

```json theme={null}
{
  "title": "Structuring - Small Transfers",
  "description": "20+ outbound EUR transfers, all under 10,000 EUR, 30 days",
  "category": "finance",
  "mode": "TEST",
  "evaluation_mode": "ALL",
  "scope": {
    "transaction_types": ["finance"],
    "directions": ["OUTBOUND"]
  },
  "conditions": [
    {"field": "currency", "operator": "eq", "value": "EUR"},
    {"field": "amount", "operator": "lt", "value": 10000}
  ],
  "aggregation": [
    {
      "metric": "count", "operator": "gte", "value": 20,
      "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    },
    {
      "metric": "max", "field": "amount",
      "operator": "lt", "value": 10000, "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    }
  ],
  "actions": [
    {"type": "add_score", "value": 35},
    {"type": "change_status", "value": "IN_REVIEW"}
  ]
}
```

A linha do CSV indica uma direção e uma moeda, por isso as duas metades da regra incluem essas informações: `scope` e `conditions` fixam a transação avaliada a uma transferência de saída em EUR inferior a 10.000, e os filtros de agregação fixam a janela de 30 dias às transferências de saída em EUR do mesmo sujeito. O `amount` bruto só é comparável dentro de uma mesma moeda, por isso mantenha a moeda fixa como indicado acima. Um limite que abrange várias moedas exige um valor normalizado para cada transação da janela. Mudar apenas para `preferred_currency_amount` não garante a disponibilidade: os valores normalizados históricos em falta podem ser tratados como zero pelas agregações numéricas.

A entrada `max` é o que mantém a janela abaixo de 10.000 EUR, porque um filtro de agregação não consegue expressar "inferior a 10.000". Veja a nota sobre o [passo de criação](#criar-fazer-backtest-e-ativar) acima para o compromisso que isso implica. Tudo o que o esquema não consiga expressar com exatidão deve ser indicado explicitamente na `description` da regra, em vez de ser aproximado sem aviso.

> [!TIP]
>
> Antes de recriar a regra de um fornecedor como personalizada, consulte a [biblioteca de regras](https://docs.didit.me/pt/management-api/transactions/rules-library.md): a Didit disponibiliza 150+ predefinições que cobrem as tipologias mais comuns (estruturação, velocidade, exposição a sanções, reutilização de dispositivos, risco de cripto-ativos), e instalar uma predefinição é uma única chamada.

## Os erros de validação são deliberadamente precisos

Os endpoints de criação e atualização validam as condições, a agregação e os valores de âmbito contra exatamente aquilo que o motor de regras aceita: operadores ou métricas desconhecidos, janelas inválidas (`"30days"` em vez de `"30d"`), direções de âmbito inválidas, `contains_any` sem uma lista, `fuzzy_match` sem um `score`, e `change_status` para `AWAITING_USER` sem um `workflow_id` devolvem todos um `400` que indica o índice e o problema, em vez de guardarem uma regra que nunca corresponde, sem aviso. Agentes e scripts devem ler o corpo do erro e corrigir o payload. As chaves de âmbito extra, além de `transaction_types`, `directions` e `action_types`, são guardadas mas ignoradas pelo motor, tal como a Business Console sempre as guardou.

## Próximos passos

> [card] [Regras e pontuação](https://docs.didit.me/pt/transaction-monitoring/rules.md)
>
> O esquema completo das regras: campos, operadores, janelas de velocidade, ações.

> [card] [API de criação de regras](https://docs.didit.me/pt/management-api/transactions/rules-create.md)
>
> Referência do endpoint com os esquemas de pedido e de resposta.

> [card] [Biblioteca de regras](https://docs.didit.me/pt/transaction-monitoring/rules-library.md)
>
> O catálogo com 150+ predefinições e os respetivos pacotes.

> [card] [Visão geral do MCP](https://docs.didit.me/pt/integration/mcp/overview.md)
>
> Ligue um agente de IA ao seu espaço de trabalho da Didit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.