> ## 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

> 通过 API 调整 Didit 交易监控规则的阈值、条件、操作，或在 TEST、ACTIVE、DISABLED 之间切换模式。库预设仅接受模式参数。



更新规则 API 提示词
        将提示词复制到剪贴板



      
      

\<pre>

\`Update a transaction-monitoring rule.

Endpoint:
PATCH https://verification.didit.me/v3/transactions/rules/{rule_uuid}/

Authentication:
Use the x-api-key header with my Didit API key.

Request body (application/json, partial - send only what changes):
\{ "mode": "ACTIVE" }
or any of: title, description, category, mode, evaluation_mode, scope, conditions, aggregation, actions, metadata.

Behavior:
\- CUSTOM rules accept every field, with the same validation as create.
\- Library (PRESET) rules accept ONLY "mode" - use it to activate, disable, or switch a preset to TEST. Any other field returns 400 naming the offending keys.
\- Changes take effect immediately for new transactions.
\- The typical activation call after a successful backtest is exactly {"mode": "ACTIVE"}.

Failure modes:
\- 400 - validation error, or a non-mode field on a library rule.
\- 404 - unknown rule uuid for this application.`

\</pre>



      
      

粘贴到



## OpenAPI

````yaml zh/openapi-25.json PATCH /v3/transactions/rules/{rule_uuid}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/transactions/rules/{rule_uuid}/:
    parameters:
      - name: rule_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: 来自列表或创建操作的规则 uuid。
    patch:
      tags:
        - Transactions
      summary: 更新规则
      description: >-
        部分更新规则。自定义规则接受所有配置字段。库（PRESET）规则仅接受 `mode`：用于激活、禁用或将预设切换为
        TEST；任何其他字段均会返回 400，因为 Didit 负责维护库规则并自动应用其更新。若要更改库规则的条件，请使用该库规则的定义以及
        `metadata.based_on`（库键名）和 `metadata.based_on_rule_uuid`，通过 `POST
        /v3/transactions/rules/` 创建自定义副本，然后将库规则切换为 `mode: DISABLED`
        关闭，以避免同一交易触发两次警报。暂缓发布的库规则的已安装副本处于关闭状态：将其 `mode` 设置为除 `DISABLED`
        以外的任何值均会返回 400（"This library rule cannot run yet: its conditions read
        data the rules engine cannot evaluate."）。
      operationId: updateTransactionRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRuleUpdateRequest'
            example:
              mode: ACTIVE
      responses:
        '200':
          description: 已更新的规则。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRuleDetail'
        '400':
          description: 验证错误，库规则上存在非 mode 字段，或者扣留的库规则上 mode 不为 DISABLED。
          content:
            application/json:
              schema:
                type: object
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            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"}'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.transactions.rules.update(
                "11111111-2222-3333-4444-555555555555",
                mode="ACTIVE",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.transactions.rules.update("11111111-2222-3333-4444-555555555555",
            {
              mode: "ACTIVE",
            });

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TransactionRuleUpdateRequest{\n\tMode: didit.Some(didit.TransactionRuleUpdateRequestMode(\"ACTIVE\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.TransactionRuleUpdateRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.transactions().rules().update("11111111-2222-3333-4444-555555555555",
            TransactionRuleUpdateRequest.builder()
                    .mode(TransactionRuleUpdateRequest.Mode.of("ACTIVE"))
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->transactions->rules->update('11111111-2222-3333-4444-555555555555',
            [
                'mode' => 'ACTIVE',
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.transactions.rules.update(
              "11111111-2222-3333-4444-555555555555",
              mode: "ACTIVE"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Transactions.Rules.UpdateAsync("11111111-2222-3333-4444-555555555555",
            new TransactionRuleUpdateRequest

            {
                Mode = new TransactionRuleUpdateRequestMode("ACTIVE"),
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    TransactionRuleUpdateRequest:
      type: object
      properties:
        title:
          type: string
          description: 规则名称。在每个应用未删除的规则中必须唯一；重复将返回 400。
        description:
          type: string
          nullable: true
        category:
          type: string
          description: >-
            用于分组和报告的风险主题，例如
            finance、aml_ctf、anomaly_detection、fatf、device_intelligence、crypto_monitoring、travel_rule、responsible_gaming、e_commerce。
        mode:
          type: string
          enum:
            - ACTIVE
            - DISABLED
            - TEST
          description: >-
            ACTIVE 会进行实时评估。TEST 会评估并记录规则运行情况，但绝不会影响评分或状态，这是推荐的初始模式。DISABLED
            则会被跳过。
        evaluation_mode:
          type: string
          enum:
            - ALL
            - ANY
          default: ALL
          description: 是否必须满足所有条件（ALL）还是至少满足一个条件（ANY）。当条件使用 group_index 时忽略此项。
        scope:
          $ref: '#/components/schemas/TransactionRuleScope'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRuleCondition'
        aggregation:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRuleAggregation'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRuleAction'
        metadata:
          type: object
          description: 存储在规则中的自由格式元数据。
      description: 部分更新。自定义规则接受所有字段；库（PRESET）规则仅接受 mode，传入任何其他内容均返回 400。
    TransactionRuleDetail:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        title:
          type: string
          description: 规则名称。在每个应用未删除的规则中必须唯一；重复将返回 400。
        description:
          type: string
          nullable: true
        category:
          type: string
          description: >-
            用于分组和报告的风险主题，例如
            finance、aml_ctf、anomaly_detection、fatf、device_intelligence、crypto_monitoring、travel_rule、responsible_gaming、e_commerce。
        mode:
          type: string
          enum:
            - ACTIVE
            - DISABLED
            - TEST
          description: >-
            ACTIVE 会进行实时评估。TEST 会评估并记录规则运行情况，但绝不会影响评分或状态，这是推荐的初始模式。DISABLED
            则会被跳过。
        evaluation_mode:
          type: string
          enum:
            - ALL
            - ANY
          default: ALL
          description: 是否必须满足所有条件（ALL）还是至少满足一个条件（ANY）。当条件使用 group_index 时忽略此项。
        scope:
          $ref: '#/components/schemas/TransactionRuleScope'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRuleCondition'
        aggregation:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRuleAggregation'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRuleAction'
        metadata:
          type: object
          description: 存储在规则中的自由格式元数据。
        severity:
          type: string
          enum:
            - UNKNOWN
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
          nullable: true
          description: 规则库规则携带的信息性严重程度；不可在自定义规则上设置。
        source:
          type: string
          enum:
            - PRESET
            - CUSTOM
          description: PRESET 规则来自规则库（安装/卸载，仅限模式编辑）；CUSTOM 规则完全由您自定义。
        library_key:
          type: string
          nullable: true
          description: 稳定的库标识符；自定义规则为 null。
        latest_triggered_at:
          type: string
          format: date-time
          nullable: true
        run_count:
          type: integer
          description: 匹配此规则的交易数量。
        approved_count:
          type: integer
        reviewed_count:
          type: integer
        declined_count:
          type: integer
        awaiting_user_count:
          type: integer
        approved_pct:
          type: number
        reviewed_pct:
          type: number
        declined_pct:
          type: number
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TransactionRuleScope:
      type: object
      properties:
        transaction_types:
          type: array
          items:
            type: string
          description: 限制交易类型，例如 finance、kyc、travel_rule、user_event。为空或缺失 = 无限制。
        directions:
          type: array
          items:
            type: string
            enum:
              - INBOUND
              - OUTBOUND
          description: 限制交易方向（写入时不区分大小写）。
        action_types:
          type: array
          items:
            type: string
          description: 限制为您定义的 action_type 值，例如 withdrawal、deposit。
      description: 该规则适用于哪些交易。仅接受这三个键。
    TransactionRuleCondition:
      type: object
      required:
        - field
        - operator
      properties:
        field:
          type: string
          description: >-
            要评估的交易字段路径。核心字段：amount、currency、direction、action_type、score、severity、transaction_type、payment_details、preferred_currency_amount（回退到
            amount_in_default_currency）、default_currency_code、subject_country、counterparty_country、subject_vendor_data、counterparty_vendor_data、subject_device_fingerprint、counterparty_device_fingerprint、subject_browser_family、subject_browser_version、subject_platform、subject_accept_language、subject_session_age_ms、subject_ip_country、counterparty_ip_country、subject_ip_address、counterparty_ip_address、subject_payment_method_type、subject_payment_method_country、subject_payment_method_fingerprint、subject_payment_method_account_id（以及
            counterparty_payment_method_*
            等效字段）、travel_rule_status、travel_rule_required、travel_rule_obligations_count、counterparty_dd_status（您对
            Travel Rule 交易对手的决策：APPROVED、RESTRICTED 或
            BLOCKED，实体遵循其品牌决策）、counterparty_risk_level（LOW、MEDIUM 或
            HIGH；在您自己的交易对手筛查被标记时为 HIGH）、counterparty_jurisdiction（交易对手 VASP
            的国家/地区）、counterparty_responsiveness（RESPONSIVE、UNRESPONSIVE 或
            UNKNOWN）、subject_days_since_previous_transaction、tags，以及在创建交易时通过
            custom_properties 提交的任何键的 custom_values.<key>。国家/地区代码字段接受 ISO-2 或
            ISO-3；比对前双方均会归一化为 ISO-3。
        operator:
          type: string
          enum:
            - eq
            - ne
            - gt
            - gte
            - lt
            - lte
            - in
            - not_in
            - contains
            - not_contains
            - contains_any
            - regex
            - fuzzy_match
            - exists
            - is_not_empty
            - is_not_null
            - not_exists
            - is_empty
            - is_null
          description: >-
            比较运算符。in/not_in 测试成员资格（值可以是一个列表或单个标量）。contains/not_contains
            是针对字符串值的大小写不敏感子字符串检查。contains_any
            接受一个字符串列表，并在其中任意一项是字段值的大小写不敏感子字符串时匹配。regex 将值模式与字段进行正则匹配。fuzzy_match
            使用所需的 `score` 阈值（0-100）与值字符串进行模糊比对。当任意一侧缺失时，gt/gte/lt/lte
            绝不会匹配。exists/is_not_empty/is_not_null（别名）和
            not_exists/is_empty/is_null（别名）是忽略 `value` 的存在性检查。
        value:
          description: >-
            比较值。其结构取决于运算符和 value_type；对于存在性检查运算符，请将其省略。其他所有运算符都需要一个既不是 `null`
            也不是空列表的值，否则规则将被拒绝并返回 `400`。`contains_any` 需要一个字符串列表，而
            `contains`、`not_contains` 和 `regex` 需要单个字符串。
        value_type:
          type: string
          enum:
            - list
            - field
            - relative_date
          description: >-
            可选的值解释方式。`list`：值为 List
            UUID，该列表中的条目将作为比对值。`field`：值为另一个字段路径，进行字段之间的比对。`relative_date`：值为相对日期对象，例如
            {"direction": "past", "unit": "days", "amount": 30}。
        score:
          type: number
          minimum: 0
          maximum: 100
          description: 当 operator 为 fuzzy_match 时必填：0-100 的相似度阈值。
        group_index:
          type: integer
          description: >-
            可选的分组逻辑。当任何条件带有 group_index 时，共享同一索引的条件将组成一个组，并由分组求值取代
            evaluation_mode。
        group_logic:
          type: string
          enum:
            - AND
            - OR
          default: AND
          description: 组内条件的组合方式。
        groups_logic:
          type: string
          enum:
            - AND
            - OR
          default: OR
          description: 跨组的组结果组合方式。从第一个条件读取。
      description: 条件仅读取正在被评估的交易，绝不筛选聚合窗口。
    TransactionRuleAggregation:
      type: object
      required:
        - value
      properties:
        metric:
          type: string
          enum:
            - count
            - sum
            - max
            - min
            - avg
            - distinct_count
          default: count
          description: 匹配的历史交易的聚合方式。unique_count 可作为 distinct_count 的别名接受。
        field:
          type: string
          default: amount
          description: 按 sum/max/min/avg/distinct_count 聚合的字段。对于 count 则忽略。
        operator:
          type: string
          enum:
            - eq
            - ne
            - gt
            - gte
            - lt
            - lte
          default: eq
          description: 应用于计算指标的比对条件。
        value:
          type: number
          description: 与计算出的指标进行比对的阈值。
        window:
          type: string
          pattern: ^\d+(m|h|d)$
          default: 1d
          description: >-
            截至交易 txn_date 的回溯窗口：<N>m（分钟，非月份）、<N>h（小时）或 <N>d（天），例如
            30m、24h、7d、30d。
        filters:
          type: object
          additionalProperties: true
          description: >-
            限制聚合的历史交易范围。键是来自条件字段目录的字段路径；值为 "__current__" 表示解析为正在评估的交易上相同字段的值（例如
            {"subject_vendor_data": "__current__"}
            将时间窗口限定为同一主体），列表值表示成员关系。没有分组值的记录绝不会被分组在一起：当正在评估的交易没有 "__current__"
            字段的值（无交易对手、无设备指纹）时，无论其运算符是什么，聚合都不会匹配。过滤器仅通过相等性或成员关系进行比较：没有 lt/gte
            过滤器，因此无法在此处表达诸如“10,000 以下的历史交易”之类的范围。请改为在指标上设置范围（运算符为 lt 的 metric
            max 会将时间窗口内的每笔交易保持在阈值以下）。
      description: >-
        在时间窗口内对应用的历次交易执行频次检查。无论 evaluation_mode
        为何，每个聚合条目都必须匹配，该规则才算匹配。聚合仅约束时间窗口；被评估的交易受范围和条件约束，因此当规则要求时，需在两部分上重复
        direction、currency 或 transaction_type。
    TransactionRuleAction:
      oneOf:
        - $ref: '#/components/schemas/TransactionRuleActionAddScore'
        - $ref: '#/components/schemas/TransactionRuleActionChangeStatus'
        - $ref: '#/components/schemas/TransactionRuleActionAddTags'
        - $ref: '#/components/schemas/TransactionRuleActionAddNote'
        - $ref: '#/components/schemas/TransactionRuleActionAddToList'
        - $ref: '#/components/schemas/TransactionRuleActionOpenCase'
      discriminator:
        propertyName: type
        mapping:
          add_score: '#/components/schemas/TransactionRuleActionAddScore'
          change_status: '#/components/schemas/TransactionRuleActionChangeStatus'
          add_tags: '#/components/schemas/TransactionRuleActionAddTags'
          add_note: '#/components/schemas/TransactionRuleActionAddNote'
          add_to_list: '#/components/schemas/TransactionRuleActionAddToList'
          open_case: '#/components/schemas/TransactionRuleActionOpenCase'
      description: 一个规则操作。一条规则可包含多个操作；命中时将一并应用。处于 TEST 模式的规则会记录本应执行的操作，而不会实际应用任何操作。
    TransactionRuleActionAddScore:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - add_score
        value:
          type: integer
          description: 添加到交易风险评分中的点数。可能为负数。
      description: 为交易的累计风险评分增加分值；总分将通过应用的审核/拒绝阈值决定状态。
    TransactionRuleActionChangeStatus:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - change_status
        value:
          type: string
          enum:
            - APPROVED
            - IN_REVIEW
            - DECLINED
            - AWAITING_USER
          description: 无论评分如何均立即设置的状态。别名键：status。
        workflow_id:
          type: string
          format: uuid
          description: >-
            当值为 AWAITING_USER
            时为必填项：要求主体完成的验证工作流。别名键：remediation_workflow_id。规则触发时，Didit
            会为主体创建一个托管的整改会话。
      description: 直接设置交易状态。在所有匹配的规则中，DECLINED 始终优先。
    TransactionRuleActionAddTags:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - add_tags
        tag_uuid:
          type: string
          format: uuid
          description: 要附加的现有应用标签。
        tag_name:
          type: string
          description: 要附加的标签名称；首次使用时创建（以大写形式存储）。请提供 tag_uuid 或 tag_name。
        tag_color:
          type: string
          description: '当 tag_name 创建新标签时使用的十六进制颜色，例如 #007AFE。'
      description: 将应用标签关联至匹配的交易。
    TransactionRuleActionAddNote:
      type: object
      required:
        - type
        - note
      properties:
        type:
          type: string
          enum:
            - add_note
        note:
          type: string
          description: 附加到交易的备注文本（作者：Rule Engine）。别名键：值。
      description: 将自动化分析师备注关联至匹配的交易。
    TransactionRuleActionAddToList:
      type: object
      required:
        - type
        - list_id
      properties:
        type:
          type: string
          enum:
            - add_to_list
        list_id:
          type: string
          format: uuid
          description: 用于添加主体 vendor_data 的列表。
      description: 将主体的 vendor_data 添加到黑名单、白名单或自定义名单中。
    TransactionRuleActionOpenCase:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - open_case
        blueprint:
          type: string
          format: uuid
          description: 案件蓝图 UUID；默认使用应用的默认蓝图。
        grouping:
          type: string
          enum:
            - by_applicant
            - by_rule_and_applicant
          description: 重复匹配是归入按申请人划分的单个案件，还是按规则+申请人划分的单个案件。
        attach_matched_transaction:
          type: boolean
          description: 将匹配的交易关联至该案件。
      description: 打开（或添加至）调查案件。对于每条规则，仅应用第一个 open_case 操作。
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        您的应用 API 密钥，可在 Business Console 的“开发者 -> API
        密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
        IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
        列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
        URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
        https://docs.didit.me/console/api-keys。

````

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