郵輪B2C P3 放掉一間佔房（ReleaseHold）

API Content

說明

放掉一間房的佔房（一次一間），這間的佔房、填寫頁報價、旅客資料作廢（旅客要重填）；選好的方案、艙型、房號不清。只有那間已佔房才打：手上有這間的 Hold_Until_Time。

方法：POST

路徑：Cruise/Products/ReleaseHold

對應畫面：P3 已選艙房區按某一間的〔重選艙房〕，而那間已佔房（佔房倒數歸零不打這支，打 ReleaseAllHolds 一次全部放）

使用重點：

按〔重選艙房〕時，那間有沒有佔房看手上這間的 Hold_Until_Time（CreateHold 回的）。P3 重整時有保留會先打 ReleaseAllHolds 全部放掉，重整後不會打到這支。人在 P3 卻有佔房的只有兩種：從填寫頁回 P3 改選某一間、按〔下一步〕只佔到一間被退回 P3 後改選佔到的那間

有佔房：先跳確認「保留會放掉」，客人確認後才打。沒佔房：不打，前端清掉這間的選擇就好

〔重選艙房〕不重查艙型：用手上的卡片重選這間，選房號再打 QueryCabin；選好按〔下一步〕，由 CreateHold 帶新的選擇重新佔房

佔房倒數歸零不打這支：跳視窗後打 ReleaseAllHolds 一次放掉全部，再導回選房號頁、全部房重選（見 ReleaseAllHolds 文件）

連續放兩間（客人兩間都改選）時依序打，第二支帶第一支回的 Session_Version

存旅客或送出時回 1003 佔房已逾時：後端已經放掉了，前端清掉手上的 Hold_Until_Time，這支和 ReleaseAllHolds 都不用打

Session_Version 帶手上最新的值：QueryCategory 回第一個值，之後每支寫入（CreateHold、本 API 等）都回新的值

文件版本：v1.0（未交付）

規格調整

日期	版本	調整內容
2026/11/11	v1.0（未交付）	初版

Request Schema

Body

名稱	描述	屬性	範例
Page_Id	必填。QueryCategory 回的 `Page_Id`	String	6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f
Room_Seq	必填。第幾間，同 QueryCategory `Room_List[].Room_Seq`	Int	1
Session_Version	必填。手上最新的訂位版本（見說明）	Int	3

JSON 範例

{
  "Page_Id": "6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "Room_Seq": 1,
  "Session_Version": 3
}

Response Schema

回應主體

名稱	描述	屬性	範例
Result_Info	結果資訊；前端先看 `Is_Success`	Object	參考 Result_Info
Result_Data	成功時是本端點的資料；不是成功時只放該代碼要帶的資料（見「錯誤回應」），沒有就是 `{}`	Object	參考 Result_Data

Result_Info

名稱	描述	屬性	範例
Is_Success	`true`＝成功；`false`＝看 `Result_Code`	Bool	true
Result_Code	結果代碼（四碼數字）；成功是空字串；其他見「錯誤回應」	String
Result_Message	給客人看的訊息；成功是空字串	String

Result_Data

名稱	描述	屬性	範例
Session_Version	新的訂位版本，下一支寫入帶這個	Int	4

JSON 範例

{
  "Result_Info": {
    "Is_Success": true,
    "Result_Code": "",
    "Result_Message": ""
  },
  "Result_Data": {
    "Session_Version": 4
  }
}

錯誤回應

200 的代碼在 Result_Info.Result_Code、訊息在 Result_Message；400、500 只回一句訊息，代碼在訊息開頭（格式「代碼｜訊息」，例「4002｜Start_Date 格式錯誤」）。訊息欄除了「重複訂位」與「出發日期已無法訂購，請重新選擇」已定，其他是暫定文字，UIUX 定稿後只改文字、不改代碼；N＝第幾間。

HTTP	Result_Code	中文名稱	訊息（給客人看）	情境	前端動作
400	4001／4002	缺少必填參數／參數格式錯誤	不給客人看（訊息開頭是代碼）	`Page_Id`、`Room_Seq`、`Session_Version` 沒帶（4001）或格式錯（4002）	前端帶錯值，修正後重打
200	5003	選擇已失效	選擇已失效，請重新查詢	`Room_Seq` 不對（這筆訂位沒有這一間）	顯示 `Result_Message`
200	2003	資料版本不符	資料已更新，請重新整理	版本不符（例：開了兩個分頁，另一頁改過）	重新還原整包後再操作（🟡 還原整包的 GetBooking 文件之後給）
200	2001	訂位資料不存在	訂位資料已失效，請重新選擇	`Page_Id` 找不到	手上有行程與人數就在 P3 開「艙房／人數」燈箱重新查詢（在 P4 先回 P3）；沒有就回 P2 重新選
200	2002	訂單已成立	訂單已成立	這筆訂位已經成立訂單，不放房	導向訂單頁（🟡 訂單頁文件之後給）
500	9999	系統錯誤	9999｜系統發生錯誤，請稍後再試	系統錯誤（未預期的例外）	顯示友善錯誤訊息，可以重試

測試情境/單元測試(開發前規劃)

畫面呼叫

舊版畫面

新版畫面

UIUX 20260922 版 P3-W01：已選艙房區（WEB 左欄、手機寬度底部列展開）每一間的〔重選艙房〕，那間已佔房時打本 API。這支沒有對應的畫面欄位，不附畫面欄位對照圖。