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

# 创建限额规则

> 创建限额规则的完整字段参考：消费、取现两组金额与笔数限额，币种、MCC、地区三类名单，ruleRef 幂等语义与全部错误码。

## 📄 正文

限额规则是归属公司的独立对象，由五个控制组拼装而成：`purchaseControl`（消费）、`cashAdvanceControl`（取现）、`currencyControl`（币种名单）、`mccControl`（商户类别名单）、`geographicControl`（地区名单）。规则新建即 `ACTIVE`，但在绑定到卡或员工之前不约束任何交易——绑定操作见[绑定与解绑](./binding-and-unbinding)，整体模型见[设置消费限额](./spend-limits)。

## 创建规则

**`POST /open-api-corp/velocity/v1/create-rule`**

<Warning>
  五个控制组**至少配置一个**，一个都不配返回 `DAPI_PARAM_INVALID`。**「不限」通过不传该字段表达，禁止传 0 或负数**——传了会返回 `VELOCITY_LIMIT_VALUE_INVALID`。
</Warning>

<Warning>
  两条不同的判定轴请勿混淆：金额限额的匹配以**核销币种**为准；`currencyControl` 名单判定的是**原始消费币种**。
</Warning>

### 请求参数：顶层

| 字段               | 类型     | 必填 | 说明                                    |
| ---------------- | ------ | -- | ------------------------------------- |
| `ruleRef`        | String | 是  | ≤64；客户端生成的幂等键；同公司同 `ruleRef` 重试返回首次结果 |
| `organizationId` | String | 是  | ≤20；规则归属公司                            |
| `ruleName`       | String | 是  | ≤64；规则名称                              |
| `remark`         | String | 否  | ≤256；规则备注                             |

<Note>
  `ruleRef` 是幂等键：网络超时后用同一 `ruleRef` 重试，DCS 不会重复建规则，而是原样返回首次创建的结果。
</Note>

### 请求参数：消费控制组 purchaseControl

不传 `purchaseControl` 即不限消费。

| 字段                                              | 类型      | 必填 | 说明                            |
| ----------------------------------------------- | ------- | -- | ----------------------------- |
| `purchaseControl.amountLimits`                  | Array   | 否  | 消费金额限额，每币种一组                  |
| `purchaseControl.amountLimits[].currency`       | String  | 是  | 3；三位币种字母码（`^[A-Z]{3}$`），如 USD |
| `purchaseControl.amountLimits[].perTransaction` | String  | 否  | 单笔限额，> 0                      |
| `purchaseControl.amountLimits[].daily`          | String  | 否  | 日累计限额                         |
| `purchaseControl.amountLimits[].monthly`        | String  | 否  | 月累计限额                         |
| `purchaseControl.amountLimits[].quarterly`      | String  | 否  | 季累计限额                         |
| `purchaseControl.amountLimits[].yearly`         | String  | 否  | 年累计限额                         |
| `purchaseControl.countLimits`                   | Object  | 否  | 消费笔数限制，不分币种，全币种合计             |
| `purchaseControl.countLimits.daily`             | Integer | 否  | 日累计笔数，> 0                     |
| `purchaseControl.countLimits.monthly`           | Integer | 否  | 月累计笔数                         |
| `purchaseControl.countLimits.quarterly`         | Integer | 否  | 季累计笔数                         |
| `purchaseControl.countLimits.yearly`            | Integer | 否  | 年累计笔数                         |

### 请求参数：取现控制组 cashAdvanceControl

不传 `cashAdvanceControl` 即不限取现。与消费组的差别在于多一个组级开关 `allowed`：只要配置了本组，`allowed` 就必填，传 `false` 直接禁止取现。

| 字段                                                 | 类型      | 必填 | 说明                        |
| -------------------------------------------------- | ------- | -- | ------------------------- |
| `cashAdvanceControl.allowed`                       | Boolean | 是  | 组级开关（组内必填），`false` 直接禁止取现 |
| `cashAdvanceControl.amountLimits`                  | Array   | 否  | 取现金额限额，每币种一组              |
| `cashAdvanceControl.amountLimits[].currency`       | String  | 是  | 3；三位币种字母码（`^[A-Z]{3}$`）   |
| `cashAdvanceControl.amountLimits[].perTransaction` | String  | 否  | 取现单笔限额，> 0                |
| `cashAdvanceControl.amountLimits[].daily`          | String  | 否  | 取现日累计限额                   |
| `cashAdvanceControl.amountLimits[].monthly`        | String  | 否  | 取现月累计限额                   |
| `cashAdvanceControl.amountLimits[].quarterly`      | String  | 否  | 取现季累计限额                   |
| `cashAdvanceControl.amountLimits[].yearly`         | String  | 否  | 取现年累计限额                   |
| `cashAdvanceControl.countLimits`                   | Object  | 否  | 取现笔数限制，不分币种，全币种合计         |
| `cashAdvanceControl.countLimits.daily`             | Integer | 否  | 取现日累计笔数，> 0               |
| `cashAdvanceControl.countLimits.monthly`           | Integer | 否  | 取现月累计笔数                   |
| `cashAdvanceControl.countLimits.quarterly`         | Integer | 否  | 取现季累计笔数                   |
| `cashAdvanceControl.countLimits.yearly`            | Integer | 否  | 取现年累计笔数                   |

### 请求参数：三类名单控制组

三类名单结构一致：`type` 二选一（`WHITELIST` / `BLACKLIST`）+ 一个非空明细列表。

| 字段                               | 类型     | 必填 | 说明                        |
| -------------------------------- | ------ | -- | ------------------------- |
| `currencyControl`                | Object | 否  | 消费币种名单，判定**原始消费币种**       |
| `currencyControl.type`           | Enum   | 是  | `WHITELIST` / `BLACKLIST` |
| `currencyControl.currencies`     | Array  | 是  | 3/项；非空；三位币种字母码            |
| `mccControl`                     | Object | 否  | 商户类别名单                    |
| `mccControl.type`                | Enum   | 是  | `WHITELIST` / `BLACKLIST` |
| `mccControl.mccList`             | Array  | 是  | 4/项；非空；4 位数字 MCC          |
| `geographicControl`              | Object | 否  | 交易地区名单，判定商户国家码            |
| `geographicControl.type`         | Enum   | 是  | `WHITELIST` / `BLACKLIST` |
| `geographicControl.countryCodes` | Array  | 是  | 2/项；非空；两位 ISO 国家码（大写）     |

### 响应 data

响应 `data` 是完整规则对象：回显上述五个控制组（未配置的控制组返回 `null`，组内未配置的字段亦返回 `null`），并额外返回以下平台字段：

| 字段               | 类型      | 说明                                  |
| ---------------- | ------- | ----------------------------------- |
| `ruleId`         | String  | 规则 ID（≤32），平台生成、全局唯一，后续操作均用它        |
| `organizationId` | String  | 归属公司                                |
| `status`         | Enum    | `ACTIVE` / `INACTIVE`；新建恒为 `ACTIVE` |
| `ruleVersion`    | Integer | 乐观锁版本号，更新 / 启停时须回传；新建为 1            |
| `bindingCount`   | Long    | 当前绑定对象数；新建为 0                       |
| `createTime`     | String  | 创建时间 ISO-8601                       |
| `modifyTime`     | String  | 更新时间 ISO-8601；新建时等于 `createTime`    |

### 请求示例

```json theme={null}
{
  "ruleRef": "ext-request-0001",
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleName": "员工日常差旅",
  "remark": "差旅卡消费与取现限制",
  "purchaseControl": {
    "amountLimits": [
      { "currency": "USD", "perTransaction": "3000.00", "daily": "10000.00",
        "monthly": "80000.00", "quarterly": "200000.00", "yearly": "600000.00" },
      { "currency": "HKD", "daily": "50000.00" }
    ],
    "countLimits": { "daily": 5, "monthly": 100 }
  },
  "cashAdvanceControl": {
    "allowed": true,
    "amountLimits": [
      { "currency": "USD", "perTransaction": "500.00", "daily": "2000.00", "monthly": "10000.00" }
    ]
  }
}
```

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "ruleId": "R000456",
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "ruleName": "员工日常差旅",
    "remark": "差旅卡消费与取现限制",
    "status": "ACTIVE",
    "ruleVersion": 1,
    "bindingCount": 0,
    "createTime": "2026-08-12T10:00:00Z",
    "modifyTime": "2026-08-12T10:00:00Z",
    "purchaseControl": {
      "amountLimits": [
        { "currency": "USD", "perTransaction": "3000.00", "daily": "10000.00",
          "monthly": "80000.00", "quarterly": "200000.00", "yearly": "600000.00" },
        { "currency": "HKD", "perTransaction": null, "daily": "50000.00",
          "monthly": null, "quarterly": null, "yearly": null }
      ],
      "countLimits": { "daily": 5, "monthly": 100, "quarterly": null, "yearly": null }
    },
    "cashAdvanceControl": {
      "allowed": true,
      "amountLimits": [
        { "currency": "USD", "perTransaction": "500.00", "daily": "2000.00",
          "monthly": "10000.00", "quarterly": null, "yearly": null }
      ],
      "countLimits": null
    },
    "currencyControl": null,
    "mccControl": null,
    "geographicControl": null
  }
}
```

### 错误码

| 错误码                             | 说明                                                      |
| ------------------------------- | ------------------------------------------------------- |
| `ORGANIZATION_INVALID`          | 公司不存在 / 非 ACTIVE / 不属本入驻方                               |
| `DAPI_PARAM_INVALID`            | 5 个控制组一个都没配（结构性缺参走通用参数错误码）                              |
| `VELOCITY_LIMIT_VALUE_INVALID`  | 限额值不合法：负数、格式错、精度超限，或长周期小于短周期（「不限」应不传字段而非传 0）            |
| `VELOCITY_CURRENCY_INVALID`     | 金额限额组的币种不合法或重复                                          |
| `VELOCITY_LIST_CONTROL_INVALID` | 名单控制组不合法：`type` 非法、清单为空、清单元素格式错（MCC 非 4 位数字 / 国家码非两位大写） |

完整错误码全集见[错误码字典](../customer-success/error-codes)。

## 下一步

* 把规则绑定到卡或员工，让它真正生效：[绑定与解绑](./binding-and-unbinding)
* 查询合并后的有效额度、更新或启停规则：[额度查询与调整](./quota-and-adjustment)