简体中文

English

简体中文

English

主题

Tourmind Hotel Distribution API - TMS API (2.0) ​

下载 OpenAPI 规范: 下载

TMS API.

总体概述 ​

欢迎阅读 TourMind 开发者文档。本指南提供了将 TourMind 集成到您的应用程序中所需的所有信息。无论您是在寻找酒店预订流程还是 AI 驱动的解决方案，我们都能满足您的需求。

主要特点 ​
  • 酒店 API：提供一套全面的 API，旨在简化酒店预订流程。
  • TourMind AI API：通过算法实现房型匹配、房型聚类和房价预测，帮助优化定价策略，提升可售房库存利用率。
技术规格 ​
  • 代理与 TourMind API 的所有通信均通过 HTTP POST 进行。
  • 请求有效负载的格式基于 JSON。
  • 所有请求都应接受 GZIP 编码，并且所有响应都以 GZIP 格式返回。
  • 所有请求都包含一个通用请求标头，其中包含身份验证信息。

API开发流程 ​

workflow_CN

更新日志 ​

版本日期说明
v1.0.12023.05.01接口文档初稿
v2.0.12023.05.25酒店接口字段调整
v2.0.22026.03.19新增按日期查询订单列表接口(Query Bookings)；查询订单响应新增字段(HotelCode, RoomCount, CheckIn, CheckOut, PaxRooms, Contact, ContactPhone, BookingTime)
v2.0.32026.08.14验价(Prebook)响应的 MealType 餐食表与搜价(Search)对齐；补充说明每个房间对象的第一个入住人为主入住人

认证 ​

1. 公共请求字段 ​

所有请求都需要一个名为 RequestHeader 的公共字段，其中必须提供账户信息。示例：

json
{
    "AgentCode": "your agent code",
    "UserName": "your username",
    "Password": "your password",
    "RequestTime": "2018-07-26T09:51:32.999Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

2. Http Header ​

请在 Http header 中添加以下两个项目：

  • X-Agent-Code: your agent code
  • X-Username: your username

3. 测试环境凭证 ​

API 测试凭证
AgentCodetms_test
UserNametms_test
Passwordtms_test

搜索 & 预订 ​

搜索指定酒店的房间价格与可用房态，使用户能够查看详细的房间空余情况及定价信息。

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/HotelDetail
请求方式POST
请求字段
CheckIn: string
入住日期，格式 “2006-01-02”
CheckOut: string
退房日期，格式 “2006-01-02”
HotelCodes[]: integer
Tourmind Hotel Id，此请求中最多支持20个ID查询
IsDailyPrice: boolean
是否需要每日价格
Nationality: string
国籍
Timeout: integer
请求超时时间，单位毫秒
响应字段
json
{
  "CheckIn": "2018-08-25",
  "CheckOut": "2018-08-26",
  "HotelCodes": [],
  "Nationality": "CN",
  "PaxRooms": [
    {
      "Adults": 4,
      "Children": 5,
      "ChildrenAges": [],
      "RoomCount": 2
    }
  ],
  "Timeout": 6000,
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  }
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "Hotels": [
    {
      "CheckIn": "2018-08-25",
      "CheckOut": "2018-08-26",
      "HotelCode": "740650",
      "RoomTypes": [
        {
          "Name": "Suite 3 bedrooms",
          "NameCN": "三床房",
          "RateInfos": [
            {
              "Allotment": 2,
              "CancelPolicyInfos": [
                {}
              ],
              "CurrencyCode": "CNY",
              "DailyPriceInfo": [
                {}
              ],
              "MealInfo": {
                "MealCount": 2,
                "MealType": "breakfast"
              },
              "Name": "SUITE THREE BEDROOMS",
              "RateCode": "13800206",
              "TotalPrice": 688.88
            }
          ],
          "RoomTypeCode": "4613"
        }
      ]
    }
  ],
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

验价 ​

检查所选特定房价的空房情况和价格，通常在用户选择要预订的房间并提交预订时请求

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/CheckRoomRate
请求方式POST
请求字段
CheckIn: string
入住日期，格式 “2006-01-02”
CheckOut: string
退房日期，格式 “2006-01-02”
HotelCodes[]: integer
Tourmind Hotel Id，此请求中仅需要1个ID
Nationality: string
国籍
RateCode: string
途灵价格计划 ID
TotalPrice: number
SearchResponse中返回的总价
响应字段
json
{
  "CheckIn": "2018-08-25",
  "CheckOut": "2018-08-26",
  "HotelCodes": [],
  "Nationality": "CN",
  "PaxRooms": [
    {
      "Adults": 4,
      "Children": 5,
      "ChildrenAges": [],
      "RoomCount": 2
    }
  ],
  "RateCode": "13800206",
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  },
  "TotalPrice": 688.88
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "Hotels": [
    {
      "CheckIn": "2018-08-25",
      "CheckOut": "2018-08-26",
      "HotelCode": "740650",
      "RoomTypes": [
        {
          "Name": "Suite 3 bedrooms",
          "NameCN": "三床房",
          "RateInfos": [
            {
              "Allotment": 2,
              "CancelPolicyInfos": [
                {}
              ],
              "CurrencyCode": "CNY",
              "DailyPriceInfo": [
                {}
              ],
              "MealInfo": {
                "MealCount": 2,
                "MealType": "breakfast"
              },
              "Name": "SUITE THREE BEDROOMS",
              "RateCode": "13800206",
              "TotalPrice": 688.88
            }
          ],
          "RoomTypeCode": "4613"
        }
      ]
    }
  ],
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

创建订单 ​

注意：如果请求超时或返回 PENDING 状态，请轮询查询订单接口以获取预订的最终状态。

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/CreateOrder
请求方式POST
请求字段
AgentRefID: string
唯一的代理商参考ID，用于识别预订，最长128; 注意！重复使用AgentRefID将不会创建新的订单，而是返回原始的订单
CheckIn: string
入住日期，格式 “2006-01-02”
CheckOut: string
退房日期，格式 “2006-01-02”
CurrencyCode: string
货币编码
HotelCode: integer
Tourmind Hotel Id，此请求中仅需要1个ID
RateCode: string
途灵价格计划 ID
SpecialRequest: string
客户特殊要求
TotalPrice: number
从CheckRoomRateResponse返回的预订总价
响应字段
ReservationID: string
途灵订单号
json
{
  "AgentRefID": "213415",
  "CheckIn": "2018-08-15",
  "CheckOut": "2018-08-18",
  "ContactInfo": {
    "Email": "xxx@google.com",
    "FirstName": "Tom",
    "LastName": "Lee",
    "PhoneNo": "1521777777"
  },
  "CurrencyCode": "CNY",
  "HotelCode": 235113,
  "PaxRooms": [
    {
      "Adults": 2,
      "Children": 0,
      "ChildrenAges": [],
      "PaxNames": [
        {
          "FirstName": "Tom",
          "LastName": "Lee",
          "Type": "ADU"
        }
      ],
      "RoomCount": 1
    }
  ],
  "RateCode": "2132151",
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  },
  "SpecialRequest": "Non-smoking room",
  "TotalPrice": 88.88
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "OrderInfo": {
    "OrderStatus": "CONFIRMED",
    "ReservationID": "10470379"
  },
  "ReservationID": "10470379",
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

取消订单 ​

发送取消订单请求以取消可退款预订和待处理的预订

注意：如果请求超时或返回错误，请轮询查询订单接口以获取预订的最终状态。

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/CancelOrder
请求方式POST
请求字段
AgentRefID: string
代理在CreateOrder请求中提供的代理参考ID，最长128
响应字段
json
{
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  }
}
json
{
  "CancelResult": {
    "CancelFee": 42,
    "CurrencyCode": "CNY",
    "OrderStatus": "CANCELLED"
  },
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

查询订单 ​

搜索订单以检查预订过程中的订单状态

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/SearchOrder
请求方式POST
请求字段
AgentRefID: string
CreateOrder请求中提供的代理参考ID，最长128
响应字段
json
{
  "AgentRefID": "21345555",
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  }
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "OrderInfo": {
    "AgentRefID": "1365422",
    "CurrencyCode": "CNY",
    "HotelConfirmationNo": "10470374",
    "OrderStatus": "CANCELLED",
    "ReservationID": "10470374",
    "TotalPrice": 888.89,
    "HotelCode": 0,
    "RoomCount": 0,
    "CheckIn": "2020-01-01",
    "CheckOut": "2020-01-02",
    "PaxRooms": [
      {
        "Adults": 2,
        "Children": 0,
        "ChildrenAges": [],
        "PaxNames": [
          {
            "FirstName": "Tom",
            "LastName": "Lee",
            "Type": "ADU"
          }
        ],
        "RoomCount": 1
      }
    ],
    "BookingTime": "2020-01-03 12:00:00"
  },
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

查询订单列表 ​

按日期范围分页查询订单列表。可按入住日期、退房日期或预订日期筛选订单。实际请求地址为 POST /v2/SearchOrder（与查询单个订单相同的URL，但使用不同的请求参数）。

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/SearchOrder
请求方式POST
请求字段
DateType: string
日期类型，可选值：CheckIn（入住日期）、CheckOut（退房日期）、Booking（预订日期）。
From: string
查询范围的开始日期，格式 YYYY-MM-DD。日期跨度（To减去From）不超过31天。
To: string
查询范围的结束日期，格式 YYYY-MM-DD。日期跨度（To减去From）不超过31天。
Page: integer
分页页码，必须 >= 1。
PageSize: integer
每页数量，范围 1-500。
响应字段
json
{
  "DateType": "CheckIn",
  "From": "2024-01-01",
  "To": "2024-01-31",
  "Page": 1,
  "PageSize": 50,
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  }
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "OrderList": {
    "OrderList": [
      {
        "AgentRefID": "1365422",
        "CurrencyCode": "CNY",
        "HotelConfirmationNo": "10470374",
        "OrderStatus": "CANCELLED",
        "ReservationID": "10470374",
        "TotalPrice": 888.89,
        "HotelCode": 0,
        "RoomCount": 0,
        "CheckIn": "2020-01-01",
        "CheckOut": "2020-01-02",
        "PaxRooms": [
          {
            "Adults": 2,
            "Children": 0,
            "ChildrenAges": [],
            "PaxNames": [
              {
                "FirstName": "Tom",
                "LastName": "Lee",
                "Type": "ADU"
              }
            ],
            "RoomCount": 1
          }
        ],
        "BookingTime": "2020-01-03 12:00:00"
      }
    ],
    "Page": 1,
    "PageSize": 50,
    "Total": 100
  },
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

静态数据 ​

MealCode ​

餐食代码

MealCodeDescription
1不含餐
2早餐
3午餐
4晚餐
5午餐和晚餐
6半膳
7全膳
8全包
9自炊式（住宿）

酒店列表 ​

获取酒店静态数据

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/HotelStaticList
请求方式POST
请求字段
CountryCode: string
国家编码
HotelIds[]: integer
查找某些酒店
Lang: string
语言，zh-CN、en-US
响应字段
json
{
  "CountryCode": "CN",
  "HotelIds": [],
  "Lang": "zh-CN",
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 10
  },
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  }
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "HotelStaticListResult": {
    "Hotels": [
      {
        "Address": "3007 Santa Monica Blvd, 90404",
        "AmenitiesHotel": [
          {
            "name": "Golfing nearby"
          }
        ],
        "AmenitiesRoom": [
          {
            "name": "Golfing nearby"
          }
        ],
        "CityCode": "14209",
        "CityName": "ShangHai",
        "CityNameCN": "上海",
        "CountryCode": "CN",
        "Description": {
          "Attractions": "Qijang Park - 1 km / 0.6 mi. Xingzhong Plaza - 1 km / 0.6 mi.",
          "BusinessAmenities": "Featured amenities include a business center, limo/town car service, and express check-in.",
          "Headline": "In Zhongshan (West District)",
          "Location": "You'll be centrally located in Zhongshan, within a 15-minute walk of Qijang Park and Xingzhong Plaza.",
          "Rooms": "Make yourself at home in one of the 362 air-conditioned rooms featuring refrigerators and LCD televisions."
        },
        "HotelId": "739315",
        "Images": [
          {
            "links": {}
          }
        ],
        "Latitude": "34.03644",
        "Longitude": "-118.47048",
        "Name": "Days Inn Santa Monica/Los Angeles",
        "Phone": "1523333333",
        "StarRating": "5"
      }
    ],
    "Pagination": {
      "PageCount": 1,
      "TotalCount": 10
    }
  },
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

区域列表 ​

获取地区列表

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/RegionList
请求方式POST
请求字段
CountryCode: string
国家编码
响应字段
json
{
  "CountryCode": "CN",
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 10
  },
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  }
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "RegionListResult": {
    "Regions": [
      {
        "CountryCode": "231",
        "Name": "ShangHai",
        "NameCN": "上海",
        "RegionID": "21312541",
        "RegionNameLong": "Shanghai, China",
        "RegionNameLongCN": "上海，中国"
      }
    ]
  },
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

酒店房型数据 ​

获取酒店全量房型数据

接口调用信息

名称值
请求地址http://developers.tourmind.cn/v2/RoomStaticList
请求方式POST
请求字段
HotelCode: integer
酒店ID
响应字段
json
{
  "RequestHeader": {
    "AgentCode": "tms_test",
    "Password": "tms_test",
    "RequestTime": "2018-07-26T09:51:32.123Z",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "UserName": "tms_test"
  }
}
json
{
  "Error": {
    "ErrorCode": "101",
    "ErrorMessage": "invaild param"
  },
  "ResponseHeader": {
    "ResponseTime": "2018-07-26 09:51:32",
    "TransactionID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  },
  "RoomTypes": [
    {}
  ]
}

验收 ​

请完成测试用例表（Test Cases）中的所有测试用例。

附件 ​

信息问卷表(点击下载)

测试用例表(点击下载)