邦斧积分消费券 · 开放平台对接方案

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

面向：接入方（贵司）技术与业务负责人

配套文档：接口文档 · 端到端对接演练记录

一、一句话说清这套系统

贵司的商城、订单、支付、会员体系全部留在贵司；邦斧只提供一个东西：

一套「消费让利 → 变为消费券 → 下笔消费抵扣」的锁客资产体系。

具体说，邦斧负责两件事：

邦斧负责说明
记账每个会员身上有多少「积分」、有多少「可用券」
发券按规则把商家的让利额，分期变成会员手上的消费券

贵司不需要搬到邦斧来，也不需要改动自己的会员体系。贵司只需要在几个关键节点"通知"邦斧一声（用户绑定了、下单成功了、退款了、要抵扣了），邦斧负责把资产算对、记对。

二、★★ 核心技术：其实只有一个概念要理解

很多对接方卡住，不是卡在技术，而是卡在这个资产模型没理解透。所以先说这个 —— 只要这一段看懂了，接口就是顺手的事。

2.1 这套系统的核心机制（一张图）

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

2.2 三个必须记住的数字

关系数值含义
让利额 ↔ 积分1 元 = 1 积分让利 20 元 ⇒ 立刻得 20 积分
积分 ↔ 券1 积分 = 5 元券所以 20 积分理论上最多能释放出 100 元券
券 ↔ 抵扣1 元券 = 1 元抵扣券是"能直接花掉的钱"，积分只是"待释放的额度"

2.3 为什么这么设计？（这是客户最该理解的一点）

问题：如果让利一进来就全额变券，商家当月现金流压力大，用户也可能拿了券就走去别家。

所以设计成"分期释放"：

再看一个更直观的例子（20 元让利、每天一批、每批释放 50%）：

批次池中释放用户积分用户券说明
下单当时—200让利入池 + 发等额积分
第 1 批10 元20 − 2 = 1810 元扣 10÷5 = 2 积分
第 2 批5 元18 − 1 = 1715 元扣 5÷5 = 1 积分
第 3 批2.5 元17 − 0.5 = 16.517.5 元持续释放…

关键洞察：用户的积分在减少、券在增加。积分是"还没兑现的额度"，券才是"到手能花的钱"。

2.4 三个常见误解（提前澄清，省掉来回沟通）

常见误解实际情况
❌ "我报订单金额"✅ 报的是让利额（profit），即你愿意拿出多少钱做锁客
❌ "积分能当钱花"✅ 积分不能抵扣任何消费，只有券能抵扣；积分只是释放券的额度
❌ "报了要等邦斧回调通知我"✅ 邦斧不做回调。接口同步返回，返回成功即已记账；想确认结果用查询接口

2.5 技术层面：为什么说"不难"

避开术语说，这套对接在技术上是最省事的那种：

项情况对你的好处
接口形态标准 HTTPS + JSON（RESTful）任何语言都能调，无需装 SDK
鉴权HMAC-SHA256 签名 + 访问令牌业界最通用做法，你方后端 20 行代码搞定
回调/消息队列完全没有不用写回调验签、不用处理乱序重复、不用做状态机
异步处理完全没有每个接口都是同步的，返回即结果
你需要实现的只在 6 个业务节点 调我们的接口（见第五节）20 个接口，你实际必接的只有 6~8 个

一句话：你要做的是「在你方商城的几个节点上，多调一次 HTTP 接口」。没有中间件、没有 SDK、没有回调。

三、责任边界（谁做什么）

事项邦斧贵司
商城、订单、支付、退款—✅ 全部在贵司
会员账号体系（登录、注册、资料）—✅ 全部在贵司
积分与券的记账、计算、发放✅ 邦斧负责—
会员身份映射（你的用户 ID ↔ 邦斧会员号）存映射传 out_uid 即可
页面展示（我的积分/我的券）提供数据✅ 贵司自己画
券的抵扣动作提供核销接口在贵司结算流程里调用
定时释放券（周期跑批）✅ 邦斧自动跑，你无需关心—
数据安全与个人信息合规提供合规接口执行合规要求

★ 注意：贵司不需要在邦斧注册任何会员。邦斧会给每个映射过来的会员自动开一个「账本账户」——只用来存积分和券，不带邀请关系、不进任何分销体系。

四、实现路径（分 5 个阶段，按顺序做）

阶段 1 · 拿到凭证并打通链路（0.5 天）

步骤你做什么验收标准
1.1领取 appid + appsecret拿到两个值，存进你的配置（不要写死在代码里）
1.2实现签名算法（HMAC-SHA256，见文档 §4）用文档 §4.4 给的自检数据验通（务必先验这一步，能省掉后面 80% 的疑难）
1.3调 auth/token 换令牌拿到 access_token
1.4调 ping返回 code=0，说明签名、网络、IP 白名单全都通了 ✅

阶段 1 的产出：一条打通的链路。只要 ping 通了，后面全是顺水推舟。

阶段 2 · 会员映射（1 天）

步骤你做什么
2.1在你方用户首次进入与积分相关的页面时，调 member/bind 把用户映射过来
2.2调 member/profile、member/balance 拿资料和余额
2.3在你方的「我的积分 / 我的券」页面展示这两个数

验收标准：你方页面上能显示一个真实用户的积分与券余额（初始都是 0）。

★ 建议在你方首次需要时再绑定（懒绑定），不要一次性全量导。

阶段 3 · 打通主流程：消费上报（2 天）★ 最关键

步骤你做什么
3.1在你方订单支付成功的流程里，调 order/consume 上报让利额
3.2让利额由你方决定（例如订单金额的 5%~20%），按实付金额算
3.3out_order_id 用你方真实订单号（不是随机串！）—— 重复上报靠它去重
3.4处理返回：code=0 即成功；网络超时就用同一个订单号重发（有幂等保护，不会重复记账）

验收标准：你方测试用户下单后，邦斧侧能看到积分到账（1 元让利 = 1 积分）。

★★ 这一步是整个方案的心脏。做通了它，剩下的都是锦上添花。

阶段 4 · 券的生命周期（2~3 天）

步骤你做什么对应接口
4.1等你方测试用户手上的券到账（平台按周期释放，或让邦斧临时把周期改成 1 天来加速联调）—
4.2用户结算时选「用券抵扣」⇒ 你方调核销接口扣券coupon/verify
4.3订单取消/退款 ⇒ 把券退回coupon/unverify
4.4（可选）做「送券给好友」入口coupon/transfer

验收标准：券能扣、能退，余额前后对得上。

阶段 5 · 退款与对账（1~2 天）

步骤你做什么对应接口
5.1你方订单退款时通知邦斧（扣回积分 + 把这笔从释放基数剔除）order/refund
5.2做日常对账：拉会员列表 + 各自资产，与你方数据核对member/list
5.3确认结果用按单号查（不必重发）order/query
5.4看自己的调用量与账单billing/usage

验收标准：能从你方系统独立核对出「每个会员的积分与券」，且与邦斧侧一致。

预计总工期：约 6~8 个工作日（1 名后端 + 少量前端）。

五、对接接口清单（20 个，但你只需重点关注前面 8 个）

5.1 ★ 必接（6 个）—— 不做就不完整

#接口什么时候调说明
1POST auth/token服务启动 / 令牌过期前换访问令牌（有效期 2 小时），复用不要每个请求都换
2GET ping联调第一件事连通性自检
3POST member/bind用户首次进入积分相关页面建立你的用户 ID ↔ 邦斧会员映射
4GET member/balance展示余额时拿积分与可用券
5POST order/consume订单支付成功后上报让利额 → 入池 + 发积分
6POST coupon/verify用户用券抵扣时扣券

5.2 ★ 强烈建议接（4 个）

#接口什么时候调说明
7POST order/refund订单退款时扣回积分 + 入池作废（不接会白送积分）
8POST coupon/unverify用了券的订单取消时把券退回给用户
9GET order/query上报超时/对账时按单号主动查处理结果（只读，无副作用）
10GET member/profile展示会员信息时已脱敏，合规要求

5.3 可选（10 个）—— 按业务需要

#接口用途
11GET member/list批量对账（会员多时用）
12GET integral/logs积分明细页
13GET coupon/balance只要券余额
14GET coupon/logs券明细页
15POST coupon/transfer会员间转赠（默认关闭，商户后台可开）
16POST integral/adjust客服补分/扣分（默认关闭）
17GET pool/summary看你还有多少让利在池子里待释放
18GET billing/usage看自己的调用量与账单
19POST member/data-request个人信息查询/删除（合规通道，删除=匿名化，默认关闭）
20POST member/unbind解除映射

★ 完整参数、错误码、示例见接口文档（含每个接口的参数速查表）。

六、三个核心业务场景的调用时序

场景 A：用户下单并支付成功

你方商城                        邦斧开放平台
   │                                │
   │  订单支付成功                   │
   ├─────── POST order/consume ────▶│  ① 让利额入池
   │        {out_uid, out_order_id, │  ② 发等额积分
   │         seq, profit,           │
   │         order_amount}          │
   │◀────── {code:0, record_id} ────┤  同步返回，已记账
   │                                │
   │  （后续平台按周期自动释放成券，你无需做任何事）

场景 B：用户结算时用券抵扣

   │  BEFORE: GET member/balance   │  先查可用券（别让用户点超了）
   │◀──── {coupon_usable_cents} ───┤
   │                                │
   │  用户勾选「用券抵扣 5 元」       │
   ├─────── POST coupon/verify ────▶│  扣券
   │        {out_uid, amount:500,   │
   │         out_order_id}          │
   │◀────── {code:0} ───────────────┤
   │                                │
   │  若订单后来取消/退款：           │
   ├─────── POST coupon/unverify ──▶│  把券退回

⚠️ 余额不足会直接返回错误（40205），不会自动截断。所以要先查余额再决定能抵多少。

场景 C：订单退款

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

七、联调怎么开始（照这个顺序，别跳步）

步动作通过标志
1我们给你沙箱环境的 appid/secret拿到凭证
2你用文档 §4.4 的自检数据验签名算法算出的签名与文档一致
3调 pingcode=0 ✅ 这一步过了，链路就通了
4调 member/bind 绑一个测试用户返回 mid
5调 order/consume 报一笔测试消费积分到账
6我们临时把释放周期调成 1 天，让你不用等券到账，能看到「积分减少、券增加」
7调 coupon/verify 扣券、coupon/unverify 退回余额前后对得上
8调 order/refund 退款积分被扣回
9做一次对账：member/list 对比你方数据两边数字一致 ✅

沙箱合格标准：贵司能在一个工作日内独立跑完上面 9 步、不需要求助 → 就可以切正式环境了。

八、你们会关心的几个问题（先答）

问题答
要不要搬系统到邦斧？不用。贵司商城、订单、支付、会员全部原样保留
贵司会员要先在邦斧注册吗？不用。邦斧用「账本账户」自动承载，不带邀请关系
积分能提现吗？不能。但可以转赠（是否开放由商户后台自己配置，默认关闭）
券有有效期吗？当前没有设有效期（如业务需要可另议）
要写回调吗？不用，邦斧不做回调，全部同步返回
重复上报会不会记两笔？不会。同一订单号+序号会返回首次结果（幂等保护）
贵司白标（用户看不到邦斧）？可以。消费者侧页面由贵司自己画，邦斧只提供数据
我们改规则会不会影响历史数据？不会。每笔业务都固化了当时的规则快照，事后再改配置不影响已发生的账
合作终止了数据怎么办？全部数据可导出交付给贵司（流式 CSV，含资产负债表与全量流水）
个人信息合规怎么做？提供合规接口：查询 / 删除（删除 = 匿名化，不可逆）。手机号、姓名、地址默认已脱敏

九、需要贵司确认的 4 个业务口径

这几项会直接影响接口调用方式，请在开工前确认：

#口径选项建议
1让利比例按订单实付金额的百分比（如 5% / 10% / 15%）建议先小比例试跑
2释放周期每几天一批、每批释放池子的百分比沙箱可设 1 天加速联调
3券能否转赠默认关闭，需要就开有社交玩法可开
4前端页面谁做我方做 H5 / 贵司自己做建议贵司自己做（与你方风格统一；我方做则你方小程序需重新提审一次）

十、附：本方案的技术资料索引

资料用途
接口文档开发同事看这个：全部 20 个接口的参数、返回、错误码、多语言签名实现、参数速查表
端到端对接演练记录业务同事看这个：用真实接口跑一遍完整业务闭环，每步的请求/返回/资产变化都有
沙箱环境凭证联调用（由我方单独提供）

_本方案描述的能力已在测试环境完成端到端验证（含账目全闭合核对）。文中所有金额、数字均为可复现的真实运行结果。_