> ## 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, faça backtest e migre regras KYT da Didit com a API de gerenciamento e o MCP, no fluxo criar, fazer backtest e ativar.

Todos os recursos de regras do Console Empresarial também estão disponíveis de forma programática: pela **Management API**, com a chave de API da sua aplicação, e pelo **Didit MCP**, para agentes de IA que atuam como um usuário conectado ao console. Use-os para gerenciar regras a partir do código, manter conjuntos de regras sob controle de versão ou deixar que um assistente de IA crie e migre regras para você.

## Quando usar cada interface

| Interface | Autenticação | Ideal para |
| - | - | - |
| **Business Console** | Login no console | Revisão humana de cada alteração; criação visual de regras e backtesting |
| **Management API** | `x-api-key` | Automação a partir do seu backend, conjuntos de regras em código, implantações de regras gerenciadas por CI |
| **Didit MCP** | Login com a Didit (OAuth) | Assistentes e agentes de IA: o Copilot do console da Didit, Claude, Cursor ou qualquer cliente MCP |

## Os endpoints

| Endpoint | Finalidade |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/pt-br/management-api/transactions/rules-list) | Listar regras com filtros e ordenação por desempenho |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/pt-br/management-api/transactions/rules-create) | Criar uma regra personalizada |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/pt-br/management-api/transactions/rules-get) | Consultar uma regra com seus contadores de execução |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/pt-br/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-br/management-api/transactions/rules-delete) | Excluir uma regra personalizada (permanentemente) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/pt-br/management-api/transactions/rules-backtest) | Avaliar uma regra hipotética com base no seu histórico |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/pt-br/management-api/transactions/rules-library) | Consultar a biblioteca de 150+ regras predefinidas, com o status de instalação |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/pt-br/management-api/transactions/rules-install) | Instalar regras predefinidas por chave, por pacote ou pela interseção de ambos |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/pt-br/management-api/transactions/rules-uninstall) | Desinstalar regras predefinidas por chave, por 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 de ferramentas MCP](https://docs.didit.me/pt-br/integration/mcp/tools.md).

O esquema completo (o catálogo de campos, os 19 operadores de condição, as janelas 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-br/transaction-monitoring/rules.md) e incorporado à referência da API.

## Criar, fazer backtest, ativar

O padrão seguro de implantação para qualquer regra nova:

**1. Crie 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 metades. `scope` e `conditions` descrevem **a transação que está sendo avaliada**: uma transação financeira de entrada em EUR com `amount` bruto abaixo de 10.000. As entradas de `aggregation` descrevem **a janela de 30 dias para o mesmo titular**: pelo menos 20 transações financeiras de entrada em EUR, e nenhuma delas de 10.000 EUR ou mais. As duas entradas de agregação precisam ser satisfeitas, seja qual for o valor de `evaluation_mode`, pois essa configuração rege apenas as condições.

Este exemplo usa o `amount` bruto e fixa `currency` em EUR nas duas metades, por isso não depende da normalização cambial. Para fazer o backtest com dados de teste do sandbox, envie pelo menos 20 transações financeiras de entrada em EUR para o mesmo titular em até 30 dias, cada uma com `amount` abaixo de 10.000. Nem `preferred_currency_amount` nem `amount_in_default_currency` são obrigatórios. A ingestão no sandbox armazena essas transações; execute o backtest explicitamente.

Uma regra `TEST` é avaliada em cada nova transação e registra as correspondências que teria encontrado, mas nunca altera a pontuação nem o status da transação.

> [!NOTE]
>
> **Um filtro de agregação não é uma condição.** Uma condição lê apenas a transação que está sendo avaliada; um filtro de agregação apenas restringe a janela histórica e compara por igualdade ou pertencimento a uma lista. Não existe filtro `lt`, portanto 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: ela exige que **todas** as transações da janela estejam abaixo de 10.000, o que é mais rigoroso do que contar apenas as pequenas. Uma única transferência de 12.000 entre as vinte impede que a regra seja acionada. Remova essa entrada se preferir que a contagem valha por si só e, nesse caso, deixe isso claro no título: sem ela, a regra conta transferências de entrada de qualquer valor, e dezenove transferências de 50.000 seguidas de uma pequena correspondem a ela.

**2. Faça o backtest com 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 }
```

Uma contagem `matched` inesperada indica que os limiares precisam de ajuste antes que a regra possa ter qualquer efeito.

> [!WARNING]
>
> Faça o backtest das configurações **exatas** que você vai ativar: os mesmos `conditions`, `aggregation`, `evaluation_mode` e `scope`. Se omitidos, `conditions`, `aggregation` e `scope` não adicionam restrições próprias; remover o escopo pode incluir direções ou tipos de transação que a regra salva ignora. Se omitido, `evaluation_mode` assume `ALL` por padrão, então omiti-lo em uma regra `ANY` pode reduzir as correspondências. Se omitido, `period_days` assume 90 dias por padrão; ele não seleciona um histórico ilimitado.

**3. Ative**

```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 passa a valer imediatamente para todas as novas transações de uma aplicação em **produção**.

> [!WARNING]
>
> Aplicações de sandbox nunca avaliam regras. Uma transação de sandbox é apenas
> armazenada, nada mais; por isso, ativar uma regra em uma aplicação de sandbox não
> produz nenhum efeito observável. O backtest é a forma suportada de testar uma regra
> antes de ela entrar em produção. Consulte [Monitoramento de transações no sandbox](https://docs.didit.me/pt-br/integration/sandbox-testing.md#monitoramento-de-transações-no-sandbox).

## Migrando regras de outro provedor

Como a criação de regras é uma simples chamada de API com um schema totalmente documentado, um assistente de IA pode converter a exportação de regras de outro provedor em regras da Didit para você.

1. **Exportar**: exporte suas regras do provedor atual. A maioria das ferramentas exporta para CSV ou Excel.
2. **Envie o arquivo** para o assistente do console da Didit (ou para qualquer agente conectado via MCP, como o Claude com o [Didit MCP](https://docs.didit.me/pt-br/integration/mcp/overview.md) configurado). Planilhas são convertidas em texto automaticamente.
3. O assistente **mapeia cada linha** para o schema da Didit (condições, janelas de velocidade, ações) e mostra o mapeamento antes de criar qualquer coisa, apontando tudo o que não tem equivalente na Didit.
4. Com a sua aprovação, ele **cria as regras no modo TEST**, faz o backtest delas com o seu próprio histórico de transações e informa as linhas criadas, as que falharam e as que não puderam ser mapeadas.
5. **Revise os números e ative** as regras que parecerem corretas, pelo console ou com um `PATCH {"mode": "ACTIVE"}`.

Uma exportação de provedor 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
```

se transforma 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 especifica uma direção e uma moeda, então as duas metades da regra as incluem: `scope` e `conditions` restringem a transação avaliada a uma transferência de saída em EUR abaixo de 10.000, e os filtros de agregação restringem a janela de 30 dias às transferências de saída em EUR desse mesmo sujeito. O `amount` bruto só é comparável dentro de uma mesma moeda, por isso mantenha a moeda fixada como acima. Um teto entre moedas diferentes exige um valor normalizado para cada transação da janela. Mudar apenas para `preferred_currency_amount` não garante essa disponibilidade: valores normalizados ausentes no histórico podem ser tratados como zero pelas agregações numéricas.

É a entrada `max` que mantém a janela abaixo de 10.000 EUR, porque um filtro de agregação não consegue expressar *abaixo de 10.000*. Veja a observação sobre a [etapa de criação](#criar-fazer-backtest-ativar) acima para entender a contrapartida envolvida. Tudo o que o schema não consegue expressar com exatidão deve ser declarado explicitamente na `description` da regra, em vez de ser aproximado silenciosamente.

> [!TIP]
>
> Antes de recriar uma regra de um provedor como regra personalizada, confira a [biblioteca de regras](https://docs.didit.me/pt-br/management-api/transactions/rules-library.md): a Didit oferece 150+ presets que cobrem as tipologias mais comuns (fracionamento, velocidade, exposição a sanções, reutilização de dispositivo, risco cripto), e instalar um preset exige uma única chamada.

## Erros de validação são precisos de propósito

Os endpoints de criação e atualização validam os valores de condições, agregação e escopo exatamente com base no que o motor de regras aceita: operadores ou métricas desconhecidos, janelas malformadas (`"30days"` em vez de `"30d"`), direções de escopo inválidas, `contains_any` sem uma lista, `fuzzy_match` sem um `score` e `change_status` para `AWAITING_USER` sem um `workflow_id` retornam um `400` que indica o índice e o problema, em vez de armazenar uma regra que silenciosamente nunca é correspondida. Agentes e scripts devem ler o corpo do erro e corrigir o payload. Chaves de escopo adicionais além de `transaction_types`, `directions` e `action_types` são armazenadas, mas ignoradas pelo motor, seguindo a forma como o Business Console sempre as salvou.

## Próximos passos

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

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

> [card] [Biblioteca de regras](https://docs.didit.me/pt-br/transaction-monitoring/rules-library.md)
>
> O catálogo de 150+ presets e seus pacotes.

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


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