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

# 绑定与解绑

> 把限额规则绑定到卡或员工：批量绑定与解绑的部分成功语义、整批级与逐条级两层错误，以及两个方向的绑定关系查询。

## 📄 正文

规则与对象（卡 `CARD` / 员工 `CUSTOMER`）是多对多绑定关系：规则建好后不约束任何交易，绑定之后才生效。绑定与解绑均为批量接口，一次针对**一条规则、一批主体**：规则级问题（不存在 / 非 ACTIVE / 不属该组织）**整批拒绝**，主体级问题**逐条独立、部分成功**——响应把结果拆成 `successTargets` 与 `failTargets` 两个列表，逐条失败原因落在 `failTargets[].errorCode`。规则创建见[创建限额规则](./creating-rules)，错误码全集见[错误码字典](../customer-success/error-codes)。

<Note>
  除了本页的 `bind` 接口，开卡时也可通过开卡请求中的 `ruleIds` 同步绑定规则（不超过 5 条），见[申请虚拟卡](./applying-virtual-cards)。无论哪条路径，**单张卡与单个员工各最多绑定 5 条规则**。
</Note>

## 批量绑定

**`POST /open-api-corp/velocity/v1/bind`**

### 请求参数

| 字段                      | 类型     | 必填 | 说明                                                       |
| ----------------------- | ------ | -- | -------------------------------------------------------- |
| `organizationId`        | String | 是  | ≤36；规则与主体所属组织                                            |
| `ruleId`                | String | 是  | ≤32；待绑定的规则（一次请求只针对一条规则）                                  |
| `targets`               | Array  | 是  | 非空；待绑定的主体列表                                              |
| `targets[].subjectType` | Enum   | 是  | `CARD` / `CUSTOMER`；其他取值整批拒绝（`SUBJECT_TYPE_NOT_ALLOWED`） |
| `targets[].subjectId`   | String | 是  | ≤36；`CARD` 时为 `cardId`（数字串）/ `CUSTOMER` 时为 `customerId`  |

### 响应 data

| 字段                              | 类型     | 说明                                                |
| ------------------------------- | ------ | ------------------------------------------------- |
| `successTargets`                | Array  | 成功条目列表                                            |
| `successTargets[].subjectType`  | Enum   | `CARD` / `CUSTOMER`                               |
| `successTargets[].subjectId`    | String | 该项的主体标识                                           |
| `successTargets[].errorCode`    | String | 成功条目恒为 `null`                                     |
| `successTargets[].errorMessage` | String | 成功条目恒为 `null`                                     |
| `failTargets`                   | Array  | 失败条目列表，结构同上，`errorCode` / `errorMessage` 标明逐条失败原因 |

> 本接口不返回 `successCount` / `failCount`：两者等同两个数组的长度，避免第二个真相来源。

绑定的逐条级 `errorCode`：

| errorCode                      | 说明                                                 |
| ------------------------------ | -------------------------------------------------- |
| `SUBJECT_INVALID`              | 主体不存在、非 ACTIVE、或不属所传组织                             |
| `CARD_RULE_DUPLICATE`          | 该主体已绑定同一规则（不静默去重）                                  |
| `CARD_RULE_CURRENCY_NOT_MATCH` | 规则的金额限额币种与该卡可核销币种无交集（可核销币种 = 已开通 VA 币种 ∪ 卡 BIN 币种） |
| `CARD_RULE_LIMIT_EXCEEDED`     | 该主体已绑规则数超上限（5 条）                                   |

### 请求示例

```json theme={null}
{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleId": "5136744097353943556",
  "targets": [
    { "subjectType": "CARD",     "subjectId": "5136759791164443137" },
    { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c" },
    { "subjectType": "CARD",     "subjectId": "5136765336134994434" }
  ]
}
```

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "successTargets": [
      { "subjectType": "CARD",     "subjectId": "5136759791164443137",
        "errorCode": null, "errorMessage": null },
      { "subjectType": "CARD",     "subjectId": "5136765336134994434",
        "errorCode": null, "errorMessage": null }
    ],
    "failTargets": [
      { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
        "errorCode": "SUBJECT_INVALID",
        "errorMessage": "target not found or not active" }
    ]
  }
}
```

### 整批级错误码

| 错误码                            | 说明                                              |
| ------------------------------ | ----------------------------------------------- |
| `ORGANIZATION_INVALID`         | 组织不存在 / 非 ACTIVE / 不属本入驻方                       |
| `VELOCITY_RULE_NOT_FOUND`      | 规则不存在，或不属所传组织——整批拒绝                             |
| `VELOCITY_RULE_STATUS_INVALID` | 规则非 ACTIVE，不可绑定——整批拒绝                           |
| `SUBJECT_TYPE_NOT_ALLOWED`     | 任一条目的 `subjectType` 非 `CARD` / `CUSTOMER`（整批拒绝） |

## 批量解绑

**`POST /open-api-corp/velocity/v1/unbind`**

结构与绑定一致：一次请求针对一条规则，逐条独立处理，一条失败不影响整批。

### 请求参数

| 字段                      | 类型     | 必填 | 说明                                                      |
| ----------------------- | ------ | -- | ------------------------------------------------------- |
| `organizationId`        | String | 是  | ≤36；规则与主体所属组织                                           |
| `ruleId`                | String | 是  | ≤32；待解绑的规则                                              |
| `targets`               | Array  | 是  | 非空；待解绑的主体列表                                             |
| `targets[].subjectType` | Enum   | 是  | `CARD` / `CUSTOMER`                                     |
| `targets[].subjectId`   | String | 是  | ≤36；`CARD` 时为 `cardId`（数字串）/ `CUSTOMER` 时为 `customerId` |

响应结构与绑定一致（`successTargets` / `failTargets`），解绑的逐条级 `errorCode`：

| errorCode                    | 说明                     |
| ---------------------------- | ---------------------- |
| `SUBJECT_INVALID`            | 主体不存在、非 ACTIVE、或不属所传组织 |
| `VELOCITY_BINDING_NOT_FOUND` | 该主体未绑定此规则              |

### 请求示例

```json theme={null}
{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleId": "5136744097353943556",
  "targets": [
    { "subjectType": "CARD",     "subjectId": "5136759791164443137" },
    { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c" },
    { "subjectType": "CARD",     "subjectId": "5136765336134994434" }
  ]
}
```

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "successTargets": [
      { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
        "errorCode": null, "errorMessage": null },
      { "subjectType": "CARD", "subjectId": "5136765336134994434",
        "errorCode": null, "errorMessage": null }
    ],
    "failTargets": [
      { "subjectType": "CARD", "subjectId": "5136759791164443137",
        "errorCode": "VELOCITY_BINDING_NOT_FOUND",
        "errorMessage": "the subject is not bound to this rule" }
    ]
  }
}
```

### 整批级错误码

| 错误码                        | 说明                                              |
| -------------------------- | ----------------------------------------------- |
| `ORGANIZATION_INVALID`     | 组织不存在 / 非 ACTIVE / 不属本入驻方                       |
| `VELOCITY_RULE_NOT_FOUND`  | 规则不存在，或不属所传组织                                   |
| `SUBJECT_TYPE_NOT_ALLOWED` | 任一条目的 `subjectType` 非 `CARD` / `CUSTOMER`（整批拒绝） |

## 按规则查绑定对象

**`GET /open-api-corp/velocity/v1/list-rule-targets`**——按规则查其绑定的卡与员工，分页、按绑定倒序。

| 字段               | 类型      | 必填 | 说明                            |
| ---------------- | ------- | -- | ----------------------------- |
| `organizationId` | String  | 是  | ≤20                           |
| `ruleId`         | String  | 是  | ≤32                           |
| `page`           | Integer | 否  | 页码，从 1 起，默认 1                 |
| `pageSize`       | Integer | 否  | 每页条数，默认 20，上限 100（超出按 100 截断） |

响应 `data` 为分页结构：`total` / `page` / `pageSize` + `result[]`，每项含 `subjectType`（`CARD` / `CUSTOMER`）、`subjectId`、`modifyTime`（绑定时间 ISO-8601）。

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "result": [
      { "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c", "modifyTime": "2026-08-12T11:05:00Z" },
      { "subjectType": "CARD",     "subjectId": "5136759791164443137",                  "modifyTime": "2026-08-12T11:00:00Z" }
    ]
  }
}
```

| 错误码                       | 说明                                                       |
| ------------------------- | -------------------------------------------------------- |
| `VELOCITY_RULE_NOT_FOUND` | 规则不存在，或不属请求 `organizationId`（不返回空页——空页会与「规则存在但没绑任何对象」混淆） |

<Note>
  规则不存在时报错而**不返回空页**，这是刻意设计：空页会与「规则存在但没绑任何对象」两种情况混淆。收到空 `result` 时，您可以确定规则存在、只是尚未绑定任何对象。
</Note>

## 按对象查约束它的规则

**`GET /open-api-corp/velocity/v1/list-target-rules`**——按卡 / 员工查约束它的规则，分页。

| 字段               | 类型      | 必填 | 说明                                                      |
| ---------------- | ------- | -- | ------------------------------------------------------- |
| `organizationId` | String  | 是  | ≤20                                                     |
| `subjectType`    | Enum    | 是  | `CARD` / `CUSTOMER`                                     |
| `subjectId`      | String  | 是  | ≤36；`CARD` 时为 `cardId`（数字串）/ `CUSTOMER` 时为 `customerId` |
| `status`         | Boolean | 否  | 默认 `true`：只返 `ACTIVE` 规则；传 `false` 含 `INACTIVE`         |
| `page`           | Integer | 否  | 页码，从 1 起，默认 1                                           |
| `pageSize`       | Integer | 否  | 每页条数，默认 20，上限 100（超出按 100 截断）                           |

响应 `data` 为分页结构：`total`（即该对象的绑定规则数）/ `page` / `pageSize` + `result[]`，每项含 `ruleId`、`ruleName`、`status`（`ACTIVE` / `INACTIVE`）、`modifyTime`。

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "result": [
      { "ruleId": "R000457", "ruleName": "取现管控",     "status": "ACTIVE", "modifyTime": "2026-08-12T11:10:00Z" },
      { "ruleId": "R000456", "ruleName": "员工日常差旅", "status": "ACTIVE", "modifyTime": "2026-08-12T11:00:00Z" }
    ]
  }
}
```

| 错误码                        | 说明                                  |
| -------------------------- | ----------------------------------- |
| `SUBJECT_TYPE_NOT_ALLOWED` | `subjectType` 非 `CARD` / `CUSTOMER` |

## 下一步

* 绑定生效后查询合并额度与已用：[额度查询与调整](./quota-and-adjustment)
* 绑定的规则在授权时如何参与校验：[交易授权与 3DS](./authorization-and-3ds)