{ "openapi": "3.1.0", "info": { "title": "Tourmind Hotel Supplier API(1.0)", "description": "途灵酒店 Pull API（供应商对接）\n\n## 对接流程 {#integration-process}\n\n1. 供应商开发并测试 API。\n2. 供应商提供测试环境 URL、api key 和 secret，途灵将创建若干测试订单。\n3. 供应商完成生产环境配置，并提供生产环境 URL、api key 和 secret。\n4. 途灵在生产环境创建一笔可取消的测试订单。\n5. 正式上线\n\n\n## 认证 {#authentication}\n\n所有接口都需要携带 `Authorization` 请求头，采用 **HMAC-SHA256** 签名方案。\n\n### 签名生成步骤 {#signature-generation-steps}\n\n1. 获取当前 Unix 时间戳（整数秒）：`timestamp`\n2. 拼接签名原文：`message = apiKey + apiSecret + timestamp`\n3. 以 `apiSecret` 为密钥对 `message` 计算 HMAC-SHA256，并对结果进行 Base64 编码，得到 `signature`\n4. 组装 Authorization 请求头：`HMAC-SHA256 apikey={apiKey}, timestamp={timestamp}, signature={signature}`\n\n### 示例 {#example}\n\n```\nAuthorization: HMAC-SHA256 apikey=myApiKey, timestamp=1715000000, signature=Base64EncodedHmacSha256Result\n```\n\n### Postman 脚本 {#postman-script}\n```\nconst CryptoJS = require('crypto-js');\n\nconst apiKey = pm.environment.get(\"apiKey\");\nconst apiSecret = pm.environment.get(\"secret\");\n\nif (!apiKey || !apiSecret) {\n console.error(\"Missing apiKey or secret\");\n return;\n}\n\nconst timestamp = Math.floor(Date.now() / 1000);\n\nconst message = apiKey + apiSecret + timestamp.toString();\n\nconst signature = CryptoJS.HmacSHA256(message, apiSecret).toString(CryptoJS.enc.Base64);\n\nconst authHeader = `HMAC-SHA256 apikey=${apiKey}, timestamp=${timestamp}, signature=${signature}`;\n\npm.request.headers.upsert({\n key: \"Authorization\",\n value: authHeader\n});\n```\n\n### 参数说明 {#parameter-reference}\n\n| 参数 | 说明 |\n|-----------|-------------|\n| `apiKey` | 由供应商提供的 API key |\n| `apiSecret` | 由供应商提供的 API Secret |\n| `timestamp` | 请求时的 Unix 时间戳（秒），服务端允许 ±300 秒误差 |\n| `signature` | HMAC-SHA256(apiKey + apiSecret + timestamp, apiSecret) 的 Base64 编码结果 |", "version": "1.0.0" }, "tags": [], "paths": { "/search": { "post": { "summary": "搜索", "deprecated": false, "description": "搜索符合指定条件的可预订酒店及房型。\n注意：搜索多间房时，所有房间使用相同的房型和价格计划，但每间房的入住人数可以不同。返回的价格为所有房间的总金额（如适用，含税费）。", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search%20Request" }, "example": { "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" } } }, "required": true }, "responses": { "200": { "description": "搜索成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search%20Response" }, "example": { "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": "" } ] } ] } ] } } }, "headers": {} } }, "security": [] } }, "/prebook": { "post": { "summary": "验价", "deprecated": false, "description": "创建订单前调用此接口。该操作会校验所选房型的实时价格与可售状态，并返回用于后续创建订单的 bookingToken。bookingToken 的有效期不得少于 10 分钟。\n超时时间：12 秒", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prebook%20Request" }, "example": { "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" } } }, "required": true }, "responses": { "200": { "description": "验价确认成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prebook%20Response" }, "example": { "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": "" } } } }, "headers": {} } }, "security": [] } }, "/booking": { "post": { "summary": "创建订单", "deprecated": false, "description": "针对指定报价发起预订确认请求。\n超时时间：60 秒。", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking%20Request" }, "example": { "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" } } }, "required": true }, "responses": { "200": { "description": "订单创建成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking%20Response" }, "example": { "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" } } } }, "headers": {} } }, "security": [] } }, "/cancel": { "post": { "summary": "取消订单", "deprecated": false, "description": "通过 referenceId 或 bookingCode 取消已确认的订单。返回取消状态及实际产生的罚金金额。\n超时时间：60 秒。", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancel%20Request" }, "examples": { "1": { "value": { "requestId": "16c74e57-9a86-4e17-843c-3dd66cf86524", "referenceId": "532432532" }, "summary": "示例 1" }, "2": { "value": { "requestId": "16c74e57-9a86-4e17-843c-3dd66cf86524", "bookingCode": "fef2fsf" }, "summary": "按 bookingCode 查询" } } } }, "required": true }, "responses": { "200": { "description": "取消成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancel%20Response" }, "example": { "requestId": "16c74e57-9a86-4e17-843c-3dd66cf86524", "errors": null, "data": { "referenceId": "532432532", "bookingCode": "fef2fsf", "status": "CANCELED", "penaltyAmount": 99.99, "currency": "USD" } } } }, "headers": {} } }, "security": [] } }, "/bookings": { "post": { "summary": "订单列表", "deprecated": false, "description": "支持以下条件查询订单详情：\n1. referenceId：途灵订单号\n2. bookingCode：供应商订单号\n3. 日期范围：入住日期 / 预订时间\n注意：供应商必须支持按 referenceId 或日期范围查询订单。创建或取消订单时可能因网络超时未收到响应，此时我们只能通过 referenceId 或日期范围获取订单状态。\n超时时间：30 秒。", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking%20List%20Request" }, "examples": { "1": { "value": { "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434", "referenceId": "532432532" }, "summary": "示例 1" }, "2": { "value": { "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434", "bookingCode": "fewfwefwf" }, "summary": "按 bookingCode 查询" }, "3": { "value": { "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434", "dateType": "BOOK", "startDate": "2026-04-01", "endDate": "2026-04-01" }, "summary": "按日期范围查询" } } } }, "required": true }, "responses": { "200": { "description": "查询成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking%20List%20Response" }, "example": { "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" } ] } } }, "headers": {} } }, "security": [] } }, "/hotels": { "post": { "summary": "酒店列表", "deprecated": false, "description": "获取酒店静态数据，包括酒店基本信息和房型列表。支持按酒店编码、国家或最近更新时间过滤。结果分页返回。", "tags": [], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HotelList%20Request" }, "examples": { "1": { "value": { "hotels": [ "12345" ], "page": 1, "perPage": 100 }, "summary": "示例 1" }, "2": { "value": { "updateTime": "2026-08-20T14:15:22.123Z", "page": 1, "perPage": 100 }, "summary": "按 updateTime 查询" }, "3": { "value": { "countryCode": "US", "page": 1, "perPage": 100 }, "summary": "按 countryCode 查询" } } } }, "required": true }, "responses": { "200": { "description": "查询成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hotel%20List%20Response" }, "example": { "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" } } ] } ] } } } }, "headers": {} } }, "security": [] } } }, "webhooks": {}, "components": { "schemas": { "Fee": { "type": "object", "properties": { "type": { "type": "string", "title": "费用类型", "description": "费用类型编码，例如 RESORT_FEE、CITY_TAX、SERVICE_CHARGE。", "enum": [ "VALUE_ADDED_TAX", "SALES_TAX", "CITY_TAX", "TOURISM_TAX", "TAX_AND_SERVICE_FEE", "PROPERTY_FEE", "DEPOSIT", "RESORT_FEE", "EXTRA_PERSON_FEE", "PLATFORM_FEE" ] }, "name": { "type": "string", "title": "费用描述", "description": "费用名称，例如 Resort Fee、City Tax。", "examples": [ "Resort Fee" ] }, "amount": { "type": "number", "title": "金额", "format": "float64", "minimum": 0, "exclusiveMinimum": 0, "examples": [ 12.12 ] }, "currency": { "type": "string", "title": "货币", "description": "ISO 4217 货币代码。" }, "included": { "type": "boolean", "title": "是否包含在总价", "description": "true 表示该费用已包含在 Price.net 中；false 表示客人需在酒店另行支付。" } }, "required": [ "type", "name", "amount", "currency", "included" ] }, "Occupancy": { "type": "object", "properties": { "roomId": { "type": "integer", "minimum": 1, "title": "房间序号", "description": "同一请求内房间的唯一标识，从 1 开始递增。" }, "adults": { "type": "integer", "minimum": 1, "maximum": 5, "title": "成人数", "description": "该房间的成人数量。", "examples": [ 2 ] }, "childrenAges": { "type": [ "array", "null" ], "items": { "type": "integer", "maximum": 17, "minimum": 1, "examples": [ 8 ] }, "title": "儿童年龄", "description": "该房间每个儿童的年龄，数组长度即儿童数量。" } }, "required": [ "roomId", "adults" ] }, "NightlyRate": { "type": "object", "properties": { "net": { "type": "number", "examples": [ 99.99 ], "minimum": 0, "exclusiveMinimum": 0, "format": "float64", "description": "所有房间的每晚净价（成本）", "title": "每晚成本" }, "gross": { "type": "number", "format": "float64", "examples": [ 99.99 ], "minimum": 0, "description": "所有房间的每晚售价", "title": "每晚售价" }, "allotment": { "type": "integer", "title": "每日库存" } }, "required": [ "net", "gross" ] }, "RoomDetail": { "type": "object", "properties": { "roomId": { "type": "string" }, "roomCode": { "type": "string" }, "roomName": { "type": "string" }, "ratePlanCode": { "type": "string" }, "ratePlanName": { "type": "string" }, "mealType": { "$ref": "#/components/schemas/MealPlan" }, "paxes": { "type": "array", "items": { "$ref": "#/components/schemas/Pax" } } }, "required": [ "roomCode", "roomId" ] }, "RelatedCode": { "type": "object", "properties": { "tourmind": { "type": [ "string", "null" ] }, "expedia": { "type": [ "string", "null" ] }, "agoda": { "type": [ "string", "null" ] }, "juniper": { "type": "string" }, "travelgate": { "type": "string" }, "ctrip": { "type": "string" }, "meituan": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "juniper", "travelgate", "ctrip", "meituan" ] }, "Search Request": { "type": "object", "properties": { "hotels": { "type": "array", "items": { "type": "string", "examples": [ "12345" ] }, "minItems": 1, "maxItems": 30, "uniqueItems": true, "title": "酒店code列表", "description": "要搜索的酒店编码列表，单次请求最多 30 家。" }, "checkIn": { "type": "string", "title": "入住日期", "description": "格式：YYYY-MM-DD，例如 2025-08-15", "format": "date" }, "checkOut": { "type": "string", "title": "离店日期", "description": "格式：YYYY-MM-DD，必须晚于 checkIn，例如 2025-08-16", "format": "date" }, "occupancies": { "type": "array", "items": { "$ref": "#/components/schemas/Occupancy" }, "minItems": 1, "maxItems": 4, "title": "入住房间和人数", "description": "每个元素代表一间房的入住信息。" }, "language": { "type": [ "string", "null" ], "title": "语言", "description": "响应内容语言，例如 en-US、zh-CN。不传默认为英文。" }, "currency": { "type": [ "string", "null" ], "title": "货币", "description": "期望的价格货币，ISO 4217 代码，例如 USD、CNY。不传默认为供应商本位货币。" }, "nationality": { "type": "string", "title": "国籍", "description": "ISO 3166-1 alpha-2 国家代码，例如 CN、US。部分供应商的价格和税率会受其影响。" }, "timeout": { "type": "integer", "title": "超时", "description": "超时时间，单位毫秒。", "examples": [ 3000 ] }, "requestId": { "type": "string", "title": "请求唯一id", "description": "调用方生成的 UUID，用于链路追踪与问题排查，响应中原样返回。" } }, "required": [ "hotels", "checkIn", "checkOut", "occupancies", "requestId" ] }, "Search Response": { "type": "object", "properties": { "requestId": { "type": "string", "description": "与请求中的 requestId 一致。" }, "errors": { "type": [ "array", "null" ], "description": "成功时为 null 或空数组；发生业务错误时包含错误详情。", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": "array", "description": "符合搜索条件的酒店及房价报价列表。无结果时返回空数组。", "items": { "$ref": "#/components/schemas/SearchHotel" } } }, "required": [ "requestId", "data" ] }, "Prebook Request": { "type": "object", "properties": { "requestId": { "type": "string", "description": "调用方生成的 UUID，用于链路追踪。" }, "hotelCode": { "type": "string", "title": "酒店编码" }, "checkIn": { "type": "string", "description": "格式：YYYY-MM-DD", "format": "date", "title": "入住日期" }, "checkOut": { "type": "string", "title": "离店日期", "description": "格式：YYYY-MM-DD，必须晚于 checkIn。", "format": "date" }, "occupancies": { "type": "array", "title": "房间和人数", "description": "必须与搜索请求中的 occupancies 保持一致。", "items": { "$ref": "#/components/schemas/Occupancy" } }, "roomCode": { "type": "string", "title": "房型编码", "description": "搜索结果中的房型编码（SearchRoom.roomType.code）。" }, "ratePlanCode": { "type": "string", "title": "报价编码", "description": "搜索结果中的报价编码（Option.ratePlanCode）。" }, "optionToken": { "type": [ "string", "null" ], "title": "报价 Token", "description": "搜索结果中的 Option.token。部分供应商需要它来精确定位报价。" }, "nationality": { "type": "string", "title": "旅客国籍", "description": "ISO 3166-1 alpha-2 国家代码，例如 CN、US。" } }, "required": [ "requestId", "hotelCode", "checkIn", "checkOut", "occupancies", "roomCode", "ratePlanCode" ] }, "Prebook Response": { "type": "object", "properties": { "requestId": { "type": "string", "description": "与请求中的 requestId 一致。" }, "errors": { "type": [ "array", "null" ], "description": "成功时为 null；发生业务错误时包含错误详情。", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": [ "object", "null" ], "description": "验价确认结果。房型不可售时为 null。", "properties": { "hotelCode": { "type": "string" }, "hotelName": { "type": "string" }, "roomCode": { "type": "string" }, "roomName": { "type": "string" }, "ratePlanCode": { "type": "string" }, "ratePlanName": { "type": "string" }, "bookingToken": { "type": "string", "title": "预订 Token", "description": "用于创建订单的 token，传入 Booking Request.bookingToken。token 有效期不得少于 10 分钟。" }, "mealPlan": { "$ref": "#/components/schemas/MealPlan" }, "price": { "$ref": "#/components/schemas/Price" }, "fees": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Fee" } }, "taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Fee" } }, "nightlyRate": { "type": [ "object", "null" ], "properties": { "[stay date]": { "$ref": "#/components/schemas/NightlyRate" } }, "additionalProperties": { "$ref": "#/components/schemas/NightlyRate" } }, "refundable": { "type": "boolean" }, "cancelPenalties": { "type": "array", "items": { "$ref": "#/components/schemas/CancelPenalty" } }, "allotment": { "type": "integer" }, "onRequest": { "type": "boolean", "description": "如果订单无法在 60 秒内确认，请将此字段设为 true。" }, "remark": { "type": [ "string", "null" ] } }, "required": [ "hotelCode", "hotelName", "roomCode", "roomName", "ratePlanCode", "mealPlan", "refundable", "price", "allotment", "bookingToken" ] } }, "required": [ "requestId" ] }, "Booking Request": { "type": "object", "properties": { "requestId": { "type": "string", "description": "调用方生成的 UUID，用于链路追踪与幂等控制。" }, "referenceId": { "type": "string", "title": "途灵订单号", "description": "途灵订单号" }, "hotelCode": { "type": "string", "title": "酒店编码" }, "checkIn": { "type": "string", "description": "格式：YYYY-MM-DD", "format": "date", "title": "入住日期" }, "checkOut": { "type": "string", "description": "格式：YYYY-MM-DD", "format": "date", "title": "离店日期" }, "bookingToken": { "type": "string", "title": "预订 Token", "description": "来自 Prebook Response.data.bookingToken。" }, "holder": { "$ref": "#/components/schemas/Contact", "title": "联系人" }, "occupancies": { "type": "array", "description": "每间房的入住人列表。roomId 必须与搜索请求中使用的值一致。", "items": { "type": "object", "properties": { "roomId": { "type": "integer", "title": "房间序号", "description": "对应搜索请求中的 Occupancy.roomId。" }, "paxes": { "type": "array", "title": "入住人列表", "items": { "$ref": "#/components/schemas/Pax" } } }, "required": [ "roomId", "paxes" ] }, "title": "房型和人数" }, "totalPrice": { "type": "number", "description": "来自 Prebook Response.data.price.net。", "title": "预定总价" }, "currency": { "type": "string", "description": "totalPrice 的货币，ISO 4217 代码，例如 USD、CNY。", "title": "货币" }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-2 国家代码，例如 CN、US。", "title": "国籍" }, "customerRequirements": { "type": [ "string", "null" ], "title": "顾客要求" }, "payment": { "description": "虚拟信用卡信息，仅部分供应商需要。", "anyOf": [ { "title": "支付信息", "description": "虚拟信用卡信息，仅部分供应商需要。", "$ref": "#/components/schemas/Payment" }, { "type": "null" } ], "title": "支付信息" } }, "required": [ "requestId", "hotelCode", "checkIn", "checkOut", "holder", "occupancies", "totalPrice", "currency", "referenceId", "bookingToken" ] }, "Booking Response": { "type": "object", "properties": { "requestId": { "type": "string", "title": "请求 ID", "description": "与请求中的 requestId 一致。" }, "errors": { "type": [ "array", "null" ], "title": "错误列表", "description": "成功时为 null；创建订单失败时包含错误详情。", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "title": "订单数据", "description": "创建成功的订单详情。创建失败时为 null。", "anyOf": [ { "title": "订单数据", "description": "创建成功的订单详情。创建失败时为 null。", "$ref": "#/components/schemas/Booking" }, { "type": "null" } ] } }, "required": [ "requestId" ] }, "Booking List Request": { "type": "object", "properties": { "requestId": { "type": "string" }, "bookingCode": { "type": "string" }, "referenceId": { "type": "string" }, "dateType": { "type": "string", "description": "与 startDate/endDate 配合使用。CHECKIN 按入住日期过滤；BOOK 按下单日期过滤。", "enum": [ "CHECKIN", "BOOK" ] }, "startDate": { "type": "string", "description": "格式：YYYY-MM-DD，与 endDate、dateType 配合使用。", "format": "date" }, "endDate": { "type": "string", "description": "格式：YYYY-MM-DD，与 startDate、dateType 配合使用。", "format": "date" } }, "required": [ "requestId" ] }, "Booking List Response": { "type": "object", "properties": { "requestId": { "type": "string" }, "errors": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": [ "array", "null" ], "description": "符合条件的订单列表。无结果时返回空数组。", "items": { "$ref": "#/components/schemas/Booking" } } }, "required": [ "requestId" ] }, "Cancel Request": { "type": "object", "properties": { "requestId": { "type": "string", "title": "请求 ID", "description": "调用方生成的 UUID，用于链路追踪与幂等控制。" }, "referenceId": { "type": "string", "description": "途灵订单号", "title": "途灵订单号" }, "bookingCode": { "type": "string", "title": "供应商订单号", "description": " " } }, "required": [ "requestId" ] }, "Cancel Response": { "type": "object", "properties": { "requestId": { "type": "string" }, "errors": { "type": [ "array", "null" ], "description": "成功时为 null；取消失败时包含错误详情。", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": "object", "properties": { "referenceId": { "type": "string" }, "bookingCode": { "type": "string", "description": "供应商系统中的订单号。" }, "status": { "type": "string", "title": "取消状态", "description": "取消成功状态返回 CANCELED。", "enum": [ "PENDING", "FAILURE", "CONFIRMED", "CANCELED" ] }, "penaltyAmount": { "type": "number", "title": "取消费用", "description": "本次取消实际产生的罚金金额，免费取消为 0。", "format": "float64" }, "currency": { "type": "string", "description": "penaltyAmount 的货币，ISO 4217 代码。" } }, "required": [ "referenceId", "bookingCode", "status", "penaltyAmount", "currency" ] } }, "required": [ "requestId", "data" ] }, "HotelList Request": { "type": "object", "properties": { "hotels": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "要查询的酒店编码列表，最多 100 个，与 countryCode 互斥。二者均不传时返回全部酒店（分页）。" }, "countryCode": { "type": "string", "description": "按国家过滤酒店，ISO 3166-1 alpha-2 国家代码，例如 CN、JP。" }, "updateTime": { "type": [ "string", "null" ], "format": "date-time", "description": "仅返回该时间之后发生变更的酒店，用于静态数据增量同步。格式：ISO 8601。" }, "page": { "type": "integer", "description": "从 1 开始。", "minimum": 1, "default": 1, "examples": [ 1 ] }, "perPage": { "type": "integer", "description": "每页酒店数量，范围 1–100，默认 100。", "minimum": 1, "maximum": 100, "default": 100, "examples": [ 100 ] } } }, "Hotel List Response": { "type": "object", "properties": { "errors": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": [ "object", "null" ], "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "title": "当前页" }, "perPage": { "type": "integer", "title": "每页酒店数" }, "pages": { "type": "integer", "title": "总页数", "description": "总页数。" }, "total": { "type": "integer", "title": "总酒店数", "description": "符合条件的酒店总数。" } }, "required": [ "page", "perPage", "pages", "total" ] }, "hotels": { "type": "array", "items": { "$ref": "#/components/schemas/Hotel" } } }, "required": [ "pagination", "hotels" ] } } }, "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "例如 HOTEL_NOT_FOUND、PRICE_CHANGED。", "enum": [ "VALIDATION_ERROR", "TIMEOUT", "RATE_LIMIT", "SYSTEM_ERROR", "NO_AVAILABILITY", "PRICE_CHANGED", "INSUFFICIENT_CREDIT", "UNKNOWN" ] }, "message": { "type": "string", "description": "可读的错误描述。" } }, "required": [ "code", "message" ] }, "RoomType": { "type": "object", "properties": { "code": { "type": "string", "title": "房型唯一编码", "description": "供应商系统内唯一的房型编码。" }, "name": { "type": "string", "title": "房型名称", "description": "例如 Deluxe Double Room（豪华双床房）" }, "area": { "type": "integer", "title": "面积", "description": "房间面积，单位平方米。" }, "bedTypes": { "type": [ "array", "null" ], "title": "床型", "description": "该房型的床型配置，可能包含多种床型。", "items": { "$ref": "#/components/schemas/BedType" } }, "maxOccupancy": { "type": "integer", "title": "最大入住人数", "description": "房间可容纳的最大总人数（成人 + 儿童）。" }, "maxAdults": { "type": "integer", "title": "最大成人数", "description": "房间可容纳的最大成人数。" }, "maxChildren": { "type": "integer", "title": "最大儿童数", "description": "房间可容纳的最大儿童数。" }, "relatedCode": { "anyOf": [ { "$ref": "#/components/schemas/RelatedCode" }, { "type": "null" } ], "title": "第三方匹配关系" } }, "required": [ "code", "name" ] }, "MealPlan": { "type": "object", "properties": { "code": { "type": "string", "title": "餐食编码", "description": "标准餐食编码，例如 RO（无餐）、BB（含早餐）、HB（半膳）、FB（全膳）、AI（全包）。", "enum": [ "RO", "BB", "HB", "FB", "AI", "BF1", "BF2", "BF3", "BF4", "LC", "DN", "LD" ], "examples": [ "RO" ] }, "name": { "type": "string", "title": "餐食描述", "description": "例如 Room Only、Bed & Breakfast", "examples": [ "Room Only" ] }, "isIncludeChildren": { "type": "boolean", "title": "是否包含儿童", "description": "true 表示餐食包含儿童；false 表示仅含成人。" } }, "required": [ "code", "name", "isIncludeChildren" ] }, "Option": { "type": "object", "properties": { "token": { "type": [ "string", "null" ], "title": "报价 Token", "description": "供应商返回的报价唯一 token，传入 Prebook Request.optionToken。部分供应商必需。" }, "ratePlanCode": { "type": "string", "title": "报价唯一Code", "description": "该报价在供应商系统内的唯一编码。" }, "ratePlanName": { "type": "string", "title": "报价名称", "description": "例如 Early Bird（早鸟价）、Non-Refundable Rate（不可退款价）" }, "mealPlan": { "$ref": "#/components/schemas/MealPlan", "title": "餐食" }, "price": { "$ref": "#/components/schemas/Price", "title": "价格", "description": "所有房间的总价" }, "fees": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Fee" }, "title": "服务费", "description": "适用的费用明细。" }, "taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Fee" }, "title": "税", "description": "适用的税费明细。" }, "refundable": { "type": "boolean", "title": "是否可取消", "description": "true 表示在截止时间前取消可获退款，具体规则见 cancelPenalties。" }, "cancelPenalties": { "type": "array", "items": { "$ref": "#/components/schemas/CancelPenalty" }, "title": "取消规则", "description": "各取消阶段的罚金规则，按截止时间升序排列。" }, "nightlyRate": { "type": [ "object", "null" ], "properties": { "[stay date]": { "$ref": "#/components/schemas/NightlyRate" } }, "title": "每日价格", "description": "所有房间的每日价格", "additionalProperties": { "$ref": "#/components/schemas/NightlyRate" } }, "allotment": { "type": "integer", "title": "库存", "description": "该报价的可售库存，范围 1–99。", "minimum": 0, "exclusiveMinimum": 0, "maximum": 99 }, "onRequest": { "type": "boolean", "title": "是否是非立即确认", "description": "true 表示订单非立即确认，需供应商人工审核，确认可能延迟。如果订单无法在 60 秒内确认，请设为 true。" }, "remark": { "type": [ "string", "null" ], "title": "备注", "description": "供应商附加说明，如特殊入住条件或促销规则。" } }, "required": [ "ratePlanCode", "ratePlanName", "mealPlan", "refundable", "allotment", "price" ] }, "Price": { "type": "object", "properties": { "net": { "type": "number", "title": "成本", "description": "所有房间所有晚数的净价（成本）总额", "format": "float64", "minimum": 0, "exclusiveMinimum": 0, "examples": [ 99.99 ] }, "gross": { "type": "number", "title": "售价", "description": "建议零售价。", "format": "float64", "minimum": 0, "exclusiveMinimum": 0, "examples": [ 99.99 ] }, "currency": { "type": "string", "title": "货币", "description": "ISO 4217 货币代码，例如 USD、CNY。" }, "commission": { "type": [ "number", "null" ], "title": "佣金", "format": "float64" } }, "required": [ "net", "gross", "currency" ] }, "CancelPenalty": { "type": "object", "properties": { "deadline": { "type": "string", "format": "date-time", "title": "截止时间", "description": "在该时间（含）之后取消适用本条罚金规则。格式：ISO 8601，例如 2026-05-13T10:00:00Z。" }, "penaltyType": { "type": "string", "title": "罚款类型", "description": "NIGHTS：按晚数收取；PERCENT：按总价百分比收取；AMOUNT：按固定金额收取。" }, "value": { "type": "number", "description": "与 penaltyType 配合使用：NIGHTS 为晚数，PERCENT 为百分比（如 50 = 50%），AMOUNT 为金额。", "format": "float64", "minimum": 0 }, "currency": { "type": "string", "title": "货币", "description": "ISO 4217 货币代码。" } }, "required": [ "penaltyType", "value", "currency", "deadline" ] }, "BedType": { "type": "object", "properties": { "code": { "type": "string", "title": "床型编码", "description": "供应商定义的床型编码，例如 KING、DOUBLE、TWIN。" }, "name": { "type": "string", "title": "床型描述", "description": "例如 1 King Bed（1 张特大床）" }, "quantity": { "type": "integer", "title": "床型数量", "description": "房间内该床型的数量。" } }, "required": [ "code", "name", "quantity" ] }, "SearchHotel": { "type": "object", "properties": { "hotelCode": { "type": "string", "title": "酒店编码" }, "hotelName": { "type": "string", "title": "酒店名称" }, "rooms": { "type": "array", "title": "可选房型", "description": "该酒店在搜索条件下可售的房型及报价。请注意：搜索多间房时，所有房间必须为同一房型，即使每间房入住人数不同。", "items": { "$ref": "#/components/schemas/SearchRoom" } } }, "required": [ "hotelCode", "hotelName", "rooms" ] }, "SearchRoom": { "type": "object", "properties": { "roomType": { "$ref": "#/components/schemas/RoomType", "title": "房型" }, "options": { "type": "array", "description": "该房型的全部可售报价。", "items": { "$ref": "#/components/schemas/Option" }, "title": "报价列表" } }, "required": [ "roomType", "options" ] }, "Contact": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } }, "required": [ "firstName", "lastName" ] }, "Pax": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "type": "integer", "description": "儿童必填；成人选填。" }, "type": { "type": "string", "description": "ADULT：成人；CHILD：儿童", "enum": [ "ADULT", "CHILD" ] } }, "required": [ "firstName", "lastName", "type" ] }, "Payment": { "type": "object", "properties": { "type": { "type": "string", "description": "目前支持 virtual_card（虚拟信用卡）。" }, "number": { "type": "string", "description": "虚拟信用卡卡号。" }, "securityCode": { "type": "string", "description": "CVV/CVC 安全码。" }, "expirationMonth": { "type": "string", "description": "两位月份，例如 08。" }, "expirationYear": { "type": "string", "description": "四位年份，例如 2027。" }, "billingContact": { "type": "object", "properties": { "givenName": { "type": "string" }, "familyName": { "type": "string" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2，例如 US、CN。" }, "postalCode": { "type": "string" }, "address": { "type": "string" } }, "required": [ "givenName", "familyName", "countryCode", "postalCode", "address" ] } }, "required": [ "type", "billingContact", "expirationYear", "expirationMonth", "securityCode", "number" ] }, "Booking": { "type": "object", "properties": { "bookingCode": { "type": "string", "title": "供应商订单号", "description": "供应商系统生成的订单号，用于后续查询和取消。" }, "status": { "type": "string", "title": "订单状态", "description": "PENDING：处理中；CONFIRMED：已确认；FAILURE：预订失败；CANCELED：已取消。", "enum": [ "PENDING", "FAILURE", "CONFIRMED", "CANCELED" ] }, "referenceId": { "type": "string", "title": "客户订单号", "description": "途灵订单号" }, "hotelConfirmationNumber": { "type": "string", "title": "酒店确认号" }, "hotelCode": { "type": "string", "title": "酒店编码" }, "hotelName": { "type": "string", "title": "酒店名称" }, "checkIn": { "type": [ "string", "null" ], "title": "入住日期", "description": "格式：YYYY-MM-DD", "format": "date" }, "checkOut": { "type": [ "string", "null" ], "title": "离店日期", "description": "格式：YYYY-MM-DD", "format": "date" }, "holder": { "anyOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "null" } ], "title": "联系人" }, "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/RoomDetail" } }, "totalPrice": { "type": "number", "title": "订单总价", "description": "实际结算的净价（成本价）。", "format": "float64" }, "penaltyAmount": { "type": "number", "title": "取消罚金", "description": "适用于已取消订单，表示实际产生的罚金金额。", "format": "float64" }, "currency": { "type": "string", "title": "货币", "description": "totalPrice 与 penaltyAmount 的货币，ISO 4217 代码。" }, "commission": { "type": "number", "title": "佣金", "description": "该订单可赚取的佣金金额。", "format": "float64" }, "cancelPenalties": { "type": "array", "title": "取消规则", "description": "该订单适用的取消罚金规则。", "items": { "$ref": "#/components/schemas/CancelPenalty" } }, "remark": { "type": [ "string", "null" ], "title": "备注" }, "customerRequirements": { "type": [ "string", "null" ], "title": "顾客需求" }, "bookedTime": { "type": "string", "format": "date-time", "title": "预定时间", "description": "订单创建时间。格式：ISO 8601。" } }, "required": [ "bookingCode", "referenceId", "status", "hotelCode", "totalPrice", "currency" ] }, "Hotel": { "type": "object", "properties": { "hotelCode": { "type": "string", "title": "酒店编码", "description": "供应商系统内唯一的酒店编码。" }, "hotelName": { "type": "string", "title": "酒店名称" }, "starRating": { "type": "integer", "title": "星级", "description": "酒店星级，范围 1–5。" }, "category": { "type": "string", "title": "类型", "description": "例如 Hotel、Resort、Hostel、Apartment。" }, "countryCode": { "type": "string", "title": "国家编码", "description": "ISO 3166-1 alpha-2，例如 CN、JP、US。" }, "country": { "type": "string", "title": "国家名称" }, "cityCode": { "type": "string", "title": "城市编码", "description": "供应商定义的城市编码。" }, "city": { "type": "string", "title": "城市名称" }, "address": { "type": "string", "title": "酒店地址" }, "latitude": { "type": "string", "title": "维度", "description": "WGS84 纬度，例如 39.9042。" }, "longitude": { "type": "string", "title": "经度", "description": "WGS84 经度，例如 116.4074。" }, "email": { "type": "string" }, "phone": { "type": "string", "description": "包含国际区号，例如 +8610-12345678。" }, "rooms": { "type": [ "array", "null" ], "title": "所有房型", "description": "该酒店全部房型的静态信息。", "items": { "$ref": "#/components/schemas/RoomType" } }, "relatedCode": { "anyOf": [ { "$ref": "#/components/schemas/RelatedCode" }, { "type": "null" } ], "description": "第三方供应商匹配关系", "title": "第三方匹配关系" } }, "required": [ "hotelCode", "hotelName", "countryCode", "address", "country", "starRating", "latitude", "longitude" ] } }, "responses": {}, "securitySchemes": {} }, "servers": [], "security": [] }