API Content

說明

客人在 P3 按〔下一步：填寫旅客資料〕時打：把每間房選的方案、艙型、房號一起送進來，每間房都佔房（保留 15 分鐘）。都佔到才進 P4；有房佔不到就回 P3 重選那間，佔到的留著。

• 方法：POST

• 路徑：Cruise/Products/CreateHold

• 對應畫面：P3 選擇艙房〔下一步：填寫旅客資料〕

使用重點：

• P3 選卡片、房號時前端先記著（不打 API），按〔下一步〕時用這支一次送出。每間房都要帶，一間一筆：Plan_Id、Category_Id、Fare_Code 取這間選的 QueryCategory 卡片，Cabin_Number 取 QueryCabin 選的房號，系統配房、保證艙送 GTY

• 卡片要是這間最近一次 QueryCategory 回的（重查過就用重查回的），不然回 5003 選擇已失效。兩間不能選同一個房號（保證艙除外）：前端在房號清單先擋，送進來也會回 1002 重複佔房

• 成功：記下 Session_Version（之後的寫入帶這個）和每間的 Hold_Until_Time，進 P4；P4 倒數用 Earliest_Hold_Until_Time。進 P4 再打 InitBooking 取餐飲時段、填寫頁報價（🟡 InitBooking 文件之後給）

• 有房佔不到（1001 艙房已被訂走、1002 重複佔房、1005 艙型已售完、6007 供應商回人數超過可住人數）：回 P3，頂端紅條說明哪間被訂走、哪間已保留（跟著回 Fail_Room_List，紅條逐間列出每間的 Fail_Text，例「艙房 1（9207）已被別人訂走，請重新選擇」）；佔到的那間維持「已選」，佔不到的那間框變紅、回「尚未選擇」。🟡 紅條畫面等 UIUX 出圖

• 回 P3 後帶 Page_Id 和佔不到那間的 Room_Seq 重查 QueryCategory，重查會回最新的 Session_Version 和每間的 Hold_Until_Time。客人重選那間後再按〔下一步〕，全部房一起帶，佔到的那間帶原本的選擇

• ⚠ 保留只有 15 分鐘，客人重選太久，佔到的那間也可能佔不到，紅條文字不要寫成保證

• 佔到的那間要改選：按〔重選艙房〕先跳確認「保留會放掉」，確認後打 ReleaseHold 放掉（見 ReleaseHold 文件）

• 從填寫頁回 P3、什麼都沒改就按〔下一步〕：照打這支，全部房都佔著、沒過期就不重佔。P4 重整不打這支，打 InitBooking

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

規格調整

Request Schema

Body

Room_List（Request）

JSON 範例

{
  "Page_Id": "6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "Session_Version": 1,
  "Room_List": [
    {
      "Room_Seq": 1,
      "Plan_Id": 8101,
      "Category_Id": 6009,
      "Fare_Code": "BESTPRICE",
      "Cabin_Number": "9207"
    },
    {
      "Room_Seq": 2,
      "Plan_Id": 8101,
      "Category_Id": 6011,
      "Fare_Code": "BESTPRICE",
      "Cabin_Number": "GTY"
    }
  ]
}

Response Schema

回應主體

Result_Info

Result_Data

Room_List（回應）

JSON 範例

{
  "Result_Info": {
    "Is_Success": true,
    "Result_Code": "",
    "Result_Message": ""
  },
  "Result_Data": {
    "Session_Version": 2,
    "Earliest_Hold_Until_Time": "2026-11-02T14:35:00",
    "Room_List": [
      {
        "Room_Seq": 1,
        "Hold_Until_Time": "2026-11-02T14:35:00"
      },
      {
        "Room_Seq": 2,
        "Hold_Until_Time": "2026-11-02T14:35:00"
      }
    ]
  }
}

錯誤回應

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

有房佔不到的回應範例（艙房 1 選的 9207 被別人佔走、艙房 2 選的保證艙那一類沒名額；兩間原因不一樣，外層回 1006）：

{
  "Result_Info": {
    "Is_Success": false,
    "Result_Code": "1006",
    "Result_Message": "部分艙房無法保留，請看各間說明"
  },
  "Result_Data": {
    "Fail_Room_List": [
      {
        "Room_Seq": 1,
        "Cabin_Number": "9207",
        "Fail_Code": "1001",
        "Fail_Text": "艙房 1（9207）已被別人訂走，請重新選擇"
      },
      {
        "Room_Seq": 2,
        "Cabin_Number": "GTY",
        "Fail_Code": "1005",
        "Fail_Text": "艙房 2 的艙型已售完，請改選其他艙型"
      }
    ]
  }
}

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

畫面呼叫

舊版畫面

新版畫面

UIUX 20260922 版 P3-W01 底部結帳列、P3-A15 的〔下一步：填寫旅客資料〕。Request 帶的是 P3 選好的卡片與房號，回應欄位在 P3 不顯示（倒數在 P4），不附畫面欄位對照圖。有房佔不到時，雛形 P3-A15 畫的是彈窗、兩間全部重選；請以「使用重點」寫的為準：頂端紅條、佔到的那間留著（UIUX 改圖中）。