创建限额规则 - DCS Technical Documentation

📄 正文

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

创建规则

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

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

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

请求参数：顶层

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

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

请求参数：消费控制组 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`

请求示例

{
  "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" }
    ]
  }
}

响应示例

{
  "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 位数字 / 国家码非两位大写）

完整错误码全集见错误码字典。

下一步

把规则绑定到卡或员工，让它真正生效：绑定与解绑
查询合并后的有效额度、更新或启停规则：额度查询与调整

​📄 正文

​创建规则

​请求参数：顶层

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

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

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

​响应 data

​请求示例

​响应示例

​错误码

​下一步

📄 正文

创建规则

请求参数：顶层

请求参数：消费控制组 purchaseControl

请求参数：取现控制组 cashAdvanceControl

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

响应 data

请求示例

响应示例

错误码

下一步