入山入園申請與送籤
登山團要辦入山證、入園證與山屋床位。toko 記錄每張申請單的狀態,旅客離團時開出取消請求,並把整梯旅客資料整理成送籤用的格式。
這些功能只在登山模組開啟、行程是登山團時出現。toko 不直接連站方網站:送件、查籤、取消由貴公司自己的送籤工具或人員處理,toko 記錄結果。
證件追蹤
在梯次頁 →「出團準備」分頁 →「證件」子分頁,逐種證件記錄申請狀態:待申請、申請中、已核准,以及檔案是否就緒與雲端連結。這團不需要的證件,標「本團不需要」。
證件種類由貴公司自訂(例:入山證、入園證、床位核准證)。每條路線要哪幾種,在行程編輯頁勾選。
›API
POST /departures/{depId}/prep/documents 記錄證件狀態,值為 todo、applying、approved。需 departure_prep.manage。
申請單
同一子分頁的「申請單」卡記錄每一張入園、入山或床位申請。一梯可以有多張,例:分組送件、兩天各一張入園申請、退件後重送。
每張申請單記錄申請處、路線與組別、入園日、人數、申請人、領隊、申請編號、狀態、最近查籤時間與證件檔。卡片上方的摘要分成「還沒送」「等結果」「要處理」「已拿到證件」四類。
操作:
- 按「新增申請單」建立。
- 送件後填申請編號與狀態。送籤工具也可以用 API 直接寫回。
- 核准後上傳證件檔(PDF、PNG、JPEG,8MB 以內,加密保存)。
- 退件要重送時,按該列的「重送」。系統建立新單,舊單改為「已作廢(重送)」。
- 不再使用的單按「作廢」。只有草稿可以刪除。
狀態規則:
- 狀態有強弱順序,較弱的狀態不會蓋掉較強的。例:已核准的單再收到「等抽籤/審核中」,狀態不變。
- 確實要改回較弱的狀態時,選帶「(需強制覆蓋)」的選項,並填寫原因。紀錄會留下「強制覆蓋狀態」。
- 已取消與已作廢的單,API 不能再改狀態,只能在後台強制覆蓋。
個資: 申請人與領隊的身分證加密保存,畫面與 API 只顯示遮罩。看明碼需要獨立的個資權限,內建角色只有管理員有,每次查看都留稽核紀錄。證件檔上也有旅客姓名與身分證,所以開啟與下載證件檔需要同一個個資權限;沒有這個權限的人只看得到檔名。每次下載都留稽核紀錄。
狀態選項:草稿、已送出(待補編號)、已送出、等抽籤/審核中、備取、未中籤轉候補、已中籤(待繳費)、已中籤(要補件)、已核准(請下載證件)、未中籤、退件、駁回、候補失敗、已取消、已作廢(重送)。
›API 與 CLI 對應
- 列出與新增一梯的申請單:
GET /departures/{depId}/permit-applications、POST /departures/{depId}/permit-applications。 - 讀與改單張:
GET /permit-applications/{id}、PATCH /permit-applications/{id}。改單時可帶expectedVersion,與伺服器版本不同時回409 stale_version,回應附目前資料。 - 送籤工具寫回:
POST /permit-applications/sync。依match(申請單 ID;申請處加申請編號;或梯次加申請處加組別)找單,找不到就建單;找到多張回409 ambiguous_match並列出候選。弱狀態不蓋強狀態時,回應的applied.status.reason為weaker_status。 - 只查不寫:
GET /permit-applications/lookup。 - 每次寫入帶
idempotencyKey。同一把 key 重送回第一次的結果;內容不同回409 idempotency_conflict。 - 重送:建新單並帶
replacesId,舊單在同一交易改為已作廢(重送)。 - 上傳證件檔:
POST /permit-applications/{id}/files。 - 讀身分證明碼:
POST /permit-applications/{id}/reveal。寫入或讀明碼都需permit_pii.read。 - 讀取需
departure_prep.read,寫入需departure_prep.manage。送籤工具用 API 金鑰呼叫時,租戶另需開通 API 存取。 - CLI:
control permit-list、permit-create、permit-get、permit-update、permit-lookup、permit-sync、permit-file-upload、permit-reveal。
旅客離團時的取消請求
國家公園中籤後沒到,可能被禁止申請一段時間。所以旅客離開梯次時(訂單取消、換梯、移除旅客),系統自動對相關的有效申請單開一筆取消請求:
- 這張單上已經沒有本梯旅客:整張到站方取消。
- 還有旅客留下:只從站方名單移除離開的旅客。
截止時間是入園日前一天台北時間 12:00。
取消請求顯示在申請單列上,標示種類與截止時間。
- 送籤工具處理完後回報結果。整張取消回報完成時,申請單同時改為「已取消」。
- 承辦自己到站方處理完,按「已在站方處理」,可填說明,再按「標記已處理」。
- 截止前 24 小時內還沒完成,或失敗達 3 次,系統每天 12:00 寄信給訂單承辦(沒有承辦時寄給預設承辦)。每筆請求只寄一次。
›API 與 CLI 對應
- 取走待處理請求:
POST /permit-cancel-requests/claim。外部程式建議每 5 分鐘呼叫一次。取走的請求 30 分鐘內沒回報,會再被取到。 - 只列出、不取走:
GET /permit-cancel-requests。 - 回報結果:
POST /permit-cancel-requests/{id}/result,帶done或failed、note與idempotencyKey。回報failed時請求回到待處理。 - 請求種類:
cancel_application(整張取消)、remove_travelers(移除travelers列出的旅客)。截止時間欄位為dueAt。 - 需
departure_prep.manage(列出只需departure_prep.read)。 - CLI:
control permit-cancel-list、permit-cancel-claim、permit-cancel-result。
匯出送籤資料
送籤與投保需要整梯旅客的完整資料,包括身分證。在後台 →「梯次」→「梯次總覽」的「列表」檢視,從梯次卡片的「更多」選單按「匯出送籤資料」。
- 把每張訂單拖到「第 N 組」,或放到「不送」。可以先按「自動分組」。同一張訂單的旅客一定在同一組,每組最多 11 人。
- 需要時,在「隨團人員」區勾選「加帶進送籤名單」,把已派的隨團人員一起送件(包括待確認的人)。
- 有旅客沒通過送籤檢查時,畫面會列出問題。確認後勾選「我已看過以上問題,仍要匯出這 N 位旅客的資料」。
- 按「複製送籤資料」,把結果貼進貴公司的送籤工具。
規則:
- 只有內建的管理員與 op 角色有匯出權限,而且要看得到全部訂單。只看得到自己訂單的角色不能匯出。
- 每次匯出都留稽核紀錄,記下誰、哪一梯、哪些旅客與隨團人員。
- 任一位的證件解不開,整次匯出失敗,不會產出缺身分證的資料。
- 外籍旅客有護照影本時,資料帶一個 30 分鐘內有效的下載網址。下載時仍要登入並有匯出權限,每次下載都留紀錄。過期就重新匯出。
- 隨團人員不算進每組人數上限。帶團排班換人後,新人預設不勾選,要重新勾。
- 送籤檢查的項目(身分證檢查碼、電話與地址格式等)見旅客與個資。
›API 與 CLI 對應
GET /departures/{depId}/submission-preview:每張訂單的人數、旅客姓名、同行組代號與送籤檢查問題。lastGroup是上次匯出時的組別;沒匯出過或人數變了時為null。staff列出已派的隨團人員(guideId、role、status、included、issues)。預覽不解密證件、不留稽核。PUT /departures/{depId}/submission-staff:帶guideIds,是要加帶的完整名單,沒列的人一律取消勾選。名單有不在本梯排班的嚮導時回409。CLI:control submission-staff <depId> --data '{"guideIds":[...]}'。POST /departures/{depId}/submission-export:帶assignments(每張訂單指定組號,null表示不送)與acknowledgedIssueCount(要送的訂單中有問題的旅客數)。組號會重編為連續的 1、2、3。分組不合規則或確認數不符時回409,此時不解密也不留稽核。
全部需要 departure.submission_export,且呼叫者的訂單可見範圍必須是全部訂單,否則回 403。
匯出 JSON:
- 版本
v: 1,來源source.tool: "toko"。trip.code是行程 slug,trip.name是行程名稱;departure帶團號與出發、回程、入園日期;exportedAt是匯出時間。 groups[]每組有no與travelers[]。每位旅客帶orderNumber、validation(OK或問題文字)、passportNo、nationality、nationalityName。未知國籍的代碼為空字串。- 外籍旅客有護照影本時帶
passportFile(url、contentType、expiresAt),沒有時為null。 staff[]每位的kind為staff,欄位比照旅客(另帶englishName),沒有訂單號與護照影本。counts帶travelers、staff、total。