郵輪B2C P1 搜尋結果（QueryCruise）

API Content

說明

P0 首頁「全球郵輪」搜尋框按搜尋、或 P1 頁首〔修改〕重新搜尋後呼叫，查詢純艙房產品，結果顯示在 P1 搜尋結果頁（一張卡片＝一個產品）。

方法：POST

路徑：Cruise/Search/QueryCruise

對應畫面：P0 搜尋框送出 → P1 搜尋結果頁（P0-RQ-P1-RS）

使用重點：

各參數帶 Cruise/Search/InitSearch 清單中所選項目的 Value，不送整個選項物件

目的地兩分頁擇一：依 InitSearch Region_Type——Ship（主題遊輪）帶 Ship_Value_List，Route（航線）帶 Route_Value_List（🟡 待定義）

一次回傳全部符合的產品；排序（總價、晚數，預設總價低→高）與往下滑每次載入 20 筆，都由前端處理

左欄篩選：選項由後端 distinct 好放在 Filter_Info（不受勾選影響）；過濾由前端在已拿到的結果上做，勾選不必重新呼叫——晚數比對卡片 Itinerary_Day、中途停靠比對卡片 Is_TransitPort

從 P2 按上一頁回到 P1：用同一組 Request 重打本 API；勾選、排序、捲動位置清掉
〔修改〕（WEB）／頁首放大鏡（APP）：重打 InitSearch 取選項，重開搜尋框，帶剛才的條件；剛才的起日已不能訂時回 5001 出發日不在可訂範圍
重整 P1、直接開 P1 網址：手上有搜尋條件就用同一組條件重打本 API；沒有就回 P0 首頁搜尋框

起價 Fare_Price 是每房、兩位大人、已含稅。ⓘ 的「每人」＝本欄 ÷ 2 後無條件進位到元；不要四捨五入，WEB 與 APP 各算會差 1 元。雛形寫「(未稅)」，字樣會改，等 UIUX

出發日的星期幾、紅字由前端依日期算，API 只給日期。🟡 哪些日子標紅字（週日、週六、國定假日）等 UIUX

P1 頁首的出發地：WEB 顯示 InitSearch 的 Display_Text（「海外登船 (不含機票)」）、APP 顯示 Text（「海外登船」）

卡片的出發日與起價只算搜尋區間內的航次：同一個產品搜不同區間，出發日和起價可能不同

沒有符合的產品時 Total_Count＝0，Product_List 與 Filter_Info 底下兩個清單都是 []，不是錯誤

🟡 產品標籤 Tag_List：雛形卡片還沒有顯示位置，等 UIUX；字典已註銷的標籤不回

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

規格調整

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

Request Schema

Body

名稱	描述	屬性	範例
Request_Mode	呼叫端平台，必填。值：WEB／APP	String	WEB
Departure_Value	① 出發地，必填。InitSearch `Departure_List` 所選項目的 `Value`	String	FlyCruise
Ship_Value_List	② 目的地「主題遊輪」分頁，與 `Route_Value_List` 擇一。InitSearch `Region_List` 中 `Region_Type`＝`Ship` 那筆，所選船（`Regions[].Ship_List[]`）的 `Value`（目前單選即一筆）	List	["DCL-DA"]
Route_Value_List	② 目的地「航線」分頁，與 `Ship_Value_List` 擇一，對應 InitSearch `Region_Type`＝`Route` 那筆。🟡 名稱與內容待定義	List	—
Start_Date	③ 理想出發區間起日，必填，格式 yyyy/MM/dd；須在 InitSearch `DepartureDate_Range` 的 `MinDate`～`MaxDate` 內；不在範圍回 `5001` 出發日不在可訂範圍（見錯誤回應）	String	2026/11/09
End_Date	③ 理想出發區間迄日，必填，格式 yyyy/MM/dd（＝起日＋1 年）	String	2027/11/09

JSON 範例

{
  "Departure_Value": "FlyCruise",
  "Ship_Value_List": [
    "DCL-DA"
  ],
  "Start_Date": "2026/11/09",
  "End_Date": "2027/11/09",
  "Request_Mode": "WEB"
}

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

名稱	描述	屬性	範例
Total_Count	符合的產品筆數（P1「共 N 筆」）；沒有結果回 0	Int	3
Filter_Info	P1 左欄篩選的選項，後端從本次全部結果 distinct（不受勾選影響）；過濾由前端做	Object	參考 Filter_Info
Product_List	產品卡片清單，一筆＝一張卡片；回傳順序不固定，前端排序	List	參考 Product_List

Filter_Info

名稱	描述	屬性	範例
Itinerary_Day_List	「行程晚數」選項，晚數由小到大	List	參考 Itinerary_Day_List
Transit_Port_List	「中途停靠港口」選項，true 在前；結果只有一種時只有一筆	List	參考 Transit_Port_List

Itinerary_Day_List

名稱	描述	屬性	範例
Value	晚數；勾選後保留 `Itinerary_Day` 等於這個值的卡片（多選取聯集）	Int	3
Text	顯示文字	String	3 晚

Transit_Port_List

名稱	描述	屬性	範例
Value	true＝有中途停靠、false＝沒有；勾選後保留 `Is_TransitPort` 等於這個值的卡片	Bool	true
Text	顯示文字；WEB、APP 都照這個字顯示，不自己寫字	String	有中途停靠

Product_List

名稱	描述	屬性	範例
Product_Id	產品編號；點〔選擇〕、出發日、〔更多〕進 P2 時帶	Int	101
Product_Title	卡片標題，照原樣顯示	String	迪士尼探險號｜新加坡出發3晚海上假期
Itinerary_Day	晚數（3＝3 晚）：縮圖左上「3 晚」、左欄晚數過濾時比對、排序「晚數」。⚠ 是晚數，不是天數	Int	3
Depart_Port_Name	出發港名稱	String	新加坡
Ship_Name	船名（卡片副標）	String	迪士尼探險號
Brand_Name	品牌名（卡片副標）	String	迪士尼郵輪
Route_Description	港口串接，以「 → 」連接；全程海上時中間是「海上巡航」（例新加坡 → 海上巡航 → 新加坡），有停靠港時只列港口	String	新加坡 → 海上巡航 → 新加坡
Is_TransitPort	有沒有中途停靠港：true＝有、false＝沒有（全程海上）；左欄「中途停靠港口」過濾時比對	Bool	false
Sail_Date_List	搜尋區間（Start_Date～End_Date）內可訂購的出發日，由早到晚（畫面日期 chips＋〔更多〕）；出發前 5 天內的航次不開放訂購，不會出現（起價也不算它們）	List	參考 Sail_Date_List
Fare_Price	起價，台幣整數：Sail_Date_List 那些出發日裡，每房、兩位大人、已含稅的最低價	Int	17875
Tag_List	產品標籤的顯示名稱，可能是空陣列。🟡 雛形還沒有顯示位置	List	[]
Cover_Image	卡片圖片＝產品封面，只有一張、不輪播；沒有封面時是 null，前端顯示預設圖	Object	參考 Cover_Image

Sail_Date_List

名稱	描述	屬性	範例
Itinerary_Id	航次編號（進 P2 選定出發日時用）	Int	5007
Departure_Date	出發日，格式 yyyy/MM/dd；星期幾、紅字由前端算	String	2026/11/09

Cover_Image

名稱	描述	屬性	範例
Image_Url	圖片網址	String	https://img.example.com/cruise/da-001.jpg
Alt_Text	圖片替代文字	String	迪士尼探險號外觀

JSON 範例

{
  "Result_Info": {
    "Is_Success": true,
    "Result_Code": "",
    "Result_Message": ""
  },
  "Result_Data": {
    "Total_Count": 3,
    "Filter_Info": {
      "Itinerary_Day_List": [
        {
          "Value": 3,
          "Text": "3 晚"
        },
        {
          "Value": 4,
          "Text": "4 晚"
        }
      ],
      "Transit_Port_List": [
        {
          "Value": true,
          "Text": "有中途停靠"
        },
        {
          "Value": false,
          "Text": "無中途停靠"
        }
      ]
    },
    "Product_List": [
      {
        "Product_Id": 101,
        "Product_Title": "迪士尼探險號｜新加坡出發3晚海上假期",
        "Itinerary_Day": 3,
        "Depart_Port_Name": "新加坡",
        "Ship_Name": "迪士尼探險號",
        "Brand_Name": "迪士尼郵輪",
        "Route_Description": "新加坡 → 海上巡航 → 新加坡",
        "Is_TransitPort": false,
        "Sail_Date_List": [
          {
            "Itinerary_Id": 5007,
            "Departure_Date": "2026/11/09"
          },
          {
            "Itinerary_Id": 5009,
            "Departure_Date": "2026/11/16"
          },
          {
            "Itinerary_Id": 5011,
            "Departure_Date": "2026/11/23"
          },
          {
            "Itinerary_Id": 5013,
            "Departure_Date": "2026/11/30"
          },
          {
            "Itinerary_Id": 5015,
            "Departure_Date": "2026/12/07"
          },
          {
            "Itinerary_Id": 5017,
            "Departure_Date": "2026/12/14"
          },
          {
            "Itinerary_Id": 5019,
            "Departure_Date": "2026/12/21"
          },
          {
            "Itinerary_Id": 5021,
            "Departure_Date": "2026/12/28"
          },
          {
            "Itinerary_Id": 5023,
            "Departure_Date": "2027/01/04"
          },
          {
            "Itinerary_Id": 5025,
            "Departure_Date": "2027/01/11"
          },
          {
            "Itinerary_Id": 5027,
            "Departure_Date": "2027/01/18"
          },
          {
            "Itinerary_Id": 5029,
            "Departure_Date": "2027/01/25"
          },
          {
            "Itinerary_Id": 5031,
            "Departure_Date": "2027/02/01"
          },
          {
            "Itinerary_Id": 5033,
            "Departure_Date": "2027/02/08"
          },
          {
            "Itinerary_Id": 5035,
            "Departure_Date": "2027/02/15"
          },
          {
            "Itinerary_Id": 5037,
            "Departure_Date": "2027/02/22"
          },
          {
            "Itinerary_Id": 5039,
            "Departure_Date": "2027/03/01"
          },
          {
            "Itinerary_Id": 5041,
            "Departure_Date": "2027/03/08"
          },
          {
            "Itinerary_Id": 5043,
            "Departure_Date": "2027/03/15"
          },
          {
            "Itinerary_Id": 5045,
            "Departure_Date": "2027/03/22"
          },
          {
            "Itinerary_Id": 5047,
            "Departure_Date": "2027/03/29"
          },
          {
            "Itinerary_Id": 5049,
            "Departure_Date": "2027/04/05"
          },
          {
            "Itinerary_Id": 5051,
            "Departure_Date": "2027/04/12"
          },
          {
            "Itinerary_Id": 5053,
            "Departure_Date": "2027/04/19"
          }
        ],
        "Fare_Price": 17875,
        "Tag_List": [],
        "Cover_Image": {
          "Image_Url": "https://img.example.com/cruise/da-001.jpg",
          "Alt_Text": "迪士尼探險號外觀"
        }
      },
      {
        "Product_Id": 102,
        "Product_Title": "迪士尼探險號｜新加坡出發4晚海上假期",
        "Itinerary_Day": 4,
        "Depart_Port_Name": "新加坡",
        "Ship_Name": "迪士尼探險號",
        "Brand_Name": "迪士尼郵輪",
        "Route_Description": "新加坡 → 海上巡航 → 新加坡",
        "Is_TransitPort": false,
        "Sail_Date_List": [
          {
            "Itinerary_Id": 5008,
            "Departure_Date": "2026/11/12"
          },
          {
            "Itinerary_Id": 5010,
            "Departure_Date": "2026/11/19"
          },
          {
            "Itinerary_Id": 5012,
            "Departure_Date": "2026/11/26"
          },
          {
            "Itinerary_Id": 5014,
            "Departure_Date": "2026/12/03"
          },
          {
            "Itinerary_Id": 5016,
            "Departure_Date": "2026/12/10"
          },
          {
            "Itinerary_Id": 5018,
            "Departure_Date": "2026/12/17"
          },
          {
            "Itinerary_Id": 5020,
            "Departure_Date": "2026/12/24"
          },
          {
            "Itinerary_Id": 5024,
            "Departure_Date": "2027/01/07"
          },
          {
            "Itinerary_Id": 5026,
            "Departure_Date": "2027/01/14"
          },
          {
            "Itinerary_Id": 5032,
            "Departure_Date": "2027/02/04"
          },
          {
            "Itinerary_Id": 5038,
            "Departure_Date": "2027/02/25"
          },
          {
            "Itinerary_Id": 5048,
            "Departure_Date": "2027/04/01"
          },
          {
            "Itinerary_Id": 5052,
            "Departure_Date": "2027/04/15"
          }
        ],
        "Fare_Price": 23238,
        "Tag_List": [],
        "Cover_Image": null
      },
      {
        "Product_Id": 103,
        "Product_Title": "迪士尼探險號｜新加坡出發4晚 停靠 蘭卡威",
        "Itinerary_Day": 4,
        "Depart_Port_Name": "新加坡",
        "Ship_Name": "迪士尼探險號",
        "Brand_Name": "迪士尼郵輪",
        "Route_Description": "新加坡 → 蘭卡威 → 新加坡",
        "Is_TransitPort": true,
        "Sail_Date_List": [
          {
            "Itinerary_Id": 5022,
            "Departure_Date": "2026/12/31"
          },
          {
            "Itinerary_Id": 5028,
            "Departure_Date": "2027/01/21"
          },
          {
            "Itinerary_Id": 5030,
            "Departure_Date": "2027/01/28"
          },
          {
            "Itinerary_Id": 5034,
            "Departure_Date": "2027/02/11"
          },
          {
            "Itinerary_Id": 5036,
            "Departure_Date": "2027/02/18"
          },
          {
            "Itinerary_Id": 5040,
            "Departure_Date": "2027/03/04"
          },
          {
            "Itinerary_Id": 5042,
            "Departure_Date": "2027/03/11"
          },
          {
            "Itinerary_Id": 5044,
            "Departure_Date": "2027/03/18"
          },
          {
            "Itinerary_Id": 5046,
            "Departure_Date": "2027/03/25"
          },
          {
            "Itinerary_Id": 5050,
            "Departure_Date": "2027/04/08"
          }
        ],
        "Fare_Price": 23238,
        "Tag_List": [],
        "Cover_Image": null
      }
    ]
  }
}

錯誤回應

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

HTTP	Result_Code	中文名稱	訊息（給客人看）	情境	前端動作
200	5001	出發日不在可訂範圍	出發日期已無法訂購，請重新選擇	`Start_Date` 不在可選範圍（`MinDate`～`MaxDate`；例：開著首頁過了午夜才按〔搜尋〕，起日已不能訂）	顯示 `Result_Message`（「出發日期已無法訂購，請重新選擇」），重打 InitSearch 拿新的日期範圍，再開搜尋框讓客人重選
400	4004	參數組合錯誤	不給客人看（訊息開頭是代碼）	目的地參數兩者同時帶或皆未帶	前端帶錯值，修正後重打
400	4002	參數格式錯誤	不給客人看（訊息開頭是代碼）	目的地參數格式不符	前端帶錯值，修正後重打
400	4004	參數組合錯誤	不給客人看（訊息開頭是代碼）	`Start_Date` 晚於 `End_Date`	前端帶錯值，修正後重打
400	4003	參數值不在範圍	不給客人看（訊息開頭是代碼）	`Request_Mode` 不在允許值	前端帶錯值，修正後重打
500	9999	系統錯誤	9999｜系統發生錯誤，請稍後再試	系統錯誤（未預期的例外）	顯示友善錯誤訊息，可以重試

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

畫面呼叫

舊版畫面

新版畫面

P0 搜尋框按搜尋（或 P1 重新搜尋）→ 呼叫本 API → P1 搜尋結果頁。進 P2 航程詳情：WEB 點〔選擇〕、APP 點整張卡片；點出發日或〔更多〕進 P2 並跳到可訂購日期。雛形：UIUX 20260922 版 WEB P1-W01～W06、APP P1-A01～A02。

畫面欄位對照（WEB）

雛形 WEB P1-W01 上標出每個畫面元素用哪個欄位；灰色虛線＝不在本 API。圖片可點開放大。

畫面欄位對照（APP）

雛形 APP P1-A01（列表初始頁）、P1-A02（篩選面板）。APP 不顯示：Total_Count。APP 沒有〔選擇〕，點整張卡片進 P2。圖片可點開放大。