Skip to main content

📄 正文

限额规则是独立对象:归属公司、多对多绑定到卡或员工,多规则同维度取最严。本页按「建规则 → 绑对象 → 查额度 → 调整」的顺序讲清接口语义,概念主线见限额与账单

创建规则

POST /open-api-corp/velocity/v1/create-rule——传 ruleRef(幂等键,同组织同 ruleRef 重试返回首次结果)、organizationIdruleName,以及五个控制组中的至少一个(一个都不配返回 DAPI_PARAM_INVALID):
「不限」通过不传该字段表达,禁止传 0 或负数VELOCITY_LIMIT_VALUE_INVALID)。金额限额匹配以核销币种为准,currencyControl 判定的是原始消费币种——两者是不同的轴。
新建规则恒为 ACTIVE,但绑定到卡 / 员工之前不约束任何交易。响应返回 ruleIdruleVersion(乐观锁)、bindingCount 等。

绑定与解绑

绑定POST /open-api-corp/velocity/v1/bind——一次针对一条规则(顶层 ruleId),targets[] 批量提交主体(subjectType CARD / CUSTOMER + subjectId)。规则级问题(不存在 / 非 ACTIVE)整批拒绝;主体级问题逐条独立、部分成功,响应分 successTargetsfailTargets,逐条失败原因如 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)只有 limitAmountsourceRuleId——单笔不累计。
  • 币种组带 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——在 ACTIVEINACTIVE 间切换(同样带 ruleVersion)。INACTIVE 不参与任何交易校验但保留绑定关系;响应回显 bindingCount,停用前建议提示:该规则正约束着 N 个对象。 查详情 / 列表query-rule(完整配置)与 list-rules(摘要分页,可按状态过滤)。

下一步