绑定与解绑 - DCS Technical Documentation

📄 正文

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

除了本页的 bind 接口，开卡时也可通过开卡请求中的 ruleIds 同步绑定规则（不超过 5 条），见申请虚拟卡。无论哪条路径，单张卡与单个员工各最多绑定 5 条规则。

批量绑定

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 条）

请求示例

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

响应示例

{
  "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`	该主体未绑定此规则

请求示例

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

响应示例

{
  "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）。

{
  "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`（不返回空页——空页会与「规则存在但没绑任何对象」混淆）

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

按对象查约束它的规则

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。

{
  "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`

下一步

绑定生效后查询合并额度与已用：额度查询与调整
绑定的规则在授权时如何参与校验：交易授权与 3DS

​📄 正文

​批量绑定

​请求参数

​响应 data

​请求示例

​响应示例

​整批级错误码

​批量解绑

​请求参数

​请求示例

​响应示例

​整批级错误码

​按规则查绑定对象

​按对象查约束它的规则

​下一步

📄 正文

批量绑定

请求参数

响应 data

请求示例

响应示例

整批级错误码

批量解绑

请求参数

请求示例

响应示例

整批级错误码

按规则查绑定对象

按对象查约束它的规则

下一步