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

# 额度查询与调整

> 查询卡或员工合并后的有效限额与当期已用（query-quota 额度对象详解），以及规则的更新、启停、详情与列表查询。

## 📄 正文

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

## 查询有效额度

**`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 后的胜出者）                                  |

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

### 响应 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` 不参与合并，不出现在此列表                                      |

### 响应示例

```json theme={null}
{
  "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`**——**全量替换**：请求中未包含的维度 / 控制组即删除；对已绑定主体**即时生效**。

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

请求字段与[创建规则](./creating-rules)的五个控制组完全一致，差别在顶层：

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

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

```json theme={null}
{
  "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
}
```

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

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

| 错误码                              | 说明                                   |
| -------------------------------- | ------------------------------------ |
| `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`。

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

```json theme={null}
{
  "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`。

```json theme={null}
{
  "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" }
    ]
  }
}
```

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

## 下一步

* 调整绑定关系（绑定、解绑与双向查询）：[绑定与解绑](./binding-and-unbinding)
* 限额在授权链路中如何参与校验：[交易授权与 3DS](./authorization-and-3ds)