行程與梯次
行程是你上架的商品介紹;梯次是行程底下一個個可報名的出團日期。客人報名的永遠是某一個梯次。
行程、梯次、出團準備、帶團排班與成本範本的 CLI 指令及員工 API 都需要行程模組(tour)。未開通時回傳 403 module_disabled。停用後,既有訂單仍可收款與退款。
行程與梯次的關係
| 概念 | 是什麼 | 記什麼 |
|---|---|---|
| 行程 | 商品介紹與共用設定 | 標題、目的地、天數、起價、介紹內容、報名規則 |
| 梯次 | 一個出團日期,客人實際報名的對象 | 出發日、回程日、席次、售價、團號、狀態 |
很多設定在行程上填一次,梯次建立時帶入或沿用,逐梯仍可覆寫。改行程設定時,要注意它是「建立時帶入一次」還是「梯次留空就即時沿用」:
| 類型 | 例子 | 改行程後 |
|---|---|---|
| 建立時帶入 | 預設席次、預設分配模式、預設需要幾位嚮導、出團作業預設 | 只影響之後新建的梯次 |
| 梯次留空就沿用 | 集合時間與地點、訂金、停止售票 | 立即影響所有沒覆寫的梯次 |
行程編輯頁有些設定提供「套用到既有梯次」,可以逐梯勾選後補套。
訂金方式選「固定金額」時,用「訂金計算單位」決定按人或按單收。選「每人」,應付訂金=金額 × 人數;選「每張訂單」,一張單只收一筆。兩者都不超過訂單總額。新行程預設「每人」。梯次覆寫的固定金額也照行程的計算單位。改計算單位不會重算已成立的訂單。
›API 對應
- 行程:
GET /trips、POST /trips、GET /trips/{id}、PATCH /trips/{id}。列表的activeDepartureCount、nextDepartureDate是後台口徑,包含不對外販售的梯次。 - 梯次:
POST /trips/{id}/departures新增;PATCH /trips/departures/{departureId}修改;GET /trips/departures列出。 - 修改都是部分更新:只送要改的欄位;可清空的欄位傳
null。 - 行程的
depositBasis是固定金額訂金的計算單位:per_person(每人,預設)或per_order(每張訂單)。 - 同一次請求內欄位互相矛盾(例:回程早於出發)回
422 validation,issues[].path指向該欄。行程訂金規則與現有值合併後不成立回422;梯次訂金與促銷規則合併後不成立回409 conflict。 - 行程狀態值:
draft、published、archived。梯次狀態值:selling、closed、cancelled、completed。 - 匯出行程:
GET /trips/export。
建立與編輯行程
後台 →「行程」列出所有行程。按「新增行程」建立,點行程名稱進入編輯頁。
有行程管理權限時,按「釘選常用」可把行程排到列表最前面。釘選依先後順序排列,全公司共用;搜尋與篩選後也維持此順序。其餘行程依最後更新時間排列,新行程排在已釘選行程後面。按「取消釘選」後重新釘選,會排在其他已釘選行程後面。官網排序不變。
員工 API 的 GET /trips 與行程匯出列使用相同順序。adminPinnedAt 是釘選時間,未釘選時為 null;釘選操作由後台提供。
行程狀態有三種:
| 狀態 | 前台 | 說明 |
|---|---|---|
| 草稿 | 不顯示 | 新行程與匯入的新行程都從草稿開始。 |
| 已上架 | 顯示 | 客人可以報名。 |
| 封存 | 不顯示 | 收進「封存區」,可批次恢復為草稿。 |
勾選多個行程後,用「批次改狀態」一次上架、改為草稿或封存。
編輯頁的分頁:
| 分頁 | 內容 |
|---|---|
| 基本 | 基本資訊、報名與費用、報名規則、出團安排、搜尋與分享、成本範本綁定 |
| 內容 | 行程介紹、亮點、每日行程、難度評估 |
| 圖片 | 行程圖片 |
| 梯次 | 這個行程的所有梯次 |
| 營運規則 | 期限規則、出團準備項目、出團作業預設、住宿 |
| 調查項 | 報名時逐位旅客回答的題目 |
編輯行程介紹
「內容」分頁直接輸入文字,並加入行程亮點、每日行程與難度評估區塊。費用包含與退改規定由「基本」分頁的專屬欄位管理,不必在內文重寫。
- 每日行程按「新增一天」會接續天數;時間表可分行輸入,不需要表格。
- 寬螢幕左邊編輯、右邊即時預覽。窄螢幕用「預覽內容」與「繼續編輯」切換,切換時保留未儲存的內容。
- 預覽用基本樣式,不套店面配色。
- 「查看原始碼」可唯讀檢查內容。偵測到單欄表格時,可一鍵整理成段落與標題,也可以還原。
- 確認後按「儲存內容」。
舊內容裡的費用與退改區塊會保留,並提示改用專屬欄位。資料移過去後,再刪除舊區塊。
難度區塊只是展示。報名資格由行程的登山難度評鑑設定控制,見旅客與個資。
›API 欄位
介紹內容在 contentMdx(MDX 字串)。
常用的行程設定
| 設定 | 位置(「基本」分頁) | 作用 |
|---|---|---|
| 內部簡稱 | 基本資訊 | 最多 30 字。後台列表、梯次總覽、排班顯示簡稱,後台搜尋也比對簡稱。前台、契約與寄給客人的信仍用正式名稱。 |
| 最低成團人數 | 出團安排 → 成團 / 名額規則 | 達到時梯次總覽提示。成團仍由承辦手動確認。 |
| 預設席次 | 同上 | 新增梯次時帶入的席次。 |
| 停止售票:出發前 N 天 | 同上 | 出發前 N 天 00:00,系統把售票中的梯次改為已關閉。梯次可自訂停止售票時間。 |
| 預設分配模式 | 同上 | 先到先得或抽籤,見抽籤與備案。 |
| 建議航班 | 報名規則 → 建議航班 | 前台行程頁的航班卡片,所有梯次共用。見下方「建議航班」。 |
| 集合資訊 | 出團安排 → 集合資訊 | 集合時間與地點。梯次留空就沿用,旅遊契約第 4 條也用這個值。 |
| 行前說明網址 | 出團安排 → 行前說明 | 所有梯次共用。訂單第一次收到款項時的通知以它代入,見罐頭訊息。 |
| 收款後通知內文 | 同上 | 所有梯次共用。有填時,訂單第一次收到款項的通知改用這段內文,主旨仍用範本。留空就用範本內文。 |
| 限外籍旅客 | 出團安排 → 報名資格 | 見下方「限外籍旅客」。 |
| 啟用候補 | 出團安排 → 候補與抽籤 | 見下方「候補」。 |
| 啟用抽籤實名制 | 同上 | 見抽籤與備案。 |
| 抽籤結果含備取 | 同上 | 開了才在團控出現「備取」鍵,見抽籤與備案。 |
隨團人員相關的「預設需要幾位嚮導」與「每幾位旅客配一位隨團人員」見出團準備與線控。
›API 欄位
shortName(空字串或 null 清空)、minGroupSize、defaultCapacity、meetingTime(HH:mm,台北時間)、meetingPlace、pretripBriefingUrl(http/https 網址,null 清空)、paymentReceivedBody(收款後通知內文,null 清空)、defaultAllocationMode、foreignTravelersOnly、lotteryIdentityGuardEnabled、lotteryWaitlistEnabled、defaultGuideCount、travelersPerGuide。
suggestedFlights 的結構與檢查規則見下方「建議航班」。
GET /departures/control 每列帶 tripShortName(未填為 null)與 hasPreTripNight(有行前集合夜時,集合日是出發前一天)。訂單列表與明細也帶 tripShortName。
開梯次
有三種方式:
| 方式 | 位置 | 適合 |
|---|---|---|
| 逐梯新增 | 行程編輯頁「梯次」分頁,或梯次總覽的「新增梯次」 | 補一兩個梯次 |
| 批次新增梯次 | 後台 →「行程」→「批次新增梯次」 | 為既有行程一次開多個日期 |
| 批次匯入 | 後台 →「行程」→「批次匯入」 | 從試算表一次建立大量行程與梯次 |
梯次欄位
梯次表單分成「日期與席次」「定價與訂金」「停止售票」「開賣排程」「旅遊契約」「標籤與販售」「促銷覆寫價」。其中:
- 梯次標籤:最多 30 字的短副標,只顯示在後台(例:「包1」)。同一天開兩梯時用來區分。
- 不對外販售:前台不顯示、客人不能自助報名,只能由後台 K 單建單,適合包團。梯次仍是售票中。
- 分配模式:先到先得、抽籤或繼承行程。抽籤模組開啟時才顯示。
- 開賣排程:填開賣日期與時間(台北時間),梯次會先建成已關閉,到點自動改成售票中。開賣時間要晚於現在、早於停止售票時間。已建好的梯次只有已關閉時能設;售票中的梯次要先停止售票。
批次新增梯次
- 勾選一個或多個行程。
- 在日曆選出發日。日曆會標出國定假日。
- 按「加入表格」。每個「行程 × 出發日」產生一列,回程日、售價與席次自動帶入。
- 直接改表格。第二列「整欄套用」可把同一個值填滿整欄。同一天要開第二梯,按該列的「複製」再改梯次標籤。留空表示沿用行程設定。
- 按「預覽」。系統標出會略過(已有同日同標籤的梯次)、有錯,以及建好後還不能開賣的梯次。
- 確認後建立。表格一改就要重新預覽。
一次最多 1,000 梯。
批次匯入(批次開團)
適合從舊系統或試算表搬資料。
- 後台 →「行程」→「批次匯入」,按「下載範本 (.xlsx)」。
- 填好後上傳 Excel/CSV,或從試算表整塊貼上,按「解析並預覽」。上限 1,000 列。
- 檢查每列結果:新行程、補梯次、略過或錯誤。
- 按「確認匯入」再「確認建檔」。
規則:
- 一列一個梯次。同一行程代碼、出發日與梯次標籤已存在時略過,保留既有值。匯入只用於新增,既有梯次請在梯次編輯修改。
- 既有行程只需填行程代碼與梯次資料。新行程另需行程名稱、目的地與天數,並可帶行程層設定(登山團、海外團、行前集合夜、難度、高山經驗、屬高海拔、入門免審、抽籤前置天數、訂金)。
- 匯入的新行程是草稿,要到行程編輯頁上架。補梯次不改既有行程的上架狀態。新梯次預設售票中。
- 補梯次到既有行程時,難度、高山經驗、屬高海拔、入門免審、抽籤前置天數與行程訂金以既有行程為準。登山、海外團旗標要與既有設定一致。
- 售價最多 10,000,000、席次最多 200、天數最多 60、行程名稱最多 200 字。超過的列在預覽就報錯。
- 時間要是整分鐘。格子顯示「06:30」仍報錯時,可能藏了秒數或毫秒,請重新輸入該格。
- 「承辦」欄填後台帳號 Email 或唯一的姓名,帳號要是 op 或 admin 且未封鎖。對不到帳號時該列照建、不掛承辦;對到不可指派的帳號時該列報錯。重複而被略過的列若填了承辦,會把該人掛到既有梯次。
- 新行程的起價取匯入梯次的最低售價。行程層直客/同業價、退改費階梯、住宿、費用包含、SEO、集合資訊與出團作業預設,請匯入後在行程編輯頁設定。
›選填欄位的填法
| 欄位 | 填值與留空的效果 |
|---|---|
| 同業價 | 整數 0–10,000,000。填 0 也是覆寫;留空沿用常規定價。 |
| 梯次訂金方式/金額/比例 | 方式填「不收/固定金額/比例」。固定金額要搭配金額,按人或按單照行程的「訂金計算單位」;比例要搭配 1–100 的整數。留空沿用行程訂金;填「不收」會覆寫。 |
| 停止售票日 | 日期或日期加時間(台北時間)。只填日期代表當天 00:00;留空沿用行程設定。 |
| 開賣時間 | 格式同停止售票日。填了梯次先建成已關閉,到點自動開賣;要晚於現在、早於停止售票日。留空照常建成售票中。 |
| 集合時間/集合地點 | 時間填 HH:mm,地點最多 200 字。留空沿用行程值。 |
| 可變更第三人期限(出發前N日) | 整數 0–365。先到先得梯次留空用公司預設;抽籤梯次留空時無法產生團體契約。個別契約不適用。 |
| 實際入園日偏移 | 入園日 = 出發日 + N 天。整數 0–60,且要落在出發日到回程日之間;留空為 0。 |
| 促銷直客價/促銷同業價 | 正整數,最多 10,000,000。填直客價即啟用促銷,同業價選填;只填同業價會報錯。 |
| 海外個別契約取消 | 填「是」時,海外新行程套用海外個別級距並啟用人工核算。不能與抽籤前置天數同時指定。 |
| 抽籤前置天數 | 寫入行程的「抽籤前幾天」並產生退改費階梯;留空沿用公司退改費設定。 |
缺少行程層設定不擋建檔,但結果會列出未設定的訂金;登山團另列未設定的難度、高山經驗與抽籤前置天數。
›API 對應
- 批次新增梯次:
POST /trips/batch-departures/validate預覽,POST /trips/batch-departures建立(提交時以當下資料重新驗證,每個行程各自一筆交易)。 - 批次匯入:
POST /trips/import/validate預覽,POST /trips/import提交同一份檔案。「承辦」欄另需departure_prep.manage,沒有時預覽只警告、梯次照建但不掛承辦。 - 皆需
trip.manage。
梯次狀態
| 狀態 | 意思 |
|---|---|
| 售票中 | 可以報名。 |
| 已關閉 | 停止報名,例:到了停止售票時間。 |
| 已取消 | 這梯不出團。 |
| 已完成 | 出團結束,已結團。 |
在行程編輯頁「梯次」分頁,用每列的「梯次狀態」選單改狀態再按「套用」,或勾選多梯批次改。梯次總覽每一梯的「更多」選單也能停止售票、恢復售票與取消本團。
-
「已完成」不能直接選。梯次只能經由結團變成已完成:在梯次總覽用「更多」選單的「結團」。結團把已確認的訂單改成已完成,並寫入旅客的登山紀錄。
-
停止售票時間已過的梯次不能改回售票中,要先把停止售票時間往後調。
-
排了開賣時間的已關閉梯次,列表顯示「排程中,MM/DD HH:mm 開賣」,最多晚一分鐘自動上架。手動改狀態會取消排程。
-
自動開賣被擋下時(例:停止售票時間已過、旅遊契約未備妥),梯次留在已關閉,顯示失敗原因,並通知承辦(沒有承辦時通知管理員)。系統不重試:修好問題後手動恢復售票,或改一個新的開賣時間。
-
梯次上還有訂單(未付款、已確認、候補、抽籤中、未中籤待安置都算)時不能改為已取消,系統列出訂單號。先安置或取消這些訂單;已取消的訂單不擋。管理員也一樣。
-
改為已取消時,系統自動釋回這梯佔用的出發前夜住宿床位,旅客自助登記連結也一併失效。
-
已結轉特殊損益的取消梯次不能改回其他狀態。
「售票中」不代表已成團。成團由承辦另外確認,見出團準備與線控。
›API 與錯誤碼
POST /trips/departures/{departureId}/status(trip.status),成功回 { ok: true, retentionDeferred }。不在四種狀態內的值回 422 validation;找不到梯次回 404 not_found。被守衛擋下回 409:
-
complete_via_closeout:不能用這支 API 改成completed,改呼叫結團POST /departures/{id}/complete。 -
has_active_orders:梯次上還有訂單,不能取消。error.details.orders是{ id, orderNumber }清單,不含個資。 -
has_special_conversion:已結轉特殊損益的取消梯次不能改回其他狀態。 -
sales_close_passed:停止售票時間已過,不能改回售票中。
梯次改期與狀態變更會影響回程關懷。retentionDeferred 為 true 表示操作已完成、回訪資料由每日排程補做,不要重送請求。梯次更新的回應也帶這個欄位。
席次、保座與候補
每個梯次有席次。客人報名時,系統立即保留所需席位。多人同時搶最後幾個位子時,只有席位足夠的訂單會成立。取消訂單會即時釋回席位。
候補: 行程勾選「啟用候補」後,先到先得梯次額滿時,前台按鈕改為「加入候補」。
- 一張訂單整團候補,不拆單。人數超過整梯席次時不能候補。
- 候補單有應收,但在遞補前不能付款。
- 有人取消、逾期未付或轉走時,系統依候補順序自動遞補第一張裝得下的訂單,並寄「候補遞補成功,請完成付款」信。付款期限從遞補時起算。
- 抽籤梯次不收候補,未中籤改走備案。
- 新建行程時,先到先得的行程預設勾選「啟用候補」,抽籤行程預設不勾。
POST /trips省略waitlistEnabled時照同一條規則:defaultAllocationMode是fcfs或省略時為true,lottery時為false。
後台 K 單排候補: 承辦 K 單時,選的梯次額滿,畫面多一個「改建候補單」勾選。勾了才建成候補單;沒勾就照樣擋下。
- 不受「啟用候補」限制。那個勾選只管客人能不能在前台自己排候補。
- K 單候補與前台候補排同一條隊,依建單先後遞補。遞補時客人收到付款通知信,承辦收到後台通知。
- 訂單頁顯示「候補第 N 位」。
- 抽籤梯次、不對外販售的梯次,或人數超過整梯席次時,不能排候補。
- 候補單不能選現場現金,也不能先申請手動折扣。遞補後再到訂單頁處理。
- API 建單帶
waitlistIfSoldOut: true(CLIorders create --waitlist-if-sold-out)。回應的waitlisted為true代表建成候補單。
API 建單遇到席位不足會回 409 conflict。這是正常結果,代表這梯在送出當下已滿。請重新讀取席位或改報其他梯次,不要重試同一筆。
價格
同一個梯次對直客與同業可以有不同價格。系統依通路決定成交單價:
| 通路 | 依序採用的第一個有值的價格 |
|---|---|
| 直客 | 梯次促銷價 → 梯次價 → 行程直客價 → 行程起價 |
| 同業 | 梯次同業促銷價 → 梯次同業價 → 行程同業價 → 梯次直客價 → 行程直客價 → 行程起價 |
- 同業不套用直客促銷價。行程起價必填,所以一定算得出單價。
- 成交當下的單價與通路會記在訂單上。之後改價,不影響已成立的訂單。
- 客戶分類只決定結帳時的預設通路;價格以訂單上的紀錄為準。
- 促銷只影響之後的新訂單。
›API 欄位
通路值為 direct、agency。促銷不是第三種通路,促銷訂單的通路仍是這兩者之一。
團號
團號是梯次對外的識別碼,用在報名、開票、出團通知與對帳。
預設格式:
國內團:26 YS 1010 A → 26YS1010A
海外團:26 EG TK 1010 A → 26EGTK1010A
年 地區 [航空] 月日 序號- 自動產生: 選好地區、航空(海外團才有)與出發日,系統組出團號,同地區同日自動配序號 A、B、C。團號在公司內不重複。
- 手填: 沿用舊系統團號時,在梯次列按「編輯團號」,用「覆寫 / 手填團號」輸入,仍要符合格式且不重複。
- 搜尋: 行程列表的「團號」搜尋框可用完整團號或前綴查詢。
地區碼與航空碼在後台 →「參考資料」→「團號代碼」維護。地區碼是 2–8 個大寫英數字、以字母結尾;航空碼是 2 碼 IATA。停用的代碼不再出現在新梯次的選項,既有團號保留。已被梯次使用的代碼不能改碼或刪除。
團號格式在後台 →「公司設定」→「團號格式」修改。可以改年份位數、加分隔符、序號改成數字補零(例:001)或跳過易混淆的 I、O,也可以讓同日第一團不帶序號、第二團起才加尾碼,或完全不放地區與航空。改格式只影響之後產生的團號,既有團號不變。
›API 對應
- 設定或產生團號:
POST /trips/departures/{departureId}/group-code、POST /trips/departures/{departureId}/group-code/generate(departure.update)。 - 以團號查行程:
GET /trips的groupCode參數(可用前綴)。列表的representativeGroupCode是該行程近期的代表團號。 - 代碼表:
GET /group-codes/regions、GET /group-codes/airlines,同路徑的POST、PATCH、DELETE維護。需group_code.manage。 - 團號格式:
PUT /settings/group-code-pattern。
退改費與契約設定
抽籤前幾天
行程退改費區的「抽籤前幾天」填一次,三處共用:
- 退改費階梯首列的門檻是這個天數+1。改這格會重新產生階梯。
- 抽籤梯次的「可變更第三人期限」是這個天數加緩衝天數。
- 契約設定中「抽籤日期來源」那個種類的期限日,是出發前這個天數。
梯次可覆寫這格(抽籤模組開啟時才顯示),只影響該梯的期限與契約,不影響退改費。改行程的值不回寫既有梯次,要在期限警戒按「重算」。
抽籤時刻與前台截止
抽籤梯次到抽籤時刻(抽籤日當天,或設定的前一天),前台自動停收新單,顯示「已截止申請」。這是忘記手動停售時的備援:提前送籤時,照舊手動停售。
- 後台 K 單、線控安置與備案轉單不受影響,梯次狀態也不變。
- 抽籤時刻依序取:行程指定的抽籤時程表上這梯的時段開始 → 梯次的「抽籤時刻」→ 行程的「抽籤時刻」(基本分頁,抽籤模組開啟時才顯示)。
- 都沒設時,抽籤日 00:00 起停收。梯次表的停止售票欄與梯次總覽會標「未設抽籤時刻」。
- 站方在抽籤日前一天深夜開抽時,把「抽籤時刻落在」設成「抽籤日前一天」。例:抽籤前 30 天、抽籤時刻 23:59、落在前一天,12/12 出發的梯次標「抽籤 11/11 23:59」,前台 11/11 23:59 起停收。
- 「抽籤時刻落在」只移動停收時刻與梯次表上的日期。抽籤日、關鍵日期、可變更第三人期限、退改費階梯都不變。抽籤時程表有時段時,以時段為準,不套用前一天。
- 行程設預設值,梯次可逐梯覆寫,選「繼承行程」退回行程值。
- 改了立即生效,不用重算。
行程的契約設定
契約流程開啟時,行程編輯頁「基本」分頁有「旅遊契約」區。留空就沿用公司設定。
- 此行程不需旅遊契約:課程等非旅遊商品用。勾選後不產生契約、不寄簽約邀請,待簽契約撤銷,已簽契約保留。
- 本行程契約種類:個別或團體。國內或國外仍依海外團旗標決定。
- 抽籤梯次緩衝天數:例:60 天抽籤、90 天前可換人,填 30。
梯次列與梯次編輯頁顯示「可變更第三人期限:出發前 N 天(自動/手填)」,不必下單就能核對。簽個別契約的行程不顯示。
公司層級的契約設定見旅遊契約。
找出並重套退改費
行程的退改費階梯是建立時的快照,修改公司預設不會自動回寫。
- 在行程列表勾選「只看退改費與預設不同」,找出用舊級距的行程。
- 勾選行程,按「重新套用公司預設階梯」,檢查預覽:受影響的行程、已開賣的行程與未結訂單數。
- 按「確認重新套用」。
- 國內行程重套目前的公司預設,並保留可辨識的 60/120 天抽籤前置設定。海外行程改用海外個別契約級距並啟用人工核算。
- 已開賣或已有訂單的行程也會改寫。無效、明確不收費或無法辨識的設定會列出原因,請逐一處理。
- 預覽後費率或範圍有變,整批停止,要重新確認。
- 每個改寫的行程都留稽核紀錄。
取消後的退款核算見取消與退款。
›API 欄位
- 行程:
lotteryLeadDays、agreementExempt(true/false)、agreementTravelForm(individual/group/null)、agreementChangeBufferDays。梯次的lotteryLeadDays傳null退回行程值。 - 抽籤時刻:行程與梯次的
lotteryDrawTime(HH:MM,台北時間)。梯次傳null退回行程值。 - 抽籤時刻落在哪一天:行程與梯次的
lotteryDrawDayOffset(0抽籤日當天,-1抽籤日前一天)。梯次傳null退回行程值。梯次讀取回應另有lotteryDrawAtDate(抽籤時刻所在的日期)。CLI 用toko trips update <id> --lottery-draw-day-offset -1與toko trips departures update <id> --lottery-draw-day-offset ''。 - 重套退改費:
POST /trips/cancellation-tiers/preview預覽,POST /trips/cancellation-tiers/reapply執行(trip.manage)。
建議航班
行程編輯頁「基本」分頁的「報名規則」最上方可以填建議航班,所有梯次共用,沒有就不必填。前台 API 的行程明細會帶出 suggestedFlights,自建前台可以排成航班卡片。
- 一份建議航班有 1–5 個方案,剛好一個推薦方案。前台 API 把推薦方案排在第一個。
- 方案分兩種:
- 搭飛機:到機場集合,逐段填航班。每段填完整班號(如
CI118)、出發與抵達機場(IATA 三碼,後台也可以打中文名稱)、第幾天與當地時間。同一個方向依順序是第 1、2、3 段;直飛、轉機次數與轉機時間由系統推算。只有去程或只有回程也可以。 - 自行前往車站:在當地車站集合,填建議抵達機場、接駁路線與所需時間,可勾「建議前一天抵達」。
- 搭飛機:到機場集合,逐段填航班。每段填完整班號(如
- 系統內建常用的機場與航空公司。清單沒有的代碼,由填寫者補名稱,存在同一份資料裡。
- 天數 0 是第 1 天的前一天。時間都是當地時間。
- 資料有錯時整筆拒絕並回中文原因,例如轉機機場前後對不上、起飛早於上一段抵達、班號或時間格式不對、超過數量或長度上限。轉機少於 1 小時、班表核對超過半年只提醒,不擋儲存。
- 不支援逐梯次不同航班、往東跨越換日線(抵達日早於起飛日)的航班,以及同城換機場的轉機。
›API 欄位
寫入時送 suggestedFlights(省略不變,null 清空):
updated:最後核對班表的年月,YYYY-MMticket:不含/可代訂/含plans[]:name、primary、mode(flight/station)、meetDay、meetTime(HH:mm,省略或空字串為抵達後)、meetPlaceflight方案:flights[]的每段為dir(out去程、ret回程、dom當地國內線)、flight、from、to、depDay、dep、arrDay、arrstation方案:airports[]、route、duration、arriveDayBefore
extraAirlines、extraAirports:清單沒有的代碼與名稱,例如{ "YO": "某某航空" }
前台 API 的 suggestedFlights 只在資料檢查通過時輸出,沒填或有錯時為 null。航班段改叫 segments[],並附航空公司名稱 airline 與機場短名 fromName、toName;車站方案的 airports[] 每筆是 { code, name }。
抽籤須知
啟用登山模組並勾選「登山團」後,行程的公開報名資訊依序是「費用包含/不包含 → 抽籤與報名須知 → 注意事項」。
- 後台 →「範本」→「抽籤須知範本」提供 30、60、90、120 天與免抽籤的起始內容,可修改名稱與內文。用「醒目提醒」區塊強調訂金、通知或入園申請限制。
- 套用範本會取代行程目前的須知;已有內容時先確認。套用後仍可再改。
- 修改或刪除範本不影響已套用的行程。取消「登山團」會隱藏須知並保留草稿。
- 須知只是說明文字,不會改動抽籤天數、分配方式、訂金、尾款或退改費。範本中的
{{客戶姓名}}等文字原樣保存,不會替換。
›API 與 CLI 對應
- 行程欄位
lotteryNoticeMdx:省略不變,null清空。 - 範本:
GET /lottery-notice-templates、POST /lottery-notice-templates、GET /lottery-notice-templates/{id}、PATCH /lottery-notice-templates/{id}(需送完整名稱與內容)、DELETE /lottery-notice-templates/{id}。需trip.manage與登山模組。 - 前台 API 把須知併入
bodyHtml,提醒區塊以data-block="notice"標記。
toko trips lottery-notice-templates list --json
toko trips lottery-notice-templates create --name "30 天抽籤" --content-mdx "請先確認訂金與抽籤通知方式。" --confirm
toko trips set-lottery-notice <tripId> --template-id <templateId> --confirm
toko trips set-lottery-notice <tripId> --clear --confirm建立或更新行程時也可傳 --is-climbing、--is-high-altitude 與 --lottery-notice-mdx;--is-climbing=false 關閉登山團,--is-high-altitude=false 取消屬高海拔。需具備高山經驗的行程一律屬高海拔,送 false 也維持 true(見登山審核)。
限外籍旅客
有些行程只收外籍旅客,例:使用國家公園外籍入園名額。在行程「出團安排 → 報名資格」勾選「限外籍旅客」後:
- 前台結帳只要有一位旅客國籍空白或是台灣,整張訂單擋下,並指出是哪幾位。
- K 單同樣擋下。管理員確認可以同行時(例:外籍客人的台灣親友),勾「仍要建立」放行,系統留稽核紀錄。
- 後台行程列表與編輯頁顯示「限外籍」,前台行程頁與結帳頁提示只收外籍旅客。
只影響之後的新訂單。
›API 與錯誤碼
POST /orders 遇到本國旅客回 422 foreign_travelers_only。放行時帶 allowDomesticTravelers: true(CLI orders create --allow-domestic-travelers),系統寫入 order.foreign_only_override 稽核紀錄。
報名調查項
行程編輯頁「調查項」分頁設定報名時逐位旅客回答的題目:單選、多選、數量、自由文字。例:餐點、上車點、裝備租借意願。梯次沿用行程的題目,可在梯次上停用個別選項。
›API 對應
- 題目:
GET /trips/{id}/survey、POST /trips/{id}/survey/questions、PATCH /trips/{id}/survey/questions/{questionId}、POST /trips/{id}/survey/questions/{questionId}/active、POST /trips/{id}/survey/questions/{questionId}/options、PATCH /trips/{id}/survey/options/{optionId}。 - 梯次停用選項:
PATCH /departures/{depId}/survey-options/{optionId},舊答案保留。
相關指南
- 抽籤與備案:抽籤梯次的應募、裁決與未中籤轉備案。
- 出團準備與線控:成團、承辦與出團前作業。
- 訂單與金流模型:報名後的應收、收款與狀態。
- trips API · departures API · group-codes API。
嚮導帶團期間
行程的 guideStartDay、guideEndDay 以 D1 為出發日,指定嚮導的預設帶團期間。
兩欄須成對設定;兩欄傳 null 時使用完整梯次。未傳欄位則保留原設定。
CLI 使用 --guide-start-day、--guide-end-day,或用 --clear-guide-days 清空兩欄。
單筆指派可另外覆寫實際日期。詳見嚮導與排班。