额度查询与调整 - DCS Technical Documentation

📄 正文

一个主体可以同时被多条规则约束，系统在每个维度上取最严值合并出「有效限额」。query-quota 返回的就是这份合并结果与当期已用，剩余额度平台已代为算出；规则本身的调整走 update-rule（全量替换）与 change-rule-status（启停），查阅走 query-rule 与 list-rules。规则创建见创建限额规则，合并模型的概念主线见限额与账单。

查询有效额度

GET /open-api-corp/velocity/v1/query-quota——查某主体（卡 / 员工）合并后的有效限额与当期已用。

请求参数（Query String）

字段	类型	必填	说明
`organizationId`	String	是	≤36；主体所属组织
`subjectType`	String	是	`CARD`（任意卡）/ `CUSTOMER`（员工）
`subjectId`	String	是	≤36；与 `subjectType` 对应的主体标识
`currency`	String	否	`USD` / `HKD`；不传返回该主体所有相关币种

GET /open-api-corp/velocity/v1/query-quota?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&subjectType=CARD&subjectId=5185740066240790530&currency=USD

额度对象：读懂响应的钥匙

响应里每个周期节点（daily / monthly / quarterly / yearly）都是一个「额度对象」。金额侧与笔数侧字段名不同，结构一一对应：

金额额度对象	笔数额度对象	说明
`limitAmount`	`limitCount`	合并后的有效上限（同维度取 min）；`null` = 不限
`usedAmount`	`usedCount`	当期已用；上限为 `null` 时也照常累计并返回
`remainingAmount`	`remainingCount`	上限减已用；上限为 `null` 时返 `null`；负数表示已超限（中途下调限额所致）
`utilizationRate`	`utilizationRate`	使用率百分比，两位小数；上限为 `null` 时返 `null`
`periodKey`	`periodKey`	当期周期键：日 `20260730` / 月 `202607` / 季 `2026Q3` / 年 `2026`
`sourceRuleId`	`sourceRuleId`	该上限来自哪条规则（取 min 后的胜出者）

单笔限额是例外：perTransaction 额度对象只有 limitAmount 与 sourceRuleId 两个字段——单笔不累计，没有已用、剩余、使用率与周期键。

响应 data 结构

字段	类型	说明
`subjectType` / `subjectId`	String	回显请求
`asOfTime`	String	额度查询的参考时刻，ISO-8601 UTC 零时区
`purchase.countLimits`	Object	消费笔数额度（跨币种），下含四个周期节点的笔数额度对象
`purchase.amountLimits`	Array	消费金额额度，每币种一项
`purchase.amountLimits[].currency`	String	`USD` / `HKD`，本组全部金额的伴生币种
`purchase.amountLimits[].effective`	Boolean	该币种组是否实际生效
`purchase.amountLimits[].ineffectiveReason`	String	仅 `effective=false` 时有值。当前值域：`NOT_CARD_SETTLEMENT_CURRENCY`——该币种不在此卡可核销币种内
`purchase.amountLimits[].perTransaction`	Object	单笔额度对象，只有 `limitAmount` 与 `sourceRuleId`
`purchase.amountLimits[].daily` … `yearly`	Object	日 / 月 / 季 / 年累计金额额度对象
`cashAdvance.allowed`	Boolean	取现开关合并结果：任一规则为 `false` 即 `false`
`cashAdvance.sourceRuleId`	String	`allowed=false` 时指出是哪条规则关闭的
`cashAdvance.countLimits` / `amountLimits`	Object / Array	取现笔数与金额额度，结构同消费部分
`appliedRules`	Array	参与本次合并的规则清单：`ruleId` / `ruleName` / `status`
`appliedRules[].status`	String	恒为 `ACTIVE`——`INACTIVE` 不参与合并，不出现在此列表

响应示例

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "subjectType": "CARD",
    "subjectId": "5136759791164443137",
    "asOfTime": "2026-08-12T15:30:00Z",
    "purchase": {
      "countLimits": {
        "daily":     { "limitCount": 5,    "usedCount": 2,   "remainingCount": 3,    "utilizationRate": "40.00", "periodKey": "20260812", "sourceRuleId": "5136744097353943556" },
        "monthly":   { "limitCount": 100,  "usedCount": 37,  "remainingCount": 63,   "utilizationRate": "37.00", "periodKey": "202608",   "sourceRuleId": "5136744097353943556" },
        "quarterly": { "limitCount": null, "usedCount": 61,  "remainingCount": null, "utilizationRate": null,    "periodKey": "2026Q3",   "sourceRuleId": null },
        "yearly":    { "limitCount": null, "usedCount": 214, "remainingCount": null, "utilizationRate": null,    "periodKey": "2026",     "sourceRuleId": null }
      },
      "amountLimits": [
        {
          "currency": "USD",
          "effective": true,
          "ineffectiveReason": null,
          "perTransaction": { "limitAmount": "3000", "sourceRuleId": "5136744097353943556" },
          "daily":     { "limitAmount": "10000",  "usedAmount": "2400",  "remainingAmount": "7600",   "utilizationRate": "24.00", "periodKey": "20260812", "sourceRuleId": "5136744097353943556" },
          "monthly":   { "limitAmount": null,     "usedAmount": "18600", "remainingAmount": null,     "utilizationRate": null,    "periodKey": "202608",   "sourceRuleId": null },
          "quarterly": { "limitAmount": "200000", "usedAmount": "45200", "remainingAmount": "154800", "utilizationRate": "22.60", "periodKey": "2026Q3",   "sourceRuleId": "5136744097353943559" },
          "yearly":    { "limitAmount": "600000", "usedAmount": "96100", "remainingAmount": "503900", "utilizationRate": "16.02", "periodKey": "2026",     "sourceRuleId": "5136744097353943556" }
        },
        {
          "currency": "HKD",
          "effective": false,
          "ineffectiveReason": "NOT_CARD_SETTLEMENT_CURRENCY",
          "perTransaction": null,
          "daily": null, "monthly": null, "quarterly": null, "yearly": null
        }
      ]
    },
    "cashAdvance": {
      "allowed": true,
      "sourceRuleId": null,
      "countLimits": {
        "daily":   { "limitCount": null, "usedCount": 0, "remainingCount": null, "utilizationRate": null, "periodKey": "20260812", "sourceRuleId": null },
        "monthly": { "limitCount": null, "usedCount": 1, "remainingCount": null, "utilizationRate": null, "periodKey": "202608",   "sourceRuleId": null }
      },
      "amountLimits": [
        {
          "currency": "USD",
          "effective": true,
          "ineffectiveReason": null,
          "perTransaction": { "limitAmount": "500", "sourceRuleId": "5136744097353943557" },
          "daily":   { "limitAmount": "2000",  "usedAmount": "0",   "remainingAmount": "2000", "utilizationRate": "0.00", "periodKey": "20260812", "sourceRuleId": "5136744097353943557" },
          "monthly": { "limitAmount": "10000", "usedAmount": "500", "remainingAmount": "9500", "utilizationRate": "5.00", "periodKey": "202608",   "sourceRuleId": "5136744097353943557" }
        }
      ]
    },
    "appliedRules": [
      { "ruleId": "5136744097353943556", "ruleName": "员工日常差旅", "status": "ACTIVE" },
      { "ruleId": "5136744097353943557", "ruleName": "取现管控",     "status": "ACTIVE" },
      { "ruleId": "5136744097353943559", "ruleName": "季度总控",     "status": "ACTIVE" }
    ]
  }
}

（示例为节省篇幅省略了部分取现周期节点，实际响应四个周期节点齐全。）

错误码

错误码	说明
`SUBJECT_TYPE_NOT_ALLOWED`	限额域只接受 `CARD` / `CUSTOMER`，传其它类型即此码——用错接口，改代码
`SUBJECT_INVALID`	类型合法，但主体不存在、非 `ACTIVE`、或不属所传组织
`UNSUPPORTED_CURRENCY`	币种不支持，仅 `USD` / `HKD`

更新规则

POST /open-api-corp/velocity/v1/update-rule——全量替换：请求中未包含的维度 / 控制组即删除；对已绑定主体即时生效。

更新是全量提交，不是增量合并：remark 不传即清空；某控制组不传即删除该控制组（等于不限）；amountLimits 中未包含的币种组即删除。五个控制组仍须至少配置一组——要停用整条规则请走启停接口，不要靠清空控制组。更新前建议先调 query-rule 拿到完整配置，在其上修改后整体提交。

请求字段与创建规则的五个控制组完全一致，差别在顶层：

字段	类型	必填	说明
`organizationId`	String	是	≤36
`ruleId`	String	是	≤32
`ruleVersion`	Integer	是	乐观锁，与服务端不一致报 `VELOCITY_RULE_VERSION_CONFLICT`
`ruleName`	String	是	≤64；规则名称（全量提交）
`remark`	String	否	≤256；规则备注；不传即清空

响应 data 为更新后的完整规则对象（结构与创建响应一致），其中 ruleVersion 已自增。

{
  "ruleId": "5136744097353943556",
  "ruleRef": "rule-20260825-0001",
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleName": "员工日常差旅",
  "remark": "差旅卡消费限制",
  "status": "ACTIVE",
  "ruleVersion": 2,
  "bindingCount": "3",
  "createTime": "2026-08-12T09:00:00Z",
  "modifyTime": "2026-08-13T11:00:00Z",
  "purchaseControl": {
    "amountLimits": [
      { "currency": "USD", "perTransaction": "3000", "daily": "12000", "monthly": "80000" }
    ],
    "countLimits": { "daily": 5, "monthly": 100 }
  },
  "cashAdvanceControl": null,
  "currencyControl": { "filterType": "WHITELIST", "values": ["USD", "HKD"] },
  "mccControl": null,
  "geographicControl": null
}

未配置的控制组返回 null 而不是空对象——空对象会让您误以为配了一个空名单。

除创建规则的错误码之外，更新另有：

错误码	说明
`VELOCITY_RULE_NOT_FOUND`	规则不存在，或不属所传 `organizationId` / 本入驻方
`VELOCITY_RULE_VERSION_CONFLICT`	`ruleVersion` 与服务端不一致，存在并发修改；重查详情后重试
`VELOCITY_RULE_STATUS_INVALID`	规则当前状态不允许修改

启停规则

POST /open-api-corp/velocity/v1/change-rule-status——在 ACTIVE ⇄ INACTIVE 间切换。INACTIVE 不参与任何交易校验，但保留既有绑定关系，重新启用即恢复约束，不需要逐个解绑。

字段	类型	必填	说明
`organizationId`	String	是	≤36
`ruleId`	String	是	≤32
`status`	String	是	目标状态：`ACTIVE` / `INACTIVE`
`ruleVersion`	Integer	是	乐观锁

响应 data：ruleId、ruleName（供客户端确认改对了规则）、status（变更后状态）、ruleVersion（变更后的新值，下次更新须用它）、bindingCount、modifyTime。

停用前建议用响应中的 bindingCount 提示客户：该规则正约束着 N 个主体，停用后这些主体不再受本规则控制。

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "ruleId": "5136744097353943556",
    "ruleName": "员工日常差旅",
    "status": "INACTIVE",
    "ruleVersion": 3,
    "bindingCount": "3",
    "modifyTime": "2026-08-13T11:00:00Z"
  }
}

错误码	说明
`VELOCITY_RULE_NOT_FOUND`	规则不存在，或不属所传 `organizationId` / 本入驻方
`VELOCITY_RULE_VERSION_CONFLICT`	`ruleVersion` 与服务端不一致，存在并发修改
`VELOCITY_RULE_STATUS_INVALID`	目标状态非法，或与当前状态相同

查规则详情与列表

详情：GET /open-api-corp/velocity/v1/query-rule——传 organizationId + ruleId，返回完整规则对象（结构与创建响应一致，含 ruleVersion、bindingCount 与五个控制组）。规则不存在或不属所传 organizationId 时返回 VELOCITY_RULE_NOT_FOUND。列表：GET /open-api-corp/velocity/v1/list-rules——分页查询组织下的规则，只返摘要。

字段	类型	必填	说明
`organizationId`	String	是	≤36
`status`	String	否	`ACTIVE` / `INACTIVE`；不传返回全部状态
`page`	Integer	否	页码，从 1 起，缺省 1
`pageSize`	Integer	否	每页条数，缺省 20、上限 100

响应 data 为标准分页壳：page / pageSize / total + result[]，每项含 ruleId、ruleName、status、bindingCount、modifyTime。

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 2,
    "result": [
      { "ruleId": "5136744097353943557", "ruleName": "取现管控", "status": "ACTIVE", "bindingCount": "1", "modifyTime": "2026-08-13T09:00:00Z" },
      { "ruleId": "5136744097353943556", "ruleName": "员工日常差旅", "status": "ACTIVE", "bindingCount": "3", "modifyTime": "2026-08-13T09:00:00Z" }
    ]
  }
}

total 是数字，bindingCount 是字符串——后者声明为装箱 Long，经序列化器出参为字符串。解析时请分别处理。

下一步

调整绑定关系（绑定、解绑与双向查询）：绑定与解绑
限额在授权链路中如何参与校验：交易授权与 3DS

​📄 正文

​查询有效额度

​请求参数（Query String）

​额度对象：读懂响应的钥匙

​响应 data 结构

​响应示例

​错误码

​更新规则

​启停规则

​查规则详情与列表

​下一步

📄 正文

查询有效额度

请求参数（Query String）

额度对象：读懂响应的钥匙

响应 data 结构

响应示例

错误码

更新规则

启停规则

查规则详情与列表

下一步