订单回调通知对接文档

版本：v1.1　|　适用：合作方酒店渠道（hotel-api 对接乙方）
说明：百米在酒店订单状态发生关键变化时，主动向渠道方配置的回调地址推送订单状态通知。本文档供乙方（渠道方）实现接收端使用。

1. 概述

乙方通过 hotel-api 创建酒店订单后，订单在百米侧每当订单状态发生对外需要感知的变化，百米会以 HTTP POST + JSON 明文方式回调乙方在开发平台配置的订单通知地址，并携带订单最新状态与金额。

乙方接收端需完成：处理业务 → 返回 success。

2. 回调地址配置

回调地址在对应开发平台的渠道配置中维护，而非渠道基础信息中：

配置项	说明
配置位置	开发平台渠道配置（ChannelApi，`apiType=Hotel`）中的通知地址 notifyUrl
请求方式	`POST`，`Content-Type: application/json; charset=UTF-8`
公网要求	回调地址需公网可访问，支持 POST

酒店订单通知地址以开发平台配置的 notifyUrl 为准。

3. 触发场景与通知类型

场景	`type`	`goodsOrderStatus`	说明
酒店确认成功	`1`	`2` 已确认	供应商已确认订单，可正常入住
拒单	`8`	`6` 已取消	供应商拒绝接单
取消 / 退单	`8`	`6` 已取消	主动取消或退单成功，`cancelReason` 带原因
订单完成	`7`	`3` 已完成	入住完成，订单完结

通知类型 type 取值：1 确认成功　2 失败　7 订单完成　8 取消/退单　9 部分退单。酒店订单目前使用 1 / 7 / 8。
订单状态以 goodsOrderStatus 为准（见 5.1 状态码表）。

4. 报文格式（明文）

4.1 请求（POST Body，明文 JSON，不加密不签名）

{
  "type": 1,
  "orderData": {
    "outOrderNo": "GO2026091000001",
    "channelOrderNo": "CH202609100001",
    "orderTitle": "酒店预订",
    "appId": "fxzb",
    "orderSubTitle": "杭州西湖大酒店",
    "orderDesc": "入住日期：2026-09-10~2026-09-11",
    "originPrice": 400.0,
    "salePrice": 320.0,
    "settlePrice": 300.0,
    "quantity": 1,
    "totalOriginAmount": 400.0,
    "totalSaleAmount": 320.0,
    "totalSettleAmount": 300.0,
    "status": 2,
    "cancelReason": null
  }
}

字段	类型	说明
`type`	int	通知类型（1 确认成功 / 7 订单完成 / 8 取消退单）
`orderData`	object	订单数据，见第 5 节

5. orderData 字段说明

字段	类型	单位	说明
`outOrderNo`	string	-	百米订单号（百米侧唯一）
`channelOrderNo`	string	-	渠道单号（乙方创建订单时传入，与百米订单一一对应）
`appId`	string	-	百米应用标识，酒店订单固定 `fxzb`
`orderTitle`	string	-	订单标题
`orderSubTitle`	string	-	订单副标题
`orderDesc`	string	-	订单描述（如入住日期）
`originPrice`	double	元	门市价单价 = 门市价总额 ÷ 数量
`salePrice`	double	元	销售价单价（对外售价）= 销售价总额 ÷ 数量
`settlePrice`	double	元	结算价单价（渠道与百米结算价）= 结算价总额 ÷ 数量
`quantity`	int	间/晚	购买数量（间夜数）
`totalOriginAmount`	double	元	门市价总额
`totalSaleAmount`	double	元	销售价总额（用户支付金额）
`totalSettleAmount`	double	元	结算价总额
`status`	int	-	订单状态码（`goodsOrderStatus`，见 5.1）
`cancelReason`	string	-	取消/退单原因（type=8 时有值）

5.1 订单状态码 `goodsOrderStatus`

值	状态
`1`	新订单
`2`	已确认（酒店确认）
`3`	已完成
`5`	已退款
`6`	已取消

金额均换算为元（内部按分存储后除以 100）。酒店订单金额以百米结算口径为准。

6. 应答要求

百米发送回调后，校验响应体（HTTP Body）文本是否包含 success（不区分大小写）。

{ "code": 0, "message": "success" }

响应包含 success → 判定通知成功，结束

响应为空 / 不包含 success / 请求异常 → 判定失败，进入重试

7. 重试机制

参数	值
重试间隔	第 1~8 次依次为 `10s、10s、10s、30s、60s、120s、360s、600s`

8. 对接检查清单

在开发平台渠道配置（ChannelApi apiType=Hotel）中配置 notifyUrl 回调地址

回调接口支持 POST application/json，公网可达

解析明文 JSON，按 type + goodsOrderStatus 更新本地订单状态（1确认/7完成/8取消）

应答体返回含 success 字样

联调覆盖：确认成功、拒单、退单、订单完成四种场景

确认取消失败处理流程（联系客服 / 罚金线下协商）

订单回调通知对接文档

1. 概述#

2. 回调地址配置#

3. 触发场景与通知类型#

4. 报文格式（明文）#

4.1 请求（POST Body，明文 JSON，不加密不签名）#

5. orderData 字段说明#

5.1 订单状态码 goodsOrderStatus#

6. 应答要求#

7. 重试机制#

8. 对接检查清单#