抽籤與備案
熱門路線的山屋床位或入園名額由主管機關抽籤決定。toko 收應募、記錄每張訂單的抽籤結果,未中籤時自動把訂單轉到客人選的備案梯次。
抽籤功能需要開通抽籤模組。抽籤本身不在 toko 裡:你在站方或自己的工具抽完,再回 toko 標記結果。
核心概念
| 詞 | 意思 |
|---|---|
| 分配模式 | 梯次的名額怎麼給:「先到先得」或「抽籤」。 |
| 應募 | 客人報名抽籤梯次。訂單成立並佔本梯席次,等待抽籤結果。 |
| 裁決 | 承辦依外部結果,把應募中的訂單標為「中籤」或「未中籤」。 |
| 備案 | 客人報名時選的其他梯次,有先後順序。未中籤時依序轉過去。 |
| 待人工安置 | 未中籤且備案用完或轉不過去的訂單,由承辦決定安置或退款。 |
| 備取 | 主管機關把應募排進備取,結果未定。仍算應募中,等結果出來再裁決。 |
應募佔的是本梯的席次,代表「誰報了這梯」。抽籤爭的是外部名額,不是 toko 的席次。
設定抽籤梯次
- 行程預設。 在行程編輯頁「基本」分頁 →「出團安排」→「成團 / 名額規則」設「預設分配模式」。新梯次(後台新增、批次匯入、API)在建立時帶入這個值。之後改預設,不會改既有梯次。
- 逐梯覆寫。 在梯次表單的「分配模式」選「抽籤」或「先到先得」,或選「繼承母行程」。
- 抽籤前幾天。 行程退改費區的「抽籤前幾天」同時決定退改費階梯首列、抽籤梯次的「可變更第三人期限」,以及抽籤相關期限。梯次可覆寫,只影響該梯的期限與契約,不影響退改費。詳見行程與梯次。
- 抽籤結果含備取。 主管機關會把申請排進備取的路線(例:排雲山莊),在行程編輯頁「候補與抽籤」勾「抽籤結果含備取」。勾了,團控才出現「備取」鍵。這和「啟用候補」(一般梯次滿席後排隊)是兩件事。
- 抽籤須知。 行程可附抽籤與報名須知,可從後台 →「範本」→「抽籤須知範本」套用。見行程與梯次。
抽籤模組關閉時,不能再把梯次設成抽籤。已是抽籤的梯次要逐梯改回先到先得。
›API 欄位
- 行程預設:
PATCH /trips/{id}的defaultAllocationMode(fcfs/lottery),預設fcfs。 - 建梯次時帶
allocationMode;更新梯次PATCH /trips/departures/{departureId}的allocationMode傳null會退回繼承。這兩條需trip.manage。 - 團控逐梯切換:
PATCH /departures/{depId}/allocation-mode,需lottery.manage。 - 設成
lottery都受抽籤模組限制;設成繼承或fcfs不受限制。
客人怎麼報名
- 客人在前台選抽籤梯次,報名並付訂金。訂單成為「應募中」。
- 結帳頁有「備案梯次(選填)」:從同一行程的其他梯次挑選並排序,可混合先到先得與抽籤梯次。
- 沒選備案的話,未中籤時直接進入退款流程。
客人在報名後不能自己改備案。要改,請客人留言,由承辦在訂單頁代改。
尾款期限:抽籤訂單下單時,尾款沒有到期日。前台與確認信顯示「中籤後 N 天內繳交」。中籤當天起算 N 天,N 在後台 →「公司設定」→「付款設定」的「抽籤團中籤後繳尾款天數」設定,預設 3 天。
後台代客建單(K 單)與 API 建到抽籤梯次的訂單,同樣立即成為應募中。K 單可在建單時代客選備案;API 建單不收備案,建單後另外設定。
裁決結果
後台 →「梯次」→「抽籤」列出今天起所有抽籤梯次的應募訂單。每列有訂購人、人數、備案梯次、已收金額與抽籤狀態。
逐單裁決: 按「中籤」或「未中籤」。
批次裁決: 勾選「全選本頁待裁決的單」或逐筆勾選,再選「標為中籤」或「標為未中籤」,確認張數後送出。系統逐單處理,一張失敗不影響其他張,結果逐單列出。
梯次總覽的「列表」檢視也能逐單或批次裁決。
同一梯分批標結果: 梯次卡的成團按鈕區有「中籤」「備取」「未中籤」三顆鍵。按下後列出這一梯還在等結果的訂單,勾這次要標的單再確認。例:一梯送兩張申請單,第一張中、第二張備取,就先勾第一張的單按「中籤」,再勾其餘的單按「備取」。按「中籤」不會自動成團,成團照舊按「標記成團」。
裁決後發生什麼:
- 中籤:訂單確認,系統寄尾款繳款單,不必等梯次成團。信沒寄成時裁決仍成立,畫面會提示,之後可逐單補寄或用批次寄尾款補寄。
- 未中籤:有備案就自動轉梯,見下一節;沒有備案就成為待人工安置。
標錯了: 裁決後可按「返回應募中」撤回最近一次裁決。下列情況不能撤回:之後已有收款、退款、人工安置、換梯、旅客或備案變更;或已轉備案、原梯次已滿、已取消、已出發。已寄出的尾款信收不回來,撤回時畫面會提醒你另外通知客人,舊的付款連結會失效。
›API 與 CLI 對應
- 一梯的應募名單:
GET /departures/{depId}/lottery-orders(order.read),每筆帶orderId、orderNumber、lotteryState、applicationKey。CLI:control lottery-orders <depId>。 - 裁決:
POST /orders/{id}/lottery/resolve,outcome為won或lost,並帶撈名單時的applicationKey。CLI:control lottery-resolve <orderId> --outcome won|lost --application-key <key>。 - 需
lottery.manage與抽籤模組,並受訂單可見範圍限制(範圍外回404)。 - 錯誤:新應募沒帶 key 回
400 application_key_required;訂單已轉入新應募、舊 key 失效回409 stale_application,請重新撈名單。已裁決、備案已售完、不是抽籤單也回409。 - 中籤時回應帶
balanceNotice,說明尾款信是否寄出。 - 訂單的抽籤狀態值:
applied(應募中)、won(中籤)、lost(未中籤)。
備取
結果是備取的單,按成團按鈕區的「備取」標記。備取的單比照應募中:
- 名額保留,不催尾款,客人也付不了尾款,不開退款。
- 系統不寄信,請用自己的管道告知客人。客人端照舊顯示待抽籤。
- 結果出來後,照常按「中籤」或「未中籤」,接原有流程(尾款期限、尾款信,或未中籤轉備案與退款)。
- 標錯了,在應募訂單表按「返回待抽籤」,只清掉備取,不動錢與席次。
梯次的抽籤狀態依序是待抽籤、備取中、已中籤或未中籤。同一梯有人中籤、有人還在備取時,顯示「已中籤(N 張備取中)」。梯次頁首、梯次總覽的抽籤欄與篩選都看得到。
›API 欄位
- 訂單:
GET /departures/{depId}/lottery-orders與訂單清單每筆帶lotteryWaitlisted。備取的單lotteryState仍是applied。 - 梯次:
GET /departures/control每筆帶lottery(result為none/pending/waitlisted/won/lost,另有waitlistedCount)與lotteryWaitlistEnabled。先到先得梯次的lottery為null。 - 行程設定:
PATCH /trips/{id}的lotteryWaitlistEnabled。 - 標記備取目前只能在後台操作,API 只讀。
未中籤自動轉備案
未中籤時,系統依客人排的順序,把同一張訂單換到下一個備案梯次:
- 先到先得的梯次有位:直接確認席位。
- 抽籤梯次:重新應募,等下一輪結果。
訂單編號、旅客與已付款都保留,尾款照新梯次續收,不用人工逐筆搬。備案梯次一律與原梯次同價(同業訂單也要求同業價相同),所以換梯不產生價差。
會被跳過的備案:額滿、停售、改價或名冊不符。系統記下跳過原因。實名抽籤的備案若因旅客缺證件號被跳過,會留在清單上、順位不變;承辦補完證件號後,可手動安置到該梯次。
代客改備案: 在訂單頁的「備案管理」卡,新增、移除或調整備案順序,再按「儲存」。只列同行程、同價、在售的梯次。
›API
- 查候選梯次:
GET /departures/{depId}/backup-candidates(order.create)。 - 設定有序備案:
PUT /orders/{id}/backup-choices(order.update)。
待人工安置
後台 →「梯次」→「未中籤轉備案」列出待人工安置、已自動轉備案、已手動安置與已取消的訂單。待處理的排在前面。
對待人工安置的訂單,有兩個處理方式:
- 手動安置:選同行程、同價、在售且有位的梯次,按「確認安置」。訂單原地換梯,不建新單。目標是抽籤梯次時,視同中籤。
- 保留 / 退款:
- 「客人要保留」:不做任何變更,款項留在訂單上。
- 「客人要退款」:取消訂單、釋回席次,並建立退款草稿,交給有權限的人核准。
退款金額 = 可退現金 − 送件行政費 − 轉帳手續費。取消本身不代表退款已執行,請開啟訂單確認退款進度。退款流程見付款流程。
訂單已取消但款項還留在單上時,客人的訂單頁顯示「您的款項」卡,客人可以自己申請退款。
›API
- 手動安置:
POST /orders/{id}/force-place。- 原梯次已下架或已額滿仍可安置,只要尚未出發。
- 失敗時回
409 conflict,訊息是原因碼:目標不可訂回target_full,原梯次已出發或席次資料不符回source_departed。
- 取消並建立退款草稿:
POST /orders/{id}/cancel-lottery-lost。 - 兩者都需
lottery.manage與抽籤模組。
送件行政費與未中籤次數
未中籤退款時,公司可依旅客未中籤的次數扣送件行政費。費率是累計階梯,由貴公司設定(例:每次 100 元,每人每單最多 500 元)。
- 次數以**一張訂單(含它的備案鏈)**計算,不跨訂單累計。
- 後台 →「梯次」→「未中籤次數」可用「證件類型」與「證件號碼」查詢次數。每次查詢都留稽核紀錄。
- 從訂單的旅客列按「查看次數」也能進入。
- 次數可人工調整,必須寫原因。
›API
- 查次數:
GET /lottery-filings/count、POST /lottery-filings/lookup(lottery.read)。 - 人工調整:
POST /lottery-filings/adjustments(lottery.manage)。
抽籤時程表
有些路線的抽籤日不是固定天數,例:假日不抽、颱風延期。抽籤時程表記錄「住宿日 → 抽籤日與時段」,行程指定時程表後,抽籤期限直接用表上的日期。表上的日期變了,相關梯次的期限會自動重算並標示。
- 後台 →「梯次」→「抽籤時程表」,按「新增時程表」。來源選「手動匯入」,或選官方公告來源讓系統每天自動抓取。
- 按「匯入 CSV」貼上資料,每行「住宿日,抽籤日,時段」,時段可省略(例:
09:00~10:00)。任一行格式錯誤,整批不寫入。 - 在行程編輯頁「營運規則」分頁的「期限規則」選擇這張時程表。
時程表不能刪除。官方不再列出的日期保留原值。
›API
- 列出時程表:
GET /lottery-schedules(lottery.read)。 - 批次寫入抽籤日:
POST /lottery-schedules/{id}/entries/batch(lottery.manage)。
抽籤實名制
國家公園入園申請採實名制:同一個人同一時間只能有一筆申請,重複申請會讓全隊送不出去。toko 可在報名時擋下重複。
開啟方式: 行程編輯頁「基本」分頁 →「出團安排」→「候補與抽籤」,勾選「啟用抽籤實名制」。只對該行程的抽籤梯次生效,預設關閉。
開啟後:
- 每位旅客都要有身分證或護照號碼,缺件不能報名。
- 同一證件在任何一個實名制抽籤梯次還有應募中的申請時,新報名會被擋下。同一張訂單內兩位旅客用同一份證件也會被擋。
- 既有訂單新增旅客或修改證件號,套用同一條規則。
- 擋下時,只有看得到衝突訂單的員工才會看到訂單號與梯次;客人只會看到「請聯絡客服」。
占用何時解除: 該筆申請裁決為中籤或未中籤、訂單取消或完成、梯次出發日已過。
漏標結果時: 在訂單頁按「解除實名占用」,填寫原因後確認。抽籤頁的應募列也有同一個按鈕。解除不能復原,會留稽核紀錄。這個操作不受抽籤模組開關限制。
系統看不到客人私下向站方的申請,請在同意書或須知中提醒客人。
›API 欄位與錯誤碼
- 行程欄位:
PATCH /trips/{id}的lotteryIdentityGuardEnabled。 - 衝突時建單與旅客寫入回
409 conflict;受管制訂單缺證件回422 validation。 - 解除占用的權限:訂單頁需
order.update,抽籤頁需lottery.manage。
權限與模組
| 動作 | 權限 |
|---|---|
| 看抽籤、未中籤轉備案、未中籤次數、抽籤時程表 | lottery.read |
| 裁決、手動安置、取消並退款、團控切換分配模式 | lottery.manage |
| 行程預設分配模式、梯次表單的分配模式 | trip.manage |
| 代客改備案 | order.update |
以上都需要抽籤模組,解除實名占用除外。來源或目標是抽籤梯次的人工換梯,另需 lottery.manage。