📄 正文
限额规则是独立对象:归属公司、多对多绑定到卡或员工,多规则同维度取最严。本页按「建规则 → 绑对象 → 查额度 → 调整」的顺序讲清接口语义,概念主线见限额与账单。创建规则
POST /open-api-corp/velocity/v1/create-rule——传 ruleRef(幂等键,同组织同 ruleRef 重试返回首次结果)、organizationId、ruleName,以及五个控制组中的至少一个(一个都不配返回 DAPI_PARAM_INVALID):
新建规则恒为
ACTIVE,但绑定到卡 / 员工之前不约束任何交易。响应返回 ruleId、ruleVersion(乐观锁)、bindingCount 等。
绑定与解绑
绑定: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(摘要分页,可按状态过滤)。

