{ "openapi": "3.0.3", "info": { "title": "房狸公開訂房查詢", "version": "1.3.0", "description": "唯讀即時住宿試算。從民宿訂房頁的 alternate / describedby 連結取得本 API 與文件。必填 check_in、check_out（YYYY-MM-DD）、adults；children、infants 預設 0；不提供嬰兒床選項。最多 30 晚，每 IP 每分鐘 120 次。received_conditions 是實際套用條件，ignored_fields 是未處理欄位。pricing 的金額為選定一間房或一個包棟、全部晚數與本次旅客的住宿總價；不是每晚或每人價。包含已設定加人、必要加床，另選加購、活動不含在內。null 代表未確認，絕不可當作 0。只在 can_book=true 時可引導訂房；is_demo=true / query_status=estimate_only 僅供展示試算，不能當成正式可訂。query_status 說明入口狀態，eligibility_status 和 reason_codes 解釋個別方案不符原因。checked_at 是查詢時間，quote_expires_at 同該時間，quote_validity_seconds=0 表示不保價、不保留庫存。回覆 no-store；進入建立訂單會重新核對房況與計價。只能轉發 booking_url 中已驗證的來源，不自行添加或取代來源；API 查詢不記錄聯盟點擊。退款以 cancellation_policy 為準，未正式可訂時退款金額為 null。 pricing.status=not_quoted 代表房況或人數不符而未計算本次總價，不等於免費或必然缺少價格設定。 先提供日期與全體旅客人數，房間模式回傳 room_guidance.feasible_room_counts 與 room_combinations。每個組合包含完整逐房旅客、全程合計與保留條件的 booking_url；items 仍表示一間房或一個包棟，因此單房人數不符時也可能有可行多房組合。每間房至少一位成人；兒童與嬰兒需提供入住當天年齡才能安排。complete=false 代表組合搜尋或旅客資料不完整，不可推斷客滿；建議組合不是全部組合或最低價保證。查詢不鎖房，後續重新驗價驗房。 新包棟依主人指定的開放房間逐房核對；package_allocation 顯示本次入住安排。guest_pricing.mode=shared_occupancy 以含價總人數計加人費，免費年齡不代表可超過入住上限。needs_confirmation / search_incomplete 代表安排待確認，不能解讀為人數不符或已滿房。請求最多300人；實際以各房型及方案上限為準。 房間若已設定不加床加住名額，會提供 sleeping_arrangement：no_bed_extra_guests 是整間房可用名額，no_bed_guests_used 是本次實際使用人數，required_extra_beds 是本次仍需加床張數。名額包含成人、兒童及嬰兒，所有人仍受全房總上限限制；不加床不代表免加人費。未設定的舊房型省略此欄位，不可當作 0；實際使用量為 null 代表尚未確認。多房組合逐房提供同樣欄位，包棟在 package_allocation.rooms 提供相同名額與 extra_beds。" }, "servers": [ { "url": "/" } ], "paths": { "/booking/{bookingChannelCode}/availability": { "get": { "operationId": "getBookingAvailability", "parameters": [ { "name": "bookingChannelCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel from the canonical /booking/{bookingChannelCode} URL." }, { "name": "check_in", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "check_out", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 300 } }, { "name": "children", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 300 } }, { "name": "infants", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 300 } }, { "name": "infant_cots", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 0 }, "deprecated": true, "description": "不提供此選項。相容舊連結僅接受 0，正數會回 422。" }, { "name": "stay_kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "room", "package" ] } }, { "name": "child_ages", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17, "nullable": true }, "maxItems": 300 }, "description": "與兒童人數相同，依民宿 guest_policy 的年齡範圍。使用 child_ages[]=7。未提供年齡時不代表已完成入住年齡驗證。", "style": "form", "explode": true }, { "name": "infant_ages", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2, "nullable": true }, "maxItems": 300 }, "description": "與嬰兒人數相同，依民宿 guest_policy。使用 infant_ages[]=1。", "style": "form", "explode": true }, { "name": "guests", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 300 }, "description": "可省略；若提供必須等於 adults+children+infants。" }, { "name": "affiliate_tracking_code", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Optional existing referral context; only valid, authorized source is retained in booking_url." }, { "name": "yingda_ref", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 }, "description": "Optional existing referral context; only valid, authorized source is retained in booking_url." }, { "name": "overflow_source_property_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional existing referral context; only valid, authorized source is retained in booking_url." }, { "name": "overflow_source_channel_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Optional existing referral context; only valid, authorized source is retained in booking_url." }, { "name": "room_count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10 }, "description": "可省略的偏好間數，並非強制條件。先由全體人數計算可行間數；若此偏好不可行，回傳其他可行選項，絕不增加旅客。" } ], "responses": { "200": { "description": "完整查詢條件、方案資格、分項價格與保留條件的訂房連結；can_book=false 或 demo 不可當成可售。", "content": { "application/json": { "schema": { "type": "object", "required": [ "schema_version", "checked_at", "status", "can_book", "is_demo", "property", "search", "items", "booking_url" ], "properties": { "schema_version": { "type": "string" }, "checked_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "available", "unavailable", "not_open", "unconfirmed" ] }, "can_book": { "type": "boolean" }, "is_demo": { "type": "boolean" }, "property": { "type": "object" }, "search": { "type": "object" }, "guest_policy": { "type": "object" }, "stay_information": { "type": "object" }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } }, "description": "完整且去重的常見問題，包含民宿公開回答與適用的線上付款／取消規則。FAQ 僅在此欄位提供；public_content 不再重複包含 faqs。" }, "booking_notices": { "type": "array", "items": { "type": "object" } }, "price_scope": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "name", "status", "can_book", "availability", "accommodation_total", "currency", "booking_url" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "room", "package" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "capacity": { "type": "string" }, "image": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "available", "unavailable", "not_open", "unconfirmed" ] }, "can_book": { "type": "boolean" }, "availability": { "type": "boolean", "nullable": true, "description": "Null means not verified for sale, never infer available." }, "accommodation_total": { "type": "integer", "nullable": true, "description": "Accommodation total for the full stay in major currency units. Null unless bookable. Optional extras excluded." }, "currency": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "booking_url": { "type": "string", "format": "uri" }, "query_status": { "type": "string", "enum": [ "available", "sold_out", "capacity_mismatch", "not_open", "price_pending", "stay_restriction", "estimate_only", "no_matching_options", "needs_confirmation", "search_incomplete" ] }, "status_label": { "type": "string" }, "eligibility_status": { "type": "string", "enum": [ "available", "sold_out", "capacity_mismatch", "not_open", "price_pending", "stay_restriction", "needs_confirmation", "search_incomplete" ] }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "capacity_limits": { "type": "object", "properties": { "included_guests": { "type": "integer" }, "maximum_guests": { "type": "integer" } } }, "pricing": { "type": "object", "properties": { "base_amount": { "type": "integer", "nullable": true, "minimum": 0 }, "adult_surcharge_amount": { "type": "integer", "nullable": true, "minimum": 0 }, "child_surcharge_amount": { "type": "integer", "nullable": true, "minimum": 0 }, "infant_surcharge_amount": { "type": "integer", "nullable": true, "minimum": 0 }, "additional_guest_amount": { "type": "integer", "nullable": true, "minimum": 0 }, "required_extra_bed_amount": { "type": "integer", "nullable": true, "minimum": 0 }, "requested_infant_cot_amount": { "type": "integer", "nullable": true, "minimum": 0 }, "mandatory_fees_amount": { "type": "integer", "nullable": true, "minimum": 0, "description": "必要加床費小計，已包含於 total_amount；不可與 required_extra_bed_amount 重複加總。" }, "total_amount": { "type": "integer", "nullable": true, "minimum": 0, "description": "基本房費 + 加人費 + 必要加床 + 所選嬰兒床。任何必要費用未確認時為 null。" }, "status": { "type": "string", "enum": [ "calculated", "pending", "estimate_only", "not_quoted" ] }, "currency": { "type": "string" }, "party_size": { "type": "integer" }, "nights": { "type": "integer" }, "quantity": { "type": "integer", "enum": [ 1 ] }, "unconfirmed_components": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "is_binding": { "type": "boolean", "enum": [ false ] }, "recheck_required": { "type": "boolean", "enum": [ true ] }, "is_demo": { "type": "boolean" }, "amounts_confirmed": { "type": "boolean" } }, "required": [ "status", "currency", "party_size", "nights", "base_amount", "additional_guest_amount", "mandatory_fees_amount", "total_amount", "unconfirmed_components", "is_demo", "is_binding" ] }, "cancellation_policy": { "type": "object", "nullable": true, "description": "同一套住宿取消規則：訂金基準、時區、依入住日計算的退款日期/比例/金額。amounts_confirmed=false 時金額不得視為承諾。" }, "sleeping_arrangement": { "type": "object", "description": "只在主人明確設定不加床名額時提供；免費旅客也占入住名額，不加床不代表加人免費。", "properties": { "no_bed_extra_guests": { "type": "integer", "minimum": 0 }, "no_bed_guests_used": { "type": "integer", "minimum": 0, "nullable": true }, "required_extra_beds": { "type": "integer", "minimum": 0, "nullable": true } } } } } }, "booking_url": { "type": "string", "format": "uri" }, "documentation_url": { "type": "string", "format": "uri" }, "query_status": { "type": "string", "enum": [ "available", "sold_out", "capacity_mismatch", "not_open", "price_pending", "stay_restriction", "estimate_only", "no_matching_options", "needs_confirmation", "search_incomplete" ] }, "status_label": { "type": "string" }, "received_conditions": { "type": "object", "description": "Normalized effective dates, nights, adults, children, infants, ages, cots, guests and stay_kind (room/package/all)." }, "ignored_fields": { "type": "array", "items": { "type": "string" } }, "status_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "quote_expires_at": { "type": "string", "format": "date-time" }, "quote_validity_seconds": { "type": "integer", "enum": [ 0 ] }, "recheck_required": { "type": "boolean", "enum": [ true ] }, "attribution": { "type": "object" }, "room_guidance": { "type": "object", "nullable": true, "description": "房間安排查詢狀態；包棟查詢為 null。", "properties": { "feasible_room_counts": { "type": "array", "items": { "type": "integer" } }, "selected_room_count": { "type": "integer", "nullable": true }, "complete": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "matched", "missing_ages", "search_limit", "no_match", "invalid_party" ] }, "message": { "type": "string", "nullable": true } } }, "room_combinations": { "type": "array", "description": "同一筆訂單的房間組合，全體旅客與年齡完整分配，每個間數最多三組。每組可調整後重新報價。", "items": { "type": "object", "required": [ "room_count", "rooms", "pricing", "can_book", "booking_url" ], "properties": { "room_count": { "type": "integer" }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "sleeping_arrangement": { "type": "object", "description": "只在主人明確設定不加床名額時提供；免費旅客也占入住名額，不加床不代表加人免費。", "properties": { "no_bed_extra_guests": { "type": "integer", "minimum": 0 }, "no_bed_guests_used": { "type": "integer", "minimum": 0, "nullable": true }, "required_extra_beds": { "type": "integer", "minimum": 0, "nullable": true } } } } } }, "pricing": { "type": "object", "description": "total_amount 為整組全晚住宿金額，is_demo=true 僅供试算。" }, "can_book": { "type": "boolean" }, "accommodation_total": { "type": "integer", "nullable": true }, "booking_url": { "type": "string" } } } } } } } } }, "404": { "description": "No public active property/channel." }, "422": { "description": "缺少必填、日期不符、總人數不一致、年齡不符或超出 30 晚。", "content": { "application/json": { "example": { "query_status": "invalid_request", "can_book": false, "missing_fields": [ "check_in", "check_out", "adults" ], "errors": { "check_in": [ "The check in field is required." ] } } } } }, "429": { "description": "每 IP 每分鐘 120 次，依 Retry-After 後再查。不要用重試繞過限制。" }, "503": { "description": "query_status=query_failed、can_book=false、retryable=true；未知錯誤不會偽裝成滿房。" } }, "x-query-example": "/booking/{bookingChannelCode}/availability?check_in=2026-12-01&check_out=2026-12-02&adults=12&children=0&infants=0&stay_kind=package", "x-pricing-examples": { "configured_12_guests": { "base_amount": 13000, "additional_guest_amount": 1000, "mandatory_fees_amount": 0, "requested_infant_cot_amount": 0, "total_amount": 14000, "unconfirmed_components": [] }, "unconfirmed_extra_guests": { "base_amount": 13000, "additional_guest_amount": null, "total_amount": null, "unconfirmed_components": [ "additional_guest" ], "status": "pending" }, "demo": { "query_status": "estimate_only", "can_book": false, "availability": null, "accommodation_total": null, "pricing": { "status": "estimate_only", "total_amount": 14000, "is_demo": true, "amounts_confirmed": false } } } } } } }