郵輪B2C P3 選擇房號（QueryCabin）

API Content

說明

P3 卡片按〔選擇〕時打這支，回這張卡片的艙型還能選的房號，依樓層分組、帶平面圖，保證艙放最後。只查不寫：客人選了哪個房號由前端記下，按〔下一步：填寫旅客資料〕時才一起送出。

方法：POST

路徑：Cruise/Products/QueryCabin

對應畫面：P3 選擇艙房，卡片按〔選擇〕開的「選擇房號」彈窗與「系統配房」彈窗（APP 是底部面板）

使用重點：

按卡片〔選擇〕打一次；切樓層、勾「無障礙房」、點房號都不重打。可自選房號、系統配房兩種卡片都打這支

不用帶 Session_Version，這支也不會改變它

在彈窗按〔選擇此艙房〕（APP〔確定〕）：前端記下房號和這張卡片的 Plan_Id、Category_Id、Fare_Code，不打 API；按 ✕ 關掉，原本選的不變。按〔下一步：填寫旅客資料〕時，各房選的一起送給 CreateHold（見 CreateHold 文件）

樓層頁籤照 Deck_List 順序，預設選第一筆（樓層最低）。Deck_Image 是 null 就顯示沒有平面圖的版本

彈窗的「每房總價」、艙型名稱用 QueryCategory 卡片的 Fare_Price、Category_Code、Profile_Name，這支不回

Deck_List 是空陣列（這個艙型已經沒有可選的房）：回 200，不是錯誤，彈窗顯示「目前無可選樓層或房號」。🟡 這個畫面 UIUX 還沒畫

系統配房的卡片：有 Is_Gty 是 true 的那一筆才開系統配房彈窗，按〔選擇此艙房〕記的房號是 GTY；沒有就顯示「目前無可選樓層或房號」。彈窗中間的說明是固定文案，前端寫死，這支不回（跟 QueryCategory 卡片的 Cabin_Selectable_Text 不同）

可自選房號的卡片：保證艙（Is_Gty 是 true）是 Deck_List 最後一筆，當最後一個樓層頁籤。🟡 保證艙頁籤的樣子 UIUX 還沒畫

另一間已選的房號：這支不標，前端比對另一間記下的 Cabin_Number，顯示「艙房1已選」、不能點；GTY 不擋，兩間都能選。進填寫頁時後端會再擋一次（回「重複訂位」）

「無障礙房」篩選：前端比對 Is_Accessible。沒有無障礙房的樓層，WEB 設成不能點、APP 不顯示；全部都沒有，顯示「目前無可選樓層或房號」。🟡 WEB、APP 做法要不要統一等 UIUX 確認，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
Category_Id	必填。這張卡片的 `Category_Id`；要是這間最近一次 QueryCategory 回過的卡片	Int	6009

JSON 範例

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

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

名稱	描述	屬性	範例
Deck_List	一層一筆，樓層由低到高，保證艙放最後。空陣列＝這個艙型沒有可選的房	List	參考 Deck_List

Deck_List

名稱	描述	屬性	範例
Deck_Floor	樓層，保證艙是 null。「甲板9樓」這類文字用它組	Int	9
Deck_Text	樓層頁籤文字，直接顯示；保證艙是「保證艙」	String	9 樓
Is_Gty	保證艙那一筆是 true。系統配房的卡片看有沒有這筆，決定開不開彈窗	Bool	false
Deck_Image	這層的平面圖；沒有平面圖、保證艙是 null，顯示沒有平面圖的版本	Object	參考 Deck_Image
Cabin_List	這層可選的房號，照房號排	List	參考 Cabin_List

Deck_Image

名稱	描述	屬性	範例
Image_Url	圖片網址	String	https://img.example.com/cruise/da-deck-09.jpg
Alt_Text	替代文字	String	9 樓平面圖

Cabin_List

名稱	描述	屬性	範例
Cabin_Number	房號；保證艙是 `GTY`。點選後前端記下，進旅客填寫頁時送出	String	9203
Is_Accessible	無障礙房：true 顯示輪椅圖示；「無障礙房」篩選比對這欄	Bool	true

JSON 範例

{
  "Result_Info": {
    "Is_Success": true,
    "Result_Code": "",
    "Result_Message": ""
  },
  "Result_Data": {
    "Deck_List": [
      {
        "Deck_Floor": 9,
        "Deck_Text": "9 樓",
        "Is_Gty": false,
        "Deck_Image": {
          "Image_Url": "https://img.example.com/cruise/da-deck-09.jpg",
          "Alt_Text": "9 樓平面圖"
        },
        "Cabin_List": [
          {
            "Cabin_Number": "9203",
            "Is_Accessible": true
          },
          {
            "Cabin_Number": "9207",
            "Is_Accessible": false
          }
        ]
      },
      {
        "Deck_Floor": 10,
        "Deck_Text": "10 樓",
        "Is_Gty": false,
        "Deck_Image": null,
        "Cabin_List": [
          {
            "Cabin_Number": "10155",
            "Is_Accessible": true
          }
        ]
      },
      {
        "Deck_Floor": null,
        "Deck_Text": "保證艙",
        "Is_Gty": true,
        "Deck_Image": null,
        "Cabin_List": [
          {
            "Cabin_Number": "GTY",
            "Is_Accessible": false
          }
        ]
      }
    ]
  }
}

錯誤回應

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

HTTP	Result_Code	中文名稱	訊息（給客人看）	情境	前端動作
200	2001	訂位資料不存在	訂位資料已失效，請重新選擇	`Page_Id` 找不到	手上有行程與人數就在 P3 開「艙房／人數」燈箱重新查詢（在 P4 先回 P3）；沒有就回 P2 重新選
200	5003	選擇已失效	選擇已失效，請重新查詢	`Room_Seq` 不是這筆訂位的房，或 `Category_Id` 不是這間最近一次 QueryCategory 回過的卡片	重查 QueryCategory 後再選
200	6005	供應商無回應	系統忙碌，請稍後再試	查房號時供應商重試後還是沒回應	顯示「系統忙碌，請稍後再試」，可以重試
200	6001	供應商拒絕	訂位未成功，請聯絡客服	查房號時供應商回錯誤（沒有名額不算錯誤，那一類不列）	顯示訊息＋客服導引
200	6006	供應商連線設定錯誤	訂位系統暫時無法使用，請聯絡客服	跟供應商的連線設定有誤（後端已告警）	顯示訊息＋客服導引
500	9999	系統錯誤	9999｜系統發生錯誤，請稍後再試	系統錯誤（未預期的例外）	顯示友善錯誤訊息，可以重試

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

畫面呼叫

舊版畫面

新版畫面

P3 卡片按〔選擇〕呼叫本 API → 可自選房號開「選擇房號」彈窗、系統配房開「系統配房」彈窗（APP 是底部面板）→ 按〔選擇此艙房〕（APP〔確定〕）前端記下，回 P3 選下一間 → 都選好按〔下一步：填寫旅客資料〕。雛形：UIUX 20260922 版 WEB P3-W13～W15，APP P3-A11～A14。