跳转到主要内容

​
RollingGo MCP Tool 参考文档

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

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

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

​
1. 核心维度对比表

​
2. 调用链路对比

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

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

​
🔍 二、初级版本接口规范（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/小程序内自行完成下单：

​
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 示例：

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

获取当前启用的酒店筛选标签列表（如“含早餐”、“海景房”、“泳池”等）。
  • Output 响应特征：返回 success + tags[]（含 name 与 category 分类）+ usageGuide（大模型标签组合使用指导文字与示例请求 JSON）。

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

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

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

全流程交易闭环版本升级为 9 个 Tool 架构，实现了从价格锁死、生成支付链接到订单履约与两阶段安全取消的全流程操作（字段定义对齐《RollingGo Hotel MCP Tool 字段参考文档》v2.7，2026-09-20）。
  • 服务端点（OAUTH 鉴权接入）：国内版 https://mcp.rollinggo.cn/mcp/hotel / 国际版 https://mcp.rollinggo.ai/mcp/hotel；授权流程详见《RollingGo OAuth 2.0 开发者接入文档（中国大陆 / 海外及港澳台）》。
  • 国内版 / 国际版核心字段差异：① 国际版支持 localeParam（currency 默认 USD、支持 25 种货币；language 默认 en、支持 en/zh/ja），国内版固定中文（zh-CN）+ 人民币（CNY），不支持传入；② placeType 枚举国内版为中文（城市/机场/景点 等）、国际版为英文（city/airport/point_of_interest 等）；③ countryCode 与 nationality 已废弃移除；④ contact.email 国内版必填、国际版可选；⑤ bookingUrl 与 miniProgramInfo（微信小程序落地对象）按渠道形态互斥返回。

​
1. getHotelSearchTags — 获取搜索标签

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

​
2. searchHotels — 搜索全球酒店

与初级版本一致（含 hotelTags 标签/品牌/预算等全部筛选能力），入参与响应结构详见第二节。注意：countryCode 已废弃移除，语言与币种改用 localeParam（仅国际版）；hotelTags.maxPricePerNight 按所传 localeParam.currency 币种理解；响应中 bookingUrl 与 miniProgramInfo 按渠道形态互斥返回。

​
3. getHotelDetail — 详查房型与套餐

与初级版本一致，直接返回可用于下一步锁价的 ratePlanId，入参与响应结构详见第二节。注意：支持 filter 房型筛选（国内版与国际版均支持，未传时返回全量房型）——filter.mealType 餐食筛选（标准英文枚举 BREAKFAST_INCLUDED / SINGLE_BREAKFAST / DOUBLE_BREAKFAST / NO_MEAL，兼容中/日文别名如“含早餐”“双早”“朝食付き”）、filter.cancelable 退改筛选（CANCELABLE / NON_CANCELABLE，兼容“可免费取消”“不可取消”“無料キャンセル”等）。

​
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[].roomNum (integer, 必填): 房间序号，从 1 起递增
      • occupancyDetails[].adultCount (integer, 必填): 该房成人数 (默认 2)
      • occupancyDetails[].childCount (integer): 该房儿童数 (默认 0)
      • occupancyDetails[].childAgeDetails (integer[]): 儿童年龄数组，有儿童时必传
    • localeParam (object, 仅国际版): 语言与币种偏好包（language / currency，国内版无需传入）
  • Output 输出：

​
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 输出：bookingResult 为实单结果包装（生单失败时为 null）；paymentType 当前固定返回 "URL"，paymentUrl 为 Dida 平台通用收银台支付页链接（前端解析相应 token，可在宿主浏览器环境调起支付宝、微信、手机 H5 等通道支付结算）：

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

  • 功能：拉取当前账户绑定的酒店订单概要列表，轻量化结构防止大模型处理多订单时遭遇信息爆炸和 Context 膨胀。
  • Input 关键入参：
    • status (string): 订单状态筛选（默认 ALL）：ALL 全部 / PENDING 进行中待出行（映射底层状态 PreBook、Booked、Pending、OnRequest、Confirmed）/ FINISHED 已结束（映射底层状态 Canceled、Failed、Finished）
    • 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）：

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

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

​
8. preCancelHotelBooking — 预取消订单与罚金试算（交易闭环版本新增）

  • 功能：两阶段安全取消的第一步——查询订单能否在线取消、试算取消罚金，并获取 10 分钟有效 的取消确认凭证 confirmId。实际取消前必须先调用本 Tool，再调用 confirmCancelHotelBooking 完成最终取消。只读操作（readOnlyHint: true、destructiveHint: false），本步骤不会真正取消订单。
  • Input 关键入参：orderNo (string, 必填): RollingGo 系统订单号
  • Output 关键输出：
    • canCancel (boolean): 核心判断依据——penaltyAmount == 0（完全免费取消）时为 true；有罚金或不可退房型时为 false，无法在线取消，message 中给出客服电话（0755-36847480 / +852 30023293）与邮箱（cs.hotel@rollinggo.cn）引导人工处理
    • confirmId (string/null): 取消确认凭证，仅 canCancel=true 时返回，有效期 10 分钟；未支付订单返回 "UNPAID"
    • bookingId (string/null): 底层供应商预订号，仅 canCancel=true 时返回，确认取消时须回传
    • penaltyAmount (number) / currency (string): 取消罚金金额与币种代码（0 表示免费取消）
    • message (string): 中 / 英 / 日多语言动态提示文案
  • Output 示例（未支付订单，可免费取消）：

​
9. confirmCancelHotelBooking — 确认并执行订单取消（交易闭环版本新增）

  • 功能：两阶段安全取消的第二步——使用 preCancelHotelBooking 返回的凭证执行最终取消。操作不可逆（destructiveHint: true，幂等 idempotentHint: true），Agent 调用前必须获得用户的明确确认。
  • Input 关键入参：
    • orderNo (string, 必填): preCancelHotelBooking 返回的订单号
    • bookingId (string, 必填): preCancelHotelBooking 返回的预订号
    • confirmId (string, 必填): preCancelHotelBooking 返回的取消确认凭证（有效期 10 分钟，过期报 6207，需重新预取消获取新凭证）
    • description (string, 可选): 取消原因或备注说明
  • Output 输出：success + code + message（中 / 英 / 日结果文案）+ orderNo：

​
10. 统一错误码与异常映射（交易类 Tool）

​
🔄 四、版本选型建议

  1. 默认接入初级版本：
    • 申请接入默认开通初级版本（APIKEY 鉴权）：Agent 完成搜索与推荐后，将 bookingUrl 推送给用户，跳转 RollingGo H5/小程序承接下单预订。
    • 开发量小、接入简单，最快几分钟完成对接上线。
  2. 接入全流程交易闭环版本：
    • 若贵方拥有自有 Agent 且希望 Agent 在对话内独立完成查询 → 锁价 → 生单 → 支付 → 订单履约的全流程闭环，可申请接入全流程交易闭环版本（OAUTH 鉴权）。
    • 该版本需联系商务开通：商务合作 contact@rollinggo.ai
文档版本： 当前生产版 （对齐v2.7：OAUTH 版本扩展为 9 个 Tool，新增两阶段订单取消与统一错误码）
更新日期： 2026-10-14