霸王餐渠道开放接口接入说明

渠道方通过 HTTP + 签名接口查询活动、报名下单、回填外卖单号、上传凭证，并通过 Webhook 接收订单状态变化。用户侧返利与渠道分润由渠道方自行处理，我方向渠道收取渠道服务费并按单结算渠道入账金额。
配套文档：接口安全（凭证、签名、响应码）、订单通知（Webhook 报文与验签）。各接口的完整出入参字段见我方提供的 Apifox 接口文档。

一、接入方式与分工

角色	职责
渠道方	展示活动、创建渠道侧订单、调用接口报名/回填/上传凭证、接收 Webhook、向用户返利
我方	提供活动与门店数据、受理报名与履约、推送订单状态、计提渠道服务费并结算渠道入账金额

渠道单不进入我方用户账户体系，渠道侧用户以 channelUserId 留存；用户侧返利由渠道方负责。

所有状态变化通过 Webhook 推送，无其它通知渠道。

二、主流程：报名到完成

Auto 模式无需上传凭证，系统自动核销；订单同样要回填外卖单号，审核通过时可能直接从 20 推进到完成（跳过 30）。

三、接口一览

步骤	方法与路径	说明
连通性自测	GET `/openapi/bwc/ping`	回显 appId 与服务器时间
活动列表	GET `/openapi/bwc/activity/search`	门店维度，一店多活动内嵌；可按坐标/类目/返利模式/排序筛选；`mobile` 必填
类目字典	GET `/openapi/bwc/activity/categories`	固定闭集，用于筛选栏
活动详情	GET `/openapi/bwc/activity/detail`	`rebateMode`、`activityId`、`mobile` 必填
报名下单	POST `/openapi/bwc/order/apply`	幂等键 `channelCode + channelOrderNo`；`mobile` 必填
报名单搜索	GET `/openapi/bwc/order/search`	按渠道侧单号/状态/时间范围分页
报名单详情	GET `/openapi/bwc/order/detail`	校验单归属，非本渠道单返回 301
取消报名	POST `/openapi/bwc/order/cancel`	仅 10 / 20 可取消
回填外卖单号	POST `/openapi/bwc/order/submitTakeoutNo`	外卖单号必须为纯数字
上传凭证	POST `/openapi/bwc/order/submitVoucher`	仅 20 / 30 可提交

查询类接口一律 GET、动作类接口一律 POST，所有接口都需携带公共签名参数，详见接口安全。

四、用户身份（mobile）

activity/search、activity/detail、order/apply 都必须传 mobile（渠道侧用户手机号，11 位明文）。

活动数据按用户身份下发，同一坐标不同手机号返回结果可能不同；报名也按该手机号提交。列表 → 详情 → 报名须传同一个号码，否则查到的活动可能报名失败。

缺失或格式非法返回 code=3 参数(mobile)错误；mobile 参与签名计算。

五、返利模式

rebateMode	含义	渠道需做的事
`Auto`	自动返利，无需上传截图	报名 + 回填外卖单号，等待自动核销
`Manual`	手动返利，需上传截图	报名 + 回填外卖单号 + 调用 `submitVoucher` 上传消费凭证

activity/search、activity/detail、order/search、order/detail 返回体都带 rebateMode，据此决定走哪条流程。

activity/detail 的 rebateMode 必填，非法值返回 301；activity/search 的 rebateMode 为可选筛选，不传或非法等同不筛选。

返利模式在报名时固定，后续查询按单返回，不会因配置变化而改变；历史单可能返回 null，需容错。

六、订单状态

6.1 状态定义

status	枚举名	含义	终态
10	`Registered`	已报名	否
20	`Submitted`	已提单	否
30	`PendingReview`	待审核	否
40	`Completed`	已完成	否
50	`Rebated`	已完成（已结算）	是
-1	`Cancelled`	已取消	是

40 与 50 对渠道方含义相同，都表示该单已完成并通过审核，渠道方按“已完成”处理即可。
接口响应中的 status 为枚举名字符串；Webhook 报文中的 status 为整数。两种载体格式不同，请勿混用。

6.2 状态流转

状态只前进不回退，回退事件被忽略。

同状态重复回调按幂等处理，只刷新原因，不重复推送事件（扣款事件除外）。

-1 是终态，取消后不会因后续回调而恢复。

6.3 各状态允许的操作

当前状态	可取消	可回填外卖单号	可上传凭证
10 已报名	是	是	否
20 已提单	是	是（重复同步）	是
30 待审核	否	是（仅更新单号，状态不回退）	是（驳回后重提）
40 / 50	否	否	否
-1 已取消	否	否	否

操作不满足时返回 code=300，可先调 order/detail 刷新状态再决定是否重试。

七、异常分支

取消：渠道调用 order/cancel（仅 10 / 20）或订单超过有效期，均置 -1 并推送 ORDER_CANCELED，reason 为取消原因（渠道未传时为「渠道取消」）。取消后已完成的结算不受影响。

驳回：订单停留在 30 待审核并写入驳回原因，推送 ORDER_REJECTED；渠道可再次调用 submitVoucher 提交新凭证，可多次重提。若订单早已处于 30，同状态驳回刷新不会再推送事件，请以 order/detail 的 reason 为准。

扣款：已完成订单被扣款时，状态与结算均不回滚，仅追加 reason（前缀 [扣款]）并推送 ORDER_DEDUCTED。渠道收到后应暂停或调整对该用户的返利，具体以双方商务约定为准。

超时：报名单有效期由我方按规则设定，到期未推进自动关闭（状态 -1 + ORDER_CANCELED）。不要依赖超时关单做业务兜底：请自行监控长时间停留在 10 / 20 的订单，主动取消后重新报名。

八、服务费与结算

项目	说明
服务费率	渠道维度配置，万分比（`commissionRate`，500 = 5%）
单笔封顶	`commissionCap`，单位分，0 表示不限
渠道服务费	`commissionAmount` = 结算额 × 服务费率（有封顶取较小值），单位分；报名时快照，之后不变
渠道入账金额	`channelAmount` = 结算额 − 渠道服务费，单位分，进入渠道霸王餐余额账户
入账时点	订单完成时入账，重复完成回调不重复入账
结算方式	渠道账户按约定周期结算，流水可向我方查询

服务费率为 0 表示不收费，报名照常（服务费为 0，入账金额等于结算额）；费率为负或渠道未开通返回 301，不存在默认值兜底。

报名、详情、搜索响应中的 commissionRate / commissionCap / commissionAmount / channelAmount 即该单最终结算口径，可与 Webhook 报文对账。

九、通用约定

报名幂等：同一 channelOrderNo 重复调用 order/apply 返回首次创建的单据，不会重复报名。

以查询为准：Webhook 异步且可能重试、乱序。判定最终态请以 order/detail 或 order/search 的实时结果为准，Webhook 仅作驱动。

分页：page 从 0 起，size 1~100（默认 20，超过按 100 处理）。

单位：所有金额字段单位为分；接口响应时间字段为 yyyy-MM-dd HH:mm:ss（GMT+8），Webhook 报文时间为毫秒时间戳。

业务流程

霸王餐渠道开放接口接入说明#

一、接入方式与分工#

二、主流程：报名到完成#

三、接口一览#

四、用户身份（mobile）#

五、返利模式#

六、订单状态#

6.1 状态定义#

6.2 状态流转#

6.3 各状态允许的操作#

七、异常分支#

八、服务费与结算#

九、通用约定#