酒店接口说明

酒店业务共 3 个接口，下单流程为：搜索 → 房型详情 → 下单（两步式下单）。

---

下单流程图

开发者                              开放平台
  │                                   │
  ├─ search ───────────────────────► │
  │  （目的地 + 入住/离店日期）           │
  │  ◄── hotels + search_offer_id ───┤
  │                                   │
  ├─ rooms（携带 search_offer_id）───► │
  │  ◄── room_types[].products[].offer_id ─┤
  │                                   │
  ├─ order/create ─────────────────► │
  │  （offer_id、入住人、联系人、         │
  │    out_trade_no、pay_mode）         │
  │  ◄── order_no + 待支付信息 ────────┤
  │      （user_pay 时附 checkout_url）  │
  │                                   │
  ├─ order/pay ────────────────────► │
  │                                   │
  │  · user_pay：返回 pay_params，用户去支付
  │  · enterprise_credit / monthly_settle：
  │    直接扣款/记账，订单转为已支付待确认
  │  ◄── pay_params / 支付成功响应 ────┤
  │                                   │
  │  （user_pay 支付完成后，平台异步推进订单）
  │  ◄═══ Webhook 推送订单状态 ════════┤
  │       paid → confirmed            │

流程说明：

1. 搜索：search 一定会返回 search_offer_id（酒店维度），它只能用于查询房型，不能直接下单。
2. 房型详情：rooms 把 search_offer_id 换成一批产品级 offer_id；products[].price 表示元/晚，订单总价由平台按入住天数计算。
3. 下单：order/create 先解密并校验 offer_id 与酒店供应商是否一致，再做幂等检查；随后统一验单（CheckOrder 核价 + 可订校验），调供应商创建订单锁房，成功后会落两张表（HotelOrder + OpenOrder）。订单初始状态为 pending_payment，并附带 15 分钟支付窗口。
4. 幂等：幂等键为 <app_id, out_trade_no>。同一个 out_trade_no 重复下单会直接返回已存在订单的 order_no，不会重复锁房。
5. 支付：order/pay 校验订单仍为 pending_payment 且归属当前 app 后，返回收银台支付链接和收款二维码，由终端用户完成支付。
6. 支付成功：支付网关异步回调到达后，平台记录支付流水（幂等去重），把订单改为 paid，并异步通知供应商确认。供应商确认成功订单推进到 confirmed；确认失败订单标记 abnormal。

---

1. 酒店搜索

POST /open/v1/hotel/search

根据目的地、入住/离店日期查询酒店列表，支持星级、价格、设施筛选。

关键流程

1. 每个酒店都会返回一个 search_offer_id（酒店维度）。
2. search_offer_id 只能用于查询房型，不能直接下单。
3. 下单前必须先调用 /open/v1/hotel/rooms 获取产品级 offer_id。

关键字段

• hotels[].search_offer_id：搜索阶段令牌，用于后续查询房型。
• hotels[].min_price：该酒店最低价（元/晚），用于列表展示。
• hotels[].star_rating / star_tag：星级评分（0~5）/ 档次标签（经济型/舒适型/高档型/豪华型）。
• hotels[].scene_tags：场景标签（couple / family / business 等），当请求传入 scene 时返回。
• hotels[].distance_km：距离用户经纬度的距离（km），传入 latitude / longitude 时返回。

注意事项

• 目的地字段：destination 支持城市名、商圈、地标（如 杭州西湖 / 北京朝阳区 / 上海外滩），优先传具体地标。
• 风控约束：
  • 不可指定过去日期；
  • check_out 必须晚于 check_in；
  • 单次最多返回 50 条（page_size 最大值），超过请分页获取。
• AI Agent 友好：传入 scene（如 couple / family / senior / business / inbound）时，返回结果带 scene_tags 提示，方便 Agent 理解酒店适用场景。
• 距离排序：sort_by = distance 需同时传入 latitude / longitude，否则排序失效。

---

2. 酒店房型详情

POST /open/v1/hotel/rooms

使用搜索返回的 search_offer_id 实时查询房型和产品，返回产品级 offer_id。

关键流程

1. 解密 search_offer_id 获取酒店和供应商信息。
2. 实时调用供应商接口查询房型和产品。
3. 为每个产品生成产品级 offer_id，用于下单。

关键字段

• room_types[].room_name：房型名称（如「豪华大床房」）。
• room_types[].bed_type：床型（big_bed / twin / multi）。
• room_types[].area：面积（平米）。
• room_types[].products[]：该房型下的产品列表（不同取消政策、早餐等）。
• room_types[].products[].offer_id：产品级 offer_id，创建订单时必填。
• room_types[].products[].price：价格（元/晚），订单总价由平台按入住天数计算。
• room_types[].products[].cancel_policy / refundable：取消政策 / 是否可退。
• room_types[].products[].has_breakfast：是否含早餐。

注意事项

• products[].price 为元/晚，订单总价 = price × 入住晚数 × 房间数。
• 创建订单时必须使用 products[].offer_id，不能直接用搜索返回的 search_offer_id。
• offer_id 有效期一般 5~10 分钟，超时需重新调用本接口。

---

3. 创建酒店订单

POST /open/v1/hotel/order/create

使用房型详情返回的产品级 offer_id 创建酒店订单。

幂等性

幂等键为 <app_id, out_trade_no>。同一 out_trade_no 重复请求只会创建一笔订单，重复调用直接返回已存在订单的 order_no。

关键字段

• out_trade_no：商户订单号（必填），幂等键，建议格式 {merchant_prefix}_{timestamp}_{seq}。
• offer_id：产品级 offer_id（必填），来自 /open/v1/hotel/rooms 接口。
• guests：入住人信息列表（姓名、证件类型、证件号、英文姓名可选）。
• contact：联系人信息（姓名、手机、邮箱）。
• arrival_time：预计到店时间（HH:MM），用于酒店保留房间。
• special_request：特殊要求（如「高楼层」、「安静房间」、「大床拼接」等）。
• callback_url：订单状态回调地址（HTTPS），平台会在订单状态变化时推送 Webhook（格式见 Webhook 文档）。

响应字段

• order_no：平台订单号，全局唯一。
• status：订单状态，初始为 pending_payment。
• expires_at：支付截止时间（北京时间），默认下单后 15 分钟，超时自动关单。
• total_amount：订单总金额（元），已按入住晚数计算。
• nights：入住晚数。
• room_count：房间数量。

订单状态

status	含义
pending_payment	待支付
paid	已支付，待确认
confirmed	已确认
checked_in	已入住
checked_out	已离店
canceled	已取消
refunded	已退款

注意事项

• 下单到支付的窗口默认 15 分钟，超时由平台自动关单（status = canceled）。
• 如果第一次请求超时，建议使用相同 out_trade_no 重试，利用幂等性避免重复下单。
• callback_url 需在接入方实现签名校验，防止伪造回调（具体签名算法见 Webhook 文档）。
• 酒店订单创建后会先调用供应商「验单」（CheckOrder），再调用供应商「下单」（CreateOrder 锁房），两步都成功才会返回 order_no。

---

完整流程示例

1. 调用 search，拿到 hotels[].search_offer_id
2. 用户选择酒店后，调用 rooms 用 search_offer_id 查询房型
3. 用户选择房型和产品后，拿到 products[].offer_id
4. 调用 order/create，携带 offer_id + 入住人 + 联系人 + out_trade_no
5. 成功后拿到 order_no，引导用户在 expires_at 前完成支付
6. 平台收到支付回调后推送 Webhook 到 callback_url，订单推进到 paid → confirmed

---

两步式下单的原因

酒店采用「搜索 → 房型详情 → 下单」两步式下单，原因如下：

1. 库存实时性：搜索结果仅用于列表展示（min_price 是估算值），真实库存和价格需实时向供应商查询。
2. 产品复杂度：同一房型可能有多个产品（不同取消政策、早餐、床型），需在房型详情页让用户选择。
3. 性能优化：搜索时不调用供应商接口，仅查离线酒店库，秒级返回；房型详情才实时查询，按需加载。

搜索返回的 search_offer_id 是酒店维度的令牌，房型详情返回的 offer_id 是产品维度的令牌，两者不可混用。