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

# 限额管理 · 概述

> 用限额规则管控消费与取现：创建规则（五个控制组）、全量更新与乐观锁、批量绑定解绑（部分成功语义）、查询合并后的有效额度与已用。

## 📄 正文

限额规则是独立对象：归属公司、多对多绑定到卡或员工，多规则同维度取最严。本页按「建规则 → 绑对象 → 查额度 → 调整」的顺序讲清接口语义,概念主线见[限额与账单](../basic-concepts/limits-and-billing)。

## 创建规则

`POST /open-api-corp/velocity/v1/create-rule`——传 `ruleRef`（幂等键，同组织同 `ruleRef` 重试返回首次结果）、`organizationId`、`ruleName`，以及五个控制组中的**至少一个**（一个都不配返回 `DAPI_PARAM_INVALID`）：

| 控制组                  | 内容                                                                                                                          |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `purchaseControl`    | 消费限额：`amountLimits[]` 每币种一组（`perTransaction` / `daily` / `monthly` / `quarterly` / `yearly`，均 > 0）+ `countLimits`（笔数，全币种合计） |
| `cashAdvanceControl` | 取现限额：结构同消费，另有组级开关 `allowed`（组内必填，`false` 直接禁止取现）                                                                            |
| `currencyControl`    | 消费币种名单：`type`（WHITELIST / BLACKLIST）+ `currencies[]`（判定**原始消费币种**）                                                          |
| `mccControl`         | 商户类别名单：`type` + `mccList[]`（4 位数字）                                                                                          |
| `geographicControl`  | 交易地区名单：`type` + `countryCodes[]`（两位 ISO 大写，判定商户国家码）                                                                         |

<Warning>
  **「不限」通过不传该字段表达，禁止传 0 或负数**（`VELOCITY_LIMIT_VALUE_INVALID`）。金额限额匹配以**核销币种**为准，`currencyControl` 判定的是原始消费币种——两者是不同的轴。
</Warning>

新建规则恒为 `ACTIVE`，但**绑定到卡 / 员工之前不约束任何交易**。响应返回 `ruleId`、`ruleVersion`（乐观锁）、`bindingCount` 等。

```json theme={null}
{
  "ruleRef": "ext-request-0001",
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleName": "员工日常差旅",
  "purchaseControl": {
    "amountLimits": [
      { "currency": "USD", "perTransaction": "3000.00", "daily": "10000.00", "monthly": "80000.00" }
    ],
    "countLimits": { "daily": 5, "monthly": 100 }
  },
  "cashAdvanceControl": {
    "allowed": true,
    "amountLimits": [ { "currency": "USD", "perTransaction": "500.00", "daily": "2000.00" } ]
  }
}
```

## 绑定与解绑

**绑定**：`POST /open-api-corp/velocity/v1/bind`——一次针对**一条规则**（顶层 `ruleId`），`targets[]` 批量提交主体（`subjectType` CARD / CUSTOMER + `subjectId`）。规则级问题（不存在 / 非 ACTIVE）**整批拒绝**；主体级问题**逐条独立、部分成功**，响应分 `successTargets` 与 `failTargets`，逐条失败原因如 `SUBJECT_INVALID` / `CARD_RULE_DUPLICATE` / `CARD_RULE_CURRENCY_NOT_MATCH`。开卡时也可经 `ruleIds` 同步绑定。单张卡与单个员工各最多绑 5 条规则。

**解绑**：`POST /open-api-corp/velocity/v1/unbind`——同样批量、部分成功；未绑定该规则的主体以 `VELOCITY_BINDING_NOT_FOUND` 逐条失败。

**查绑定关系**：`list-rule-targets`（按规则查绑定对象）与 `list-target-rules`（按卡 / 员工查约束它的规则，默认只返 ACTIVE）。

## 查询有效额度

`GET /open-api-corp/velocity/v1/query-quota`——查某卡 / 员工**合并后的**有效限额与当期已用，据此自行计算剩余额度。要点：

* 每个额度节点返回 `limitAmount` / `usedAmount` / `remainingAmount` / `utilizationRate` / `periodKey` / `sourceRuleId`——`sourceRuleId` 指出最严值来自哪条规则；`limit=null` 表示该维度未设限（`usedAmount` 仍照常累计）。
* 单笔限额（`perTransaction`）只有 `limitAmount` 与 `sourceRuleId`——单笔不累计。
* 币种组带 `effective` 标志：`false` + `NOT_CARD_SETTLEMENT_CURRENCY` 表示该币种不在此卡可核销币种内、实际不生效。
* `cashAdvance.allowed` 为各规则开关的合并结果：**任一规则为 false 即 false**，并以 `sourceRuleId` 指出是哪条关的。
* `appliedRules` 列出参与合并的规则（恒为 ACTIVE——INACTIVE 不参与合并）。

## 调整规则

**更新**：`POST /open-api-corp/velocity/v1/update-rule`——**全量替换语义**：请求中未包含的维度 / 控制组即删除；须回传 `ruleVersion`，与服务端不一致返回 `VELOCITY_RULE_VERSION_CONFLICT`（存在并发修改，重查详情后重试）。对已绑定对象**即时生效**。

**启停**：`POST /open-api-corp/velocity/v1/change-rule-status`——在 `ACTIVE` ⇄ `INACTIVE` 间切换（同样带 `ruleVersion`）。`INACTIVE` 不参与任何交易校验但保留绑定关系；响应回显 `bindingCount`，停用前建议提示：该规则正约束着 N 个对象。

**查详情 / 列表**：`query-rule`（完整配置）与 `list-rules`（摘要分页，可按状态过滤）。

## 下一步

* 规则就绪后开卡绑定：[管理卡片](./managing-cards)
* 授权时限额如何参与校验：[交易授权与 3DS](./authorization-and-3ds)
* 本组详页：[创建限额规则](./creating-rules) · [绑定与解绑](./binding-and-unbinding) · [额度查询与调整](./quota-and-adjustment)