● 路由编排 · /v1

路由编排

路由规则走配置即代码:从代码仓库发布、带版本号、可先模拟再发布。不把编排锁在控制台里。

读取当前规则集

GET /v1/routing/rules

返回带版本号的完整规则集。把它存进你的代码仓库,改完调发布接口推回来,这样路由变更有 code review 和回滚。

响应 200

version integer 规则集版本号。发布时必须带当前版本,不一致返回 409,防止两个人同时改覆盖对方
rules object[]
└name string
└priority integer 数字小的先匹配。相同优先级时按数组顺序
└conditions object 匹配条件,字段取值见控制台的「路由字段」页。全部条件同时满足才命中
└targets object[] 按顺序级联。第一个是首选,后面的是软拒之后的备用
└connector_code string
└weight integer 同层多个目标时按权重分流,用于灰度
└three_ds auto | force | skip
published_at string<date-time>
published_by string
请求
curl -X GET https://api.baton.example/v1/routing/rules \
  -H "Authorization: Bearer sk_live_xxx"
响应 · 200
{
  "version": 7,
  "published_at": "2026-11-14T06:20:00Z",
  "published_by": "[email protected]",
  "rules": [
    {
      "name": "EU cards",
      "priority": 10,
      "conditions": {
        "country": [
          "DE",
          "FR"
        ],
        "currency": [
          "EUR"
        ]
      },
      "targets": [
        {
          "connector_code": "adyen",
          "weight": 100
        },
        {
          "connector_code": "stripe"
        }
      ],
      "three_ds": "auto"
    }
  ]
}

模拟路由

POST /v1/routing/simulate

干跑,不产生任何支付。回答「这笔会走哪个渠道、为什么」。

explain 里逐条给出规则的命中与未命中原因——这是解释「为什么没走我想要的渠道」的唯一办法。 把它接进 CI:规则提交前跑一组用例断言,比上线后看成功率掉了再查快得多。

请求体

amount必填 integer
currency必填 string
country string
payment_method_type string
card_bin string
rules object
└version必填 integer 规则集版本号。发布时必须带当前版本,不一致返回 409,防止两个人同时改覆盖对方
└rules必填 object[]
└name必填 string
└priority integer 数字小的先匹配。相同优先级时按数组顺序
└conditions必填 object 匹配条件,字段取值见控制台的「路由字段」页。全部条件同时满足才命中
└targets必填 object[] 按顺序级联。第一个是首选,后面的是软拒之后的备用
└three_ds auto | force | skip
└published_at必填 string<date-time>
└published_by string

响应 200

matched_rule string 命中的规则名,null 表示走默认路由
targets string[] 级联顺序
three_ds string
explain string[] 逐条规则的命中/未命中原因,用来解释「为什么没走我想要的渠道」
请求
curl -X POST https://api.baton.example/v1/routing/simulate \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 8900,
  "currency": "EUR",
  "country": "DE",
  "payment_method_type": "card",
  "card_bin": "411111"
}'
响应 · 200
{
  "matched_rule": "EU cards",
  "targets": [
    "adyen",
    "stripe"
  ],
  "three_ds": "auto",
  "explain": [
    "rule \"EU cards\" matched: country in [DE,FR] and currency in [EUR]",
    "rule \"High value\" skipped: amount 8900 < 50000"
  ]
}

发布规则集

POST /v1/routing/rules/publish

整集替换,不做增量合并——增量合并在路由上极易产生谁也没预期的组合。

必须带当前 version,不一致返回 409,防止两个人同时改覆盖对方。 发布前请先 simulate 干跑;直接发布到 live 没有保护网。

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

version必填 integer 规则集版本号。发布时必须带当前版本,不一致返回 409,防止两个人同时改覆盖对方
rules必填 object[]
└name必填 string
└priority integer 数字小的先匹配。相同优先级时按数组顺序
└conditions必填 object 匹配条件,字段取值见控制台的「路由字段」页。全部条件同时满足才命中
└targets必填 object[] 按顺序级联。第一个是首选,后面的是软拒之后的备用
└connector_code string
└weight integer 同层多个目标时按权重分流,用于灰度
└three_ds auto | force | skip
published_at必填 string<date-time>
published_by string

响应 200

version integer 规则集版本号。发布时必须带当前版本,不一致返回 409,防止两个人同时改覆盖对方
rules object[]
└name string
└priority integer 数字小的先匹配。相同优先级时按数组顺序
└conditions object 匹配条件,字段取值见控制台的「路由字段」页。全部条件同时满足才命中
└targets object[] 按顺序级联。第一个是首选,后面的是软拒之后的备用
└connector_code string
└weight integer 同层多个目标时按权重分流,用于灰度
└three_ds auto | force | skip
published_at string<date-time>
published_by string

错误

400参数不合法
409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/routing/rules/publish \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."