> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rollinggo.store/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Matrix & Specifications

## Core Tool Matrix

| # | Tool Name | Redirect Mode | Closed-Loop Mode | Key Capability & Scenario |
| :- | :- | :-: | :-: | :- |
| 1 | **`getHotelSearchTags`** | ✅ | ✅ | Retrieve platform search tags to extract user preferences |
| 2 | **`searchHotels`** | ✅ | ✅ | Discover candidate hotels, starting rates, bookingUrl, and stateless pagination |
| 3 | **`getHotelDetail`** | ✅ | ✅ | Query room rates and amenities with exact server-side meal and cancellation filters |
| 4 | **`hotelPriceConfirm`** | ❌ | ✅ | Lock price and inventory for 30 mins, returning `referenceNo` and guest profiles |
| 5 | **`createHotelBookingWithPaymentURL`** | ❌ | ✅ | Submit guest info to create booking and return checkout voucher (`paymentUrl` / `miniProgramPayInfo`) |
| 6 | **`searchHotelOrders`** | ❌ | ✅ | Query order summary list (lightweight schema to prevent LLM context bloat) |
| 7 | **`getHotelOrderDetail`** | ❌ | ✅ | Query full order details (voucher number, address, GPS coordinates, front desk phone) |
| 8 | **`preCancelHotelBooking`** | ❌ | ✅ | **Two-phase cancellation quote**: Quotes penalties and issues 10-minute `confirmId` |
| 9 | **`confirmCancelHotelBooking`** | ❌ | ✅ | **Two-phase cancellation execution**: Irreversible execution with `confirmId` and automatic refund |

***

> **Last Updated**: 2026-10-16\
> **Environment**: Production (Active)\
> **Tool Count**: 9 Tools\
> **Service Endpoints**:\
> • **API Key Mode**: China `https://mcp.rollinggo.cn/mcp` / Global `https://mcp.rollinggo.ai/mcp`\
> • **OAuth 2.1 Mode**: China `https://mcp.rollinggo.cn/mcp/hotel` / Global `https://mcp.rollinggo.ai/mcp/hotel`
>
> 💡 **China (`cn`) vs Global (`ai`) Core Differences**:
>
> 1. **Localization Package (`localeParam`)**: Only supported on **Global (`ai`)** endpoints (`localeParam: { currency, language }`, default `USD`, 25 currencies; default `en`, supports `en`/`zh`/`ja`). **China (`cn`)** endpoint is fixed to `zh-CN` and `CNY` (omit `localeParam`).
> 2. **Place Type Enum (`placeType`)**: China endpoint uses Chinese enums (`城市`, `机场`, `景点`, `酒店`, etc.); Global endpoint uses English enums (`city`, `airport`, `point_of_interest`, `hotel`, etc.).
> 3. **Deprecated Fields**: Both editions have fully removed `countryCode` and `nationality`.
> 4. **Contact Email (`contact.email`)**: **Required** for China edition; **Optional** for Global edition (Global requires only `firstName` and `lastName`).
> 5. **Rate Plan Filter (`filter`)**: Fully supported on both China and Global endpoints.
> 6. **Order Cancellation Tools (`preCancelHotelBooking` / `confirmCancelHotelBooking`)**: Parameter structures and two-phase safety mechanisms are identical across both editions with native multilingual feedback.

***

## Table of Contents

* [1. getHotelSearchTags — Fetch Search Tags](#1-gethotelsearchtags--fetch-search-tags)
* [2. searchHotels — Search Hotels Worldwide](#2-searchhotels--search-hotels-worldwide)
* [3. getHotelDetail — Get Hotel Details & Room Rate Plans](#3-gethoteldetail--get-hotel-details--room-rate-plans)
* [4. hotelPriceConfirm — Real-Time Price Verification & Locking](#4-hotelpriceconfirm--real-time-price-verification--locking)
* [5. createHotelBookingWithPaymentURL — Create Order with Payment URL](#5-createhotelbookingwithpaymenturl--create-order-with-payment-url)
* [6. searchHotelOrders — Query Hotel Orders List](#6-searchhotelorders--query-hotel-orders-list)
* [7. getHotelOrderDetail — Query Hotel Order Detail](#7-gethotelorderdetail--query-hotel-order-detail)
* [8. preCancelHotelBooking — Pre-Cancel Booking & Penalty Quote](#8-precancelhotelbooking--pre-cancel-booking--penalty-quote)
* [9. confirmCancelHotelBooking — Confirm & Execute Cancellation](#9-confirmcancelhotelbooking--confirm--execute-cancellation)
* [10. Unified Error Codes & Exception Mapping](#10-unified-error-codes--exception-mapping)

***

## 1. getHotelSearchTags — Fetch Search Tags

### Description

Retrieves all enabled hotel filter tags.

### Input Parameters

None.

### Output

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `success` | boolean | ❌ No | Whether the API call succeeded |
| `tags` | array | ❌ No | List of tag data |
| `tags[].name` | string | ❌ No | Tag display name (e.g., "Free Wi-Fi", "Local Chain") |
| `tags[].category` | string | ❌ No | Tag category (e.g., "Views & Room Types", "Core Amenities") |
| `usageGuide` | object | ❌ No | Guidance for the LLM on using filter preferences |
| `usageGuide.tagUsage` | string | ❌ No | Text guide on how tags are combined/bound in the request body |
| `usageGuide.exampleRequest` | string | ❌ No | Complete request JSON example string with tag filters |

***

## 2. searchHotels — Search Hotels Worldwide

### Description

Performs an initial global hotel search within a specified area based on filter criteria, returning candidate hotels and estimated lowest retail prices with real-time currency conversion.

### Input Parameters (Complete field list 📋)

| Parameter | Type | Required | Default | Description |
| :- | :- | :- | :- | :- |
| `originQuery` | string | ✅ | — | Full accommodation intent text distilled from multi-turn conversation |
| `place` | string | ✅ | — | Target search name (place name / airport / attraction / station / specific hotel name, etc.) |
| `placeType` | string | ✅ | — | Place type. **China edition** uses Chinese enums (`城市`, `机场`, `景点`, `火车站`, `地铁站`, `酒店`, `区/县`, `详细地址`); **Global edition** uses English enums (`city`, `airport`, `point_of_interest`, `train_station`, `subway_station`, `hotel`, `district/county`, `detailed address`) |
| `checkInParam` | object | ❌ | — | Check-in and length-of-stay information bundle |
| `checkInParam.checkInDate` | string | ❌ | Tomorrow | Check-in date, format `YYYY-MM-DD` |
| `checkInParam.stayNights` | integer | ❌ | `1` | Number of nights (range `1`–`28`) \[format: int32] |
| `checkInParam.adultCount` | integer | ❌ | `2` | Number of adults per room \[format: int32] |
| `localeParam` | object | ❌ | — | **\[Global Edition Only]** Localization package (China edition is fixed to `zh-CN` + `CNY`, omit this parameter) |
| `localeParam.language` | string | ❌ | `en` (Global) / `zh-CN` | Language code (e.g., `en`, `zh`, `ja`) |
| `localeParam.currency` | string | ❌ | `USD` (Global) / `CNY` | Settlement currency code (e.g., `USD`, `EUR`, `JPY`, `HKD`, etc. 25 currencies) |
| `filterOptions` | object | ❌ | — | Geographic parsing and star-rating filter layer |
| `filterOptions.distanceInMeter` | integer | ❌ | `2000` | Straight-line distance limit (meters); effective when placeType is "Attraction" or "Airport" \[format: int32] |
| `filterOptions.starRatings` | float\[] | ❌ | `[0.0, 5.0]` | Star rating range array, values 0.0–5.0 (step 0.5) |
| `hotelTags` | object | ❌ | — | Advanced tag, brand, and budget restriction filter bundle |
| `hotelTags.requiredTags` | string\[] | ❌ | — | List of hard-requirement tags that must be matched |
| `hotelTags.preferredBrands` | string\[] | ❌ | — | Preferred chain brand names |
| `hotelTags.maxPricePerNight` | float | ❌ | — | Per-room-per-night budget cap in specified settlement currency |
| `size` | integer | ❌ | `5` | Maximum number of hotels to return (max `20`) \[format: int32] |

### Output

#### Top-Level Fields

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `success` | boolean | ❌ No | Whether the search succeeded |
| `message` | string | ❌ No | Business-layer processing feedback message |
| `hotelInformationList` | array | ❌ No | List of hotel objects matching the filter criteria |

#### hotelInformationList\[] Hotel Data Structure

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `hotelId` | integer | ❌ No | Unique hotel ID (preferred parameter for getHotelDetail pricing) |
| `bookingUrl` | string | ✅ Yes | Front-end static route URL of the hotel detail & booking H5 page; mutually exclusive with `miniProgramInfo` |
| `miniProgramInfo` | object | ✅ Yes | Structured WeChat Mini Program landing object, output in streamlined form per channel configuration (mutually exclusive with `bookingUrl`) |
| `name` | string | ❌ No | Hotel name (localized per localeParam.language) |
| `nameEn` | string | ❌ No | Official English long name of the hotel |
| `brand` | string/null | ✅ Yes | Brand name (returned only for branded hotels) |
| `address` | string | ❌ No | Detailed physical address |
| `destinationId` | string | ❌ No | Secondary destination identifier |
| `distanceInMeters` | integer/null | ✅ Yes | Straight-line distance from search center point (returned only when searching POI with distance match) |
| `latitude` | double | ❌ No | Latitude in WGS-84 coordinates |
| `longitude` | double | ❌ No | Longitude in WGS-84 coordinates |
| `starRating` | number | ❌ No | Star rating (1–5) |
| `price` | object | ❌ No | Lowest first-night price information bundle |
| `price.hasPrice` | boolean | ❌ No | Whether a quote is available for the dates |
| `price.currency` | string | ❌ No | Settlement currency code (e.g., `CNY`, `JPY`, `USD`) |
| `price.lowestPrice` | number | ❌ No | Lowest reference discounted room-night price (converted to settlement currency) |
| `price.message` | string | ❌ No | Price note text |
| `areaCode` | string | ❌ No | ISO 2-letter country code (e.g., `CN`, `JP`, `US`) |
| `description` | string | ❌ No | Hotel rich text description (may include HTML tags) |
| `imageUrl` | string | ❌ No | Hotel cover/main image CDN URL |
| `hotelAmenities` | string\[] | ❌ No | List of hotel amenities and services |
| `tags` | string\[] | ❌ No | Distilled tags matching user search context |

***

## 3. getHotelDetail — Get Hotel Details & Room Rate Plans

### Description

Queries all sellable room types for a specific hotel, average per-night rates, and cancellation/modification rules. Supports server-side structured room filtering by meal and cancellation terms.

### Input Parameters (Complete field list 📋)

*`hotelId` and `name` are mutually exclusive; `hotelId` is preferred for high-precision matching.*

| Parameter | Type | Required | Default | Description |
| :- | :- | :- | :- | :- |
| `hotelId` | integer | ⚠️ One of | — | Unique hotel ID \[format: int32] |
| `name` | string | ⚠️ One of | — | Hotel name (fuzzy search, used when no ID is available) |
| `dateParam` | object | ❌ | — | Check-in/check-out date bundle |
| `dateParam.checkInDate` | string | ❌ | — | Check-in date, format `YYYY-MM-DD` |
| `dateParam.checkOutDate` | string | ❌ | — | Check-out date, format `YYYY-MM-DD` (must be later than checkInDate) |
| `occupancyParam` | object | ❌ | — | Room count and occupancy constraints |
| `occupancyParam.roomCount` | integer | ❌ | `1` | Number of rooms to book, default 1 \[format: int32] |
| `occupancyParam.adultCount` | integer | ❌ | `2` | Adults per room, default 2 \[format: int32] |
| `occupancyParam.childCount` | integer | ❌ | `0` | Children per room, default 0 \[format: int32] |
| `occupancyParam.childAgeDetails` | integer\[] | ❌ | — | Array of children's ages (length must strictly match childCount) |
| `localeParam` | object | ❌ | — | **\[Global Edition Only]** Language and currency preferences (China edition is fixed to `CNY`, omit this parameter) |
| `localeParam.language` | string | ❌ | `en` (Global) / `zh-CN` | Language code (e.g., `en`, `zh`, `ja`) |
| `localeParam.currency` | string | ❌ | `USD` (Global) / `CNY` | Settlement currency code (e.g., `USD`, `EUR`, `JPY`, `HKD`, etc. 25 currencies) |
| `filter` | object | ❌ | — | **Room rate plan filtering bundle (returns all plans if omitted; supported on both China & Global)** |
| `filter.mealType` | string | ❌ | — | Meal plan filter, e.g., `"BREAKFAST_INCLUDED"`, `"DOUBLE_BREAKFAST"`, `"NO_MEAL"` (supports EN/ZH/JA, see matrix below) |
| `filter.cancelable` | string | ❌ | — | Cancellation policy filter, e.g., `"CANCELABLE"`, `"NON_CANCELABLE"` (supports EN/ZH/JA, see matrix below) |

#### Multilingual Filter Compatibility Matrix

| Filter Dimension | Matching Logic | Standard Enum (Recommended) | Chinese Aliases | Japanese Aliases |
| :- | :- | :- | :- | :- |
| **Meal Filter** (`mealType`) | `mealAmount > 0` (Breakfast included) | `"BREAKFAST_INCLUDED"` | `"含早餐"`, `"含早"` | `"朝食付き"`, `"朝食あり"` |
| | `mealAmount == 1` (Single breakfast) | `"SINGLE_BREAKFAST"` | `"单份早餐"`, `"单早"` | `"1名朝食付き"` |
| | `mealAmount == 2` (Double breakfast) | `"DOUBLE_BREAKFAST"` | `"双份早餐"`, `"双早"` | `"2名朝食付き"` |
| | `mealAmount == 0` (No meal / Room only) | `"NO_MEAL"` / `"ROOM_ONLY"` | `"不含餐食"`, `"无早"` | `"食事なし"`, `"素泊まり"` |
| **Cancellation Filter** (`cancelable`) | Free cancellation only | `"CANCELABLE"` | `"可免费取消"`, `"免费取消"` | `"無料キャンセル"`, `"キャンセル可能"` |
| | Non-refundable only | `"NON_CANCELABLE"` | `"不可取消"`, `"不可免费取消"` | `"キャンセル不可"` |

### Output

#### Top-Level Fields

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `success` | boolean | ❌ No | Whether the query succeeded at the business layer |
| `hotelId` | integer | ❌ No | Hotel ID |
| `name` | string | ❌ No | Hotel name |
| `nameEn` | string | ❌ No | Official English long name of the hotel |
| `checkIn` | string | ❌ No | Confirmed check-in date `YYYY-MM-DD` |
| `checkOut` | string | ❌ No | Confirmed check-out date `YYYY-MM-DD` |
| `bookingUrl` | string | ✅ Yes | Front-end static route URL of the hotel detail booking H5 page; mutually exclusive with `miniProgramInfo` |
| `miniProgramInfo` | object | ✅ Yes | Structured WeChat Mini Program landing object, output in streamlined form per channel configuration (mutually exclusive with `bookingUrl`) |
| `roomRatePlans` | array | ❌ No | List of real-time sellable rate plan bundles at room-type level (filtered per criteria) |
| `message` | string | ❌ No | Status or feedback message |

#### miniProgramInfo Structure & Channel Forms Matrix

| Form ID (`type`) | Applicable Scene | Technical Vehicle | Prerequisites | `miniProgramInfo` Output Fields |
| :- | :- | :- | :- | :- |
| `H5` (Default) | Web Browser / H5 | Plain URL string | None | *Does not return miniProgramInfo, returns top-level `bookingUrl` (string)* |
| `H5_TO_MINIAPP` | H5 jumping to Mini Program | Encrypted URL Link (`https://wxmpurl.cn/*`) | Mini Program published | `type`: `"H5_TO_MINIAPP"`, `url`: Encrypted URL Link |
| `APP_TO_MINIAPP` | Native App jumping to Mini Program | Plain Scheme (`weixin://dl/business/?...`) | Scheme enabled in WeChat Console | `type`: `"APP_TO_MINIAPP"`, `url`: Plain Scheme |
| `MINIAPP_TO_MINIAPP` | In-Mini Program navigation | Structured params (`appId` + `path` + `query`) | Handled by host Mini Program | `type`: `"MINIAPP_TO_MINIAPP"`, `appId`: Mini Program AppID, `path`: Pure path, `query`: Dynamic query string |

#### roomRatePlans\[] Rate Plan Sub-object

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `roomName` | string | ❌ No | Standard English room type name |
| `roomNameCn` | string | ❌ No | Standard Chinese room type description (e.g., `"高级大床房"`) |
| `ratePlanId` | string | ❌ No | Unique quote plan ID for the plan's time period (**ratePlanID input for price confirmation**) |
| `ratePlanName` | string | ❌ No | Rate plan name (including bed width, occupancy details) |
| `averagePrice` | number | ❌ No | Average discounted all-inclusive (tax-included) price per night for the period in settlement currency |
| `bedTypeDescription` | string | ❌ No | Physical bed type description (e.g., `"1 King Bed"`, `"2 Twin Beds"`) |
| `currency` | string | ❌ No | Settlement currency code (e.g., `CNY`, `JPY`, `USD`) |
| `mealAmount` | integer | ❌ No | Number of included breakfasts with this plan (e.g., `0` = no meals; `2` = double breakfast) |
| `mealTypeStr` | string | ❌ No | Meal type description text |
| `isOnRequest` | boolean | ❌ No | Whether deferred manual approval is required (`false` = instant confirmation) |
| `cancelPolicy` | string | ❌ No | Simplified cancellation/modification rule text |
| `roomInfo` | object | ❌ No | Room static facility info bundle |
| `roomInfo.hasWifi` | boolean | ❌ No | Whether the room has Wi-Fi |
| `roomInfo.hasWindow` | boolean | ❌ No | Whether the room has a window |
| `roomInfo.maxOccupancy` | integer | ❌ No | Maximum room occupancy |
| `roomInfo.size` | string | ❌ No | Room area (text in square meters, e.g., `"36"`) |
| `roomInfo.smoking` | string | ❌ No | Smoking policy description |
| `roomInfo.images` | string/null | ✅ Yes | Room type cover image URL, returns `null` when no valid image is available |

***

## 4. hotelPriceConfirm — Real-Time Price Verification & Locking

### Description

Locks in the final real-time price and room status for the selected room type, generating the booking reference tracking number `referenceNo`. Lock validity is 30 minutes. Also returns intelligent guest profile bundle (`guestProfile`) for seamless form prefilling.

### Input Parameters (Complete field list 📋)

*Both `dateParam` and `occupancyDetails` are required.*

| Parameter | Type | Required | Default | Description |
| :- | :- | :- | :- | :- |
| `hotelID` | integer | ✅ | — | Unique hotel ID \[format: int32] |
| `ratePlanID` | string | ✅ | — | ratePlanId returned from getHotelDetail roomRatePlans |
| `numOfRooms` | integer | ✅ | `1` | Number of rooms to lock \[format: int32] |
| `localeParam` | object | ❌ | — | **\[Global Edition Only]** Language and currency preferences (`currency`, `language`) |
| `dateParam` | object | ✅ | — | Date control object |
| `dateParam.checkInDate` | string | ✅ | — | Check-in date, format `YYYY-MM-DD` |
| `dateParam.checkOutDate` | string | ✅ | — | Check-out date, format `YYYY-MM-DD` |
| `occupancyDetails` | array | ✅ | — | Occupancy breakdown per room; array length must equal `numOfRooms` |
| `occupancyDetails[].roomNum` | integer | ✅ | `1` | Room sequence number starting from 1 \[format: int32] |
| `occupancyDetails[].adultCount` | integer | ✅ | `2` | Number of adults for this room \[format: int32] |
| `occupancyDetails[].childCount` | integer | ❌ | `0` | Number of children for this room \[format: int32] |
| `occupancyDetails[].childAgeDetails` | integer\[] | ❌ | — | Array of children's ages |

### Output (Complete field list 📋)

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `success` | boolean | ❌ No | Whether price locking succeeded |
| `code` | integer | ❌ No | Business status code (`2000` = success) |
| `message` | string | ❌ No | Lock confirmation message |
| `referenceNo` | string | ❌ No | **Locked price reference tracking number (critical for booking creation)** |
| `totalPrice` | number | ❌ No | Verified total all-inclusive price |
| `currency` | string | ❌ No | Settlement currency |
| `priceDetailsInfo` | object | ❌ No | Detailed price lock object |
| `priceDetailsInfo.referenceNo` | string | ❌ No | Reference number matching top-level referenceNo |
| `priceDetailsInfo.checkInDate` | string | ❌ No | Confirmed check-in date |
| `priceDetailsInfo.checkOutDate` | string | ❌ No | Confirmed check-out date |
| `priceDetailsInfo.totalPrice` | number | ❌ No | Confirmed total price |
| `priceDetailsInfo.currency` | string | ❌ No | Settlement currency (e.g., `CNY`, `USD`) |
| `priceDetailsInfo.lockExpirationMinutes` | integer | ❌ No | Lock validity period (fixed at `30` minutes) |
| `guestProfile` | object | ❌ No | Intelligent frequent guest profile prefill bundle |
| `guestProfile.guestNameList` | string\[] | ❌ No | Pre-filled guest names (Pinyin or English) |
| `guestProfile.contactPhone` | string | ❌ No | Contact phone number |
| `guestProfile.contactEmail` | string | ❌ No | Contact email address |

***

## 5. createHotelBookingWithPaymentURL — Create Order with Payment URL

### Description

Submits guest and contact details to generate an active booking order and retrieve cashier payment information.

Based on the client host environment (Web / Browser vs. WeChat / Mini Program), the system returns one of two mutually exclusive payment fields:

1. **`paymentUrl`**: Web payment URL, directly opened in browser to complete checkout;
2. **`miniProgramPayInfo`**: Mini Program payment object, directly launching the native WeChat Mini Program cashier in Mini Program or native APP environments.

* **Strict Mutual Exclusivity**: Only the field matching the current client environment is returned; the other is completely omitted from the response;
* **Non-Pending State Returns null**: If an order is paid, cancelled, or expired, the configured payment field is retained and set to `null`.

### Input Parameters (Complete field list 📋)

| Parameter | Type | Required | Default | Description |
| :- | :- | :- | :- | :- |
| `referenceNo` | string | ✅ | — | Valid referenceNo obtained from price confirmation stage |
| `contact` | object | ✅ | — | Primary order contact person details |
| `contact.firstName` | string | ✅ | — | Contact first name (Pinyin or English) |
| `contact.lastName` | string | ✅ | — | Contact last name (Pinyin or English) |
| `contact.email` | string | ⚠️ | — | Email address for confirmation voucher and invoice. **Required for China edition**; **Optional for Global edition** (Global only requires firstName, lastName). |
| `contact.phone` | string | ✅ | — | Contact phone number for SMS and emergency contact (e.g., `"13800138000"`) |
| `guestList` | array | ✅ | — | List of assigned guests per room; array length must equal room count |
| `guestList[].roomNum` | integer | ✅ | — | Room sequence number starting from `1` \[format: int32] |
| `guestList[].guestInfo` | array | ✅ | — | List of guests staying in this room (at least 1 adult required) |
| `guestList[].guestInfo[].firstName` | string | ✅ | — | Guest first name (Pinyin or English) |
| `guestList[].guestInfo[].lastName` | string | ✅ | — | Guest last name (Pinyin or English) |
| `guestList[].guestInfo[].isAdult` | boolean | ✅ | — | Whether guest is an adult (`true`) or child (`false`) |
| `guestList[].guestInfo[].age` | integer | ⚠️ Child required | — | Age of child guest (mandatory if `isAdult` is `false`) \[format: int32] |
| `customerRequest` | string | ❌ | — | Special customer requests (e.g., non-smoking, high floor) |

### Output (Complete field list 📋)

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `success` | boolean | ❌ No | Whether booking was successfully created |
| `code` | integer | ❌ No | Business status code (`2000` = success) |
| `bookingResult` | object/null | ✅ Yes | Booking confirmation result object (null on failure) |
| `bookingResult.orderNo` | string | ❌ No | Unique order number created by RollingGo system (e.g., `"H178..."`) |
| `bookingResult.paymentType` | string | ❌ No | Payment invocation type (fixed as `"PAYMENT_PAGE"`) |
| `bookingResult.paymentUrl` | string | ⚠️ Conditional | **Web Payment URL** (returned for Web/browser environments; omitted for Mini Program environments) |
| `bookingResult.miniProgramPayInfo` | object | ⚠️ Conditional | **Mini Program Payment Object** (returned for Mini Program/APP environments; omitted for Web environments) |
| `bookingResult.miniProgramPayInfo.type` | string | ❌ No | Payment invocation category description |
| `bookingResult.miniProgramPayInfo.url` | string | ⚠️ Conditional | WeChat launch link / scheme (for external web or APP invocation) |
| `bookingResult.miniProgramPayInfo.appId` | string | ⚠️ Conditional | Target WeChat Mini Program AppID (for cross-program navigation) |
| `bookingResult.miniProgramPayInfo.path` | string | ⚠️ Conditional | Target page path (`"pages/order/token-pay/index"`) |
| `bookingResult.miniProgramPayInfo.query` | string | ⚠️ Conditional | Page query parameters string (`"token=B8ZUZoPx"`) |
| `bookingResult.paymentUrlNote` | string | ❌ No | Payment environment guidance and invocation notes |
| `bookingResult.amount` | number | ❌ No | Total order amount payable |
| `bookingResult.currency` | string | ❌ No | Settlement currency |

#### Response Examples

##### Example 1: Web Link Payment (`paymentUrl` returned)

```json theme={null}
{
  "success": true,
  "code": 2000,
  "bookingResult": {
    "orderNo": "H179058199622762501",
    "amount": 171.00,
    "currency": "CNY",
    "paymentType": "PAYMENT_PAGE",
    "paymentUrl": "https://rollinggo.cn/pages/order/token-pay/index?token=B8ZUZoPx",
    "paymentUrlNote": "Open this payment page. The page will resolve the token and choose payment method."
  }
}
```

##### Example 2: Mini Program Payment (`miniProgramPayInfo` returned)

```json theme={null}
{
  "success": true,
  "code": 2000,
  "bookingResult": {
    "orderNo": "H179058199622762501",
    "amount": 171.00,
    "currency": "CNY",
    "paymentType": "PAYMENT_PAGE",
    "miniProgramPayInfo": {
      "type": "MINIAPP_TO_MINIAPP",
      "appId": "wx1234567890abcdef",
      "path": "pages/order/token-pay/index",
      "query": "token=B8ZUZoPx"
    },
    "paymentUrlNote": "Invoke wx.navigateToMiniProgram with miniProgramPayInfo parameters."
  }
}
```

***

## 6. searchHotelOrders — Query Hotel Orders List

### Description

Fetches a lightweight summary list of hotel orders for the current user to prevent LLM context bloating.

### Input Parameters

| Parameter | Type | Required | Default | Description |
| :- | :- | :- | :- | :- |
| `status` | string | ❌ | `"ALL"` | Order lifecycle status filter: • `ALL` (All orders) • `PENDING` (Active / Upcoming: `PreBook`, `Booked`, `Pending`, `OnRequest`, `Confirmed`) • `FINISHED` (Ended: `Canceled`, `Failed`, `Finished`) |
| `dateRange` | object | ❌ | — | Booking date range filter |
| `dateRange.startDate` | string | ❌ | — | Start date (`YYYY-MM-DD`) |
| `dateRange.endDate` | string | ❌ | — | End date (`YYYY-MM-DD`) |

### Output

#### Top-Level Fields

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `success` | boolean | ❌ No | Whether query succeeded |
| `code` | integer | ❌ No | Business status code (`2000` = success) |
| `message` | string | ❌ No | Processing feedback message |
| `orderList` | array | ❌ No | List of order summaries (descending order by booking time) |

#### orderList\[] Order Summary Object

*(Streamlined version, preserving core fields for list rendering and LLM coarse filtering)*

| Field | Type | Description |
| :- | :- | :- |
| `orderNo` | string | Unified order identification number |
| `hotelName` | string | Full hotel name |
| `roomName` | string | Booked room name |
| `numOfRooms` | integer | Number of booked rooms |
| `checkInDate` | string | Check-in date (`YYYY-MM-DD`) |
| `checkOutDate` | string | Check-out date (`YYYY-MM-DD`) |
| `mealDesc` | string | Meal description (e.g., "Double Breakfast", "No Meals") |
| `cancelPolicyDesc` | string | Concise summary of cancellation terms |
| `orderStatus` | string | Order status description (e.g., `"Confirmed"`, `"Pending Payment"`, `"Canceled"`) |
| `totalPrice` | number | Total order amount |
| `currency` | string | Settlement currency |
| `orderDate` | string | Creation timestamp (`YYYY-MM-DD HH:mm:ss`) |
| `orderDetailUrl` | string | Front-end H5 URL to view/manage order in browser |
| `paymentUrl` | string/null | Web payment URL (returned in Web environments; active if pending within 30m; returns `null` if paid, cancelled, or expired; omitted in Mini Program environments) |
| `miniProgramPayInfo` | object/null | Mini Program payment object (returned in Mini Program environments; active if pending within 30m; returns `null` if paid, cancelled, or expired; omitted in Web environments) |

***

## 7. getHotelOrderDetail — Query Hotel Order Detail

### Description

Fetches complete structured details for a specific order for check-in verification, map navigation, pending payment, and receipts.

### Input Parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `orderNo` | string | ✅ | Unified order number (e.g., `"H178..."`) |

### Output

#### Top-Level Fields

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `success` | boolean | ❌ No | Whether query succeeded |
| `code` | integer | ❌ No | Business status code (`2000` = success) |
| `message` | string | ❌ No | Feedback message |
| `orderDetail` | object | ✅ Yes | Structured order detail bundle (non-null on success) |

#### orderDetail Detail Object

| Field | Type | Description |
| :- | :- | :- |
| `baseInfo` | object | **\[Module]** Base order & voucher information |
| `baseInfo.orderNo` | string | Unified order identification number |
| `baseInfo.referenceNo` | string | Price locking reference ID |
| `baseInfo.hotelConfirmationNo` | string/null | Official hotel confirmation number for check-in |
| `baseInfo.orderStatus` | string | Readable order status (e.g., `"Confirmed"`, `"Pending Payment"`, `"Cancelled"`) |
| `baseInfo.orderDate` | string | Order creation timestamp (`YYYY-MM-DD HH:mm:ss`) |
| `baseInfo.orderDetailUrl` | string | Direct H5 URL to view/manage order in browser |
| `hotelInfo` | object | **\[Module]** Hotel entity and geo information |
| `hotelInfo.hotelName` | string | Full hotel name |
| `hotelInfo.hotelImageUrl` | string | Main image CDN URL |
| `hotelInfo.hotelPhone` | string | Front-desk telephone number |
| `hotelInfo.platformSupportPhone` | string | RollingGo customer support hotline |
| `hotelInfo.hotelAddress` | string | Physical address |
| `hotelInfo.latitude` | double | Latitude for map navigation |
| `hotelInfo.longitude` | double | Longitude for map navigation |
| `stayInfo` | object | **\[Module]** Itinerary and guest information |
| `stayInfo.roomName` | string | Booked room name |
| `stayInfo.bedTypeStr` | string/null | Bed description (e.g., `"1 King Bed"`) |
| `stayInfo.checkInDate` | string | Check-in date (`YYYY-MM-DD`) |
| `stayInfo.checkOutDate` | string | Check-out date (`YYYY-MM-DD`) |
| `stayInfo.checkInTime` | string | Earliest check-in time (`14:00`) |
| `stayInfo.checkOutTime` | string | Latest check-out time (`12:00`) |
| `stayInfo.numOfRooms` | integer | Number of booked rooms |
| `stayInfo.nights` | integer | Total nights |
| `stayInfo.mealDesc` | string | Meal description |
| `stayInfo.contact` | object | Primary order contact details |
| `stayInfo.contact.name` | string | Contact name |
| `stayInfo.contact.phone` | string | Contact telephone |
| `stayInfo.contact.email` | string | Contact email |
| `stayInfo.guestNames` | string\[] | Array of registered guest names for check-in |
| `priceInfo` | object | **\[Module]** Price and payment status |
| `priceInfo.totalPrice` | number | Total order price |
| `priceInfo.currency` | string | Settlement currency |
| `priceInfo.paymentUrl` | string/null | Web payment URL if pending payment within 30 minutes; returns `null` if paid, cancelled, or expired; omitted in Mini Program environments |
| `priceInfo.miniProgramPayInfo` | object/null | Mini Program payment object if pending payment within 30 minutes; returns `null` if paid, cancelled, or expired; omitted in Web environments |
| `priceInfo.paymentDeadline` | string/null | Payment expiration deadline (`YYYY-MM-DD HH:mm:ss`) |
| `policyInfo` | object | **\[Module]** Cancellation policy |
| `policyInfo.isCancelable` | boolean | Whether free cancellation is currently permitted |
| `policyInfo.freeCancelDeadline` | string/null | Exact deadline for penalty-free cancellation |
| `policyInfo.cancelPolicyDesc` | string | Concise summary of cancellation terms |

***

## 8. preCancelHotelBooking — Pre-Cancel Booking & Penalty Quote

### Description

Pre-cancels a hotel booking to calculate applicable cancellation penalties and obtain a **10-minute valid** confirmation voucher `confirmId`. This tool must always be called before `confirmCancelHotelBooking`.

* **Operation Hints**: `readOnlyHint: true`, `destructiveHint: false`

### Input Parameters

| Parameter | Type | Required | Description |
| :- | :-: | :-: | :- |
| `orderNo` | string | ✅ | RollingGo unique hotel order ID |

### Output

| Field | Type | Nullable | Description |
| :- | :-: | :-: | :- |
| `success` | boolean | ❌ No | Whether the API call succeeded |
| `code` | integer | ❌ No | Business status code (`2000` = success) |
| `canCancel` | boolean | ❌ No | **Core Decision Flag**: Whether online cancellation is permitted. • `true` when `penaltyAmount == 0` (free cancellation); • `false` when `penaltyAmount > 0` (penalty incurred) or non-refundable. |
| `orderNo` | string | ❌ No | Order number operated upon |
| `bookingId` | string/null | ✅ Yes | Supplier booking ID (returned only when `canCancel == true`) |
| `confirmId` | string/null | ✅ Yes | **Cancellation confirmation token** (valid for 10 minutes; returns `"UNPAID"` for unpaid orders) |
| `currency` | string | ❌ No | Currency code for penalty (e.g., `CNY`, `USD`) |
| `penaltyAmount` | number | ❌ No | Assessed penalty fee (`0` indicates free cancellation) |
| `message` | string | ❌ No | Multilingual guidance message (see matrix below) |

#### `message` Multilingual Dynamic Matrix

| Scenario | Language Code | `message` Template |
| :- | :-: | :- |
| **Free Cancellation** (`penaltyAmount == 0` or Unpaid Order) | `zh-CN` | `“查询成功，当前时段可免费取消（罚金 0.00 ${currency}）。凭证有效期 10 分钟。”` *(Unpaid: “查询成功，该订单尚未支付，可免费取消。凭证有效期 10 分钟。”)* |
| | `en` | `"Query successful. Free cancellation is currently available (Penalty: 0.00 ${currency}). Confirmation valid for 10 minutes."` |
| | `ja` | `"照会に成功しました。現在無料キャンセルが可能です（キャンセル料：0.00 ${currency}）。確認コードの有効期限は10分間です。"` |
| **Penalty Incurred / Non-Refundable** (`penaltyAmount > 0` or Non-Refundable Rate) | `zh-CN` | `“该订单取消将产生罚金（${penaltyAmount} ${currency}），按规则无法在线取消，如需取消请联系客服处理（客服电话：0755-36847480 / +852 30023293，客服邮箱：cs.hotel@rollinggo.cn）。”` |
| | `en` | `"Cancelling this booking will incur a penalty of ${penaltyAmount} ${currency}. Online cancellation is not supported per policy. Please contact customer service (Phone: 0755-36847480 / +852 30023293, Email: cs.hotel@rollinggo.cn)."` |
| | `ja` | `"この予約をキャンセルすると、キャンセル料（${penaltyAmount} ${currency}）が発生するため、オンラインでのキャンセルはできません。カスタマーサポートまでご連絡ください（電話：0755-36847480 / +852 30023293、メール：cs.hotel@rollinggo.cn）。"` |

> **Customer Service Specification**: Phone: `0755-36847480 / +852 30023293`; Email is strictly segregated by business line: Hotel service uses **`cs.hotel@rollinggo.cn`** (Flight service uses `cs.flight@rollinggo.cn`).

#### Example Output ①: Free Cancellation Available (English)

```json theme={null}
{
  "success": true,
  "code": 2000,
  "canCancel": true,
  "orderNo": "H178969986438480851",
  "bookingId": "H178969986438480851",
  "confirmId": "UNPAID",
  "penaltyAmount": 0,
  "message": "Query successful. Free cancellation is currently available (Penalty: 0.00 CNY). Confirmation valid for 10 minutes."
}
```

#### Example Output ②: Non-Refundable / Penalty Incurred (English)

```json theme={null}
{
  "success": false,
  "canCancel": false,
  "orderNo": "H178901055708172341",
  "confirmId": null,
  "currency": "USD",
  "penaltyAmount": 120.0,
  "message": "Cancelling this booking will incur a penalty of 120.00 USD. Online cancellation is not supported per policy. Please contact customer service (Phone: 0755-36847480 / +852 30023293, Email: cs.hotel@rollinggo.cn)."
}
```

***

## 9. confirmCancelHotelBooking — Confirm & Execute Cancellation

### Description

Executes the irreversible final cancellation of a hotel booking using `confirmId` and `bookingId` obtained from `preCancelHotelBooking`. Explicit user confirmation is required prior to calling.

* **Operation Hints**: `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: true`

### Input Parameters

| Parameter | Type | Required | Description |
| :- | :-: | :-: | :- |
| `orderNo` | string | ✅ | Order ID returned from `preCancelHotelBooking` |
| `bookingId` | string | ✅ | Supplier booking ID (`bookingId`) from `preCancelHotelBooking` |
| `confirmId` | string | ✅ | 10-minute cancellation confirmation voucher from `preCancelHotelBooking` |
| `description` | string | ❌ | Optional cancellation reason or remarks |

### Output

| Field | Type | Nullable | Description |
| :- | :-: | :-: | :- |
| `success` | boolean | ❌ No | Whether the cancellation succeeded |
| `code` | integer | ❌ No | Business status code (`2000` = success) |
| `message` | string | ❌ No | Cancellation outcome message |
| `orderNo` | string | ❌ No | Successfully cancelled order ID |

#### `message` Multilingual Rules

* **Chinese (`zh-CN`)**: `“订单 ${orderNo} 已成功取消。”`
* **English (`en`)**: `"Booking ${orderNo} has been successfully cancelled."`
* **Japanese (`ja`)**: `"予約 ${orderNo} のキャンセルが完了しました。"`

#### Example Output

```json theme={null}
{
  "success": true,
  "code": 2000,
  "message": "Booking H178969986438480851 has been successfully cancelled.",
  "orderNo": "H178969986438480851"
}
```

***

## 10. Unified Error Codes & Exception Mapping

| Code (`code`) | HTTP Status | Error Enum | Description | Client / Agent Action |
| :- | :-: | :- | :- | :- |
| `2000` | 200 | `SUCCESS` | Operation succeeded | Render success card and message |
| `6001` | 403 | `BOOKING_FORBIDDEN` | Order does not exist or belongs to another user | Prompt user to check order number |
| `6201` | 400 | `PRICE_CONFIRM_FAILED` | Price verification failed / room sold out | Guide user to search alternative rooms |
| `6207` | 400 | `CONFIRM_ID_EXPIRED` | Cancellation voucher expired (> 10 mins) | Re-invoke `preCancelHotelBooking` for a fresh token |
| `6301` | 400 | `BOOKING_NON_CANCELABLE` | Online cancellation disallowed by policy | Display customer service phone and email |
| `6302` | 502 | `SUPPLIER_CANCEL_FAILED` | Upstream supplier cancellation error | Suggest retry or contact support |

***

*Maintained by: RollingGo Open Platform Engineering Team*\
*Last Updated: 2026-10-16*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.