> ## 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.

# Overview

## 1. Overview & Core Differences of the Two Integration Modes

The RollingGo Hotel Open Platform provides two core integration patterns for partners: **Redirect Mode** and **In-Agent Closed-Loop Mode**:

### Core Differences Comparison

| Comparison Dimension | Redirect Mode | In-Agent Closed-Loop Mode |
| :- | :- | :- |
| **Available Tools** | **3 Tools** (Search tags, hotel search, hotel details) | **9 Tools** (From search, price locking, booking, payment, to post-sales cancellation) |
| **Agent Core Role** | Search & recommendation only; pushes booking link cards | Guides users through "Search → Details → Lock → Book → Pay → Order Query → Safe Cancellation" full flow |
| **Booking & Payment Surface** | User clicks and redirects to **RollingGo H5 / WeChat Mini Program** to complete order | Order created within Agent chat; user clicks **Cashier `paymentUrl`** to pay |
| **Price Lock Capability** | ❌ No price locking | ✅ Supported via `hotelPriceConfirm` (30-minute lock) with guest profile prefill |
| **Order Management** | User checks orders via OpenAPI / Mini Program / H5 | ✅ Supported via `searchHotelOrders` (summary list) & `getHotelOrderDetail` (structured vouchers) |
| **Cancellation Capability** | ❌ User handles cancellation via Mini Program / H5 | ✅ **Supported via Two-Phase Safe Cancellation** (`preCancelHotelBooking` penalty quote + `confirmCancelHotelBooking` execution) |
| **Integration Cost** | Minimal | Standard |
| **Recommended Scenarios** | • Info search / price comparison aggregators • Lightweight routing & referral plugins • Non-transactional conversational assistants | • Commercial AI travel assistants • Brand official conversational booking apps • High-conversion transactional agents |

***

## 2. Mode 1: Redirect Mode (Query Only, bookingUrl Handles Booking)

### Interaction Characteristics

1. The Agent invokes only 3 query tools: `getHotelSearchTags`, `searchHotels`, and `getHotelDetail`;
2. The Agent does not create bookings or initiate payments; its capability stops at "search recommendation → push booking link";
3. The user clicks `bookingUrl` on the card to redirect to the RollingGo H5 page or Mini Program to select rooms, fill in personal details, and complete payment.

### Redirect Mode Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor User as "End User"
    participant Agent as "AI Agent Client"
    participant RG as "RollingGo MCP Service"
    participant H5 as "RollingGo H5 / Mini Program"
    participant Pay as "Payment Channels (WeChat / Alipay)"

    User->>Agent: "Find 5-star hotels near the Bund in Shanghai for 1 night tomorrow"
    Agent->>RG: searchHotels(Shanghai, The Bund, 5-Star)
    RG-->>Agent: Returns hotel list (including bookingUrl)
    Agent-->>User: Recommends hotel list with booking cards

    User->>Agent: "I choose the first one, help me book it"
    Agent-->>User: "Here is your booking entry, please click the link to complete your order:"
    Agent->>User: Sends bookingUrl link card

    User->>H5: Clicks link to open H5 / Mini Program
    User->>H5: Selects room rate plan, enters guest info, submits order
    User->>Pay: Completes payment within H5 cashier
    Pay-->>H5: Payment successful
    H5-->>User: Displays order confirmation and check-in voucher

    Note over User, Agent: Order Management - Redirect Mode has no order tools, and Agent guides user to check in Mini Program
```

***

## 3. Mode 2: In-Agent Closed-Loop Mode (Full In-Chat Transactional Loop)

### Interaction Characteristics

1. Utilizes all **9 Tools** for a complete closed loop from information discovery, price locking, booking, payment, order inspection, to post-sales cancellation;
2. **Price & Room Locking**: Calls `hotelPriceConfirm` before booking to lock real-time price and inventory for 30 minutes, preventing price slippage, while returning intelligent guest profile (`guestProfile`);
3. **Secure Cashier Payment**: Issues a secure cashier link (`paymentUrl`) upon booking creation for seamless and compliant user checkout;
4. **Full Lifecycle Order Management**: Users can query booking summaries (`searchHotelOrders`) and inspect detailed check-in vouchers, navigation coordinates, and policies (`getHotelOrderDetail`) anytime in chat;
5. **Two-Phase Safe Cancellation Mechanism (Quote-Execute Pattern)**: Adds `preCancelHotelBooking` to assess cancellation penalties and issue a **10-minute valid token** (`confirmId`). After explicit user confirmation, `confirmCancelHotelBooking` executes final irreversible cancellation. Orders with penalties or non-refundable terms are seamlessly routed to customer service.

### Closed-Loop Mode Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor User as "End User"
    participant Agent as "AI Agent Client"
    participant MCP as "RollingGo MCP Service"
    participant Cashier as "Dida Secure Cashier"

    Note over User, Cashier: Stage 1 - Multilingual & Multi-Currency Search
    User->>Agent: "Find 4-star+ hotels near Xixi Wetland under 800 RMB"
    Agent->>MCP: searchHotels(place="Xixi Wetland", hotelTags={maxPricePerNight:800})
    MCP-->>Agent: Returns hotel recommendations (supporting multilingual & real-time FX)
    Agent-->>User: Displays structured hotel list with reference starting prices

    Note over User, Cashier: Stage 2 - View Details & Precision Room Filtering
    User->>Agent: "Show FlyZoo Hotel, only rooms with double breakfast and free cancellation"
    Agent->>MCP: getHotelDetail(hotelId=102906, filter={mealType:"DOUBLE_BREAKFAST", cancelable:"CANCELABLE"})
    MCP-->>Agent: Server-side precision filtering, returns matched roomRatePlans
    Agent-->>User: Displays filtered room rate plans with amenities

    Note over User, Cashier: Stage 3 - Real-Time Price Verification & Locking (30-min Lock)
    User->>Agent: "Book this Executive King Room"
    Agent->>MCP: hotelPriceConfirm(hotelID=102906, ratePlanID="RP_992019_DELUXE_BF2")
    MCP-->>Agent: Verifies inventory, returns referenceNo + locked price + guestProfile
    Agent-->>User: Confirms final price and policies, requests guest information

    Note over User, Cashier: Stage 4 - Booking Creation & Cashier Payment
    User->>Agent: "Confirm booking, guest: San Zhang, phone: 13800138000"
    Agent->>MCP: createHotelBookingWithPaymentURL(referenceNo, contact, guestList)
    MCP-->>Agent: Creates booking, returns orderNo + paymentUrl
    Agent-->>User: Returns order number and payment link, guides user to pay within 30 minutes

    User->>Cashier: Clicks paymentUrl and completes payment in Dida Cashier
    Cashier-->>User: Payment successful, check-in voucher issued

    Note over User, Cashier: Stage 5 - Order Query & Check-In Voucher
    User->>Agent: "Check the hotel order I just placed and show me the address"
    Agent->>MCP: getHotelOrderDetail(orderNo="H178969795522549201")
    MCP-->>Agent: Returns full order details (voucher, GPS coordinates, front desk phone)
    Agent-->>User: Displays structured order details card

    Note over User, Cashier: Stage 6 - Two-Phase Safe Cancellation Flow
    User->>Agent: "Something came up and I can't travel tomorrow, please cancel my reservation"
    Agent->>MCP: preCancelHotelBooking(orderNo="H178969795522549201")
    MCP-->>Agent: Penalty=0, issues 10-minute confirmId: "CNF_...", canCancel=true
    Agent-->>User: "Free cancellation is currently available. Confirm token is valid for 10 minutes. Do you confirm cancellation?"
    User->>Agent: "Yes, please cancel it"
    Agent->>MCP: confirmCancelHotelBooking(orderNo, bookingId, confirmId)
    MCP-->>Agent: Execution successful (success=true, code=2000)
    Agent-->>User: Confirms booking cancellation and full refund initiation
```

***

## 4. Account Provisioning & Credential Acquisition Channels

Partners can obtain access credentials through the following two channels:

### Channel 1: Self-Service Portal Application (Instant Online Onboarding)

* 🇨🇳 **China Portal (Chinese)**: [https://partner.rollinggo.cn](https://partner.rollinggo.cn)
* 🌐 **Global Portal (English)**: [https://partner.rollinggo.ai](https://partner.rollinggo.ai)

> Sign up and log in to the Partner Console to create applications and generate credentials instantly.

### Channel 2: Managed Account Provisioning by Operations (Enterprise & VIP Custom Channel)

* **Target Audience**: Strategic business partners, enterprise contract clients, and special developers.
* **Provisioning Method**: The RollingGo operations team directly creates and configures accounts in the admin console, securely delivering credentials offline:
  * **API Key Mode Deliverables**: Dedicated `API Key` (format `mcp_xxxxx...`) and assigned service endpoints;
  * **OAuth 2.1 Mode Deliverables**: `clientId`, `clientSecret`, and pre-registered callback configuration.
* **Fast Track**: Partners who receive credentials directly from operations **do not need to register online again**; proceed directly to [5. Service Nodes & Integration Endpoints](#5-service-nodes--integration-endpoints) and [6. Agent Client Configuration Examples](#6-agent-client-configuration-examples).

***

### Authentication Modes Overview

#### 1. API Key Mode (Recommended · Fast Integration)

* **Use Cases**: Developer tools, Claude CLI / Desktop, self-hosted enterprise agents, automated backend workflows.
* **Request Authentication**: HTTP Request Header carries `Authorization: Bearer <API_KEY>`.

#### 2. OAuth 2.1 Mode (End-User Authorization)

* **Use Cases**: Consumer-facing client apps, web applications, multi-tenant SaaS platforms.
* **Key Configuration**: Requires configured PKCE redirect endpoints (Web `redirect_uri` or local client loopback `callbackPort`).
* **Request Authentication**: Standard OAuth 2.1 Authorization Code Flow with PKCE to obtain user-level Access Tokens.

***

## 5. Service Nodes & Integration Endpoints

RollingGo provides dual service nodes for users in Mainland China and globally. The endpoint URLs are as follows:

| Service Node | Auth Mode | Endpoint URL | Default Language & Currency | Core Characteristics |
| :- | :- | :- | :- | :- |
| **China Production Node** | **API Key Mode** | `https://mcp.rollinggo.cn/mcp` | Chinese (`zh-CN`) / CNY (`CNY`) | Fixed Chinese & CNY; `placeType` uses Chinese enums; email is required |
| **China Production Node** | **OAuth 2.0 Mode** | `https://mcp.rollinggo.cn/mcp/hotel` | Chinese (`zh-CN`) / CNY (`CNY`) | User-bound token; natural cross-tenant isolation |
| **Global Production Node** | **API Key Mode** | `https://mcp.rollinggo.ai/mcp` | English (`en`) / USD (`USD`) | Supports `localeParam: { currency, language }` (25 currencies / EN, ZH, JA); email optional |
| **Global Production Node** | **OAuth 2.0 Mode** | `https://mcp.rollinggo.ai/mcp/hotel` | English (`en`) / USD (`USD`) | Global end-user OAuth login system |

***

## 6. Agent Client Configuration Examples

### 6.1 API Key Mode Configuration (Claude Desktop / Claude CLI)

Create or update `.mcp.json` (or `claude_desktop_config.json`) in project root or global configuration:

```jsonc theme={null}
{
  "mcpServers": {
    "rollinggo-hotel": {
      "type": "http",
      // Use https://mcp.rollinggo.cn/mcp for China, or https://mcp.rollinggo.ai/mcp for Global
      "url": "https://mcp.rollinggo.ai/mcp",
      "headers": {
        "Authorization": "Bearer mcp_your_api_key_here"
      }
    }
  }
}
```

Add in one command via Claude CLI:

```bash theme={null}
claude mcp add \
  --transport http \
  --header "Authorization: Bearer mcp_your_api_key_here" \
  RollingGo-Hotel \
  https://mcp.rollinggo.ai/mcp
```

### 6.2 OAuth Mode Configuration (Claude Code / Web Client)

```jsonc theme={null}
{
  "mcpServers": {
    "rollinggo-hotel": {
      "type": "http",
      "url": "https://mcp.rollinggo.cn/mcp/hotel",
      "oauth": {
        "clientId": "your-client-id",
        // Local client uses loopback port; Web client configures redirect_uri
        "callbackPort": 55082
      }
    }
  }
}
```

***


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