第一部分 · 接口接入说明
1.1 接口公约
| 项目 | 约定 |
| 协议 | HTTPS(生产)/ HTTP(测试),统一 POST |
| Content-Type | application/json; charset=UTF-8 |
| 网关根路径 | /base,部署在 tmc-openapi 服务,默认端口 8090 |
| 鉴权方式 | 除「获取 Token」外,所有接口请求头需携带 Authorization: Bearer {token} |
| 签名 | MD5 大写,见 1.2 |
| 时间戳 | TimeStamp 为秒级时间戳;网关只接受前后 600 秒(10 分钟)内的请求,超时返回「请求已过期」 |
| 随机数 | RandomNum 为 6 位随机数字,参与签名 |
| 返回结构 | 统一 ApiBaseResp:code / msg / data |
请求体公共字段
| 字段 | 类型 | 必填 | 说明 |
| PartnerId | String | 是 | 合作伙伴 ID(接入时分配,对应系统内 appId) |
| Sign | String | 是 | 签名,MD5 大写 |
| RandomNum | String | 是 | 6 位随机数字 |
| TimeStamp | String | 是 | 请求时间戳,单位秒 |
| Data | String | 条件 | 业务参数 JSON 字符串(注意:必须作为字符串传,不能传嵌套 JSON 对象);「获取 Token」传 "{}" 或不传 |
Data 必须传字符串。网关用 params.getString("Data") 读取,若传成 JSON 对象会导致解析失败或签名不一致。
正确示例:"Data": "{\"hotelCode\":\"10000011\"}"。
请求体示例(业务接口)
{
"PartnerId": "partner001",
"Sign": "5F2F7E2C1A4B9D8E0F3C6A1B2D4E5F7A",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"hotelCode\":\"10000011\",\"checkInDate\":\"2026-11-18\",\"checkOutDate\":\"2026-11-19\"}"
}
公共返回体 ApiBaseResp
| 字段 | 类型 | 说明 |
| code | String | 状态码,200 成功;其余见 5.2 |
| msg | String | 提示信息,成功为空字符串 |
| data | Object | 业务数据,成功时有值 |
1.2 签名与验签
签名串按下列顺序拼接:
signData = accessKey
+ (Data 非空且不等于 "{}" 时:"&DATA=" + Data)
+ "&PARTNERID=" + PartnerId
+ "&RANDOMNUM=" + RandomNum
+ "&TIMESTAMP=" + TimeStamp
sign = MD5(signData).toUpperCase()
accessKey 为接入时分配的密钥,服务端保存在 AppInfo.accessKey。
获取 Token 时 Data 视为空("{}"),即签名串不包含 &DATA= 段。
签名串示例(获取 Token,无 Data)
yourAccessKey&PARTNERID=partner001&RANDOMNUM=123456&TIMESTAMP=1763366400
签名串示例(业务接口,含 Data)
yourAccessKey&DATA={"hotelCode":"10000011","checkInDate":"2026-11-18","checkOutDate":"2026-11-19"}&PARTNERID=partner001&RANDOMNUM=123456&TIMESTAMP=1763366400
服务端验签逻辑(对应 NormController.getSignData / signVerify):
private String getSignData(AppInfo appInfo, ApiRequest apiRequest) {
String a = appInfo.getAccessKey();
if (StringUtils.isNotBlank(apiRequest.getBizParams()) && !"{}".equals(apiRequest.getBizParams())) {
a = a + "&DATA=" + apiRequest.getBizParams();
}
a = a + "&PARTNERID=" + apiRequest.getAppId()
+ "&RANDOMNUM=" + apiRequest.getRandomNum()
+ "&TIMESTAMP=" + apiRequest.getReqTime();
return a;
}
public boolean signVerify(AppInfo appInfo, ApiRequest apiRequest) {
return apiRequest.getSign().equals(DigestUtils.md5Hex(getSignData(appInfo, apiRequest)).toUpperCase());
}
开发辅助接口 /createSign
当 tmc-openapi 配置 isDevEnv: true 时,可用 POST /createSign 直接生成签名参数(仅开发/联调用,生产关闭)。
POST /createSign
Content-Type: application/json
{ "appId": "partner001", "data": "{\"hotelCode\":\"10000011\"}" }
返回 PartnerId / Sign / RandomNum / TimeStamp / Data,可直接作为业务请求体使用。
1.3 Java 调用 Demo
下面是无第三方依赖的完整示例(JDK 11+ java.net.http.HttpClient + MessageDigest)。
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
public class TmcOpenApiDemo {
private static final String BASE = "http://你的域名:8090/base";
private static final String PARTNER_ID = "partner001";
private static final String ACCESS_KEY = "yourAccessKey";
public static void main(String[] args) throws Exception {
// 1. 获取 Token
String token = getToken();
// 2. 调用业务接口(例:酒店ID列表)
String data = "{\"data\":{\"cityId\":330100,\"page\":1,\"pageSize\":10}}";
String resp = callApi("/hotel/resource/GetHotelList", token, data);
System.out.println(resp);
}
/** 获取 Token:Data 为空,签名串不含 &DATA 段 */
public static String getToken() throws Exception {
String timeStamp = String.valueOf(System.currentTimeMillis() / 1000);
String randomNum = randomNum();
String sign = sign(ACCESS_KEY, PARTNER_ID, randomNum, timeStamp, null);
String body = "{"
+ "\"PartnerId\":\"" + PARTNER_ID + "\","
+ "\"Sign\":\"" + sign + "\","
+ "\"RandomNum\":\"" + randomNum + "\","
+ "\"TimeStamp\":\"" + timeStamp + "\""
+ "}";
HttpResponse<String> r = post("/api/token", null, body);
// 简化解析:实际工程建议用 Jackson / fastjson2 解析
// 返回: {"code":"200","msg":"","data":{"expDate":"...","token":"..."}}
String dataJson = r.body();
// 从 data.token 中提取(示例���略具体 JSON 解析)
return extractToken(dataJson);
}
/** 调用业务接口,携带 Authorization: Bearer token */
public static String callApi(String path, String token, String data) throws Exception {
String timeStamp = String.valueOf(System.currentTimeMillis() / 1000);
String randomNum = randomNum();
String sign = sign(ACCESS_KEY, PARTNER_ID, randomNum, timeStamp, data);
String body = "{"
+ "\"PartnerId\":\"" + PARTNER_ID + "\","
+ "\"Sign\":\"" + sign + "\","
+ "\"RandomNum\":\"" + randomNum + "\","
+ "\"TimeStamp\":\"" + timeStamp + "\","
+ "\"Data\":" + jsonString(data)
+ "}";
return post(path, token, body).body();
}
/** 签名:data 为业务 Data 字符串,null 表示无 Data */
public static String sign(String accessKey, String partnerId,
String randomNum, String timeStamp, String data) throws Exception {
StringBuilder sb = new StringBuilder(accessKey);
if (data != null && !data.isEmpty() && !"{}".equals(data)) {
sb.append("&DATA=").append(data);
}
sb.append("&PARTNERID=").append(partnerId);
sb.append("&RANDOMNUM=").append(randomNum);
sb.append("&TIMESTAMP=").append(timeStamp);
return md5Upper(sb.toString());
}
private static HttpResponse<String> post(String path, String token, String body) throws Exception {
HttpRequest.Builder b = HttpRequest.newBuilder()
.uri(URI.create(BASE + path))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8));
if (token != null) {
b.header("Authorization", "Bearer " + token);
}
return HttpClient.newHttpClient().send(b.build(), HttpResponse.BodyHandlers.ofString());
}
private static String randomNum() {
return String.valueOf((int) ((Math.random() * 9 + 1) * 100000));
}
private static String jsonString(String s) {
return "\"" + s.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
}
private static String md5Upper(String s) throws Exception {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] bs = md.digest(s.getBytes(StandardCharsets.UTF_8));
StringBuilder hex = new StringBuilder();
for (byte b : bs) {
hex.append(String.format("%02X", b));
}
return hex.toString();
}
private static String extractToken(String body) {
// 仅示意:真实工程请用 JSON 库解析
int i = body.indexOf("\"token\":\"");
return body.substring(i + 9, body.indexOf("\"", i + 9));
}
}
第二部分 · Token 获取
POST 无需 Authorization
| 项目 | 值 |
| 路径 | /base/api/token |
| 服务名 | GET_TOKEN |
| 说明 | 获取访问 Token;Token 用于其余所有接口的 Authorization: Bearer {token} |
请求体
| 字段 | 类型 | 必填 | 说明 |
| PartnerId | String | 是 | 合作伙伴 ID |
| Sign | String | 是 | 签名(Data 视为空,不含 &DATA 段) |
| RandomNum | String | 是 | 6 位随机数字 |
| TimeStamp | String | 是 | 秒级时间戳 |
请求示例
POST /base/api/token
Content-Type: application/json
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400"
}
响应示例
{
"code": "200",
"msg": "",
"data": {
"expDate": "2026-11-18 06:00:00",
"token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}
}
返回 data 字段
| 字段 | 类型 | 说明 |
| token | String | 访问令牌,32 位无横线 UUID;调用业务接口时放 Authorization: Bearer {token} |
| expDate | String | 过期时间,格式 yyyy-MM-dd HH:mm:ss;有效期为生成时刻起 10 小时(代码 600 * 60 秒) |
Token 服务端缓存 key 为 tmcGate:tmcHotelToken:{partnerId},同一 PartnerId 有效期内重复获取会返回同一 Token。
Java 调用 Demo
// 见 1.3 中 getToken();核心步骤:
String signData = ACCESS_KEY + "&PARTNERID=" + PARTNER_ID
+ "&RANDOMNUM=" + randomNum + "&TIMESTAMP=" + timeStamp;
String sign = md5Upper(signData);
// 请求体无 Data,响应 data.token 即为后续请求的 Bearer token
第三部分 · 静态接口
本章接口的入口在 tmc-openapi(HotelStaticInfoDispatcher),业务实现类在
tmc-biz 的 tmc-static-service 工程(NormalHotelStaticInfoServiceImpl)。
响应中 data 直接就是下方各接口的业务 DTO,无额外包装。
3.1 城市列表 CITY_LIST
POST
| 项目 | 值 |
| 路径 | /base/hotel/resource/GetCityList |
| 服务名 | CITY_LIST |
入参
| 字段 | 类型 | 必填 | 说明 |
| Data | String | 是 | 传 "{}" |
业务 DTO CityRep 无字段。
出参(data 内)
| 字段 | 类型 | 说明 |
| cityList | List<CityInfo> | 城市列表 |
| cityList[].country | String | 国家(当前实现未填充) |
| cityList[].countryId | Integer | 国家 ID(当前实现未填充) |
| cityList[].province | String | 省份 |
| cityList[].provinceId | Integer | 省份 ID |
| cityList[].city | String | 城市 |
| cityList[].cityId | Integer | 城市 ID |
| cityList[].parentCityId | Integer | 父城市 ID(当前实现未填充) |
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"cityList": [
{
"country": null,
"countryId": null,
"province": "浙江省",
"provinceId": 330000,
"city": "杭州",
"cityId": 330100,
"parentCityId": null
}
]
}
}
3.2 酒店ID列表 HOTEL_BASE_QRY
POST
| 项目 | 值 |
| 路径 | /base/hotel/resource/GetHotelList |
| 服务名 | HOTEL_BASE_QRY |
入参(Data 内)
| 字段 | 类型 | 必填 | 说明 |
| data | Object | 是 | 查询参数对象 |
| data.cityId | Integer | 否 | 城市 ID;不传查全部 |
| data.page | Integer | 否 | 页码,默认 1 |
| data.pageSize | Integer | 否 | 每页条数,默认 50 |
| data.hotelGrade | List<String> | 否 | 酒店等级过滤,取值 A~F(见 5.3;当前实现未参与查询) |
入参 JSON 示例
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"data\":{\"cityId\":330100,\"page\":1,\"pageSize\":10}}"
}
出参(data 内)
| 字段 | 类型 | 说明 |
| page | Integer | 当前页码 |
| total | Integer | 总条数 |
| hotelList | List<HotelModel> | 酒店列表 |
| hotelList[].cityId | Integer | 城市 ID |
| hotelList[].cityName | String | 城市名称 |
| hotelList[].hotelId | Long | 酒店 ID(平台酒店代码) |
| hotelList[].hotelName | String | 酒店名称 |
| hotelList[].updatedTime | String | 更新时间 |
| hotelList[].isBookable | Boolean | 是否可订 |
| hotelList[].isScarce | Boolean | 是否紧张 |
| hotelList[].isAdvantage | Boolean | 是否优势 |
| hotelList[].isHighDemand | Boolean | 是否高需求 |
| hotelList[].hotelGrade | String | 酒店等级(当前实现未填充) |
| hotelList[].isSpecial | Boolean | 是否特价 |
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"page": 1,
"total": 128,
"hotelList": [
{
"cityId": 330100,
"cityName": "杭州",
"hotelId": 10000011,
"hotelName": "杭州XX大酒店",
"updatedTime": "2026-11-16T10:20:30",
"isBookable": true,
"isScarce": false,
"isAdvantage": true,
"isHighDemand": false,
"hotelGrade": null,
"isSpecial": false
}
]
}
}
3.3 酒店静态详情 HOTEL_DETAIL_QRY
POST
| 项目 | 值 |
| 路径 | /base/hotel/resource/GetHotelInfo |
| 服务名 | HOTEL_DETAIL_QRY |
入参(Data 内)
| 字段 | 类型 | 必填 | 说明 |
| data | Object | 是 | 查询参数对象 |
| data.hotelId | Long | 是 | 酒店 ID(平台酒店代码) |
入参 JSON 示例
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"data\":{\"hotelId\":10000011}}"
}
出参(data 内,HotelDetailResp)
| 字段 | 类型 | 说明 |
| isInternational | Boolean | 是否国际酒店 |
| isHuazhu | Boolean | 是否华住 |
| hotelId | Long | 酒店 ID |
| hotelName | String | 酒店名称 |
| hotelNameEn | String | 酒店英文名 |
| cityId | String | 城市 ID |
| cityName | String | 城市名称 |
| prefectureLevelCityId | String | 地级市 ID(当前实现未填充) |
| prefectureLevelCityName | String | 地级市名称(当前实现未填充) |
| geo | GeoModel | 经纬度 |
| geo.lat | BigDecimal | 纬度 |
| geo.lon | BigDecimal | 经度 |
| geo.name | String | 名称(当前实现未填充) |
| openYear | String | 开业年份 |
| renovationYear | String | 翻修年份 |
| address | String | 地址 |
| adjacentIntersection | String | 邻近路口(当前实现未填充) |
| logUrl | String | logo 地址(当前实现未填充) |
| imageAmount | Integer | 图片数量(当前实现未填充) |
| starRating | Integer | 星级 |
| starRateDesc | String | 星级描述 |
| districtCode | String | 商圈代码(当前实现未填充) |
| district | String | 行政区 |
| business | String | 商圈 |
| reviewGoodRate | BigDecimal | 好评率(当前实现未填充) |
| reviewScore | BigDecimal | 评分(当前实现未填充) |
| telephoneNum | String | 电话 |
| facilityList | List<Long> | 设施列表(当前实现未填充) |
| hasCollection | Boolean | 是否收藏(当前实现未填充) |
| inOutDesc | String | 入住离店说明(当前实现未填充) |
| brandCode | String | 品牌代码(当前实现未填充) |
| brandName | String | 品牌名称(当前实现未填充) |
| specialTips | String | 特别提示(当前实现未填充) |
| reviewScoreDesc | String | 评分描述(当前实现未填充) |
| hotelTypeDesc | String | 酒店类型描述(当前实现未填充) |
| hotelLabels | String | 酒店标签(当前实现未填充) |
| isProtocol | Boolean | 是否协议 |
| hotelSource | String | 酒店来源(当前实现未填充) |
| invoiceType | Integer | 发票类型(当前实现未填充) |
| hotelImages | HotelImgList | 酒店图片(当前实现未填充) |
| guestType | Integer | 宾客类型 |
| isBookable | Boolean | 是否可订 |
| isScarce | Boolean | 是否紧张 |
| isAdvantage | Boolean | 是否优势 |
| isHighDemand | Boolean | 是否高需求 |
| isSpecial | Boolean | 是否特价 |
| mappingHotels | List<MappingHotelModel> | 映射酒店(当前实现未填充) |
| transportationInfos | List<TransportationInfo> | 交通信息(当前实现未填充) |
带「当前实现未填充」的字段在 DTO 中已定义,但 NormalHotelStaticInfoServiceImpl 尚未赋值,实际返回为 null,对接时请勿依赖。
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"isInternational": false,
"isHuazhu": false,
"hotelId": 10000011,
"hotelName": "杭州XX大酒店",
"hotelNameEn": null,
"cityId": "330100",
"cityName": "杭州",
"prefectureLevelCityId": null,
"prefectureLevelCityName": null,
"geo": {
"lat": 30.2741,
"lon": 120.1551,
"name": null
},
"openYear": "2018",
"renovationYear": "2022",
"address": "杭州市西湖区XX路1号",
"starRating": 5,
"starRateDesc": "五星级",
"district": "西湖区",
"business": "西湖商圈",
"telephoneNum": "0571-88888888",
"isProtocol": true,
"guestType": 1,
"isBookable": true,
"isScarce": false,
"isAdvantage": true,
"isHighDemand": false,
"isSpecial": false,
"mappingHotels": null,
"transportationInfos": null
}
}
第四部分 · 酒店预订场景接口
本章接口的入口在 tmc-openapi(HotelOpenApiDispatcher),业务实现类在
tmc-biz 的 tmc-biz-service 工程(OpenApiHotelServiceImpl → 各 Logic)。
本章响应结构比静态接口多一层包装。响应 data 是 OpenApiBaseResp
(success / errorMsg / data / traceId),真正的业务数据在 data.data 里。
{
"code": "200",
"msg": "",
"data": {
"success": true,
"errorMsg": null,
"data": { /* 真正的业务数据 */ },
"traceId": "uuid"
}
}
4.1 房型实时报价 ROOM_RATE
POST
| 项目 | 值 |
| 路径 | /base/hotel/resource/GetHotelRoomRateList |
| 服务名 | ROOM_RATE |
入参(Data 内)
| 字段 | 类型 | 必填 | 说明 |
| hotelCode | String | 是 | 酒店代码 |
| checkInDate | String | 是 | 入住日期,yyyy-MM-dd |
| checkOutDate | String | 是 | 离店日期,yyyy-MM-dd |
| param | Object | 否 | 内部渠道参数,服务端会覆盖,下游无需传 |
入参 JSON 示例
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"hotelCode\":\"10000011\",\"checkInDate\":\"2026-11-18\",\"checkOutDate\":\"2026-11-19\"}"
}
出参 data.data(RoomType)
| 字段 | 类型 | 说明 |
| hotelId | String | 酒店代码 |
| checkInDate | String | 入住日期 |
| checkOutDate | String | 离店日期 |
| roomInfos | List<RoomInfo> | 房型列表 |
| roomInfos[].roomId | String | 房型代码(平台内部 md5) |
| roomInfos[].roomName | String | 房型名称 |
| roomInfos[].roomImag | List<String> | 房型图片 |
| roomInfos[].bedType | String | 床型 |
| roomInfos[].windowType | String | 窗型 |
| roomInfos[].floor | String | 楼层 |
| roomInfos[].area | String | 面积 |
| roomInfos[].ratePlans | List<RatePlan> | 价格计划列表 |
| ratePlans[].ratePlanId | String | 价格计划 ID(下单/验价要用) |
| ratePlans[].ratePlanName | String | 价格计划名称 |
| ratePlans[].breakfast | String | 早餐 |
| ratePlans[].cancelPolicy | CancelPolicyInfo | 取消规则 |
| cancelPolicy.cancelRule | String | 取消规则:0-不可取消,1-限时免费取消 |
| cancelPolicy.lastCancelTime | String | 最晚取消时间 yyyy-MM-dd HH:mm:ss |
| cancelPolicy.cancelRuleDec | String | 取消规则描述 |
| ratePlans[].invoiceMode | String | 发票类型:S-专票,G-普票 |
| ratePlans[].isInstantConfirm | String | 是否立即确认 |
| ratePlans[].minAmount | Integer | 最小间数限制 |
| ratePlans[].maxAmount | Integer | 最大间数限制 |
| ratePlans[].person | Integer | 房间最大入住人数 |
| ratePlans[].dailyList | List<DailyPrice> | 每日价格日历 |
| dailyList[].daily | String | 日期 yyyy-MM-dd |
| dailyList[].price | BigDecimal | 售卖价 |
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"success": true,
"errorMsg": null,
"traceId": "3f2a8c1e9d4b4f1a8c2e5d7b9a0f6c3d",
"data": {
"hotelId": "10000011",
"checkInDate": "2026-11-18",
"checkOutDate": "2026-11-19",
"roomInfos": [
{
"roomId": "md5roomid0001",
"roomName": "高级大床房",
"roomImag": ["https://img.example.com/r1.jpg"],
"bedType": "大床",
"windowType": "有窗",
"floor": "8",
"area": "28",
"ratePlans": [
{
"ratePlanId": "md5rateplan0001",
"ratePlanName": "含双早价",
"breakfast": "双早",
"cancelPolicy": {
"cancelRule": "1",
"lastCancelTime": "2026-11-17 18:00:00",
"cancelRuleDec": "2026-11-17 18:00:00前可免费取消"
},
"invoiceMode": "S",
"isInstantConfirm": "1",
"minAmount": 1,
"maxAmount": 5,
"person": 2,
"dailyList": [
{ "daily": "2026-11-18", "price": 588.00 }
]
}
]
}
]
}
}
}
4.2 可订检查 BOOKING_CHECK
POST
| 项目 | 值 |
| 路径 | /base/hotel/order/HotelDataValidate |
| 服务名 | BOOKING_CHECK |
入参(Data 内)
| 字段 | 类型 | 必填 | 说明 |
| hotelCode | String | 是 | 酒店代码 |
| checkInDate | String | 是 | 入住日期 yyyy-MM-dd |
| checkOutDate | String | 是 | 离店日期 yyyy-MM-dd |
| ratePlanId | String | 是 | 价格计划 ID(报价接口返回) |
| priceCodeDto | Object | 否 | 价格信息缓存失效时的兜底;仅当 ratePlanId 查不到缓存时需传 |
| priceCodeDto.channel | String | 条件 | 渠道代码(缓存失效时必填) |
| priceCodeDto.roomId | String | 否 | 房型 ID |
| priceCodeDto.supplierRoomId | String | 否 | 供应商原始房型 ID |
| priceCodeDto.ratePlanId | String | 否 | 供应商价格计划 ID |
| supplierHotelCode | String | 否 | 供应商酒店代码(部分供应商需要) |
| totalSuppPrice | BigDecimal | 否 | 供应商结算总价(单间,部分供应商验价需要) |
入参 JSON 示例
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"hotelCode\":\"10000011\",\"checkInDate\":\"2026-11-18\",\"checkOutDate\":\"2026-11-19\",\"ratePlanId\":\"md5rateplan0001\"}"
}
出参 data.data(PreCheckVo)
| 字段 | 类型 | 说明 |
| canBooking | Boolean | 是否可预订 |
| breakfast | String | 早餐 |
| cancelPolicy | CancelPolicyInfo | 取消规则(结构同 4.1) |
| dailyList | List<DailyPrice> | 每日价格:daily 日期、price 售价 |
| preCheckDatetime | String | 验价查询时间(ISO 时间) |
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"success": true,
"errorMsg": null,
"traceId": "3f2a8c1e9d4b4f1a8c2e5d7b9a0f6c3d",
"data": {
"canBooking": true,
"breakfast": "双早",
"cancelPolicy": {
"cancelRule": "1",
"lastCancelTime": "2026-11-17 18:00:00",
"cancelRuleDec": "2026-11-17 18:00:00前可免费取消"
},
"dailyList": [
{ "daily": "2026-11-18", "price": 588.00 }
],
"preCheckDatetime": "2026-11-17T20:00:00"
}
}
}
4.3 创建订单 BOOKING_ROOM
POST
| 项目 | 值 |
| 路径 | /base/hotel/order/SubmitOrder |
| 服务名 | BOOKING_ROOM |
入参(Data 内)
| 字段 | 类型 | 必填 | 说明 |
| hotelCode | String | 是 | 酒店代码 |
| ratePlanId | String | 是 | 价格计划 ID(报价接口返回) |
| checkInDate | String | 是 | 入住日期 yyyy-MM-dd |
| checkOutDate | String | 是 | 离店日期 yyyy-MM-dd |
| customerOrderNo | String | 是 | 采购商订单号(幂等,同一采购商不可重复) |
| roomCount | Integer | 是 | 房间数量,大于 0 |
| orderAmount | BigDecimal | 是 | 订单总价 = Σ每日售价 × 房间数 |
| contactName | String | 是 | 联系人姓名 |
| contactTel | String | 是 | 联系人电话 |
| customerList | List<GuestInfo> | 是 | 住客信息,不能为空 |
| customerList[].travellerName | String | 是 | 入住人姓名 |
| customerList[].travellerTel | String | 是 | 入住人电话 |
| customerList[].lastName | String | 否 | 姓 |
| customerList[].firstName | String | 否 | 名 |
| customerList[].adults | int | 否 | 成人数,默认 1 |
| customerList[].children | List<Integer> | 否 | 儿童年龄列表 |
| dailyPrices | List<DailyPrice> | 是 | 每日价格,条数必须等于间夜数 |
| dailyPrices[].daily | String | 是 | 日期 yyyy-MM-dd,需覆盖全部间夜且不重复 |
| dailyPrices[].price | BigDecimal | 是 | 每日售价(每间每晚),大于 0 |
入参 JSON 示例
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"hotelCode\":\"10000011\",\"ratePlanId\":\"md5rateplan0001\",\"checkInDate\":\"2026-11-18\",\"checkOutDate\":\"2026-11-19\",\"customerOrderNo\":\"PUR20261117001\",\"roomCount\":1,\"orderAmount\":588.00,\"contactName\":\"张三\",\"contactTel\":\"13800138000\",\"customerList\":[{\"travellerName\":\"张三\",\"travellerTel\":\"13800138000\",\"adults\":1}],\"dailyPrices\":[{\"daily\":\"2026-11-18\",\"price\":588.00}]}"
}
出参 data.data(OrderCreateResult)
| 字段 | 类型 | 说明 |
| orderNo | String | 平台订单号 |
| orderStatus | String | 订单状态(见 5.4) |
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"success": true,
"errorMsg": null,
"traceId": "3f2a8c1e9d4b4f1a8c2e5d7b9a0f6c3d",
"data": {
"orderNo": "261117203000123",
"orderStatus": "PAY_SUCCESS"
}
}
}
4.4 订单信息查询 ORDER_INFO_QRY
POST
| 项目 | 值 |
| 路径 | /base/hotel/order/GetOrderDetails |
| 服务名 | ORDER_INFO_QRY |
入参(Data 内)
| 字段 | 类型 | 必填 | 说明 |
| orderNo | String | 条件 | 平台订单号;与 purchaserOrderNo 至少传一个 |
| purchaserOrderNo | String | 条件 | 采购商订单号;与 orderNo 至少传一个 |
入参 JSON 示例
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"orderNo\":\"261117203000123\"}"
}
出参 data.data(OrderDetailResult)
| 字段 | 类型 | 说明 |
| hotelCode | String | 酒店代码 |
| hotelName | String | 酒店名称 |
| orderNo | String | 平台订单号 |
| purchaserOrderNo | String | 采购商订单号 |
| roomId | String | 房型 ID |
| roomName | String | 房型名称 |
| window | String | 窗型 |
| bed | String | 床型 |
| breakfast | String | 早餐 |
| invoiceMode | String | 发票类型:S-专票,G-普票 |
| cancelRule | String | 退订规则描述 |
| freeCancelDatetime | String | 免费取消截止时间(ISO 时间) |
| orderStatus | String | 订单状态(见 5.4) |
| checkInDate | String | 入住日期 yyyy-MM-dd |
| checkOutDate | String | 离店日期 yyyy-MM-dd |
| roomCount | Integer | 房间数量 |
| orderAmount | BigDecimal | 订单总金额 |
| refundAmount | BigDecimal | 退款金额 |
| contactName | String | 联系人姓名 |
| contactMobile | String | 联系人电话 |
| travellerName | String | 入住人姓名 |
| travellerMobile | String | 入住人电话 |
| confirmNo | String | 酒店确认号 |
| failInfo | String | 失败原因 |
| dailyList | List<DailyPriceItem> | 每日价格明细(每间每晚) |
| dailyList[].daily | String | 日期 yyyy-MM-dd |
| dailyList[].price | BigDecimal | 下游结算价 |
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"success": true,
"errorMsg": null,
"traceId": "3f2a8c1e9d4b4f1a8c2e5d7b9a0f6c3d",
"data": {
"hotelCode": "10000011",
"hotelName": "杭州XX大酒店",
"orderNo": "261117203000123",
"purchaserOrderNo": "PUR20261117001",
"roomId": "md5roomid0001",
"roomName": "高级大床房",
"window": "有窗",
"bed": "大床",
"breakfast": "双早",
"invoiceMode": "S",
"cancelRule": "2026-11-17 18:00:00前可免费取消",
"freeCancelDatetime": "2026-11-17T18:00:00",
"orderStatus": "BOOKING_SUCCESS",
"checkInDate": "2026-11-18",
"checkOutDate": "2026-11-19",
"roomCount": 1,
"orderAmount": 588.00,
"refundAmount": 0.00,
"contactName": "张三",
"contactMobile": "13800138000",
"travellerName": "张三",
"travellerMobile": "13800138000",
"confirmNo": "CONF123456",
"failInfo": "",
"dailyList": [
{ "daily": "2026-11-18", "price": 588.00 }
]
}
}
}
4.5 退订和取消 ORDER_CANCEL
POST
| 项目 | 值 |
| 路径 | /base/hotel/order/CancelOrder |
| 服务名 | ORDER_CANCEL |
入参(Data 内)
| 字段 | 类型 | 必填 | 说明 |
| orderNo | String | 是 | 平台订单号 |
入参 JSON 示例
{
"PartnerId": "partner001",
"Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
"RandomNum": "123456",
"TimeStamp": "1763366400",
"Data": "{\"orderNo\":\"261117203000123\"}"
}
出参 data.data(RefundApplyResult)
| 字段 | 类型 | 说明 |
| orderNo | String | 平台订单号 |
| orderStatus | String | 订单状态(退订申请受理后通常为 REFUND_APPLY,见 5.4) |
出参 JSON 示例
{
"code": "200",
"msg": "",
"data": {
"success": true,
"errorMsg": null,
"traceId": "3f2a8c1e9d4b4f1a8c2e5d7b9a0f6c3d",
"data": {
"orderNo": "261117203000123",
"orderStatus": "REFUND_APPLY"
}
}
}
退订是异步流程:申请受理后先返回 REFUND_APPLY,后续由定时任务向供应商发起退订并轮询结果,最终订单状态会流转为 REFUND_SUCCESS 或 REFUND_FAIL。建议用「4.4 订单信息查询」轮询结果。