RollingGo MCP Tool 参考文档

面向： 第三方 AI Agent 开发者、系统集成架构师、MCP 客户端用户
目标： 详细说明 RollingGo MCP 服务在初级版本（APIKEY 鉴权）与全流程交易闭环版本（OAUTH 鉴权）的 API 参数规范、响应结构以及演进差异。

---

📌 一、初级版本与全流程交易闭环版本核心差异

RollingGo MCP 的演进方向：核心从 “单一信息查询” 演进为 “从搜索到在线下单履约的完整交易闭环”。

1. 核心维度对比表

对比维度	初级版本（APIKEY 鉴权）	全流程交易闭环版本（OAUTH 鉴权）
定位与能力	信息查询与展示（搜索/房型详情/标签）	全流程交易闭环（搜索 -> 详查 -> 锁价 -> 生单支付 -> 订单履约）
酒店 Tool 数量	3 个 (searchHotels, getHotelDetail, getHotelSearchTags)	7 个 (增加锁价、生单收银、订单列表、订单详情)
机票 Tool 状态	2 个 (searchAirports, searchFlights)	⚠️ 机票业务已暂停下线维护，聚焦酒店闭环
交易与预订能力	⚠️ 不支持 Agent 下单，推送 bookingUrl 由用户自行下单	✅ 支持在线下单支付（锁价 30 分钟，下发收银台 paymentUrl）
订单管理能力	⚠️ 无接口，用户可在下单页面自行查询订单	✅ 提供精简列表 searchHotelOrders 与全量详情 getHotelOrderDetail

---

2. 调用链路对比

极简查询链路（初级版本）

[用户提问] ➔ getHotelSearchTags (可选) ➔ searchHotels (列表初筛) ➔ getHotelDetail (展示房型/价格) ➔ 推送 bookingUrl，用户跳 H5/小程序自行下单

全流程预订与履约闭环链路（全流程交易闭环版本）

[1. 搜索初筛]  getHotelSearchTags ➔ searchHotels ➔ getHotelDetail
                                                            │
[2. 锁价下单]  createHotelBookingWithPaymentURL ⬅️ hotelPriceConfirm
                     │ (获取 paymentUrl 收银台)
                     ▼
[3. 履约管理]  searchHotelOrders (概要列表) ➔ getHotelOrderDetail (订单详情)

---

🔍 二、初级版本接口规范（APIKEY 鉴权）

初级版本适用于仅需要向用户展示酒店信息、将下单动作交由用户自行完成的 Agent 场景：Agent 不创建订单，但返回 bookingUrl 供用户跳转 H5/小程序自行下单。

说明： 本节的 3 个 Tool（searchHotels、getHotelDetail、getHotelSearchTags）为初级版本与全流程交易闭环版本共有，字段定义以当前生产版为准。

1. searchHotels — 搜索全球酒店

按地点、日期、星级、标签筛选酒店，返回候选列表及首夜预估最低参考价。

• Input 关键入参：

  • originQuery (string, 必填): 多轮会话提炼出的完整住宿意图（如“上海外滩五星酒店”）
  • place (string, 必填): 目标搜索名称（如“上海外滩”）
  • placeType (string, 必填): 地点类型枚举 (城市 / 景点 / 机场 / 火车站 / 地铁站 / 酒店 / 区/县 / 详细地址)
  • checkInParam (object): 入住信息包
    • checkInParam.checkInDate (string): 入住日期 YYYY-MM-DD（默认明天）
    • checkInParam.stayNights (integer): 入住晚数 (范围 1~28，默认 1)
    • checkInParam.adultCount (integer): 每间房成人数 (默认 2)
  • countryCode (string): 国家二字码（ISO 3166-1，如 CN、JP）
  • filterOptions (object): 地理解析与星级过滤
    • filterOptions.distanceInMeter (integer): 直线距离限制（米，默认 2000，景点/机场时生效）
    • filterOptions.starRatings (float[]): 星级范围，如 [4.0, 5.0]
  • hotelTags (object): 高级标签、品牌与预算过滤
    • hotelTags.requiredTags (string[]): 必须满足的硬性标签
    • hotelTags.preferredBrands (string[]): 偏好品牌列表
    • hotelTags.maxPricePerNight (float): 每晚预算上限
  • size (integer): 返回条数 (默认 5，最大 20)

• Output 响应特征：
  返回 success / message / hotelInformationList 数组，价格字段 price 仅代表首夜展示用参考价；每个酒店附带 bookingUrl，可由 Agent 以链接卡片形式推送给用户，用户点击后在 H5/小程序内自行完成下单：

  {
    "success": true,
    "message": "酒店搜索成功",
    "hotelInformationList": [
      {
        "hotelId": 29529,
        "bookingUrl": "https://rollinggo.cn/pages/hotel/detail/index?id=29529&...",
        "name": "上海和平饭店",
        "nameEn": "Fairmont Peace Hotel on the Bund",
        "brand": null,
        "address": "南京东路20号",
        "destinationId": "553248621526920274",
        "distanceInMeters": 124,
        "latitude": 31.239021,
        "longitude": 121.489459,
        "starRating": 5.0,
        "price": {
          "hasPrice": true,
          "currency": "CNY",
          "lowestPrice": 4665.0,
          "message": "查价成功。最低价格：4,665，币种：CNY"
        },
        "areaCode": "CN",
        "description": "<p>酒店坐落于著名的外滩和繁华的南京路交汇处...</p>",
        "imageUrl": "https://image-cdn.aigohotel.com/Image/CN/29529/Featured Image/...",
        "hotelAmenities": ["酒吧", "健身房", "泳池", "SPA", "停车场", "WIFI"],
        "tags": ["SPA服务", "度假酒店", "运动友好酒店", "室内恒温泳池", "商务中心"]
      }
    ]
  }
  

---

2. getHotelDetail — 查询房型与价格

根据酒店 ID（或名称）获取指定入住时段的详细房型与报价。

• Input 关键入参：

  • hotelId (integer, 与 name 二选一，优先使用): 酒店唯一 ID
  • name (string, 二选一): 酒店名称（模糊搜索）
  • dateParam (object): checkInDate / checkOutDate（YYYY-MM-DD，离店必须晚于入住）
  • occupancyParam (object): roomCount（默认 1）/ adultCount（默认 2）/ childCount（默认 0）/ childAgeDetails（儿童年龄数组，须与 childCount 对齐）
  • localeParam (object): countryCode（默认 CN）/ currency（默认 CNY）

• Output 响应特征：返回 roomRatePlans 房型套餐列表（核心字段含 roomNameCn, ratePlanId（锁价入参）, averagePrice, mealTypeStr, isOnRequest, cancelPolicy, roomInfo（房型设施信息包，含房型首图 roomInfo.images，无图返回 null）），JSON 示例：

  {
    "success": true,
    "hotelId": 1356133,
    "name": null,
    "nameEn": "Yitel Collection Hotel (Hangzhou West Lake Scenic Area Intime in77)",
    "checkIn": "2026-06-29",
    "checkOut": "2026-06-30",
    "bookingUrl": "https://rollinggo.cn/pages/hotel/detail/index?id=1356133...",
    "message": "搜索成功",
    "roomRatePlans": [
      {
        "roomName": "Queen Room",
        "roomNameCn": "大床房A",
        "ratePlanId": "fQJLb3OK1nE-4yPeHkCSFrG",
        "ratePlanName": "DOUBLE ROOM A",
        "averagePrice": 265.0,
        "bedTypeDescription": "1 大床",
        "currency": "CNY",
        "mealAmount": 0,
        "mealTypeStr": "不含早餐",
        "isOnRequest": false,
        "cancelPolicy": "不可免费取消",
        "roomInfo": {
          "hasWifi": true,
          "hasWindow": true,
          "maxOccupancy": 3,
          "size": "36",
          "smoking": "不可吸烟",
          "images": "https://image-cdn.rollinggo.cn//v2/1090005/room-type/default/12/90582968/0003/image/nw_18OWyLEPcGs.jpg-t"
        }
      },
      {
        "roomName": "Standard Twin Room",
        "roomNameCn": "标准双床房",
        "ratePlanId": "zQxLb9WK2mF-7yReHdGTBr",
        "ratePlanName": "TWIN ROOM",
        "averagePrice": 289.0,
        "bedTypeDescription": "2 单人床",
        "currency": "CNY",
        "mealAmount": 2,
        "mealTypeStr": "含早餐",
        "isOnRequest": false,
        "cancelPolicy": "7月10日前免费取消",
        "roomInfo": {
          "hasWifi": true,
          "hasWindow": false,
          "maxOccupancy": 2,
          "size": "28",
          "smoking": "可吸烟",
          "images": null
        }
      }
    ]
  }
  

---

3. getHotelSearchTags — 获取搜索标签（通用）

获取当前启用的酒店筛选标签列表（如“含早餐”、“海景房”、“泳池”等）。

• Output 响应特征：返回 success + tags[]（含 name 与 category 分类）+ usageGuide（大模型标签组合使用指导文字与示例请求 JSON）。

---

4. 机票接口（⚠️ 已下线维护）

• searchAirports: 输入城市/机场关键词换取三字码（如 HGH）。
• searchFlights: 使用三字码查询单程/往返机票列表。

---

🛒 三、全流程交易闭环版本接口规范（OAUTH 鉴权）

全流程交易闭环版本升级为 7 个 Tool 架构，实现了从价格锁死到生成支付链接及售后凭证的全流程操作。

1. getHotelSearchTags — 获取搜索标签

与初级版本一致，返回系统当前启用的全部标签及大模型组合偏好指导文案。

---

2. searchHotels — 搜索全球酒店

与初级版本一致（含 hotelTags 预算/品牌与 countryCode 等全部筛选能力），入参与响应结构详见第二节。

---

3. getHotelDetail — 详查房型与套餐

与初级版本一致，直接返回可用于下一步锁价的 ratePlanId，入参与响应结构详见第二节。

---

4. hotelPriceConfirm — 价格确认与锁价（交易闭环版本新增）

• 功能：锁定选定房型的实时最终价格，生成预订参考凭证号 referenceNo，锁定有效期 30 分钟。
• Input 关键入参：
  • hotelID (integer, 必填): 酒店 ID
  • ratePlanID (string, 必填): getHotelDetail 返回的方案 ID
  • numOfRooms (integer, 必填): 预订房间数 (默认 1)
  • dateParam (object, 必填): checkInDate / checkOutDate（YYYY-MM-DD）
  • occupancyDetails (array, 必填): 房间人数配比，项数须与 numOfRooms 一致
    • occupancyDetails[].adultCount (integer, 必填): 该房成人数 (默认 2)
    • occupancyDetails[].childCount (integer): 该房儿童数 (默认 0)
    • occupancyDetails[].childAgeDetails (integer[]): 儿童年龄数组，有儿童时必传
• Output 输出：

  {
    "success": true,
    "referenceNo": "REF2026081299812",
    "totalPrice": 9330.0,
    "currency": "CNY",
    "message": "价格校验通过，锁定成功"
  }
  

---

5. createHotelBookingWithPaymentURL — 创建订单与获取收银台（交易闭环版本新增）

• 功能：提交入住人姓名拼音与联系方式，创建系统订单（orderNo），并下发 Dida 平台通用收银台 paymentUrl。
• Input 关键入参：
  • referenceNo (string, 必填): hotelPriceConfirm 返回依然有效的锁价凭证
  • contact (object, 必填): 联系人信息
    • contact.firstName (string, 必填): 名（拼音或英文）
    • contact.lastName (string, 必填): 姓（拼音或英文）
    • contact.email (string, 必填): 接收确认邮件及行程单的邮箱
    • contact.phone (string, 必填): 接收短信通知与紧急联络的电话
  • guestList (array, 必填): 入住旅客名录，长度须与预订间数一致
    • guestList[].roomNum (integer, 必填): 房间序号，从 1 起递增
    • guestList[].guestInfo (array, 必填): 该房入住旅客列表，每房至少 1 名成人
      • guestInfo[].firstName (string, 必填): 名拼音或官方英文名
      • guestInfo[].lastName (string, 必填): 姓拼音或官方英文姓
      • guestInfo[].isAdult (boolean, 必填): true 成人 / false 儿童
      • guestInfo[].age (integer, 儿童必填): 儿童年龄，isAdult=false 时不得漏传
  • customerRequest (string, 可选): 备注式选房要求（如无烟、高楼层）
• Output 输出：

  {
    "success": true,
    "bookingResult": {
      "orderNo": "H17820260812001",
      "paymentType": "URL",
      "paymentUrl": "https://checkout.dida.com/pay?token=pay_tok_881923"
    }
  }
  

---

6. searchHotelOrders — 查询订单列表（交易闭环版本新增）

• 功能：拉取当前账户绑定的酒店订单概要列表，轻量化结构防止大模型处理多订单时遭遇信息爆炸和 Context 膨胀。
• Input 关键入参：
  • status (string): 订单状态筛选 (ALL 全部 / PENDING 进行中待出行 / FINISHED 已结束，默认 ALL)
  • dateRange (object): 下单时间区间
    • dateRange.startDate (string): 开始日期 YYYY-MM-DD
    • dateRange.endDate (string): 结束日期 YYYY-MM-DD
• Output 输出：orderList[] 概要列表（按生单时间倒序），各字段为 orderNo, hotelName, roomName, numOfRooms, checkInDate, checkOutDate, mealDesc, cancelPolicyDesc, orderStatus, totalPrice, currency, orderDate, orderDetailUrl（H5 详情页链接，含支付/退改按钮）, paymentUrl（待支付时返回收银台链接，否则 null）：

  {
    "success": true,
    "message": "查询成功",
    "orderList": [
      {
        "orderNo": "H17820260812001",
        "hotelName": "上海和平饭店",
        "roomName": "高级大床房",
        "numOfRooms": 1,
        "checkInDate": "2026-08-12",
        "checkOutDate": "2026-08-13",
        "mealDesc": "双早",
        "cancelPolicyDesc": "8月11日 18:00 前免费取消",
        "orderStatus": "待支付",
        "totalPrice": 9330.0,
        "currency": "CNY",
        "orderDate": "2026-08-12 10:30:00",
        "orderDetailUrl": "https://rollinggo.cn/pages/order/detail/index?id=H17820260812001",
        "paymentUrl": "https://checkout.dida.com/pay?token=pay_tok_881923"
      }
    ]
  }
  

---

7. getHotelOrderDetail — 查询订单全量详情（交易闭环版本新增）

• 功能：根据订单号获取单笔订单的完整结构化详情，满足前台快捷办理入住、地图路线导航、订单限时付款、退改时效判定、凭证报销等场景。
• Input 关键入参：orderNo (string, 必填): 主体订单号（如 "H178..."）
• Output 输出：success + message + orderDetail，按五个模块分组（baseInfo / hotelInfo / stayInfo / priceInfo / policyInfo）：

  {
    "success": true,
    "message": "查询成功",
    "orderDetail": {
      "baseInfo": {
        "orderNo": "H17820260812001",
        "referenceNo": "REF2026081299812",
        "hotelConfirmationNo": "HK2026081201CN876",
        "orderStatus": "待支付",
        "orderDate": "2026-08-12 10:30:00",
        "orderDetailUrl": "https://rollinggo.cn/pages/order/detail/index?id=H17820260812001"
      },
      "hotelInfo": {
        "hotelName": "上海和平饭店",
        "hotelImageUrl": "https://image-cdn.aigohotel.com/Image/CN/29529/Featured Image/main.jpg",
        "hotelPhone": "021-63216888",
        "platformSupportPhone": "400-888-xxxx",
        "hotelAddress": "南京东路20号",
        "latitude": 31.239021,
        "longitude": 121.489459
      },
      "stayInfo": {
        "roomName": "高级大床房",
        "bedTypeStr": "1张特大床 (1.8m)",
        "checkInDate": "2026-08-12",
        "checkOutDate": "2026-08-13",
        "checkInTime": "14:00",
        "checkOutTime": "12:00",
        "numOfRooms": 1,
        "nights": 1,
        "mealDesc": "双早",
        "contact": {
          "name": "ZHANG SAN",
          "phone": "13800138000",
          "email": "zhangsan@example.com"
        },
        "guestNames": ["ZHANG SAN"]
      },
      "priceInfo": {
        "totalPrice": 9330.0,
        "currency": "CNY",
        "paymentUrl": "https://checkout.dida.com/pay?token=pay_tok_881923",
        "paymentDeadline": "2026-08-12 11:00:00"
      },
      "policyInfo": {
        "isCancelable": true,
        "freeCancelDeadline": "2026-08-11 18:00:00",
        "cancelPolicyDesc": "8月11日 18:00 前免费取消"
      }
    }
  }
  

---

🔄 四、版本选型建议

1. 默认接入初级版本：

   • 申请接入默认开通初级版本（APIKEY 鉴权）：Agent 完成搜索与推荐后，将 bookingUrl 推送给用户，跳转 RollingGo H5/小程序承接下单预订。
   • 开发量小、接入简单，最快几分钟完成对接上线。

2. 接入全流程交易闭环版本：

   • 若贵方拥有自有 Agent 且希望 Agent 在对话内独立完成查询 → 锁价 → 生单 → 支付 → 订单履约的全流程闭环，可申请接入全流程交易闭环版本（OAUTH 鉴权）。
   • 该版本需联系商务开通：商务合作 contact@rollinggo.ai

---

文档版本： 当前生产版
更新日期： 2026-08-12