{ "openapi": "3.1.0", "info": { "title": "Tourmind Hotel Supplier API(1.0)", "description": "Tourmind hotel pull API for supplier\n\n## Integration Process\n\n1. The supplier develops and tests the API.\n2. The supplier provides the test environment URL, api key, and secret. Tourmind will create some test bookings.\n3. The supplier completes the production environment configuration and provides the production environment URL, api key, and secret.\n4. Tourmind creates a cancellable test booking in the production environment.\n5. Go live\n\n\n## Authentication\n\nAll endpoints require an `Authorization` header using **HMAC-SHA256** signature scheme.\n\n### Signature Generation Steps\n\n1. Get the current Unix timestamp (integer seconds): `timestamp`\n2. Concatenate the signature input: `message = apiKey + apiSecret + timestamp`\n3. Compute HMAC-SHA256 of `message` using `apiSecret` as the key, then Base64-encode the result to get `signature`\n4. Assemble the Authorization header: `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 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| Parameter | Description |\n|-----------|-------------|\n| `apiKey` | The API key is provided by the supplier |\n| `apiSecret` | The API Secret is provided by the supplier |\n| `timestamp` | Unix timestamp (seconds) at request time; server allows ±300 seconds tolerance |\n| `signature` | Base64-encoded result of HMAC-SHA256(apiKey + apiSecret + timestamp, apiSecret) |", "version": "1.0.0" }, "tags": [], "paths": { "/search": { "post": { "summary": "Search", "deprecated": false, "description": "Search for bookable hotels and rooms that meet specific criteria.\nNote: When searching for multiple rooms, the same room type and rate plan apply to all rooms, but each room may have a different occupancy count. The returned price is the total amount (including taxes and fees, if applicable) for all rooms.", "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": "Search successful", "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": "Prebook", "deprecated": false, "description": "Call this API before making a reservation. This operation will verify the real-time price and availability of the selected room type and return a bookingToken for use in subsequent booking requests. The bookingToken must be valid for at least 10 minutes.\nTimeout: 12s", "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": "Pre-booking confirmation successful", "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": "Booking", "deprecated": false, "description": "The Booking operation requests a reservation confirmation for the specified rate option\nTimeout: 60s.", "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": "Booking created successfully", "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": "Cancel", "deprecated": false, "description": "Cancel a confirmed reservation using the referenceId or bookingCode. Returns the cancellation status and the actual penalty amount incurred.\nTimeout: 60s.", "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": "by bookingCode" } } } }, "required": true }, "responses": { "200": { "description": "Cancellation successful", "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": "Booking List", "deprecated": false, "description": "Search for booking details using the following criteria:\n1. referenceId: TourMind booking ID\n2. bookingCode: Supplier booking ID\n3. date range: Check-in / Booking Time\nNote: The supplier must support searching for bookings by referenceId or date range. When create or canceling a booking, network timeouts may prevent us from receiving a response; in such cases, we can only retrieve the booking status using the referenceId or date range.\nTimeout: 30s.", "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": "by bookingCode" }, "3": { "value": { "requestId": "16c74e57-9a86-4e34-843c-3dd66534ef434", "dateType": "BOOK", "startDate": "2026-04-01", "endDate": "2026-04-01" }, "summary": "by date range" } } } }, "required": true }, "responses": { "200": { "description": "Query successful", "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": "Hotel List", "deprecated": false, "description": "Retrieve hotel static data including basic hotel information and room type lists. Supports filtering by hotel code, country, or last update time. Results are paginated.", "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": "by updateTime" }, "3": { "value": { "countryCode": "US", "page": 1, "perPage": 100 }, "summary": "by countryCode" } } } }, "required": true }, "responses": { "200": { "description": "Query successful", "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": "Fee category code, e.g. 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": "Human-readable fee name, e.g. 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 currency code." }, "included": { "type": "boolean", "title": "是否包含在总价", "description": "true means this fee is already included in Price.net; false means the guest must pay it separately at the hotel." } }, "required": [ "type", "name", "amount", "currency", "included" ] }, "Occupancy": { "type": "object", "properties": { "roomId": { "type": "integer", "minimum": 1, "title": "房间序号", "description": "Unique identifier for a room within the same request. Starts from 1 and increments." }, "adults": { "type": "integer", "minimum": 1, "maximum": 5, "title": "成人数", "description": "Number of adults occupying the room.", "examples": [ 2 ] }, "childrenAges": { "type": [ "array", "null" ], "items": { "type": "integer", "maximum": 17, "minimum": 1, "examples": [ 8 ] }, "title": "儿童年龄", "description": "Age of each child in the room. The array length determines the number of children." } }, "required": [ "roomId", "adults" ] }, "NightlyRate": { "type": "object", "properties": { "net": { "type": "number", "examples": [ 99.99 ], "minimum": 0, "exclusiveMinimum": 0, "format": "float64", "description": "Net per night for all rooms", "title": "每晚成本" }, "gross": { "type": "number", "format": "float64", "examples": [ 99.99 ], "minimum": 0, "description": "Gross per night for all rooms", "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": "List of hotel codes to search. Maximum 30 hotels per request." }, "checkIn": { "type": "string", "title": "入住日期", "description": "Format: YYYY-MM-DD, e.g. 2025-08-15", "format": "date" }, "checkOut": { "type": "string", "title": "离店日期", "description": "Format: YYYY-MM-DD. Must be after checkIn, e.g. 2025-08-16", "format": "date" }, "occupancies": { "type": "array", "items": { "$ref": "#/components/schemas/Occupancy" }, "minItems": 1, "maxItems": 4, "title": "入住房间和人数", "description": "Each element represents the occupancy of one room." }, "language": { "type": [ "string", "null" ], "title": "语言", "description": "Language for response content, e.g. en-US, zh-CN. Defaults to English if not provided." }, "currency": { "type": [ "string", "null" ], "title": "货币", "description": "Desired price currency as ISO 4217 code, e.g. USD, CNY. Defaults to the supplier's base currency if not provided." }, "nationality": { "type": "string", "title": "国籍", "description": "ISO 3166-1 alpha-2 country code, e.g. CN, US. Affects pricing and tax rates for some suppliers." }, "timeout": { "type": "integer", "title": "超时", "description": "Timeout in milliseconds.", "examples": [ 3000 ] }, "requestId": { "type": "string", "title": "请求唯一id", "description": "A UUID generated by the caller for tracing and troubleshooting. Returned as-is in the response." } }, "required": [ "hotels", "checkIn", "checkOut", "occupancies", "requestId" ] }, "Search Response": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Matches the requestId sent in the request." }, "errors": { "type": [ "array", "null" ], "description": "Null or empty array on success. Contains error details when business errors occur.", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": "array", "description": "List of hotels and room rate quotes matching the search criteria. Returns an empty array if no results are available.", "items": { "$ref": "#/components/schemas/SearchHotel" } } }, "required": [ "requestId", "data" ] }, "Prebook Request": { "type": "object", "properties": { "requestId": { "type": "string", "description": "A UUID generated by the caller for tracing." }, "hotelCode": { "type": "string", "title": "酒店编码" }, "checkIn": { "type": "string", "description": "Format: YYYY-MM-DD", "format": "date", "title": "入住日期" }, "checkOut": { "type": "string", "title": "离店日期", "description": "Format: YYYY-MM-DD. Must be after checkIn.", "format": "date" }, "occupancies": { "type": "array", "title": "房间和人数", "description": "Must match the occupancies used in the original search request.", "items": { "$ref": "#/components/schemas/Occupancy" } }, "roomCode": { "type": "string", "title": "房型编码", "description": "Room type code from the search results (SearchRoom.roomType.code)." }, "ratePlanCode": { "type": "string", "title": "报价编码", "description": "Rate plan code from the search results (Option.ratePlanCode)." }, "optionToken": { "type": [ "string", "null" ], "title": "Option Token", "description": "The Option.token from the search results. Required by some suppliers to precisely identify the rate." }, "nationality": { "type": "string", "title": "旅客国籍", "description": "ISO 3166-1 alpha-2 country code, e.g. CN, US." } }, "required": [ "requestId", "hotelCode", "checkIn", "checkOut", "occupancies", "roomCode", "ratePlanCode" ] }, "Prebook Response": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Matches the requestId sent in the request." }, "errors": { "type": [ "array", "null" ], "description": "Null on success. Contains error details when business errors occur.", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": [ "object", "null" ], "description": "Pre-booking confirmation result. Null if the room type is unavailable.", "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 used to create the booking. Pass to Booking Request.bookingToken. The token's validity period must be at least 10 minutes." }, "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": "If the reservation cannot be confirmed within 60 seconds, set this to 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": "A UUID generated by the caller for tracing and idempotency control." }, "referenceId": { "type": "string", "title": "途灵订单号", "description": "Tourmind Booking id" }, "hotelCode": { "type": "string", "title": "酒店编码" }, "checkIn": { "type": "string", "description": "Format: YYYY-MM-DD", "format": "date", "title": "入住日期" }, "checkOut": { "type": "string", "description": "Format: YYYY-MM-DD", "format": "date", "title": "离店日期" }, "bookingToken": { "type": "string", "title": "Booking Token", "description": "From Prebook Response.data.bookingToken." }, "holder": { "$ref": "#/components/schemas/Contact", "title": "联系人" }, "occupancies": { "type": "array", "description": "Guest list per room. roomId must match the values used in the search request.", "items": { "type": "object", "properties": { "roomId": { "type": "integer", "title": "Room ID", "description": "Corresponds to Occupancy.roomId in the search request." }, "paxes": { "type": "array", "title": "Guest List", "items": { "$ref": "#/components/schemas/Pax" } } }, "required": [ "roomId", "paxes" ] }, "title": "房型和人数" }, "totalPrice": { "type": "number", "description": "From Prebook Response.data.price.net. ", "title": "预定总价" }, "currency": { "type": "string", "description": "Currency for totalPrice as an ISO 4217 code, e.g. USD, CNY.", "title": "货币" }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-2 country code, e.g. CN, US.", "title": "国籍" }, "customerRequirements": { "type": [ "string", "null" ], "title": "顾客要求" }, "payment": { "description": "Virtual credit card details. Required by some suppliers only.", "anyOf": [ { "title": "Payment Information", "description": "Virtual credit card details. Required by some suppliers only.", "$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": "Request ID", "description": "Matches the requestId sent in the request." }, "errors": { "type": [ "array", "null" ], "title": "Error List", "description": "Null on success. Contains error details when the booking fails.", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "title": "Booking Data", "description": "Details of the successfully created booking. Null if the booking failed.", "anyOf": [ { "title": "Booking Data", "description": "Details of the successfully created booking. Null if the booking failed.", "$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": "Used with startDate/endDate. CHECKIN filters by check-in date; BOOK filters by booking creation date.", "enum": [ "CHECKIN", "BOOK" ] }, "startDate": { "type": "string", "description": "Format: YYYY-MM-DD. Used in combination with endDate and dateType.", "format": "date" }, "endDate": { "type": "string", "description": "Format: YYYY-MM-DD. Used in combination with startDate and 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": "List of bookings matching the criteria. Returns an empty array if no results are found.", "items": { "$ref": "#/components/schemas/Booking" } } }, "required": [ "requestId" ] }, "Cancel Request": { "type": "object", "properties": { "requestId": { "type": "string", "title": "Request ID", "description": "A UUID generated by the caller for tracing and idempotency control." }, "referenceId": { "type": "string", "description": "Tourmind booking id", "title": "途灵订单号" }, "bookingCode": { "type": "string", "title": "供应商订单号", "description": " " } }, "required": [ "requestId" ] }, "Cancel Response": { "type": "object", "properties": { "requestId": { "type": "string" }, "errors": { "type": [ "array", "null" ], "description": "Null on success. Contains error details when the cancellation fails.", "items": { "$ref": "#/components/schemas/Error" } }, "data": { "type": "object", "properties": { "referenceId": { "type": "string" }, "bookingCode": { "type": "string", "description": "The booking number in the supplier's system." }, "status": { "type": "string", "title": "取消状态", "description": "Typically CANCELED after a successful cancellation.", "enum": [ "PENDING", "FAILURE", "CONFIRMED", "CANCELED" ] }, "penaltyAmount": { "type": "number", "title": "取消费用", "description": "The actual penalty amount incurred by this cancellation. 0 for free cancellations.", "format": "float64" }, "currency": { "type": "string", "description": "Currency for penaltyAmount as an ISO 4217 code." } }, "required": [ "referenceId", "bookingCode", "status", "penaltyAmount", "currency" ] } }, "required": [ "requestId", "data" ] }, "HotelList Request": { "type": "object", "properties": { "hotels": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Specific hotel codes to query. Maximum 100. Mutually exclusive with countryCode. If neither is provided, all hotels are returned (paginated)." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code to filter hotels by country, e.g. CN, JP." }, "updateTime": { "type": [ "string", "null" ], "format": "date-time", "description": "Returns only hotels that have changed since this timestamp. Used for incremental static data sync. Format: ISO 8601." }, "page": { "type": "integer", "description": "Starts from 1.", "minimum": 1, "default": 1, "examples": [ 1 ] }, "perPage": { "type": "integer", "description": "Number of hotels per page. Range: 1–100. Defaults to 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 number of pages." }, "total": { "type": "integer", "title": "总酒店数", "description": "Total number of hotels matching the criteria." } }, "required": [ "page", "perPage", "pages", "total" ] }, "hotels": { "type": "array", "items": { "$ref": "#/components/schemas/Hotel" } } }, "required": [ "pagination", "hotels" ] } } }, "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "e.g. HOTEL_NOT_FOUND, PRICE_CHANGED.", "enum": [ "VALIDATION_ERROR", "TIMEOUT", "RATE_LIMIT", "SYSTEM_ERROR", "NO_AVAILABILITY", "PRICE_CHANGED", "INSUFFICIENT_CREDIT", "UNKNOWN" ] }, "message": { "type": "string", "description": "Human-readable error description." } }, "required": [ "code", "message" ] }, "RoomType": { "type": "object", "properties": { "code": { "type": "string", "title": "房型唯一编码", "description": "Unique room type code within the supplier's system." }, "name": { "type": "string", "title": "房型名称", "description": "e.g. Deluxe Double Room" }, "area": { "type": "integer", "title": "面积", "description": "Room area in square meters." }, "bedTypes": { "type": [ "array", "null" ], "title": "床型", "description": "Bed configuration for this room type. May include multiple bed types.", "items": { "$ref": "#/components/schemas/BedType" } }, "maxOccupancy": { "type": "integer", "title": "最大入住人数", "description": "Maximum total number of guests (adults + children) the room can accommodate." }, "maxAdults": { "type": "integer", "title": "最大成人数", "description": "Maximum number of adults the room can accommodate." }, "maxChildren": { "type": "integer", "title": "最大儿童数", "description": "Maximum number of children the room can accommodate." }, "relatedCode": { "anyOf": [ { "$ref": "#/components/schemas/RelatedCode" }, { "type": "null" } ], "title": "第三方匹配关系" } }, "required": [ "code", "name" ] }, "MealPlan": { "type": "object", "properties": { "code": { "type": "string", "title": "餐食编码", "description": "Standard meal plan code, e.g. RO (Room Only), BB (Bed & Breakfast), HB (Half Board), FB (Full Board), AI (All Inclusive).", "enum": [ "RO", "BB", "HB", "FB", "AI", "BF1", "BF2", "BF3", "BF4", "LC", "DN", "LD" ], "examples": [ "RO" ] }, "name": { "type": "string", "title": "餐食描述", "description": "e.g. Room Only, Bed & Breakfast", "examples": [ "Room Only" ] }, "isIncludeChildren": { "type": "boolean", "title": "是否包含儿童", "description": "true means the meal plan covers children; false means adults only." } }, "required": [ "code", "name", "isIncludeChildren" ] }, "Option": { "type": "object", "properties": { "token": { "type": [ "string", "null" ], "title": "Option Token", "description": "Unique rate token from the supplier. Pass to Prebook Request.optionToken. Required by some suppliers." }, "ratePlanCode": { "type": "string", "title": "报价唯一Code", "description": "Unique code for this rate within the supplier's system." }, "ratePlanName": { "type": "string", "title": "报价名称", "description": "e.g. Early Bird, Non-Refundable Rate" }, "mealPlan": { "$ref": "#/components/schemas/MealPlan", "title": "餐食" }, "price": { "$ref": "#/components/schemas/Price", "title": "价格", "description": "Total price for all rooms" }, "fees": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Fee" }, "title": "服务费", "description": "Applicable fee breakdown." }, "taxes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Fee" }, "title": "税", "description": "Applicable tax breakdown." }, "refundable": { "type": "boolean", "title": "是否可取消", "description": "true indicates a cancellation before the deadline qualifies for a refund. See cancelPenalties for specific rules." }, "cancelPenalties": { "type": "array", "items": { "$ref": "#/components/schemas/CancelPenalty" }, "title": "取消规则", "description": "Penalty rules for each cancellation phase, sorted in ascending order by deadline." }, "nightlyRate": { "type": [ "object", "null" ], "properties": { "[stay date]": { "$ref": "#/components/schemas/NightlyRate" } }, "title": "每日价格", "description": "Nightly price for all rooms", "additionalProperties": { "$ref": "#/components/schemas/NightlyRate" } }, "allotment": { "type": "integer", "title": "库存", "description": "Plan allotment available. Range: 1–99.", "minimum": 0, "exclusiveMinimum": 0, "maximum": 99 }, "onRequest": { "type": "boolean", "title": "是否是非立即确认", "description": "true indicates the booking is not instantly confirmed and requires manual review by the supplier. Confirmation may be delayed. If the reservation cannot be confirmed within 60 seconds, set this to true." }, "remark": { "type": [ "string", "null" ], "title": "备注", "description": "Additional supplier notes, such as special check-in conditions or promotional rules." } }, "required": [ "ratePlanCode", "ratePlanName", "mealPlan", "refundable", "allotment", "price" ] }, "Price": { "type": "object", "properties": { "net": { "type": "number", "title": "成本", "description": "Total net price for all rooms and all nights", "format": "float64", "minimum": 0, "exclusiveMinimum": 0, "examples": [ 99.99 ] }, "gross": { "type": "number", "title": "售价", "description": "Recommended retail price. ", "format": "float64", "minimum": 0, "exclusiveMinimum": 0, "examples": [ 99.99 ] }, "currency": { "type": "string", "title": "货币", "description": "ISO 4217 currency code, e.g. 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": "This penalty rule applies to cancellations made on or after this time. Format: ISO 8601, e.g. 2026-05-13T10:00:00Z." }, "penaltyType": { "type": "string", "title": "罚款类型", "description": "NIGHTS: charged per night; PERCENT: charged as a percentage of the total price; AMOUNT: charged as a fixed amount." }, "value": { "type": "number", "description": "Used together with penaltyType: number of nights for NIGHTS, percentage (e.g. 50 = 50%) for PERCENT, or monetary amount for AMOUNT.", "format": "float64", "minimum": 0 }, "currency": { "type": "string", "title": "货币", "description": "ISO 4217 currency code." } }, "required": [ "penaltyType", "value", "currency", "deadline" ] }, "BedType": { "type": "object", "properties": { "code": { "type": "string", "title": "床型编码", "description": "Supplier-defined bed type code, e.g. KING, DOUBLE, TWIN." }, "name": { "type": "string", "title": "床型描述", "description": "e.g. 1 King Bed" }, "quantity": { "type": "integer", "title": "床型数量", "description": "Number of this bed type in the room." } }, "required": [ "code", "name", "quantity" ] }, "SearchHotel": { "type": "object", "properties": { "hotelCode": { "type": "string", "title": "酒店编码" }, "hotelName": { "type": "string", "title": "酒店名称" }, "rooms": { "type": "array", "title": "可选房型", "description": "Available room types and rates for this hotel under the search criteria. Please note that when searching for multiple rooms, all rooms must be of the same type, even if the number of guests per room differs.", "items": { "$ref": "#/components/schemas/SearchRoom" } } }, "required": [ "hotelCode", "hotelName", "rooms" ] }, "SearchRoom": { "type": "object", "properties": { "roomType": { "$ref": "#/components/schemas/RoomType", "title": "房型" }, "options": { "type": "array", "description": "All available rates for this room type.", "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": "Required for children; optional for adults." }, "type": { "type": "string", "description": "ADULT: adult; CHILD: children", "enum": [ "ADULT", "CHILD" ] } }, "required": [ "firstName", "lastName", "type" ] }, "Payment": { "type": "object", "properties": { "type": { "type": "string", "description": "Currently supports virtual_card (virtual credit card)." }, "number": { "type": "string", "description": "Virtual credit card number." }, "securityCode": { "type": "string", "description": "CVV/CVC security code." }, "expirationMonth": { "type": "string", "description": "Two-digit month, e.g. 08." }, "expirationYear": { "type": "string", "description": "Four-digit year, e.g. 2027." }, "billingContact": { "type": "object", "properties": { "givenName": { "type": "string" }, "familyName": { "type": "string" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2, e.g. 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": "Booking number generated by the supplier's system. Used for subsequent queries and cancellations." }, "status": { "type": "string", "title": "订单状态", "description": "PENDING: processing; CONFIRMED: confirmed; FAILURE: booking failed; CANCELED: cancelled.", "enum": [ "PENDING", "FAILURE", "CONFIRMED", "CANCELED" ] }, "referenceId": { "type": "string", "title": "客户订单号", "description": "Tourmind booking id" }, "hotelConfirmationNumber": { "type": "string", "title": "酒店确认号" }, "hotelCode": { "type": "string", "title": "酒店编码" }, "hotelName": { "type": "string", "title": "酒店名称" }, "checkIn": { "type": [ "string", "null" ], "title": "入住日期", "description": "Format: YYYY-MM-DD", "format": "date" }, "checkOut": { "type": [ "string", "null" ], "title": "离店日期", "description": "Format: 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": "The actual settled net price (cost price).", "format": "float64" }, "penaltyAmount": { "type": "number", "title": "取消罚金", "description": "Applicable for cancelled bookings. Represents the actual penalty amount incurred.", "format": "float64" }, "currency": { "type": "string", "title": "货币", "description": "Currency for totalPrice and penaltyAmount as an ISO 4217 code." }, "commission": { "type": "number", "title": "佣金", "description": "Earnable commission amount for this booking.", "format": "float64" }, "cancelPenalties": { "type": "array", "title": "取消规则", "description": "Cancellation penalty rules applicable to this booking.", "items": { "$ref": "#/components/schemas/CancelPenalty" } }, "remark": { "type": [ "string", "null" ], "title": "备注" }, "customerRequirements": { "type": [ "string", "null" ], "title": "顾客需求" }, "bookedTime": { "type": "string", "format": "date-time", "title": "预定时间", "description": "Booking creation timestamp. Format: ISO 8601." } }, "required": [ "bookingCode", "referenceId", "status", "hotelCode", "totalPrice", "currency" ] }, "Hotel": { "type": "object", "properties": { "hotelCode": { "type": "string", "title": "酒店编码", "description": "Unique hotel code within the supplier's system." }, "hotelName": { "type": "string", "title": "酒店名称" }, "starRating": { "type": "integer", "title": "星级", "description": "Hotel star classification. Range: 1–5." }, "category": { "type": "string", "title": "类型", "description": "e.g. Hotel, Resort, Hostel, Apartment." }, "countryCode": { "type": "string", "title": "国家编码", "description": "ISO 3166-1 alpha-2, e.g. CN, JP, US." }, "country": { "type": "string", "title": "国家名称" }, "cityCode": { "type": "string", "title": "城市编码", "description": "Supplier-defined city code." }, "city": { "type": "string", "title": "城市名称" }, "address": { "type": "string", "title": "酒店地址" }, "latitude": { "type": "string", "title": "维度", "description": "WGS84 latitude, e.g. 39.9042." }, "longitude": { "type": "string", "title": "经度", "description": "WGS84 longitude, e.g. 116.4074." }, "email": { "type": "string" }, "phone": { "type": "string", "description": "Include international dialing code, e.g. +8610-12345678." }, "rooms": { "type": [ "array", "null" ], "title": "所有房型", "description": "Static information for all room types at this hotel.", "items": { "$ref": "#/components/schemas/RoomType" } }, "relatedCode": { "anyOf": [ { "$ref": "#/components/schemas/RelatedCode" }, { "type": "null" } ], "description": "Third-Party Supplier Matching Relationships", "title": "第三方匹配关系" } }, "required": [ "hotelCode", "hotelName", "countryCode", "address", "country", "starRating", "latitude", "longitude" ] } }, "responses": {}, "securitySchemes": {} }, "servers": [], "security": [] }