邦斧开放平台 · 对外接口文档 v1

版本：v1.5.1 · 2026-10-12

适用：接入方（乙方）对接邦斧开放平台「会员资产与激励体系」开放能力

文档状态：契约已冻结。签名规则、错误码语义一经发布不再变更，只允许新增。

维护方：邦斧开放平台 · 技术支持：见附录 F

文档导航（先看这里，按角色选读）

三条最省时间的提示（很多对接方在这里绕远路）：

1. 先用沙箱账号把链路打通（§2.2 直接给了可用凭证），不要拿生产凭证等开通流程。
2. 先用 §4.4 的自检数据验签名，再写业务代码 —— 签名错会导致"所有接口都报 40002"，很难定位。
3. 本平台不做回调（§0.2.4），不用写回调验签/状态机；上报结果用 order/query 主动查。

〇、接口总览

共 20 个接口（其中 10 个是「只读查询类」：#2 #5 #6 #9 #10 #13 #14 #18 #19 #20 —— 只读不写、不需要幂等键、 随便调不会改任何数据）。建议按「先连通 → 再绑会员 → 再报业务 → 用查询类对账」的顺序接入。

0.1 一张表看懂所有接口

优先级说明：必接 6 个（不接则功能不完整）· 建议 4 个（退款、券回退、超时确认、会员资料）· 其余 可选。

最小可用接入 = 必接的 6 个，约 1 天可打通。

「改资产」= 会改变会员积分或券的接口。这类接口必须实现幂等（用上表的幂等键），

只有它们需要传 out_order_id；查询类接口不需要。

0.2 「改资产」接口的统一要求（三条，务必先看）

1. out_order_id 必须是稳定的业务单号（不是随机串、不是时间戳）——

重复上报靠它去重；用随机串会导致同一笔钱被记两次。

1. 金额一律整数分（1000 = 10 元）。全站不出现浮点金额。
2. 重复调用是安全的：同幂等键再次提交会返回首次的结果并带 idempotent:true，不会重复记账。

所以超时后请放心重试（重试要换新 nonce，见 §4）。

0.3 ★★ 业务资产模型速览（先看懂这个，接口就顺了）

很多对接方卡住不是卡在技术，而是卡在这个资产模型没理解透。所以先讲它。

0.3.1 一张图看懂资产怎么流转

①  用户在你方商城下单，付款成功
        │
        ▼
②  你方把「让利额」报给邦斧            ← 注意：报的是【让利额】，不是订单金额
        │    例：订单 200 元，让利 10% ⇒ 报 profit=2000（单位：分）
        ▼
③  邦斧在同一瞬间做两件事
        ├── 让利额 进【商家奖励池】      ← 等平台按周期释放
        └── 给该会员发【等额积分】        ← 1 元让利 = 1 积分
        │
        ▼
④  平台按周期自动释放（商家可配：每几天一批、每批释放池子的百分之几）
        │
        ▼
⑤  ★ 释放的那一刻：【扣积分 + 发券】
        │    例：释放 20 元券 ⇒ 扣 20 ÷ 5 = 4 积分
        │    ⇒ 积分 20 → 16 ；可用券 0 → 20 元
        ▼
⑥  用户下笔消费时用券抵扣                ← ★ 只有券能抵扣，积分不能

0.3.2 三个必须记住的数字

0.3.3 一个完整的数字实例（让利 20 元，每天一批、每批释放 50%）

关键现象：会员的「积分在减少、券在增加」。 积分是"还没兑现的额度"，券才是"到手能花的钱"。

0.3.4 为什么这么设计（业务视角）

如果让利一进来就全额变券，商家当月现金压力大、用户也可能拿完就走。所以设计成先入池、再分期释放： 用户为了拿到后续的券会持续回来消费 —— 这就是这套体系的锁客作用。

0.3.5 三个最常见的误解（提前澄清）

0.3.6 技术层面为什么不难

〇之二、术语与公共字段

先看这一节，后面所有接口都只列"业务字段"，不再重复公共字段。

0.2.1 术语表（对接必读，避免理解偏差）

★ 常见误解纠正：

· 「入池」不等于「发券」—— 入池只是记账，券要等出批才发到会员手上（有周期）。

· 积分与券是两笔不同的资产，不要混为一谈。

· 券是商家专属的：只能在贵司商城抵扣，与邦斧其他商家无关。

0.2.2 公共请求参数（所有接口都要带）

0.2.3 公共响应字段（所有接口统一）

{ "code": 0, "msg": "成功", "data": { }, "request_id": "本次请求的 request_id（回显）" }

msg 会写进用户界面吗？不会 —— 它是给贵司技术人员排障看的。面向消费者的文案请贵司自己组织。

0.2.4 ★★ 交互模式：本平台不做回调，全部同步返回

这一点请务必先知道，可以省掉大量对接工作：

• 没有异步回调，也没有「事件推送」「等待通知」「回调地址配置」这些东西。
• 每个接口都是同步的：调用返回时，结果就已经确定了（成功即已记账）。
• 因此贵司不需要：配回调 URL、写回调签名验签、处理回调乱序/重复、做"上报后等通知"的状态机。
• 唯一需要异步处理的是券的发放：上报消费后，券要等平台的释放周期才发到会员手上

（这是业务规则，不是接口延迟）。贵司只需定时查 coupon/balance 即可，不要轮询上报接口。

★ 那"上报超时了，到底记上没有"怎么确认？ 用 GET /open/v1/order/query（#19）—— 按业务单号主动查、只读无副作用地看到这笔的处理结果（是否入池、发了多少积分、券动作、是否已退款作废）。 它和"重复提交同一单号"是两条并行的确认路径，任选其一或都用：

如果贵司业务上确实需要"券发到手"的即时通知，属于新增回调能力，需另行评审与排期

（涉及重试、乱序、幂等一整套机制），请先与平台对接人确认。

0.2.5 超时与重试建议

0.2.6 精度与金额口径（★ 最容易出 100 倍错误的地方）

• 接口层全部用整数分：profit: 1000 = 10.00 元。不要传小数。
• 积分是 decimal(15,4)（带 4 位小数），返回时以字符串给出，请勿当浮点数运算后取整（会丢资产）。
• 券余额同时给分与元两个字段（如 coupon_usable_cents / coupon_usable），请用分那个做计算。

一、5 分钟跑通（先做这一步）

对接第一件事不是写业务，是先确认网络、凭证、签名算法三者都对。按下面四步走。

第 1 步：拿到凭证

向平台方索取：

⚠️ 凭证可用有三个前提，缺一个都调不通：

想「先验通链路再走签约」？请向平台方要【沙箱凭证】。 沙箱接入方免签约、免开通，拿到即可联调（详见第十一节）。正式凭证必须走完「签约 → 平台开通」才能使用。

第 2 步：算签名

// PHP 示例
$ts    = time();                              // 10 位秒级时间戳
$nonce = bin2hex(random_bytes(8));            // 16 位随机串，5 分钟内不可重复
$rid   = '';                                  // 取令牌时不传 request_id
$body  = json_encode(['appsecret' => $appsecret]);

$payload = implode("\n", [$appid, $ts, $nonce, $rid, hash('sha256', $body)]);
$sign    = hash_hmac('sha256', $payload, $appsecret);

第 3 步：取令牌

auth/token 用 appsecret 自身鉴权（请求体里要带 appsecret），签名也用 appsecret 算。

curl -s -X POST "http://<平台地址>/open/v1/auth/token?appid=<appid>&timestamp=<ts>&nonce=<nonce>" \
  -H "Content-Type: application/json" \
  -H "X-Open-Sign: <用 appsecret 算出的 sign>" \
  -d '{"appsecret":"<appsecret>"}'

# 期望返回：
# {"code":0,"msg":"签发成功","data":{"access_token":"...","expires_in":7200,"token_type":"Bearer","appid":"..."},"request_id":""}

拿到 access_token 就是第 3 步成功。 若返回 40001，多半是请求体里的 appsecret 没被发出去（检查 Content-Type: application/json）。

第 4 步：打 ping 验证链路

ping 是业务端点：令牌放 X-Open-Token 头，签名改用 access_token 作密钥（不是 appsecret，这里最容易搞反）。

curl -s -X POST "http://<平台地址>/open/v1/ping?appid=<appid>&timestamp=<ts2>&nonce=<nonce2>" \
  -H "X-Open-Sign: <用 access_token 算出的 sign>" \
  -H "X-Open-Token: <access_token>"

# 期望返回：
# {"code":0,"msg":"pong","data":{"appid":"...","rate_limit":600,"rate_used":1,...},"request_id":""}

看到 {"code":0,"msg":"pong",...} 就通了 —— 一次性确认了四件事：① 网络与路由可达 ② 凭证正确 ③ 签名算法一致 ④ 令牌有效。若不通，按 code 查第七节错误码表，常见问题见第十四节。

二、环境地址与沙箱测试账号

2.1 环境地址

所有接口均在 <地址>/open/v1/ 之下。生产环境启用 HTTPS。

2.2 ★★ 沙箱测试账号（可直接用，无需申请）

为了让贵司拿到文档当天就能动手，我们直接提供一个可用的沙箱账号：

这个账号的限额（刻意压到最低，防止误用）：

拿到账号后 60 秒自测（复制即可跑）：

# 1) 取令牌（把 <ts> 换成当前秒级时间戳、<nonce> 换成任意随机串）
curl -s "https://a.jetu.cc/open/v1/auth/token?appid=bfop261012c8ab974b60&timestamp=<ts>&nonce=<nonce>" \
  -X POST -H "X-Open-Sign: <按 §4 算出的签名>" -H "Content-Type: application/json" \
  -d '{"appsecret":"bab2b513dee1dd7e65ad75804f1bb84f7ef50a1e96fd956b"}'

# 2) 连通性自检（把 <token> 换成上一步的 access_token）
curl -s "https://a.jetu.cc/open/v1/ping?appid=bfop261012c8ab974b60&timestamp=<ts>&nonce=<nonce>" \
  -H "X-Open-Token: <token>" -H "X-Open-Sign: <按 §4 算出的签名>"

期望：第 2 步返回 {"code":0,"msg":"pong",...} —— 看到它就说明签名、网络、链路全部正确。

★ 凭证维护：此账号的 appid/appsecret 长期有效、不会随意变动；如平台因安全原因轮换，

会提前通知并同步更新本文档。请以本文档显示的最新值为准。

★ 安全说明（请知悉）：此账号仅限沙箱联调与体验，只能操作沙箱商家的数据、不计费、限额极低，

且平台可随时一键重置（重置后其中的测试数据清空，凭证不变）。

生产环境凭证由平台在签约后单独签发，不会使用、也不应复用此沙箱凭证。

若贵司希望使用独立沙箱账号（不与他人共用），可联系我们单独开通。

沙箱可用测试数据：沙箱不预置会员，请用 member/bind 自行绑定（建议用 out_uid 如 DEMO-001）。 沙箱的释放周期可由我们临时调整为 1 天，便于快速看到"积分减少、券增加"的效果，需要时告知即可。

三、鉴权流程

① 用 appid + appsecret 调 POST /open/v1/auth/token  →  拿到 access_token（有效期 2 小时）
② 之后所有业务接口带 HTTP 头 X-Open-Token: <access_token>
③ 令牌过期（40104）→ 重新调 ① 换取
④ 每个 appid 可同时持有多个有效令牌（无单点登录限制）

两个端点两类密钥（最容易搞错的地方）：

安全提醒：

• appsecret 只在调用 auth/token 时出现在请求体里，不要放到 URL 查询串（会被访问日志记录）
• 平台侧 appsecret 只存哈希，即使我们自己也查不出明文；丢失只能重置/轮换

3.1 密钥轮换 vs 密钥重置（★ 请分清，用错会中断服务）

平台提供两个操作，后果完全不同：

⇒ 定期轮换请要求平台用「轮换」（说清是轮换，避免被误当作重置而中断你的服务）。

推荐的轮换操作顺序（全程零失败）：

① 请平台执行「轮换」→ 你方拿到新密钥（明文只显示一次）
② 你方把新密钥配置上线（此时新、旧密钥同时有效，重叠期内随便切）
③ 观察确认新密钥调用正常
④ 重叠期自然结束，旧密钥自动失效 —— 你方无需做任何操作

• 重叠期时长由平台按接入方配置（0~720 小时，默认 24 小时）；0 表示不留重叠期，效果等同重置
• 重叠期内新旧密钥各自有效、互不影响；重叠期结束后旧密钥返回 40103

你方应在自己系统里记录密钥的启用/停用时间，避免把两把密钥的用途搞混（例如误把旧密钥留在配置里）。

四、签名算法（契约，不可变）

4.1 规则

payload = appid + "\n" + timestamp + "\n" + nonce + "\n" + request_id + "\n" + sha256hex(rawBody)
sign    = HMAC-SHA256(payload, secret)          输出小写十六进制

• rawBody = HTTP 请求体的原始字符串（原样，不做任何重排/序列化）
• 无请求体时用空字符串 ""，其 sha256 为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
• request_id 未传时按空字符串参与拼接
• 每次请求都要用新的 nonce（含重试）；request_id 才是在重试时要保持不变的
• 字段之间用 \n（换行符） 分隔，不是 & 或 |

4.2 参数位置（硬规定）

为什么 sign 走请求头：签名覆盖了请求体，若把 sign 也放进请求体，就成了「签的内容里包含签名自身」，无法计算。

4.3 多语言实现（可直接抄）

PHP

function bopSign($appid, $timestamp, $nonce, $requestId, $rawBody, $secret) {
    $payload = implode("\n", [
        (string)$appid, (string)$timestamp, (string)$nonce,
        (string)$requestId, hash('sha256', (string)$rawBody),
    ]);
    return hash_hmac('sha256', $payload, $secret);
}

Java

public static String bopSign(String appid, String ts, String nonce, String rid, String rawBody, String secret) throws Exception {
    String bodyHash = toHex(MessageDigest.getInstance("SHA-256").digest(rawBody.getBytes("UTF-8")));
    String payload = appid + "\n" + ts + "\n" + nonce + "\n" + rid + "\n" + bodyHash;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
    return toHex(mac.doFinal(payload.getBytes("UTF-8")));   // toHex 输出小写十六进制
}

Node.js

const crypto = require('crypto');
function bopSign(appid, ts, nonce, rid, rawBody, secret) {
  const bodyHash = crypto.createHash('sha256').update(rawBody, 'utf8').digest('hex');
  const payload  = [appid, String(ts), nonce, rid, bodyHash].join('\n');
  return crypto.createHmac('sha256', secret).update(payload, 'utf8').digest('hex');
}

Python

import hmac, hashlib
def bop_sign(appid, ts, nonce, rid, raw_body, secret):
    body_hash = hashlib.sha256((raw_body or '').encode('utf-8')).hexdigest()
    payload = '\n'.join([str(appid), str(ts), nonce, rid or '', body_hash])
    return hmac.new(secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()

4.4 签名自检（★ 请务必先用这组数据验通，再写业务代码）

用下面这组固定输入跑你方实现，结果必须逐字节一致：

第 1 步 · 验 sha256

sha256({"note":"hello"}) = 498207608015e1c6ea99b40748b3ecefd7d9035d5c0a70817902058823362be6

第 2 步 · 验拼接（注意是字面换行符 \n，不是 \n 两个字符）

bfoptest0001
1800000000
abcdef1234567890
demo-0001
498207608015e1c6ea99b40748b3ecefd7d9035d5c0a70817902058823362be6

即 payload = bfoptest0001\n1800000000\nabcdef1234567890\ndemo-0001\n498207608015e1c6ea99b40748b3ecefd7d9035d5c0a70817902058823362be6

第 3 步 · 验 HMAC

sign = 4601ac48c04aa780348549ac2df50fff6f7bd4318eafbbf04e701b183848a77b

你能算出这个值 ⇒ 签名算法已经对，可以进入业务对接。算不出 ⇒ 先别写业务，先按第十四节排查。

附：无请求体时的 sha256("")

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

（GET 类请求或 body 为空时用这个值参与拼接。）

五、请求与响应约定

5.1 统一响应信封

{
  "code": 0,
  "msg": "ok",
  "data": { },
  "request_id": "你在查询串里传的值原样回传"
}

幂等命中额外带 "idempotent": true（见第八节）。

5.2 HTTP 状态码

请同时判断 HTTP 状态与 code：即使 HTTP 是 4xx/5xx，响应体始终是 JSON（不会是 HTML），可直接解析。

★ 响应体永远是 JSON —— 包括出错和平台内部异常时。

平台对 /open/v1/* 的所有响应都保证是上面这个统一信封的 JSON，不会返回 HTML 错误页。 即使平台内部出错（HTTP 500），响应体也是：

{"code":50001,"msg":"服务内部错误","data":null,"request_id":""}

所以贵司的代码可以无条件 json_decode，不用为"解析失败/拿到 HTML"写分支。 请同时判断 HTTP 状态与 code：HTTP 200 不等于业务成功，以 code == 0 为准。

5.3 传输与编码

• 请求体统一 JSON（UTF-8），Content-Type: application/json
• 金额一律 整数分（例：12.34 元传 1234），不要传浮点
• 时间统一 10 位秒级 Unix 时间戳（不是毫秒）

六、接口清单

6.1 POST /open/v1/auth/token —— 签发令牌

6.2 POST|GET /open/v1/ping —— 连通性自检

用途：验证 ① 网络与路由可达 ② 凭证正确 ③ 签名算法一致 ④ 令牌有效 ⑤ 查剩余配额。建议你方在监控里定时调用。

6.3 POST /open/v1/member/bind —— 绑定外部会员

把你的会员 ID 与邦斧会员建立一一对应关系。这是对接的第一件事：没有映射，你的会员在邦斧侧就无处挂账。

规则（请务必按此实现）：

★ 为什么「一个邦斧会员只能被一个 out_uid 绑定」：若允许两个外部身份绑同一会员，

这些积分与券的归属将无法界定，对账必然产生纠纷。按约定的一一匹配原则，此类请求一律拒绝。

★ 为什么不做账号合并：合并要处理两个主键体系的历史流水、券余额、上下级关系，

第一版明确不做（见《商用解决方案》§4.1）。请在你方侧保证 out_uid 的稳定与唯一。

6.4 POST /open/v1/member/unbind —— 解绑

★ 解绑不影响用户已有积分与券：权益保留在邦斧侧，只是外部身份不再关联。

解绑后该 out_uid 再查余额会得到 40203；若之后重新绑定同一个会员，会复用原有映射（历史流水不断）。

6.5 GET /open/v1/member/profile —— 会员资料（已脱敏）

★ 脱敏口径（与本平台客户服务一致，不是本接口自创）：

若你方业务确需完整手机号，属另行评估事项，须单独书面约定（涉及个人信息合规），本接口不做。

6.6 GET /open/v1/member/balance —— 积分与券余额

这是你方最常用的接口（下单确认页、我的页面、客服查询都靠它）。

★ 关于「冻结」：它是整体禁用开关，不是「冻结了多少钱」。

平台不提供冻结金额这个数，请勿在你方界面展示「冻结 ¥X」。你方只需按 coupon_frozen 决定券能否使用。

注意：冻结不改变余额，coupon_usable_cents 照常返回。

★★ 关于券的范围（重要）：邦斧系统里券分「平台通用券」与「商家专属券」两层，

但本次对接你方只使用「商家专属券」 —— 平台通用券是邦斧平台自有的券，

由你方之外的体系发放与承担，你方既不发放也不核销。

因此 coupon_usable_cents 只等于商家专属券。

若某会员在邦斧侧另有平台通用券，会以 coupon_platform_cents 单列并注明"未计入可用" ——

请勿把它算进可用额度，否则会拿一个自己用不了的额度去抵扣、在用户侧穿帮。

口径权威性：积分与券的完整口径（换算比例、抵扣上限、有效期、活跃度闸门等）

以《邦斧开放平台 · 会员资产口径权威文档 v1.0》为准，请一并索取。

6.7 POST /open/v1/order/consume —— 上报消费（让利入池）

把你方订单的让利额报给邦斧，进入你方对应商家的奖励池。之后由既有释放机制自动按周期与比例 释放成券给会员 —— 你方不需要也不应该做释放，平台不提供"手动释放"接口。

★ 业务幂等键与 request_id 是两件事：request_id 只防"同一请求重发"；

你方换一个 request_id 再报同一订单，靠的是 out_order_id + seq 挡住重复入池。

所以 out_order_id 必须是稳定的业务单号，不能是随机串。

★ 入池 ≠ 发券：入池只是把让利记进池子，券要等出批时才释放。

上报后立刻查券余额看不到变化是正常的，不要重试上报。

6.8 POST /open/v1/order/refund —— 退款回冲

订单退款后调用，把该订单从后续每一批的释放基数里剔除 —— 否则释放池会为一张已退款的订单持续释放消费券（白送）。

★ 两类券的处理不同，别搞混：

本接口不会替你回退你方核销的券（核销是你方的交易流程），

但会在响应里用 has_verified_coupon 告诉你"这单有核销记录"，避免你漏掉。

found=false 不是错误：表示该订单没有入池记录（可能没上报过，或已回冲过）。

接口返回成功、stopped_records=0，请不要重试。

6.9 GET /open/v1/pool/summary —— 奖励池概览（只读）

★ 别把 history_intake 当余额：它是历史累计入池额，只增不减。

看"现在能释放多少"请看 pool_balance。

6.9.1 ★ POST /open/v1/order/refund 到底做了几件事

返回新增 integral_reclaimed = 本次扣回的积分数。

★ 你方的会员积分账要与之对齐：退款后你方商城的会员积分也应回到「消费前」的状态

—— 即「发出的积分 − 已换券用掉的积分」。

6.10 GET /open/v1/integral/logs —— 积分流水

★★ 积分不是整数！ 邦斧积分是 4 位小数的数值（生产实测 26,418 / 26,967 个会员带小数，

如 2.7238、9671.3113）。接口以字符串返回，请勿取整 —— 取整会直接丢掉用户资产。

★ 积分是平台级字段，不按商家隔离（这点与券不同：券分会员级/商家专属两层）。

本接口只返回该会员在本商家产生的流水，但 integral_total 是他的全部积分。

6.11 POST /open/v1/integral/adjust —— 积分人工调整（补分 / 扣分）

★ 默认关闭。 该操作等于直接变动用户资产（1 积分最多可释放 5 元券）， 需平台在参数配置中开启，并受单笔上限（默认 1000 积分）约束。

关于「双人复核」：这是你方客服系统的流程。本平台提供完整的可追溯留痕

（既有积分流水 + 本模块业务流水，含 operator、reason、request_id），供你方审计。

6.12 POST /open/v1/member/data-request —— 个人信息合规通道

★ 「删除」= 匿名化，不是物理删除：消费者的积分/券与全部流水必须保留

（账务留存、对账、反欺诈需要 —— 这是个保法删除权的法定例外）。物理删会员行会直接抹掉用户的资产。

★ 匿名化后 out_uid ↔ mid 映射保留，所以你方按 out_uid 查资产仍能查到（资产不丢）。

但若之后用同一手机号绑一个新的 out_uid，会形成新账户、资产不合并 ——

这是去标识化的必然结果，你方应始终使用稳定的 out_uid，不要靠手机号重绑。

6.12.1 ★ POST /open/v1/coupon/transfer —— 券转赠

口径（已与贵司确认）：消费券不支持提现；支持转赠；是否开启由商户后台配置（默认关闭）。

★ 双方各产生一条券流水：转出方 action=0（减少）、接收方 action=1（增加），

remark 互指对方标识与单号 ⇒ 双方各自对账时都能看到这笔，不需要额外解释。

两条流水的 ordernum 都是本次转赠单号，可倒查。

并发安全：转赠按会员 ID 升序加行锁，A→B 与 B→A 同时发起不会死锁（已实测）。

6.13 券：余额与流水

source 的含义：bop = 由你方通过本平台产生；other = 该会员在这个商家下的其它来源流水。

平台一并返回，不做隐藏 —— 只给你方自己的流水会看起来像隐瞒。

★ 关于「可用券列表」（方案原列的 coupon/list）：本平台的券是余额制（一个金额），

不是卡券制 —— 系统里没有"一张张券"，所以没有面额、有效期、适用范围这些字段，

也就不存在"可用券列表"这个接口。要明细请看 coupon/logs（流水）。

这与《口径权威文档》里"券不做过期回收"是同一条事实。

6.14 关于「发券」——券只能由奖励池释放产生

★ 平台不提供「直接发券」接口。 券的唯一来源是奖励池按配置释放：

```

订单让利额 profit

↓ 入池 （order/consume 上报）

奖励池 platform_profit_stage ← 池子里就是这笔钱

↓ 发等额积分（1 元让利 = 1 积分）

会员积分

↓ 按池子配置分批释放：本批 = back_amount × member_profit ÷ back_integral

↓ 同时【扣积分】= 券额 ÷ 5

券（本商家专属券，会员可用于抵扣）

```

为什么必须这样：券的量天生被让利额顶死 —— 上限 = 让利额 × 5（Member.php 的

bcmul($record['member_profit'], 5, 2)）。池子里有多少钱，就只能释放出多少券。

若允许绕过池子直接给会员加券，券就会与积分、利润脱钩，

会员拿到的抵扣将没有对应的资金支撑 —— 这既破坏账目闭合，也不是任何一方想要的结果。

因此：贵司要让会员拿到券，正确且唯一的做法是 order/consume 上报让利额，

之后平台会按奖励池配置（周期、每批比例）自动释放，贵司无需实现任何释放逻辑。

释放进度可随时用 GET /open/v1/pool/summary 查看。

6.15 POST /open/v1/coupon/verify —— 券核销（扣减）

在你方自己的交易流程里决定抵多少，然后调本接口扣减。 平台不判断你方订单该不该抵、抵多少。

★ 一次消费要核销多次怎么办（如分单核销）：用不同的 seq。

6.16 POST /open/v1/coupon/unverify —— 券回退（订单取消 / 退款）

6.19 GET /open/v1/order/query —— 按业务单号查询处理结果（★ 超时确认用）

为什么有这个接口：本平台不做回调（见 §0.2.4），上报后如果遇到网络超时，贵司需要一种 不产生任何副作用的方式确认"这笔到底处理成功了吗"。这个接口就是干这个的。

请求参数

响应 data 字段

★ found: false 不等于失败。 可能是：还没到达本平台、仍在重试中、或者单号写错了。 此时正确做法是重发——用同一 out_order_id + seq（有幂等保护，不会重复记账）， 不要换新单号（换新单号会变成一笔新的业务）。

示例

GET /open/v1/order/query?appid=bfop260101xxxxxxxx&out_order_id=SO20261012001&timestamp=1750000000&nonce=abc123

{
  "code": 0, "msg": "ok",
  "data": {
    "out_order_id": "SO20261012001", "found": true, "event_count": 1,
    "events": [{"action":"consume","seq":1,"amount_cents":3000,"integral":"30","biz_id":1302,"processed_at":"2026-10-12 17:39:21"}],
    "coupon_logs": 0, "integral_logs": 1,
    "pool": [{"in_pool_cents":3000,"back_status":"normal","back_status_text":"有效（会参与后续释放）","record_id":90755}],
    "hint": "已查到处理记录。重复提交同一单号会返回这份同样的结果，不会重复记账。",
    "amount_unit": "分"
  },
  "request_id": ""
}

数据范围：只能查到本接入方自己的单号，别家的同名单号查不到（按 appid 严格隔离）。

6.20 GET /open/v1/member/list —— 会员列表（批量对账）

为什么有这个接口：贵司做批量对账时，需要"我这边绑了哪些会员、各自多少积分多少券"。 一个个调 member/balance 在会员上千时不可行。

请求参数

响应 data 字段

只回本接入方名下的会员（已解绑的不在内）；不回姓名、手机号（个人信息最小化）——

需要某个会员的详细信息请调 member/profile（已脱敏）。券额度为本商家专属券口径。

6.21 GET /open/v1/billing/usage —— 本期用量与账单

为什么有这个接口：贵司需要在自己系统里看"这个月调了多少次、要交多少钱"，不用每次问平台。

请求参数

响应 data 字段

计费口径与平台账单完全一致（同一个实现）；账号信息（是否签约、费率）请见平台提供的接入方信息页。

6.17 其他接口

退款回冲（消费入池的回冲）、积分流水、积分人工调整、释放池明细等将随对接方案确认后逐个开放。

当前已开放的接口：auth/token、ping、member/bind、member/unbind、member/profile、 member/balance、member/data-request、order/consume、order/refund、pool/summary、 integral/logs、integral/adjust、coupon/balance、coupon/logs、 coupon/verify、coupon/unverify、coupon/transfer。其余路径一律返回 40006。

★ 不提供 coupon/grant（直接发券） —— 原因见 §6.14。

6.18 未定义路径（兜底）

请求 open/v1/ 下未定义的路径，在鉴权通过的前提下返回：

{"code":40006,"msg":"接口不存在","data":null,"request_id":""}

（HTTP 404，仍是 JSON，不会返回 HTML。）

⚠️ 前提是「鉴权通过」：平台先鉴权、后路由，所以若签名或令牌无效，会优先返回鉴权类错误码（40001 / 40002 / 40102 / 40104），而不会返回 40006。

也就是说：连 40006 都拿不到，先怀疑签名/令牌，而不是路径。

七、错误码表（完整，已冻结）

关于 40301 与「豁免端点」：ping 与 auth/token 这两个端点是合规门禁的豁免端点

（为的是合规状态变化时你仍能自检连通性），所以它们永远不会返回 40301。

40301 只会出现在业务接口上（member/* 即业务接口）。所以联调 member/* 时若收到 40301，

说明该接入方尚未完成签约，请到商户后台「合规中心」完成签署。

关于 40106（服务到期）：接入服务按年计费，到期后所有接口（含 ping/auth/token）

都会返回 40106。请在生产环境监控里对 40106 单独告警 —— 它和 40102 的处置方式不同：

40102 是「被平台停用」（要问原因），40106 是「该续费了」。

八、幂等与重试（重要，请务必实现）

8.1 语义

带 request_id 的写接口，平台按「appid + request_id」去重：

8.2 你方必须做的

1. 写接口必带 request_id，取值建议：你方业务单号 + 操作类型（如 ORDER123456:consume）
2. 超时不要换 request_id：超时后用同一个 request_id 重发，平台会告诉你真实结果
3. 非幂等接口（如 auth/token）不要复用 request_id
4. request_id 长度 ≤ 64

8.3 重试建议

网络超时/5xx → 同 request_id 重试，间隔 1s / 3s / 10s（最多 3 次）
收到 40901    → 说明前一次还在处理，等待 ≥2s 后同 request_id 重试
收到 42901    → 按响应中的限流信息退避（建议 ×2 递增）
收到 4xx 参数/鉴权类 → 重试无意义，先修问题

⚠️ 重试时必须重新生成 nonce（请求体与 request_id 保持不变）。

「防重放」与「幂等」是两道独立的闸门，且防重放在前：

| 重试方式 | 平台返回 | 含义 |

|---|---|---|

| 同 request_id + 新 nonce ✅ | idempotent: true + 首次结果 | 正确姿势，直接拿到真实结果 |

| 同 request_id + 同 nonce（原样重发） ❌ | 40004 | 被防重放拦下，不会回放结果 |

40004 只说明「这个 nonce 用过了」，不代表业务失败 —— 别据此判定失败并另开新单，否则可能重复入账。换成新 nonce 用同一个 request_id 再发一次即可。

九、限流与访问控制

为什么有两个维度：总额度是"总闸"。若你方某个循环写错、只打一个接口，总余量还很充足，

但那个接口已经把平台侧写库（发券/入池都带锁）打满。单接口闸门会在总闸仍放行的情况下，

单独把异常高频的那一个接口拦住 —— 保护的是双方：平台不被单点打爆，你方也不会因此

把整包额度耗尽。建议按该接口正常峰值的 3~5 倍设置。

⚠️ 单接口维度只拦被超限的那个接口，不影响你方其他接口的调用（不连坐）。

📌 计费口径也是按分钟调用量统计，与本限流窗口自洽：限流口径 = 计费口径。

如需更高配额，提前告知平台方并说明峰值 QPS 与调用模型（批量/实时）。

超限时响应头会带 Retry-After（秒），请按它退避，不要固定 sleep。

9.2 IP 调用白名单（★ 生产环境建议必配）

为什么要有它：appsecret 一旦泄露，签名就是「合法」的。IP 白名单是凭证之外的第二道门 —— 即使密钥被盗，攻击者不在白名单里也进不来。

上线前请把这三件事确认掉：

1. 报准出口 IP：不是「服务器内网 IP」，而是访问外网时对端看到的公网 IP。

可用 curl https://ifconfig.me 在你方服务器上查。若你方走 NAT/网关/云函数，要报网关的出口 IP。

1. 覆盖变化范围：若你方出口 IP 是浮动池或会扩容，请把整个网段报过来（如 203.0.113.0/24），

否则某台机器扩容后就会突然收到 40107。

1. 双向对等：平台回调你方（如事件通知，后续开放）时，也需要你方把我方出口 IP 加入你方白名单 ——

届时平台会书面提供固定出口 IP 清单。

运维提醒：40107 通常不是故障，而是你方出口 IP 变了。如果业务突然中断且返回 40107，

先自查出口 IP，再带 request_id 联系平台。

十、调用可见性（排查「我上报了但没到账」）

10.1 平台侧记录

平台对每一次调用都留痕（不论成功失败、不论有没有 request_id），记录：时间、接口、request_id、业务单号、结果码、失败原因、耗时、来源 IP、脱敏后的请求体。

10.2 你方遇到「上报了但没到账」的排查顺序

1. 你方是否拿到响应？ 没拿到 → 网络/超时问题
2. 响应是 code=0 吗？ 不是 → 按第七节处理
3. 把 request_id 提供给平台方，平台可立刻定位：
4. 查不到记录 ⇒ 请求根本没到平台（你方没发出、地址写错、被中间层拦掉）
5. 有记录且是失败 ⇒ 记录里有明确原因（如会员不存在）
6. 有记录且成功 ⇒ 问题在后续业务环节，带上记录一起排查

10.3 你方应自留

• 每次调用的 request_id、请求体、响应体、耗时
• 建议落库并保留 ≥ 90 天，便于双方对账

十一、沙箱环境

11.1 用途

客户不要拿生产联调 —— 否则脏数据污染真实账本，后续对账永久对不上。

11.2 使用方式

★ 文档 §2.2 直接给了一个可用的沙箱测试账号（appid + appsecret + 限额），无需申请即可开始联调。

若贵司需要独立沙箱（不与他人共用），可联系我们单独开通。

平台方也可为贵司额外开通一个沙箱接入方（独立的 appid）。

沙箱最大的好处：免签约、免开通，拿到凭证立刻能调。 所以「先验通链路」这件事请用沙箱做，不要占着正式凭证等签约流程。

11.3 重要边界（必须知晓）

沙箱是逻辑沙箱：按 appid 隔离平台侧数据（调用日志/令牌/规则快照），可一键重置。

但涉及会员积分、消费券等实际业务数据的写入，会落在沙箱接入方所绑定的那个商家名下。因此：

沙箱接入方必须绑定一个【专用的沙箱商家】，不得绑定真实客户商家，否则沙箱联调会污染真实客户的会员数据。

平台方在开通时会做这个绑定，请勿要求把沙箱绑到生产商家上。

11.4 沙箱合格标准

贵司应在拿到沙箱凭证后 24 小时内，自行跑通「绑定会员 → 上报消费 → 查询积分 → 券到账 → 核销券」全链路，不需要向平台求助。 遇到问题请先按第十节自查，再带 request_id 联系平台。

十二、合规要求（接入前置条件）

邦斧开放平台在合规上是有门禁的，请知悉。

正确顺序（顺序错了会一直报 40102）：

① 平台方建好接入方并发给你 appid / appsecret
② 贵司在商户后台「合规中心」在线签署《客户合规承诺书》
③ 平台方在「接入方管理」点【开通】   ← 签约 ≠ 开通，这步必须做
④ 此时业务接口才可用（此前一律 40102）
⑤ 急等联调？直接用【沙箱凭证】，跳过后三步

签署完成后，平台为该接入方开通，业务接口即可正常调用。签署过程会留痕（协议全文快照 + SHA256 内容哈希 + 逐项勾选 + 签署人声明 + 身份确认 + IP/设备/时间），双方均可下载《签署证明》。

十三、接入自检清单（提交联调前请逐项确认）

• 已拿到 appid / appsecret，并确认对应环境（测试 / 沙箱 / 生产）
• 已确认该接入方【已签约且已被平台开通】（否则一切接口都是 40102；只想验链路请改用沙箱凭证）
• 签名算得对：用第四节 4.4 的自检数据比对通过
• 时间戳取自 NTP 同步的服务器时间，误差 < 5 分钟
• 每次请求生成新的 nonce
• 已实现 auth/token 取令牌 + 令牌过期（40104）自动重新获取
• 已与平台约定密钥轮换周期，并知悉【轮换】不会断服而【重置】会立即失效（见 §3.1）
• 业务端点用 access_token 签名，auth/token 用 appsecret 签名（别搞反）
• X-Open-Sign 在请求头，公共参数在查询串
• 金额按整数分传递
• 写接口都带 request_id，且重试用同一个 request_id
• 实现了超时（建议 5~10 秒）+ 有限次重试 + 指数退避
• 处理了 40102（被停服）、40106（服务到期，需续期）与 40301（未签约）三个状态
• 对 40106 与 40102 分别告警（40102 要问平台原因，40106 是提示续费）
• 已把出口 IP（或网段）报给平台加入白名单，且已覆盖扩容后的地址范围（见 §9.2）
• 已处理 40107：能区分「IP 变了」与「真故障」，并对 40107 单独告警
• 已实现 ping 定时自检（建议 1~5 分钟一次）并接入你方告警
• 每次调用落库留痕（request_id + 请求 + 响应 + 耗时），保留 ≥ 90 天
• 已按第十一节在沙箱完成全链路联调
• 已签署《客户合规承诺书》并通过平台开通

十四、常见问题

Q：40001 但参数我都传了？ 调 auth/token 时请求体里必须有 appsecret（该端点用密钥自身鉴权）。业务端点不需要传 appsecret。

Q：突然全是 40107「调用来源 IP 不在白名单内」？ 不是你方代码问题，是出口 IP 变了（换机、扩容、改 NAT、上了云函数/代理都会变）。 先在你方服务器执行 curl https://ifconfig.me 看当前出口 IP，报给平台添加即可。 若你方出口是浮动池，建议改报整个网段。

Q：40002 签名失败，我按示例写的？ 三个高频原因：① rawBody 用的不是你实际发出的字节（例如先 json_encode 算签名、发送时又被重新序列化）；② 字段间分隔符不是 \n；③ 业务端点误用了 appsecret 作密钥（应该用 access_token）。

Q：40104 但我刚取的令牌？ 检查 X-Open-Token 请求头名是否正确、值里是否混入空格或换行；令牌有效期 2 小时。

Q：40301 是什么？ 该接入方还没完成合规签约。请到商户后台「合规中心」签署，签完平台开通即可。

Q：40901 要不要换 request_id 重试？ 不要换。 用同一个 request_id 稍后重试，平台会返回真实结果。

Q：重试时收到 40004，是不是说明前面那次失败了？ 不是。 40004 只表示 nonce 重复（你原样重发了）。请换一个新 nonce、保持同一个 request_id 再发一次 —— 平台会告诉你前一次的真实结果。

Q：我上报了但查不到记录？ 把 request_id 给平台，若平台查不到记录，说明请求没到平台 —— 请先检查你方是否真的发出、地址是否写对、是否被代理/防火墙拦掉。

Q：我换了密钥，为什么突然全断？ 大概率是平台执行了「重置」而不是「轮换」 —— 重置会同时作废旧密钥与全部令牌。 下次定期换密钥请明确要求轮换（旧密钥有重叠期、令牌不断）。详见 §3.1。

Q：我刚拿到凭证，第一次调就 40102「服务已停止」？ 大概率不是被停服，而是这个接入方还没被开通。正常顺序是：签约 → 平台点开通 → 才可用。急等联调请改用沙箱凭证（沙箱免签约、免开通）。

Q：沙箱能不能绑我的正式商家？ 不能。 沙箱接入方必须绑定专用沙箱商家，否则沙箱联调会污染真实客户的会员数据。

附录 A、各接口请求参数速查表

只为省你翻页：每个接口的字段、类型、必填一次列全。公共参数（appid/timestamp/nonce/签名头）见 §0.2.2，此处不重复。

「二选一」表示该组字段至少填一个；「否（默认 X）」表示可不填，不填按 X 处理。

A.0 POST|GET /open/v1/ping

用途：连通性自检（豁免合规门禁，但不豁免开通状态）　详见：§6.2

A.1 POST /open/v1/auth/token

用途：—（除公共参数外无）　详见：§6.1

A.2 POST /open/v1/member/bind

用途：绑定贵司会员与我方账本账户（一对一）　详见：§6.3

A.3 POST /open/v1/member/unbind

用途：解绑（资产保留，重新绑可恢复）　详见：§6.4

A.4 GET /open/v1/member/profile

用途：会员资料（已脱敏：姓名首字/手机前3后4/地址到省市）　详见：§6.5

A.5 GET /open/v1/member/balance

用途：积分与券余额　详见：§6.6

A.6 POST /open/v1/order/consume

用途：上报消费：让利入池 + 同步发等额积分　详见：§6.7

A.7 POST /open/v1/order/refund

用途：退款回冲：剔出释放基数 + 扣回积分（发券同步扣）　详见：§6.8

A.8 GET /open/v1/pool/summary

用途：奖励池概览（只读，不需 out_uid）　详见：§6.9

A.9 GET /open/v1/integral/logs

用途：积分流水（分页）　详见：§6.10

A.10 POST /open/v1/integral/adjust

用途：积分人工调整（默认关闭，需平台开启）　详见：§6.11

A.11 POST /open/v1/member/data-request

用途：个人信息合规通道（查询/删除权，删除=匿名化）　详见：§6.12

A.12 位号保留（原「POST /open/v1/coupon/grant」已随直接发券下线，见 §6.14）。

A.13 GET /open/v1/coupon/balance

用途：券余额（商家专属层）　详见：§6.13

A.14 GET /open/v1/coupon/logs

用途：券流水（每笔带单号可倒查）　详见：§6.13

A.15 POST /open/v1/coupon/verify

用途：券核销（扣减）　详见：§6.15

A.16 POST /open/v1/coupon/unverify

用途：券回退（订单取消/退款）　详见：§6.16

A.17 POST /open/v1/coupon/transfer

用途：券转赠（默认关闭，商户后台可开）　详见：§6.12.1

A.18 GET /open/v1/order/query

请求头：X-Open-Sign（必需）、X-Open-Token（必需）。

A.19 GET /open/v1/member/list

请求头：X-Open-Sign（必需）、X-Open-Token（必需）。

A.20 GET /open/v1/billing/usage

请求头：X-Open-Sign（必需）、X-Open-Token（必需）。

附录 B、数据字典与枚举

B.1 业务流水事件类型（order/query 返回的 action）

B.2 金额与积分方向（流水表）

⚠️ 注意区分：业务流水（biz_record）的 action 是事件类型（上表 B.1，值 1~8）；

积分/券流水的 action 是方向（1=增 0=减）。两者取值空间不同，不要混用。

B.3 order/query 返回的入池状态

B.4 券的口径字段（member/balance）

★ 券是余额制，不是卡券制（没有一张张独立的券码）。所以只有"余额"与"流水"，没有"券列表"。

B.5 会员资料字段（member/profile）

B.6 账期格式

附录 C、端到端集成时序

C.1 场景一：用户下单并支付成功（核心）

你方商城                                邦斧开放平台
   │                                        │
   │  ① 订单支付成功                         │
   ├──── POST /open/v1/order/consume ───────▶│
   │      {out_uid, out_order_id,            │  ② 让利额入池
   │       seq, profit, order_amount}        │  ③ 发等额积分（1 元=1 积分）
   │◀─── {code:0, data:{record_id}} ────────┤  ④ 同步返回（已记账）
   │                                        │
   │  （后续平台按周期自动释放成券，贵司无需实现任何定时逻辑）
   │                                        │
   │  ⑤ 想确认结果？                          │
   ├──── GET /open/v1/order/query ──────────▶│  只读，无副作用
   │      ?out_order_id=...                  │
   │◀─── {found, events[], pool[]} ─────────┤

注意事项

• out_order_id 必须是稳定的业务单号（用你方真实订单号，不要用随机串/时间戳）。
• 同一单号多笔事件用 seq 区分（seq 从 1 开始）。
• 网络超时不要慌：用同一单号 + 同一 seq 重发（有幂等保护，不会重复记账）。

C.2 场景二：用户用券抵扣

   │  ① 结算页先查可用券                        │
   ├──── GET /open/v1/member/balance ─────────▶│
   │◀─── {coupon_usable_cents} ───────────────┤
   │                                           │
   │  ② 用户勾选「用券抵扣 5 元」                │
   ├──── POST /open/v1/coupon/verify ─────────▶│  扣券
   │      {out_uid, amount:500, out_order_id}  │
   │◀─── {code:0} ─────────────────────────────┤
   │                                           │
   │  ③ 若该订单后来取消/退款                    │
   ├──── POST /open/v1/coupon/unverify ───────▶│  把券退回
   │      {out_uid, out_order_id, seq}         │
   │◀─── {code:0} ─────────────────────────────┤

注意事项

• 余额不足会直接拒绝（40205），不会自动截断 ⇒ 必须先查余额再决定能抵多少。
• 回退必须带原核销的同一 out_order_id（幂等键沿用原核销键）。

C.3 场景三：订单退款

   │  ① 你方订单退款                            │
   ├──── POST /open/v1/order/refund ──────────▶│
   │      {out_uid, out_order_id, seq}         │  ② 扣回当时发的积分
   │                                           │     （扣回额 = 发出积分 − 已释放消耗）
   │                                           │  ③ 这笔让利从释放基数中剔除
   │◀─── {code:0} ─────────────────────────────┤     ⇒ 不再参与后续发券

注意事项

• 不接这个接口 = 白送积分。退款场景务必实现。
• 退款后可再用 order/query 看到该笔的 back_status = stop（已作废）。

C.4 场景四：券自动释放到账（平台侧行为，贵司无需实现）

   平台定时任务（按商家配置的周期自动跑）
   ┌────────────────────────────────────────────────┐
   │ ① 出批：计算本批可释放额度                       │
   │ ② 结算：生成派发明细                            │
   │ ③ 发券：扣积分 + 发券（券额÷5 = 扣的积分；即 1 积分 = 5 元券） │
   │    ⇒ 会员侧现象：积分减少、券增加                 │
   └────────────────────────────────────────────────┘

贵司唯一要做的事：在展示"我的券"时调 member/balance 拿最新余额； 不要轮询上报接口去等券到账。

附录 D、集成问题排查手册（按现象查）

附录 E、curl / Postman 快速验证集合

把 APPID / SECRET 换成 §2.2 的沙箱账号即可直接跑。签名算法见 §4.3。

# ===== 公共变量 =====
BASE="https://a.jetu.cc"
APPID="bfop261012c8ab974b60"
SECRET="bab2b513dee1dd7e65ad75804f1bb84f7ef50a1e96fd956b"

# ===== 签名函数（bash + openssl）=====
# sign <appid> <timestamp> <nonce> <rawBody> <secret>
sign() {
  local s1="${1}\n${2}\n${3}\n"
  local bodyHash=$(printf '%s' "${4}" | openssl dgst -sha256 -hex | awk '{print $2}')
  printf "${s1}${bodyHash}" | openssl dgst -sha256 -hmac "${5}" -hex | awk '{print $2}'
}

# ===== 1) 取令牌 =====
TS=$(date +%s); NONCE=$(openssl rand -hex 8)
BODY="{\"appsecret\":\"${SECRET}\"}"
SIGN=$(sign "$APPID" "$TS" "$NONCE" "$BODY" "$SECRET")
TOKEN=$(curl -s -X POST "${BASE}/open/v1/auth/token?appid=${APPID}&timestamp=${TS}&nonce=${NONCE}" \
  -H "X-Open-Sign: ${SIGN}" -H "Content-Type: application/json" -d "${BODY}" \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["access_token"])')
echo "TOKEN=${TOKEN}"

# ===== 2) 连通性自检 =====
TS=$(date +%s); NONCE=$(openssl rand -hex 8)
SIGN=$(sign "$APPID" "$TS" "$NONCE" "" "$TOKEN")
curl -s "${BASE}/open/v1/ping?appid=${APPID}&timestamp=${TS}&nonce=${NONCE}" \
  -H "X-Open-Sign: ${SIGN}" -H "X-Open-Token: ${TOKEN}"

# ===== 3) 绑定会员 =====
TS=$(date +%s); NONCE=$(openssl rand -hex 8)
BODY='{"out_uid":"DEMO-001","phone":"13800001234"}'
SIGN=$(sign "$APPID" "$TS" "$NONCE" "$BODY" "$TOKEN")
curl -s -X POST "${BASE}/open/v1/member/bind?appid=${APPID}&timestamp=${TS}&nonce=${NONCE}" \
  -H "X-Open-Sign: ${SIGN}" -H "X-Open-Token: ${TOKEN}" -H "Content-Type: application/json" -d "${BODY}"

# ===== 4) 上报消费（让利 20 元 = 2000 分）=====
TS=$(date +%s); NONCE=$(openssl rand -hex 8)
BODY='{"out_uid":"DEMO-001","out_order_id":"DEMO-ORD-001","seq":1,"profit":2000,"order_amount":20000}'
SIGN=$(sign "$APPID" "$TS" "$NONCE" "$BODY" "$TOKEN")
curl -s -X POST "${BASE}/open/v1/order/consume?appid=${APPID}&timestamp=${TS}&nonce=${NONCE}" \
  -H "X-Open-Sign: ${SIGN}" -H "X-Open-Token: ${TOKEN}" -H "Content-Type: application/json" -d "${BODY}"

# ===== 5) 查余额（积分应为 20）=====
TS=$(date +%s); NONCE=$(openssl rand -hex 8)
SIGN=$(sign "$APPID" "$TS" "$NONCE" "" "$TOKEN")
curl -s "${BASE}/open/v1/member/balance?appid=${APPID}&timestamp=${TS}&nonce=${NONCE}&out_uid=DEMO-001" \
  -H "X-Open-Sign: ${SIGN}" -H "X-Open-Token: ${TOKEN}"

# ===== 6) 按单号查处理结果 =====
TS=$(date +%s); NONCE=$(openssl rand -hex 8)
SIGN=$(sign "$APPID" "$TS" "$NONCE" "" "$TOKEN")
curl -s "${BASE}/open/v1/order/query?appid=${APPID}&timestamp=${TS}&nonce=${NONCE}&out_order_id=DEMO-ORD-001" \
  -H "X-Open-Sign: ${SIGN}" -H "X-Open-Token: ${TOKEN}"

Postman 环境变量（导入后只需改 TOKEN）：

附录 F、服务等级与技术支持

F.1 服务指标（生产环境）

F.2 技术支持渠道与响应时间

报障请务必提供：request_id、appid、out_order_id、发生时间、完整请求与响应。 有了 request_id，我们能在调用日志里精确定位到那一次请求（含请求参数、返回、耗时）。

F.3 联调支持

F.4 数据与安全

F.5 接口变更策略

• 接口只增不改：已发布的接口路径、参数语义、返回字段含义不会变更。
• 允许新增：新错误码、新接口、响应中新增字段（贵司应有忽略未知字段的容错）。
• 如需破坏性变更：提前 30 天书面通知，并提供并行过渡期（新旧版本同时可用）。
• 文档每次变更都在「变更记录」中留痕，并更新版本号。

十五、变更记录

契约承诺：签名规则、错误码语义一经发布不再变更，只允许新增错误码或接口；如有必要变更，提前 30 天书面通知并提供并行过渡期。