Hotel Supplier API (1.0)

下载 OpenAPI 规范: 下载 · 下载 Postman 集合: 下载

途灵酒店 Pull API（供应商对接）

对接流程

1. 供应商开发并测试 API。
2. 供应商提供测试环境 URL、api key 和 secret，途灵将创建若干测试订单。
3. 供应商完成生产环境配置，并提供生产环境 URL、api key 和 secret。
4. 途灵在生产环境创建一笔可取消的测试订单。
5. 正式上线

认证

所有接口都需要携带 Authorization 请求头，采用 HMAC-SHA256 签名方案。

签名生成步骤

1. 获取当前 Unix 时间戳（整数秒）：timestamp
2. 拼接签名原文：message = apiKey + apiSecret + timestamp
3. 以 apiSecret 为密钥对 message 计算 HMAC-SHA256，并对结果进行 Base64 编码，得到 signature
4. 组装 Authorization 请求头：HMAC-SHA256 apikey={apiKey}, timestamp={timestamp}, signature={signature}

示例

Authorization: HMAC-SHA256 apikey=myApiKey, timestamp=1715000000, signature=Base64EncodedHmacSha256Result

Postman 脚本

const CryptoJS = require('crypto-js');

const apiKey = pm.environment.get("apiKey");
const apiSecret = pm.environment.get("secret");

if (!apiKey || !apiSecret) {
    console.error("Missing apiKey or secret");
    return;
}

const timestamp = Math.floor(Date.now() / 1000);

const message = apiKey + apiSecret + timestamp.toString();

const signature = CryptoJS.HmacSHA256(message, apiSecret).toString(CryptoJS.enc.Base64);

const authHeader = `HMAC-SHA256 apikey=${apiKey}, timestamp=${timestamp}, signature=${signature}`;

pm.request.headers.upsert({
    key: "Authorization",
    value: authHeader
});

参数说明

参数	说明
apiKey	由供应商提供的 API key
apiSecret	由供应商提供的 API Secret
timestamp	请求时的 Unix 时间戳（秒），服务端允许 ±300 秒误差
signature	HMAC-SHA256(apiKey + apiSecret + timestamp, apiSecret) 的 Base64 编码结果

搜索 & 预订

搜索

搜索符合指定条件的可预订酒店及房型。 注意：搜索多间房时，所有房间使用相同的房型和价格计划，但每间房的入住人数可以不同。返回的价格为所有房间的总金额（如适用，含税费）。

接口调用信息

名称	值
请求地址	/search
请求方式	POST

请求字段

hotels[]: string必填

要搜索的酒店编码列表，单次请求最多 30 家。

checkIn: string必填

格式：YYYY-MM-DD，例如 2025-08-15

checkOut: string必填

格式：YYYY-MM-DD，必须晚于 checkIn，例如 2025-08-16

roomId: integer必填

同一请求内房间的唯一标识，从 1 开始递增。

adults: integer必填

该房间的成人数量。

childrenAges[]: integer

该房间每个儿童的年龄，数组长度即儿童数量。

language: string

响应内容语言，例如 en-US、zh-CN。不传默认为英文。

currency: string

期望的价格货币，ISO 4217 代码，例如 USD、CNY。不传默认为供应商本位货币。

nationality: string

ISO 3166-1 alpha-2 国家代码，例如 CN、US。部分供应商的价格和税率会受其影响。

timeout: integer

超时时间，单位毫秒。

requestId: string必填

调用方生成的 UUID，用于链路追踪与问题排查，响应中原样返回。

响应字段

requestId: string必填

与请求中的 requestId 一致。

code: string必填

例如 HOTEL_NOT_FOUND、PRICE_CHANGED。

message: string必填

可读的错误描述。

hotelCode: string必填

hotelName: string必填

code: string必填

供应商系统内唯一的房型编码。

name: string必填

例如 Deluxe Double Room（豪华双床房）

area: integer

房间面积，单位平方米。

code: string必填

供应商定义的床型编码，例如 KING、DOUBLE、TWIN。

name: string必填

例如 1 King Bed（1 张特大床）

quantity: integer必填

房间内该床型的数量。

maxOccupancy: integer

房间可容纳的最大总人数（成人 + 儿童）。

maxAdults: integer

房间可容纳的最大成人数。

maxChildren: integer

房间可容纳的最大儿童数。

tourmind: string

expedia: string

agoda: string

juniper: string必填

travelgate: string必填

ctrip: string必填

meituan: string必填

token: string

供应商返回的报价唯一 token，传入 Prebook Request.optionToken。部分供应商必需。

ratePlanCode: string必填

该报价在供应商系统内的唯一编码。

ratePlanName: string必填

例如 Early Bird（早鸟价）、Non-Refundable Rate（不可退款价）

code: string必填

标准餐食编码，例如 RO（无餐）、BB（含早餐）、HB（半膳）、FB（全膳）、AI（全包）。

name: string必填

例如 Room Only、Bed & Breakfast

isIncludeChildren: boolean必填

true 表示餐食包含儿童；false 表示仅含成人。

net: number必填

所有房间所有晚数的净价（成本）总额

gross: number必填

建议零售价。

currency: string必填

ISO 4217 货币代码，例如 USD、CNY。

commission: number

type: string必填

费用类型编码，例如 RESORT_FEE、CITY_TAX、SERVICE_CHARGE。

name: string必填

费用名称，例如 Resort Fee、City Tax。

amount: number必填

currency: string必填

ISO 4217 货币代码。

included: boolean必填

true 表示该费用已包含在 Price.net 中；false 表示客人需在酒店另行支付。

type: string必填

费用类型编码，例如 RESORT_FEE、CITY_TAX、SERVICE_CHARGE。

name: string必填

费用名称，例如 Resort Fee、City Tax。

amount: number必填

currency: string必填

ISO 4217 货币代码。

included: boolean必填

true 表示该费用已包含在 Price.net 中；false 表示客人需在酒店另行支付。

refundable: boolean必填

true 表示在截止时间前取消可获退款，具体规则见 cancelPenalties。

deadline: string必填

在该时间（含）之后取消适用本条罚金规则。格式：ISO 8601，例如 2026-05-13T10:00:00Z。

penaltyType: string必填

NIGHTS：按晚数收取；PERCENT：按总价百分比收取；AMOUNT：按固定金额收取。

value: number必填

与 penaltyType 配合使用：NIGHTS 为晚数，PERCENT 为百分比（如 50 = 50%），AMOUNT 为金额。

currency: string必填

ISO 4217 货币代码。

net: number必填

所有房间的每晚净价（成本）

gross: number必填

所有房间的每晚售价

allotment: integer

allotment: integer必填

该报价的可售库存，范围 1–99。

onRequest: boolean

true 表示订单非立即确认，需供应商人工审核，确认可能延迟。如果订单无法在 60 秒内确认，请设为 true。

remark: string

供应商附加说明，如特殊入住条件或促销规则。

请求参数

{
  "hotels": [
    "12345",
    "67891"
  ],
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-16",
  "occupancies": [
    {
      "roomId": 1,
      "adults": 2,
      "childrenAges": [
        8
      ]
    },
    {
      "roomId": 2,
      "adults": 2,
      "childrenAges": [
        8
      ]
    }
  ],
  "currency": "USD",
  "nationality": "US",
  "timeout": 3000,
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf84788"
}

响应结果

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf84788",
  "errors": null,
  "data": [
    {
      "hotelCode": "12345",
      "hotelName": "Hotel Name",
      "rooms": [
        {
          "roomType": {
            "code": "12345#DBL",
            "name": "Single room city view",
            "area": 25,
            "bedTypes": [
              {
                "code": "DBL",
                "name": "single bed",
                "quantity": 1
              }
            ],
            "maxOccupancy": 1,
            "maxAdults": 1,
            "maxChildren": 0,
            "relatedCode": {
              "Expedia": "1352345323",
              "HotelBed": "3432423423"
            }
          },
          "options": [
            {
              "token": "12345|12345#DBL#16#RF#32235",
              "ratePlanCode": "17",
              "ratePlanName": "Room Only",
              "mealPlan": {
                "code": "RO",
                "name": "Room Only",
                "isIncludeChildren": false
              },
              "price": {
                "net": 99.99,
                "gross": 99.99,
                "currency": "USD",
                "commission": 0
              },
              "fees": [
                {
                  "type": "TAX_AND_SERVICE_FEE",
                  "name": "tax and service fee",
                  "amount": 12.12,
                  "currency": "USD",
                  "included": false
                },
                {
                  "type": "EXTRA_PERSON_FEE",
                  "name": "Resort Fee",
                  "amount": 12.12,
                  "currency": "USD",
                  "included": true
                }
              ],
              "taxes": [
                {
                  "type": "CITY_TAX",
                  "name": "city tax",
                  "amount": 12.12,
                  "currency": "USD",
                  "included": false
                }
              ],
              "refundable": true,
              "cancelPenalties": [
                {
                  "deadline": "2026-04-17T16:58:48.131Z",
                  "penaltyType": "PERCENT",
                  "value": 100,
                  "currency": "USD"
                },
                {
                  "deadline": "2026-04-15T16:58:48.131Z",
                  "penaltyType": "AMOUNT",
                  "value": 20.2,
                  "currency": "USD"
                }
              ],
              "nightlyRate": {
                "2026-04-17": {
                  "net": 99.99,
                  "gross": 99.99,
                  "allotment": 9
                }
              },
              "allotment": 9,
              "onRequest": false,
              "remark": ""
            }
          ]
        }
      ]
    }
  ]
}

验价

创建订单前调用此接口。该操作会校验所选房型的实时价格与可售状态，并返回用于后续创建订单的 bookingToken。bookingToken 的有效期不得少于 10 分钟。 超时时间：12 秒

接口调用信息

名称	值
请求地址	/prebook
请求方式	POST

请求字段

requestId: string必填

调用方生成的 UUID，用于链路追踪。

hotelCode: string必填

checkIn: string必填

格式：YYYY-MM-DD

checkOut: string必填

格式：YYYY-MM-DD，必须晚于 checkIn。

roomId: integer必填

同一请求内房间的唯一标识，从 1 开始递增。

adults: integer必填

该房间的成人数量。

childrenAges[]: integer

该房间每个儿童的年龄，数组长度即儿童数量。

roomCode: string必填

搜索结果中的房型编码（SearchRoom.roomType.code）。

ratePlanCode: string必填

搜索结果中的报价编码（Option.ratePlanCode）。

optionToken: string

搜索结果中的 Option.token。部分供应商需要它来精确定位报价。

nationality: string

ISO 3166-1 alpha-2 国家代码，例如 CN、US。

响应字段

requestId: string必填

与请求中的 requestId 一致。

code: string必填

例如 HOTEL_NOT_FOUND、PRICE_CHANGED。

message: string必填

可读的错误描述。

hotelCode: string必填

hotelName: string必填

roomCode: string必填

roomName: string必填

ratePlanCode: string必填

ratePlanName: string

bookingToken: string必填

用于创建订单的 token，传入 Booking Request.bookingToken。token 有效期不得少于 10 分钟。

code: string必填

标准餐食编码，例如 RO（无餐）、BB（含早餐）、HB（半膳）、FB（全膳）、AI（全包）。

name: string必填

例如 Room Only、Bed & Breakfast

isIncludeChildren: boolean必填

true 表示餐食包含儿童；false 表示仅含成人。

net: number必填

所有房间所有晚数的净价（成本）总额

gross: number必填

建议零售价。

currency: string必填

ISO 4217 货币代码，例如 USD、CNY。

commission: number

type: string必填

费用类型编码，例如 RESORT_FEE、CITY_TAX、SERVICE_CHARGE。

name: string必填

费用名称，例如 Resort Fee、City Tax。

amount: number必填

currency: string必填

ISO 4217 货币代码。

included: boolean必填

true 表示该费用已包含在 Price.net 中；false 表示客人需在酒店另行支付。

type: string必填

费用类型编码，例如 RESORT_FEE、CITY_TAX、SERVICE_CHARGE。

name: string必填

费用名称，例如 Resort Fee、City Tax。

amount: number必填

currency: string必填

ISO 4217 货币代码。

included: boolean必填

true 表示该费用已包含在 Price.net 中；false 表示客人需在酒店另行支付。

net: number必填

所有房间的每晚净价（成本）

gross: number必填

所有房间的每晚售价

allotment: integer

refundable: boolean必填

deadline: string必填

在该时间（含）之后取消适用本条罚金规则。格式：ISO 8601，例如 2026-05-13T10:00:00Z。

penaltyType: string必填

NIGHTS：按晚数收取；PERCENT：按总价百分比收取；AMOUNT：按固定金额收取。

value: number必填

与 penaltyType 配合使用：NIGHTS 为晚数，PERCENT 为百分比（如 50 = 50%），AMOUNT 为金额。

currency: string必填

ISO 4217 货币代码。

allotment: integer必填

onRequest: boolean

如果订单无法在 60 秒内确认，请将此字段设为 true。

remark: string

请求参数

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd6653453434",
  "hotelCode": "12345",
  "checkIn": "2026-03-23",
  "checkOut": "2026-03-24",
  "occupancies": [
    {
      "roomId": 1,
      "adults": 2,
      "childrenAges": null
    }
  ],
  "roomCode": "12345#DBL",
  "ratePlanCode": "1734534",
  "optionToken": "12345|12345#DBL#16#RF#32235",
  "nationality": "US"
}

响应结果

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd6653453434",
  "errors": null,
  "data": {
    "hotelCode": "12345",
    "hotelName": "hotel name",
    "roomCode": "12345#DBL",
    "roomName": "Single room city view",
    "ratePlanCode": "17",
    "ratePlanName": "Room Only",
    "bookingToken": "12345|12345#DBL#16#RF#32235|2026-03-23|2026-03-24|2",
    "mealPlan": {
      "code": "RO",
      "name": "Room Only",
      "isIncludeChildren": true
    },
    "price": {
      "net": 99.99,
      "gross": 99.99,
      "currency": "USD",
      "commission": 0
    },
    "fees": [
      {
        "type": "VALUE_ADDED_TAX",
        "name": "Resort Fee",
        "amount": 12.12,
        "currency": "USD",
        "included": false
      }
    ],
    "taxes": [
      {
        "type": "VALUE_ADDED_TAX",
        "name": "Resort Fee",
        "amount": 12.12,
        "currency": "USD",
        "included": true
      }
    ],
    "nightlyRate": {
      "2026-04-17": {
        "net": 99.99,
        "gross": 99.99,
        "allotment": 2
      }
    },
    "refundable": true,
    "cancelPenalties": [
      {
        "deadline": "2026-08-03T14:15:22.123Z",
        "penaltyType": "PERCENT",
        "value": 100,
        "currency": "USD"
      }
    ],
    "allotment": 2,
    "onRequest": true,
    "remark": ""
  }
}

创建订单

针对指定报价发起预订确认请求。 超时时间：60 秒。

接口调用信息

名称	值
请求地址	/booking
请求方式	POST

请求字段

requestId: string必填

调用方生成的 UUID，用于链路追踪与幂等控制。

referenceId: string必填

途灵订单号

hotelCode: string必填

checkIn: string必填

格式：YYYY-MM-DD

checkOut: string必填

格式：YYYY-MM-DD

bookingToken: string必填

来自 Prebook Response.data.bookingToken。

firstName: string必填

lastName: string必填

phone: string

email: string

roomId: integer必填

对应搜索请求中的 Occupancy.roomId。

firstName: string必填

lastName: string必填

age: integer

儿童必填；成人选填。

type: string必填

ADULT：成人；CHILD：儿童

totalPrice: number必填

来自 Prebook Response.data.price.net。

currency: string必填

totalPrice 的货币，ISO 4217 代码，例如 USD、CNY。

nationality: string

ISO 3166-1 alpha-2 国家代码，例如 CN、US。

customerRequirements: string

type: string必填

目前支持 virtual_card（虚拟信用卡）。

number: string必填

虚拟信用卡卡号。

securityCode: string必填

CVV/CVC 安全码。

expirationMonth: string必填

两位月份，例如 08。

expirationYear: string必填

四位年份，例如 2027。

givenName: string必填

familyName: string必填

countryCode: string必填

ISO 3166-1 alpha-2，例如 US、CN。

postalCode: string必填

address: string必填

响应字段

requestId: string必填

与请求中的 requestId 一致。

code: string必填

例如 HOTEL_NOT_FOUND、PRICE_CHANGED。

message: string必填

可读的错误描述。

bookingCode: string必填

供应商系统生成的订单号，用于后续查询和取消。

status: string必填

PENDING：处理中；CONFIRMED：已确认；FAILURE：预订失败；CANCELED：已取消。

referenceId: string必填

途灵订单号

hotelConfirmationNumber: string

hotelCode: string必填

hotelName: string

checkIn: string

格式：YYYY-MM-DD

checkOut: string

格式：YYYY-MM-DD

firstName: string必填

lastName: string必填

phone: string

email: string

roomId: string必填

roomCode: string必填

roomName: string

ratePlanCode: string

ratePlanName: string

code: string必填

标准餐食编码，例如 RO（无餐）、BB（含早餐）、HB（半膳）、FB（全膳）、AI（全包）。

name: string必填

例如 Room Only、Bed & Breakfast

isIncludeChildren: boolean必填

true 表示餐食包含儿童；false 表示仅含成人。

firstName: string必填

lastName: string必填

age: integer

儿童必填；成人选填。

type: string必填

ADULT：成人；CHILD：儿童

totalPrice: number必填

实际结算的净价（成本价）。

penaltyAmount: number

适用于已取消订单，表示实际产生的罚金金额。

currency: string必填

totalPrice 与 penaltyAmount 的货币，ISO 4217 代码。

commission: number

该订单可赚取的佣金金额。

deadline: string必填

在该时间（含）之后取消适用本条罚金规则。格式：ISO 8601，例如 2026-05-13T10:00:00Z。

penaltyType: string必填

NIGHTS：按晚数收取；PERCENT：按总价百分比收取；AMOUNT：按固定金额收取。

value: number必填

与 penaltyType 配合使用：NIGHTS 为晚数，PERCENT 为百分比（如 50 = 50%），AMOUNT 为金额。

currency: string必填

ISO 4217 货币代码。

remark: string

customerRequirements: string

bookedTime: string

订单创建时间。格式：ISO 8601。

请求参数

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "referenceId": "532432532",
  "hotelCode": "12345",
  "checkIn": "2026-08-24",
  "checkOut": "2026-08-25",
  "bookingToken": "12345|12345#DBL#16#RF#32235|2026-03-23|2026-03-24|2",
  "holder": {
    "firstName": "Shan",
    "lastName": "Zhang",
    "phone": "13212341234",
    "email": "xxx@xx.com"
  },
  "occupancies": [
    {
      "roomId": 1,
      "paxes": [
        {
          "firstName": "Shan",
          "lastName": "Zhang",
          "type": "ADULT"
        },
        {
          "age": 8,
          "type": "CHILD"
        }
      ]
    }
  ],
  "totalPrice": 99.99,
  "currency": "USD",
  "nationality": "US",
  "customerRequirements": "xxxxx"
}

响应结果

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "errors": null,
  "data": {
    "bookingCode": "fef2fsf",
    "status": "CONFIRMED",
    "referenceId": "532432532",
    "hotelConfirmationNumber": "KHKHG324",
    "hotelCode": "12345",
    "hotelName": "hotel name",
    "checkIn": "2026-08-24",
    "checkOut": "2026-08-25",
    "holder": {
      "firstName": "Shan",
      "lastName": "Zhang",
      "phone": "13212341234",
      "email": "xxx@xx.com"
    },
    "rooms": [
      {
        "roomId": 1,
        "paxes": [
          {
            "firstName": "Shan",
            "lastName": "Zhang",
            "type": "ADULT"
          },
          {
            "age": 8,
            "type": "CHILD"
          }
        ]
      }
    ],
    "totalPrice": 99,
    "penaltyAmount": 0,
    "currency": "USD",
    "commission": 0,
    "cancelPenalties": [
      {
        "deadline": "2026-08-03T14:15:22.123Z",
        "penaltyType": "PERCENT",
        "value": 100,
        "currency": "USD"
      }
    ],
    "remark": "",
    "customerRequirements": "xxxxx",
    "bookedTime": "2026-08-20T14:15:22.123Z"
  }
}

取消订单

通过 referenceId 或 bookingCode 取消已确认的订单。返回取消状态及实际产生的罚金金额。 超时时间：60 秒。

接口调用信息

名称	值
请求地址	/cancel
请求方式	POST

请求字段

requestId: string必填

调用方生成的 UUID，用于链路追踪与幂等控制。

referenceId: string

途灵订单号

bookingCode: string

响应字段

requestId: string必填

code: string必填

例如 HOTEL_NOT_FOUND、PRICE_CHANGED。

message: string必填

可读的错误描述。

referenceId: string必填

bookingCode: string必填

供应商系统中的订单号。

status: string必填

取消成功状态返回 CANCELED。

penaltyAmount: number必填

本次取消实际产生的罚金金额，免费取消为 0。

currency: string必填

penaltyAmount 的货币，ISO 4217 代码。

请求参数

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf86524",
  "referenceId": "532432532"
}

响应结果

{
  "requestId": "16c74e57-9a86-4e17-843c-3dd66cf86524",
  "errors": null,
  "data": {
    "referenceId": "532432532",
    "bookingCode": "fef2fsf",
    "status": "CANCELED",
    "penaltyAmount": 99.99,
    "currency": "USD"
  }
}

订单列表

支持以下条件查询订单详情：

1. referenceId：途灵订单号
2. bookingCode：供应商订单号
3. 日期范围：入住日期 / 预订时间 注意：供应商必须支持按 referenceId 或日期范围查询订单。创建或取消订单时可能因网络超时未收到响应，此时我们只能通过 referenceId 或日期范围获取订单状态。 超时时间：30 秒。

接口调用信息

名称	值
请求地址	/bookings
请求方式	POST

请求字段

requestId: string必填

bookingCode: string

referenceId: string

dateType: string

与 startDate/endDate 配合使用。CHECKIN 按入住日期过滤；BOOK 按下单日期过滤。

startDate: string

格式：YYYY-MM-DD，与 endDate、dateType 配合使用。

endDate: string

格式：YYYY-MM-DD，与 startDate、dateType 配合使用。

响应字段

requestId: string必填

code: string必填

例如 HOTEL_NOT_FOUND、PRICE_CHANGED。

message: string必填

可读的错误描述。

bookingCode: string必填

供应商系统生成的订单号，用于后续查询和取消。

status: string必填

PENDING：处理中；CONFIRMED：已确认；FAILURE：预订失败；CANCELED：已取消。

referenceId: string必填

途灵订单号

hotelConfirmationNumber: string

hotelCode: string必填

hotelName: string

checkIn: string

格式：YYYY-MM-DD

checkOut: string

格式：YYYY-MM-DD

firstName: string必填

lastName: string必填

phone: string

email: string

roomId: string必填

roomCode: string必填

roomName: string

ratePlanCode: string

ratePlanName: string

code: string必填

标准餐食编码，例如 RO（无餐）、BB（含早餐）、HB（半膳）、FB（全膳）、AI（全包）。

name: string必填

例如 Room Only、Bed & Breakfast

isIncludeChildren: boolean必填

true 表示餐食包含儿童；false 表示仅含成人。

firstName: string必填

lastName: string必填

age: integer

儿童必填；成人选填。

type: string必填

ADULT：成人；CHILD：儿童

totalPrice: number必填

实际结算的净价（成本价）。

penaltyAmount: number

适用于已取消订单，表示实际产生的罚金金额。

currency: string必填

totalPrice 与 penaltyAmount 的货币，ISO 4217 代码。

commission: number

该订单可赚取的佣金金额。

deadline: string必填

在该时间（含）之后取消适用本条罚金规则。格式：ISO 8601，例如 2026-05-13T10:00:00Z。

penaltyType: string必填

NIGHTS：按晚数收取；PERCENT：按总价百分比收取；AMOUNT：按固定金额收取。

value: number必填

与 penaltyType 配合使用：NIGHTS 为晚数，PERCENT 为百分比（如 50 = 50%），AMOUNT 为金额。

currency: string必填

ISO 4217 货币代码。

remark: string

customerRequirements: string

bookedTime: string

订单创建时间。格式：ISO 8601。

请求参数

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "referenceId": "532432532"
}

响应结果

{
  "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434",
  "errors": null,
  "data": [
    {
      "bookingCode": "fef2fsf",
      "status": "CONFIRMED",
      "referenceId": "532432532",
      "hotelConfirmationNumber": "KHKHG324",
      "hotelCode": "12345",
      "hotelName": "hotel name",
      "checkIn": "2026-08-24",
      "checkOut": "2026-08-25",
      "holder": {
        "firstName": "Shan",
        "lastName": "Zhang",
        "phone": "13212341234",
        "email": "xxx@xx.com"
      },
      "rooms": [
        {
          "roomId": 1,
          "paxes": [
            {
              "firstName": "Shan",
              "lastName": "Zhang",
              "type": "ADULT"
            },
            {
              "age": 8,
              "type": "CHILD"
            }
          ]
        }
      ],
      "totalPrice": 99,
      "penaltyAmount": 0,
      "currency": "USD",
      "commission": 0,
      "cancelPenalties": [
        {
          "deadline": "2026-08-03T14:15:22.123Z",
          "penaltyType": "PERCENT",
          "value": 100,
          "currency": "USD"
        }
      ],
      "remark": "",
      "customerRequirements": "xxxxx",
      "bookedTime": "2026-08-20T14:15:22.123Z"
    }
  ]
}

静态数据

酒店列表

获取酒店静态数据，包括酒店基本信息和房型列表。支持按酒店编码、国家或最近更新时间过滤。结果分页返回。

接口调用信息

名称	值
请求地址	/hotels
请求方式	POST

请求字段

hotels[]: string

要查询的酒店编码列表，最多 100 个，与 countryCode 互斥。二者均不传时返回全部酒店（分页）。

countryCode: string

按国家过滤酒店，ISO 3166-1 alpha-2 国家代码，例如 CN、JP。

updateTime: string

仅返回该时间之后发生变更的酒店，用于静态数据增量同步。格式：ISO 8601。

page: integer

从 1 开始。

perPage: integer

每页酒店数量，范围 1–100，默认 100。

响应字段

code: string必填

例如 HOTEL_NOT_FOUND、PRICE_CHANGED。

message: string必填

可读的错误描述。

page: integer必填

perPage: integer必填

pages: integer必填

总页数。

total: integer必填

符合条件的酒店总数。

hotelCode: string必填

供应商系统内唯一的酒店编码。

hotelName: string必填

starRating: integer必填

酒店星级，范围 1–5。

category: string

例如 Hotel、Resort、Hostel、Apartment。

countryCode: string必填

ISO 3166-1 alpha-2，例如 CN、JP、US。

country: string必填

cityCode: string

供应商定义的城市编码。

city: string

address: string必填

latitude: string必填

WGS84 纬度，例如 39.9042。

longitude: string必填

WGS84 经度，例如 116.4074。

email: string

phone: string

包含国际区号，例如 +8610-12345678。

code: string必填

供应商系统内唯一的房型编码。

name: string必填

例如 Deluxe Double Room（豪华双床房）

area: integer

房间面积，单位平方米。

code: string必填

供应商定义的床型编码，例如 KING、DOUBLE、TWIN。

name: string必填

例如 1 King Bed（1 张特大床）

quantity: integer必填

房间内该床型的数量。

maxOccupancy: integer

房间可容纳的最大总人数（成人 + 儿童）。

maxAdults: integer

房间可容纳的最大成人数。

maxChildren: integer

房间可容纳的最大儿童数。

tourmind: string

expedia: string

agoda: string

juniper: string必填

travelgate: string必填

ctrip: string必填

meituan: string必填

tourmind: string

expedia: string

agoda: string

juniper: string必填

travelgate: string必填

ctrip: string必填

meituan: string必填

请求参数

{
  "hotels": [
    "12345"
  ],
  "page": 1,
  "perPage": 100
}

响应结果

{
  "errors": null,
  "data": {
    "pagination": {
      "page": 1,
      "perPage": 100,
      "pages": 1,
      "total": 1
    },
    "hotels": [
      {
        "hotelCode": "12345",
        "hotelName": "hotel name",
        "starRating": 3,
        "category": "Hotel",
        "countryCode": "US",
        "country": "USA",
        "cityCode": "CA",
        "city": "Burlingame",
        "address": "600 Airport Boulevard",
        "latitude": "37.59002",
        "longitude": "-122.342915",
        "email": "",
        "phone": "1-650-340-8500",
        "relatedCode": {
          "expedia": "1232353"
        },
        "rooms": [
          {
            "code": "DBL",
            "name": "Double Room",
            "area": 20,
            "bedTypes": [
              {
                "code": "2",
                "name": "Single Bed",
                "quantity": 2
              }
            ],
            "maxOccupancy": 2,
            "maxAdults": 2,
            "maxChildren": 0,
            "relatedCode": {
              "expedia": "3253252"
            }
          }
        ]
      }
    ]
  }
}

参考

订单状态

值	说明
PENDING	订单处理中，等待确认。
CONFIRMED	订单已被供应商确认。
FAILURE	订单确认失败。
CANCELED	订单已取消。

餐食编码

编码	说明
RO	无餐（Room Only）
BB	含早餐（Bed & Breakfast）
HB	半膳（早餐 + 晚餐）
FB	全膳（早餐 + 午餐 + 晚餐）
AI	全包（All Inclusive）
BF1	1 人份早餐
BF2	2 人份早餐
BF3	3 人份早餐
BF4	4 人份早餐
LC	午餐
DN	晚餐
LD	午餐 & 晚餐

费用 / 税类型

值	说明
VALUE_ADDED_TAX	增值税（VAT）
SALES_TAX	销售税
CITY_TAX	城市税
TOURISM_TAX	旅游税
TAX_AND_SERVICE_FEE	税费与服务费合计
PROPERTY_FEE	物业费
DEPOSIT	押金
RESORT_FEE	度假村费
EXTRA_PERSON_FEE	加人费
PLATFORM_FEE	平台费

日期类型

值	说明
CHECKIN	按入住日期过滤订单。
BOOK	按下单日期过滤订单。

旅客类型

值	说明
ADULT	成人（18 岁及以上）。
CHILD	儿童（17 岁及以下）。

错误码

编码	说明
VALIDATION_ERROR	请求参数校验失败。
TIMEOUT	上游供应商请求超时。
RATE_LIMIT	请求超出频率限制。
SYSTEM_ERROR	系统内部错误。
NO_AVAILABILITY	请求条件下无可售资源。
PRICE_CHANGED	价格自上次搜索或验价后发生变化。
INSUFFICIENT_CREDIT	账户额度不足，无法完成预订。
UNKNOWN	未知错误。