邦斧开放平台 · 端到端对接演练记录

本页性质：研发内部验证记录，用于展示接口的真实输入输出行为与账目闭合过程。数字取自验证环境（非生产数据），便于接入方理解接口语义。

生成时间：2026-10-12 18:07:32

环境：研发内部验证环境（对外接口 https://a.jetu.cc/open/v1）

说明：全部步骤都是真实调用真实接口，资产数字每次从库里读真值（不看接口自述），最后做会计恒等式核对。

第 0 步 · 环境准备

• 接入方：新建（正式接入方，非沙箱）
• 会员：新建账本账户（对方会员体系在你方，无需先来邦斧注册）
• 商家奖励池：开启周期释放（每 1 天一批）

拿到凭证：appid=<演练用临时 appid，已失效> 、appsecret=******（仅创建时可见一次）

第 1 步 · 取访问令牌（POST /open/v1/auth/token）

接入方要做的：用 appsecret 换 access_token（有效期 2 小时），后续业务接口都带这个令牌。

POST /open/v1/auth/token?appid=<演练用临时 appid，已失效>&timestamp=1791799653&nonce=<随机串>
X-Open-Sign: <HMAC-SHA256 签名>

• HTTP 200 · code=0
• 返回：access_token=<前 12 位>e481fb...（日志里不落令牌，只留前 12 位）、有效期 7200 秒

★ 令牌到点会失效，请提前刷新并复用，不要每个请求都重新签发（会浪费一次调用额度）。

第 2 步 · 连通性自检（GET /open/v1/ping）

接入方要做的：代码写完第一件事打这个接口，确认签名算法、网络、白名单都通。

• HTTP 200 · code=0 · msg=pong
• 返回：appid / 限流额度 600 次每分钟 / 已用 2

第 3 步 · 绑定你方会员（POST /open/v1/member/bind）

接入方要做的：把你方会员体系的用户 ID（out_uid）与邦斧的会员 ID 建立一一映射。 为什么需要：积分和券记在邦斧侧的会员身上，out_uid 就是你方唯一的锚点。

POST /open/v1/member/bind   {"out_uid":"U-1001","phone":"138****4177"}

• HTTP 200 · code=0 · 邦斧会员号 mid=41452
• ★ 你方会员没在邦斧注册也没关系：自动开一个「账本账户」（只持有积分和券，不建邀请关系、不进分销体系）

• 再绑一个会员 U-1002 ⇒ mid=41453（后面演示转赠要用）

第 4 步 · 查会员资料与余额（member/profile、member/balance）

接入方要做的：在你方的会员中心展示这些数（积分、可用券）。

• GET member/profile?out_uid=U-1001 ⇒ HTTP 200 · code=0
• 返回：手机号 ?、昵称 ``
• ★ 默认已脱敏（手机号前 3 后 4、姓名首字）—— 这是合规要求，不要把完整明文给到前端

• GET member/balance?out_uid=U-1001 ⇒ code=0
• 积分 0.0000 · 可用券 0.00 元（单位：分 ⇒ 0）
• 刚刚绑定，所以都是 0 —— 接下来上报一笔消费就变了

第 5 步 · ★ 上报一笔消费（POST /open/v1/order/consume）—— 核心机制的起点

接入方要做的：你方商城用户下单付款成功后，把订单让利额报给邦斧。

★★ 这是整套方案最关键的一个概念，请务必理解：

传的是「让利额」（profit），不是订单金额。让利额 = 你愿意拿出多少比例来换锁客。

例如订单 200 元、你让利 10% ⇒ profit=2000（单位分）。

邦斧拿这个让利额做两件事：①入池（等平台按周期释放成券）②发等额积分（1 元让利 = 1 积分）。

POST /open/v1/order/consume
{"out_uid":"U-1001","out_order_id":"SO-20261012-0001","seq":1,"profit":2000,"order_amount":20000}

• HTTP 200 · code=0 · msg=ok（已入池，释放按本商家既有的周期与比例自动进行）
• 返回：入池记录 record_id=90864（此笔让利已进入商家奖励池）
• 其中发出的积分：20（从库里读到，1 元让利 = 1 积分）

此刻会员资产（库里真值）：积分 20.0000 · 券 0.00 元 ⇒ 让利 20 元 ⇒ 积分 +20（1 元让利 = 1 积分，一一对应）；券还是 0（券要等释放周期）

★ 这一步是同步返回的：返回成功就代表已经记账，不需要等回调（本平台不做回调）。

第 6 步 · 按业务单号查处理结果（GET /open/v1/order/query）

接入方要做的：上报超时/不确定结果时，用你方订单号主动查，只读、无副作用。

• GET order/query?out_order_id=SO-20261012-0001 ⇒ code=0
• found=true · 事件 1 条 · 入池 20.00 元
• 入池状态：有效（会参与后续释放）
• 处置提示：已查到处理记录。重复提交同一单号会返回这份同样的结果，不会重复记账。

★ 查不到不等于失败（可能还在路上）。此时正确做法是用同一个单号重发（有幂等保护，不会重复记账），不要换新单号。

第 7 步 · ★★ 平台释放周期到了 —— 积分减少、券增加（核心机制的落地）

这一步不需要接入方做任何事，是邦斧的定时任务按商家配置的周期自动跑的。 下面把它真实跑一遍给你看。

★★ 为什么有这个环节：让利额先「入池」，平台按周期分批释放，释放时扣掉一部分积分、发对应金额的券。

换算关系：5 积分换 1 元券（所以 1 积分最多能释放出 5 元券）。

这就是为什么「积分本身不能抵扣消费，只有券能抵扣」—— 积分是待释放的额度，券才是能花掉的钱。

• 奖励池当前累计让利：20.00 元（= 这笔入池的 20.00）
• ① 出批（ApiAsynCallback::businessAutoRelease）⇒ HTTP 200
• 本批可释放基数 max_back_amount=20.00 · 本批释放 back_amount=20.00 元
• ② 结算（ApiAuto::settleStageBack）⇒ HTTP 200 · 生成派发明细 id=3768484
• ③ 发券（既有发券函数 settleBugSmallDeductionMoneyForty）⇒ 执行成功

释放前后对比（库里真值）

⇒ 积分 −4.0000、券 +20.00 元 ⇒ 换算式：每消耗 1 积分释放出 5.00 元券（20.00 元 ÷ 4.0000 积分 = 5.00） ⇒ 反过来说：5 积分换 1 元券；所以一个会员持有多少积分，就决定了他最多还能拿到多少券（积分 × 5 = 券上限）

★★ 这就是核心机制的一句话：让利入池 → 释放时扣积分、发券 → 券才能抵扣。

第 8 步 · 查券与积分流水（coupon/logs、integral/logs）

接入方要做的：做对账、做你方的资产明细页。

• GET coupon/balance?out_uid=U-1001 ⇒ code=0 · 可用券 20.00 元（= 2000 分）
• GET coupon/logs?out_uid=U-1001 ⇒ code=0 · 1 条
• 2026-10-12 18:07:35 · 增加 20.00 元 · 余额 20.00 · 平台结算用户下单抵用券
• GET integral/logs?out_uid=U-1001 ⇒ code=0 · 2 条
• 2026-10-12 18:07:35 · 减少 4.0000 积分 · 余额 16.0000 · 抵用券结算扣除积分
• 2026-10-12 18:07:33 · 增加 20.0000 积分 · 余额 20.0000 · 开放平台上报消费获得

第 9 步 · 用券抵扣（POST /open/v1/coupon/verify）

接入方要做的：你方商城用户结算时选了「用券抵扣」，你方在我们这边核销对应金额。

• 核销 5.00 元 ⇒ HTTP 200 · code=0
• 券余额：20.00 → 15.00 元

★ 余额不够会直接拒绝（40205），不会自动截断 —— 你方要先按余额判断能不能抵扣。

第 10 步 · 订单取消 ⇒ 券回退（POST /open/v1/coupon/unverify）

接入方要做的：你方订单取消/退款时，把刚核销的券退回去。

• 回退 ⇒ code=0 · 券余额：15.00 → 20.00 元

第 11 步 · 会员之间转赠券（POST /open/v1/coupon/transfer）

接入方要做的：给会员做一个「送给好友」入口。券不支持提现，但支持转赠； 是否开放转赠由商户后台自己配置（默认关闭）。

• 转赠 5 元（本商家内） ⇒ code=0 · msg=ok（转赠成功；不支持提现，仅可在本商家内使用或继续转赠）
• U-1001：20.00 → 15.00 元
• U-1002：0.00 → 5.00 元

★ 守恒：转出方减少的 = 接收方增加的（后面账目核对会验这个）。

第 12 步 · 你方直接发券（POST /open/v1/coupon/grant）

接入方要做的：活动/补偿/客服场景，直接给会员发券（有单笔与单日上限风控）。

• 发 10 元 ⇒ code=0 · data.granted_cents=1000
• ★ 风控：单笔默认上限 1000 元（40214）、单日累计默认上限 10000 元（40215），超限直接拒

第 13 步 · 退款（POST /open/v1/order/refund）—— 扣回积分 + 入池作废

接入方要做的：你方订单退款时通知邦斧，邦斧会 ①扣回当时发的积分 ②把这笔从释放基数里剔除。

• 退款第 5 步那笔消费 ⇒ code=0
• 积分：16.0000 → 0.0000（扣回 = 当时发出 20 − 已释放消耗掉的）
• 这笔的入池状态：已因退款作废（不再参与释放） ⇒ 不再参与后续释放

第 14 步 · 积分人工调整（POST /open/v1/integral/adjust，默认关闭）

接入方要做的：客服补分/扣分。默认关闭，需平台后台开启并设单笔上限。

• 加 5 积分 ⇒ code=0 · msg=ok（未开启时返回 40207）

第 15 步 · 奖励池概览（GET /open/v1/pool/summary）

接入方要做的：在你方后台显示「还有多少让利在池子里等着释放」。

• code=0 · 返回：{"bid":1777,"exists":1,"pool_balance":"0.0000","pending_intake":"0","surplus":"0.00","history_intake":"20.0000","history_reward":"20","batch_count":1,"last_release_time":"2026-10-12 18:07:35","release_pool_day":1,"release_pool_rate":100,"deduct_dec_rate":20,"exchange_rate":"5","release_active_months":0,"release_pool":1,"current_pool":"0.0000","history_pool":"20.0000","field_map":{"current_pool(=pool_balance)":"池余额 = 待入池 + 上批剩余（后台页面显示的这个数）","history_pool(=history_intake)":"历史入池累计量（只增不减，不是可用余额）","history_reward":"累计已释放（后台页面的「历史已释放」）","batch_count":"已出批次数（后台页面的「共 N 批」）"},"note_pool_balance":"池余额 = 待入池 + 上批未释放剩余（当前可释放的部分）","note_history_intake":"历史入池总额是只增不减的累计量，不是可用余额","note_release":"释放由本商家既有机制自动进行：每 1 天出批一次，按 100% 释放；兑换比例 5（1 积分最多释放 5 元券）","amount_unit":"元"}

第 16 步 · 会员列表（GET /open/v1/member/list）—— 批量对账

• code=0 · 本接入方会员共 2 人
• U-1002 (mid=41453) · 积分 0.0000 · 可用券 15.00 元
• U-1001 (mid=41452) · 积分 5.0000 · 可用券 15.00 元

★ 只回本接入方名下的会员；不回姓名/手机号（个人信息最小化）。

第 17 步 · 本期用量与账单（GET /open/v1/billing/usage）

• code=0 · 账期 2026-10
• 请求数 21 · 成功 20 · 失败 1 · 幂等重放 0（不计费） · 计费调用 20

第 18 步 · 个人信息合规通道（POST /open/v1/member/data-request）

接入方要做的：会员要求「查我的数据/删我的数据」时调这个接口。删除 = 匿名化（不可逆，默认关闭）。

• 查数据 ⇒ code=0

第 19 步 · 解绑（POST /open/v1/member/unbind）

• 解除 U-1002 的映射 ⇒ code=0

★ 最后 · 账目核对（会计恒等式）

一份完整的对接必须能对得上账。下面每一条都是独立 SQL 复算，不采信接口自述：

核对结论：✅ 三条核心恒等式全部闭合 —— 账目对得上

接口覆盖清单（本演练实际调用）

• 1. /open/v1/auth/token ✅ 本演练已调
• 2. /open/v1/ping ✅ 本演练已调
• 3. /open/v1/member/bind ✅ 本演练已调
• 4. /open/v1/member/unbind ✅ 本演练已调
• 5. /open/v1/member/list ✅ 本演练已调
• 6. /open/v1/member/profile ✅ 本演练已调
• 7. /open/v1/member/balance ✅ 本演练已调
• 8. /open/v1/member/data-request ✅ 本演练已调
• 9. /open/v1/order/consume ✅ 本演练已调
• 10. /open/v1/order/refund ✅ 本演练已调
• 11. /open/v1/order/query ✅ 本演练已调
• 12. /open/v1/integral/logs ✅ 本演练已调
• 13. /open/v1/integral/adjust ✅ 本演练已调
• 14. /open/v1/coupon/balance ✅ 本演练已调
• 15. /open/v1/coupon/logs ✅ 本演练已调
• 16. /open/v1/coupon/grant ✅ 本演练已调
• 17. /open/v1/coupon/verify ✅ 本演练已调
• 18. /open/v1/coupon/unverify ✅ 本演练已调
• 19. /open/v1/coupon/transfer ✅ 本演练已调
• 20. /open/v1/pool/summary ✅ 本演练已调
• 21. /open/v1/billing/usage ✅ 本演练已调

合计 21 个接口（其中只读查询类 10 个）。

_本记录由验证环境真实执行生成；演练数据已清理，商家配置已还原。_