中国道商户接入中心

1. 接口定位

结论：这些接口是“对授权商户开放的外部能力”，但不是给普通 C 端用户裸调。C 端用户在商户页面付款，商户确认收款后再通过 SDK/OpenAPI 通知平台履约。联调测试统一放在商户后台，避免公开文档暴露测试工具。

2. 完整业务流程

资金安全 当前测试环境已经采用冻结/确认/解冻机制，不再直接扣款后再履约。

价格体系与调价规则

平台采用三层价格治理，商户端展示和下单金额必须以平台后端快照为准，不能相信前端裸传金额。

价格模式

商户调价边界

• 商户可在平台授权范围内设置零售价、建议价、最低价、最高价。
• 低于结算价的零售价不允许保存；已存在历史倒挂数据会被治理脚本拉回安全价。
• 动态价产品不允许商户自行填写最终履约价，必须使用 quoteId 或平台实时价格快照。
• 建议零售价默认按平台基准结算价加合理毛利生成，后续可按商户等级、行业、城市、活动配置差异化规则。

3. SDK 接入路径

4. OpenAPI 接入路径

OpenAPI 给技术型商户/合作方后端使用。所有核心接口需要签名。

签名规则

METHOD + "\n" + URI_PATH + "\n" + timestamp + "\n" + nonce + "\n" + body
sign = Base64URL(HMAC-SHA256(上述原文, app_secret)) 去掉 =

注意：URI 只签 path，不包含 query；timestamp 是秒级；GET body 为空但 nonce 后仍保留换行。

4.1 统一产品接口与智能路由

对外原则：下游客户只接中国道标准产品接口，不按服务通道分别适配。电影票、票务、快递、打车、生活服务 H5 等同一业务产品保持统一请求字段、统一响应字段、统一订单状态、统一错误码和统一回调通知。

后台路由：中国道根据商户授权、产品配置、服务通道可用性、成本价、城市/资源覆盖、接口健康状态、履约成功率和风控策略，在后台自动选择最合适的服务通道。下游文档不暴露服务方私有字段为必接字段，下游客户无需感知具体服务方。

内部系统可保留服务方名称用于成本、路由、运维和排障；开放平台、SDK 文档和商户接入文档统一使用“标准产品接口 / 服务通道 / 服务访问地址”等中性口径。

4.2 H5 产品入口接口

适用场景：生活服务、权益服务、到店服务、商超、生鲜、票务等已有成熟服务页面的 H5 类产品。

核心模式：下游客户请求中国道标准 H5 入口；中国道校验商户授权、用户参数和产品配置；后台选择服务通道并完成签名；中国道返回服务访问地址 h5Url/url 给下游。客户只需要跳转用户访问，并接收中国道统一订单状态和异步通知。

POST /openapi/v1/h5/entry
Content-Type: application/json
app_id: app_xxx
timestamp: 1783510000
nonce: random16
sign: HMAC_SHA256_BASE64URL

{
  "typeCode": "Weg",
  "interfaceTypeCode": "weg_interface",
  "deliveryMode": "h5_page",
  "userId": "merchant-user-001",
  "phone": "13800138000",
  "outRequestNo": "REQ202607080001"
}

POST /openapi/v1/h5/query
Content-Type: application/json
app_id: app_xxx
timestamp: 1783510000
nonce: random16
sign: HMAC_SHA256_BASE64URL

{
  "outRequestNo": "REQ202607080001"
}

当前可申请的 H5 产品编码

4.3 服务通道接入状态

新增服务能力统一进入中国道后台服务通道路由池。对下游仍按中国道标准产品接口输出，不要求客户直接适配任何服务方私有字段。

5. 客户常用入口

以下仅保留商户接入必须使用的正式入口。

6. 回调与订单状态

{
  "orderNo":"SDK202605201812405703",
  "status":"SUCCESS",
  "merchantId":1,
  "payAmount":"105.00",
  "event":"ORDER_SUCCESS"
}

7. 异步通知与商户退款责任

平台订单状态变化后，会向商户配置的 notifyUrl 发起异步通知。商户必须按 orderNo + event 做幂等；重复通知只更新状态，不得重复发货或重复退款。

通知报文示例

{
  "event":"ORDER_FAIL",
  "orderNo":"SDK202606131806064067",
  "merchantId":37,
  "typeCode":"DirectchargeNew",
  "orderStatus":"CLOSED",
  "payAmount":50,
  "userPayAmount":50,
  "merchantSettleAmount":50,
  "upstreamStatus":"FAILED",
  "upstreamErrorMsg":"接口未授权（错误码：...）",
  "timestamp":1781416601000
}

商户接口返回 SUCCESS 或 HTTP 2xx 仅表示“已接收通知”，不代表用户侧退款完成。

餐饮/券类 quoteId 报价锁价

餐饮、咖啡、兑换券等 SKU 价格不能由前端裸传金额。商户端应先让平台后端重查真实菜单并生成短期 quoteId，再用 quoteId 创建订单。

报价接口

POST /prod-api/openapi/v1/sdk/food/quote?merchantId=3
Content-Type: application/json

{
  "merchantId": 3,
  "shopType": "XBK",
  "shopId": "ff6f2064-8bf7-4f4a-9c83-4bf201714971",
  "productId": "sbk_135533136191685166",
  "quantity": 1
}

下单接口

POST /prod-api/openapi/v1/sdk/order-create?merchantId=3
Content-Type: application/json

{
  "merchantId": 3,
  "typeCode": "Food",
  "testMode": true,
  "quoteId": "foodq_xxx",
  "phoneNumber": "18100348861"
}

安全要求：正式餐饮/券类下单必须使用 quoteId；quoteId 5分钟有效，后续应增加一次性消费、防重放和 SKU 级成本校验。

7. 安全与正式上线

• SDK：必须配置商户域名白名单，避免任意站点盗用 merchantId。
• OpenAPI：必须使用 AppId/AppSecret/HMAC 签名，建议配置 IP 白名单。
• 价格：动态价格/券类/餐饮类必须使用平台后端价格快照 quoteId，不能相信前端裸传金额。
• 资金：正式环境只允许冻结/确认/解冻闭环，不允许回到直接扣款模式。
• 上线：正式环境同步前必须备份代码、JAR、关键表，并重新跑价格/商户/补偿检查。