tmc-openapi 酒店开放接口文档

第一部分 · 接口接入说明

1.1 接口公约

项目约定
协议HTTPS(生产)/ HTTP(测试),统一 POST
Content-Typeapplication/json; charset=UTF-8
网关根路径/base,部署在 tmc-openapi 服务,默认端口 8090
鉴权方式除「获取 Token」外,所有接口请求头需携带 Authorization: Bearer {token}
签名MD5 大写,见 1.2
时间戳TimeStamp 为秒级时间戳;网关只接受前后 600 秒(10 分钟)内的请求,超时返回「请求已过期」
随机数RandomNum 为 6 位随机数字,参与签名
返回结构统一 ApiBaseResp:code / msg / data

请求体公共字段

字段类型必填说明
PartnerIdString是合作伙伴 ID(接入时分配,对应系统内 appId)
SignString是签名,MD5 大写
RandomNumString是6 位随机数字
TimeStampString是请求时间戳,单位秒
DataString条件业务参数 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

字段类型说明
codeString状态码,200 成功;其余见 5.2
msgString提示信息,成功为空字符串
dataObject业务数据,成功时有值

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}

请求体

字段类型必填说明
PartnerIdString是合作伙伴 ID
SignString是签名(Data 视为空,不含 &DATA 段)
RandomNumString是6 位随机数字
TimeStampString是秒级时间戳

请求示例

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 字段

字段类型说明
tokenString访问令牌,32 位无横线 UUID;调用业务接口时放 Authorization: Bearer {token}
expDateString过期时间,格式 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

入参

字段类型必填说明
DataString是传 "{}"

业务 DTO CityRep 无字段。

出参(data 内)

字段类型说明
cityListList<CityInfo>城市列表
cityList[].countryString国家(当前实现未填充)
cityList[].countryIdInteger国家 ID(当前实现未填充)
cityList[].provinceString省份
cityList[].provinceIdInteger省份 ID
cityList[].cityString城市
cityList[].cityIdInteger城市 ID
cityList[].parentCityIdInteger父城市 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 内)

字段类型必填说明
dataObject是查询参数对象
data.cityIdInteger否城市 ID;不传查全部
data.pageInteger否页码,默认 1
data.pageSizeInteger否每页条数,默认 50
data.hotelGradeList<String>否酒店等级过滤,取值 A~F(见 5.3;当前实现未参与查询)

入参 JSON 示例

{
  "PartnerId": "partner001",
  "Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
  "RandomNum": "123456",
  "TimeStamp": "1763366400",
  "Data": "{\"data\":{\"cityId\":330100,\"page\":1,\"pageSize\":10}}"
}

出参(data 内)

字段类型说明
pageInteger当前页码
totalInteger总条数
hotelListList<HotelModel>酒店列表
hotelList[].cityIdInteger城市 ID
hotelList[].cityNameString城市名称
hotelList[].hotelIdLong酒店 ID(平台酒店代码)
hotelList[].hotelNameString酒店名称
hotelList[].updatedTimeString更新时间
hotelList[].isBookableBoolean是否可订
hotelList[].isScarceBoolean是否紧张
hotelList[].isAdvantageBoolean是否优势
hotelList[].isHighDemandBoolean是否高需求
hotelList[].hotelGradeString酒店等级(当前实现未填充)
hotelList[].isSpecialBoolean是否特价

出参 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 内)

字段类型必填说明
dataObject是查询参数对象
data.hotelIdLong是酒店 ID(平台酒店代码)

入参 JSON 示例

{
  "PartnerId": "partner001",
  "Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
  "RandomNum": "123456",
  "TimeStamp": "1763366400",
  "Data": "{\"data\":{\"hotelId\":10000011}}"
}

出参(data 内,HotelDetailResp)

字段类型说明
isInternationalBoolean是否国际酒店
isHuazhuBoolean是否华住
hotelIdLong酒店 ID
hotelNameString酒店名称
hotelNameEnString酒店英文名
cityIdString城市 ID
cityNameString城市名称
prefectureLevelCityIdString地级市 ID(当前实现未填充)
prefectureLevelCityNameString地级市名称(当前实现未填充)
geoGeoModel经纬度
geo.latBigDecimal纬度
geo.lonBigDecimal经度
geo.nameString名称(当前实现未填充)
openYearString开业年份
renovationYearString翻修年份
addressString地址
adjacentIntersectionString邻近路口(当前实现未填充)
logUrlStringlogo 地址(当前实现未填充)
imageAmountInteger图片数量(当前实现未填充)
starRatingInteger星级
starRateDescString星级描述
districtCodeString商圈代码(当前实现未填充)
districtString行政区
businessString商圈
reviewGoodRateBigDecimal好评率(当前实现未填充)
reviewScoreBigDecimal评分(当前实现未填充)
telephoneNumString电话
facilityListList<Long>设施列表(当前实现未填充)
hasCollectionBoolean是否收藏(当前实现未填充)
inOutDescString入住离店说明(当前实现未填充)
brandCodeString品牌代码(当前实现未填充)
brandNameString品牌名称(当前实现未填充)
specialTipsString特别提示(当前实现未填充)
reviewScoreDescString评分描述(当前实现未填充)
hotelTypeDescString酒店类型描述(当前实现未填充)
hotelLabelsString酒店标签(当前实现未填充)
isProtocolBoolean是否协议
hotelSourceString酒店来源(当前实现未填充)
invoiceTypeInteger发票类型(当前实现未填充)
hotelImagesHotelImgList酒店图片(当前实现未填充)
guestTypeInteger宾客类型
isBookableBoolean是否可订
isScarceBoolean是否紧张
isAdvantageBoolean是否优势
isHighDemandBoolean是否高需求
isSpecialBoolean是否特价
mappingHotelsList<MappingHotelModel>映射酒店(当前实现未填充)
transportationInfosList<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 内)

字段类型必填说明
hotelCodeString是酒店代码
checkInDateString是入住日期,yyyy-MM-dd
checkOutDateString是离店日期,yyyy-MM-dd
paramObject否内部渠道参数,服务端会覆盖,下游无需传

入参 JSON 示例

{
  "PartnerId": "partner001",
  "Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
  "RandomNum": "123456",
  "TimeStamp": "1763366400",
  "Data": "{\"hotelCode\":\"10000011\",\"checkInDate\":\"2026-11-18\",\"checkOutDate\":\"2026-11-19\"}"
}

出参 data.data(RoomType)

字段类型说明
hotelIdString酒店代码
checkInDateString入住日期
checkOutDateString离店日期
roomInfosList<RoomInfo>房型列表
roomInfos[].roomIdString房型代码(平台内部 md5)
roomInfos[].roomNameString房型名称
roomInfos[].roomImagList<String>房型图片
roomInfos[].bedTypeString床型
roomInfos[].windowTypeString窗型
roomInfos[].floorString楼层
roomInfos[].areaString面积
roomInfos[].ratePlansList<RatePlan>价格计划列表
ratePlans[].ratePlanIdString价格计划 ID(下单/验价要用)
ratePlans[].ratePlanNameString价格计划名称
ratePlans[].breakfastString早餐
ratePlans[].cancelPolicyCancelPolicyInfo取消规则
cancelPolicy.cancelRuleString取消规则:0-不可取消,1-限时免费取消
cancelPolicy.lastCancelTimeString最晚取消时间 yyyy-MM-dd HH:mm:ss
cancelPolicy.cancelRuleDecString取消规则描述
ratePlans[].invoiceModeString发票类型:S-专票,G-普票
ratePlans[].isInstantConfirmString是否立即确认
ratePlans[].minAmountInteger最小间数限制
ratePlans[].maxAmountInteger最大间数限制
ratePlans[].personInteger房间最大入住人数
ratePlans[].dailyListList<DailyPrice>每日价格日历
dailyList[].dailyString日期 yyyy-MM-dd
dailyList[].priceBigDecimal售卖价

出参 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 内)

字段类型必填说明
hotelCodeString是酒店代码
checkInDateString是入住日期 yyyy-MM-dd
checkOutDateString是离店日期 yyyy-MM-dd
ratePlanIdString是价格计划 ID(报价接口返回)
priceCodeDtoObject否价格信息缓存失效时的兜底;仅当 ratePlanId 查不到缓存时需传
priceCodeDto.channelString条件渠道代码(缓存失效时必填)
priceCodeDto.roomIdString否房型 ID
priceCodeDto.supplierRoomIdString否供应商原始房型 ID
priceCodeDto.ratePlanIdString否供应商价格计划 ID
supplierHotelCodeString否供应商酒店代码(部分供应商需要)
totalSuppPriceBigDecimal否供应商结算总价(单间,部分供应商验价需要)

入参 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)

字段类型说明
canBookingBoolean是否可预订
breakfastString早餐
cancelPolicyCancelPolicyInfo取消规则(结构同 4.1)
dailyListList<DailyPrice>每日价格:daily 日期、price 售价
preCheckDatetimeString验价查询时间(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 内)

字段类型必填说明
hotelCodeString是酒店代码
ratePlanIdString是价格计划 ID(报价接口返回)
checkInDateString是入住日期 yyyy-MM-dd
checkOutDateString是离店日期 yyyy-MM-dd
customerOrderNoString是采购商订单号(幂等,同一采购商不可重复)
roomCountInteger是房间数量,大于 0
orderAmountBigDecimal是订单总价 = Σ每日售价 × 房间数
contactNameString是联系人姓名
contactTelString是联系人电话
customerListList<GuestInfo>是住客信息,不能为空
customerList[].travellerNameString是入住人姓名
customerList[].travellerTelString是入住人电话
customerList[].lastNameString否姓
customerList[].firstNameString否名
customerList[].adultsint否成人数,默认 1
customerList[].childrenList<Integer>否儿童年龄列表
dailyPricesList<DailyPrice>是每日价格,条数必须等于间夜数
dailyPrices[].dailyString是日期 yyyy-MM-dd,需覆盖全部间夜且不重复
dailyPrices[].priceBigDecimal是每日售价(每间每晚),大于 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)

字段类型说明
orderNoString平台订单号
orderStatusString订单状态(见 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 内)

字段类型必填说明
orderNoString条件平台订单号;与 purchaserOrderNo 至少传一个
purchaserOrderNoString条件采购商订单号;与 orderNo 至少传一个

入参 JSON 示例

{
  "PartnerId": "partner001",
  "Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
  "RandomNum": "123456",
  "TimeStamp": "1763366400",
  "Data": "{\"orderNo\":\"261117203000123\"}"
}

出参 data.data(OrderDetailResult)

字段类型说明
hotelCodeString酒店代码
hotelNameString酒店名称
orderNoString平台订单号
purchaserOrderNoString采购商订单号
roomIdString房型 ID
roomNameString房型名称
windowString窗型
bedString床型
breakfastString早餐
invoiceModeString发票类型:S-专票,G-普票
cancelRuleString退订规则描述
freeCancelDatetimeString免费取消截止时间(ISO 时间)
orderStatusString订单状态(见 5.4)
checkInDateString入住日期 yyyy-MM-dd
checkOutDateString离店日期 yyyy-MM-dd
roomCountInteger房间数量
orderAmountBigDecimal订单总金额
refundAmountBigDecimal退款金额
contactNameString联系人姓名
contactMobileString联系人电话
travellerNameString入住人姓名
travellerMobileString入住人电话
confirmNoString酒店确认号
failInfoString失败原因
dailyListList<DailyPriceItem>每日价格明细(每间每晚)
dailyList[].dailyString日期 yyyy-MM-dd
dailyList[].priceBigDecimal下游结算价

出参 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 内)

字段类型必填说明
orderNoString是平台订单号

入参 JSON 示例

{
  "PartnerId": "partner001",
  "Sign": "C0E4E1B7A9F3D5C2E8B1A4F6D7C9E0B2",
  "RandomNum": "123456",
  "TimeStamp": "1763366400",
  "Data": "{\"orderNo\":\"261117203000123\"}"
}

出参 data.data(RefundApplyResult)

字段类型说明
orderNoString平台订单号
orderStatusString订单状态(退订申请受理后通常为 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 订单信息查询」轮询结果。

第五部分 · 枚举

5.1 服务枚举 BaseApiEnum

服务名 action完整路径(相对 /base)说明分类
GET_TOKEN/api/token获取 token鉴权
CITY_LIST/hotel/resource/GetCityList城市列表静态接口
HOTEL_BASE_QRY/hotel/resource/GetHotelList获取酒店 ID 列表静态接口
HOTEL_DETAIL_QRY/hotel/resource/GetHotelInfo获取酒店静态详情静态接口
ROOM_RATE/hotel/resource/GetHotelRoomRateList房型实时报价预订
BOOKING_CHECK/hotel/order/HotelDataValidate可订检查预订
BOOKING_ROOM/hotel/order/SubmitOrder创建订单预订
ORDER_INFO_QRY/hotel/order/GetOrderDetails订单信息查询预订
ORDER_CANCEL/hotel/order/CancelOrder退订和取消预订

5.2 公共报文头状态枚举(ApiBaseResp.code)

code说明出现场景
200成功所有接口成功
101参数无效 / 参数校验失败token 接口缺参;业务接口校验失败时也使用该语义(业务接口被统一包成 997)
102partnerId 错误或未配置token 接口
103IP 不在白名单内token 接口
104服务未授权 / 服务不可用业务接口(错误信息经 997 返回)
105签名校验失败token 接口;业务接口(经 997 返回)
106请求频率超限 / 无效请求路径 / 暂查无数据token 接口、业务接口(经 997 返回)
107服务定义不存在业务接口(经 997 返回)
108请求已过期(时间戳超出前后 600 秒)token 接口;业务接口(经 997 返回)
401授权未通过(token 缺失/非法/过期)业务接口
997接口调用失败(业务/校验错误统一包装)业务接口,具体原因见 msg
注意:业务接口(除 401 与成功 200 外)的校验/业务错误,网关统一返回 997,具体原因在 msg 中; Token 接口则直接返回 101/102/103/105/106/108 等具体码。

5.3 酒店等级 HotelGrade

来源:HotelIdReq.HotelGrade,用于酒店列表过滤(当前实现未参与查询)。

取值说明
A等级 A
B等级 B
C等级 C
D等级 D
E等级 E
F等级 F

5.4 订单状态 OrderStatus

来源:OrderStatusConstant,出现在下单/退订/订单查询的 orderStatus 字段。

取值说明
WAIT_PAY下单成功待支付
PAY_SUCCESS支付成功
CLOSED已关闭
WAIT_CONFIRM订房确认中
BOOKING_SUCCESS预订成功
BOOKING_FAIL预订失败
REFUND_APPLY退订申请中
REFUND_SUCCESS退订成功
REFUND_FAIL退订失败
CHECK_OUT已离店

5.5 供应商退订状态 SupplierRefundStatus

来源:SupplierRefundStatus(内部退订流转状态,供应商侧)。

取值说明
INIT初始化
REFUND_APPLY退订申请中
REFUND_SUCCESS退订成功
REFUND_FAIL退订失败

5.6 渠道 / 来源 EnumSourceChannel

来源:EnumSourceChannel。主要供内部渠道选择使用,部分接口的 channel 取值可参考。

channel渠道名source来源名
1001思客_专100思客
1007思客_普100思客
1011艺龙_专101艺龙
1017艺龙_普101艺龙
1021游由_专102游由
1027游由_普102游由

5.7 其他取值约定

字段取值说明
invoiceModeS / GS-专票,G-普票
cancelRule0 / 10-不可取消,1-限时免费取消
isInstantConfirm0 / 11-立即确认
Success / successtrue / false布尔型成功标志