toko

入山入園申請與送籤

登山團要辦入山證、入園證與山屋床位。toko 記錄每張申請單的狀態,旅客離團時開出取消請求,並把整梯旅客資料整理成送籤用的格式。

這些功能只在登山模組開啟、行程是登山團時出現。toko 不直接連站方網站:送件、查籤、取消由貴公司自己的送籤工具或人員處理,toko 記錄結果。

證件追蹤

在梯次頁 →「出團準備」分頁 →「證件」子分頁,逐種證件記錄申請狀態:待申請、申請中、已核准,以及檔案是否就緒與雲端連結。這團不需要的證件,標「本團不需要」。

證件種類由貴公司自訂(例:入山證、入園證、床位核准證)。每條路線要哪幾種,在行程編輯頁勾選。

›API

POST /departures/{depId}/prep/documents 記錄證件狀態,值為 todo、applying、approved。需 departure_prep.manage。

申請單

同一子分頁的「申請單」卡記錄每一張入園、入山或床位申請。一梯可以有多張,例:分組送件、兩天各一張入園申請、退件後重送。

每張申請單記錄申請處、路線與組別、入園日、人數、申請人、領隊、申請編號、狀態、最近查籤時間與證件檔。卡片上方的摘要分成「還沒送」「等結果」「要處理」「已拿到證件」四類。

操作:

  1. 按「新增申請單」建立。
  2. 送件後填申請編號與狀態。送籤工具也可以用 API 直接寫回。
  3. 核准後上傳證件檔(PDF、PNG、JPEG,8MB 以內,加密保存)。
  4. 退件要重送時,按該列的「重送」。系統建立新單,舊單改為「已作廢(重送)」。
  5. 不再使用的單按「作廢」。只有草稿可以刪除。

狀態規則:

  • 狀態有強弱順序,較弱的狀態不會蓋掉較強的。例:已核准的單再收到「等抽籤/審核中」,狀態不變。
  • 確實要改回較弱的狀態時,選帶「(需強制覆蓋)」的選項,並填寫原因。紀錄會留下「強制覆蓋狀態」。
  • 已取消與已作廢的單,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。

匯出送籤資料

送籤與投保需要整梯旅客的完整資料,包括身分證。在後台 →「梯次」→「梯次總覽」的「列表」檢視,從梯次卡片的「更多」選單按「匯出送籤資料」。

  1. 把每張訂單拖到「第 N 組」,或放到「不送」。可以先按「自動分組」。同一張訂單的旅客一定在同一組,每組最多 11 人。
  2. 需要時,在「隨團人員」區勾選「加帶進送籤名單」,把已派的隨團人員一起送件(包括待確認的人)。
  3. 有旅客沒通過送籤檢查時,畫面會列出問題。確認後勾選「我已看過以上問題,仍要匯出這 N 位旅客的資料」。
  4. 按「複製送籤資料」,把結果貼進貴公司的送籤工具。

規則:

  • 只有內建的管理員與 op 角色有匯出權限,而且要看得到全部訂單。只看得到自己訂單的角色不能匯出。
  • 每次匯出都留稽核紀錄,記下誰、哪一梯、哪些旅客與隨團人員。
  • 任一位的證件解不開,整次匯出失敗,不會產出缺身分證的資料。
  • 外籍旅客有護照影本時,資料帶一個 30 分鐘內有效的下載網址。下載時仍要登入並有匯出權限,每次下載都留紀錄。過期就重新匯出。
  • 隨團人員不算進每組人數上限。帶團排班換人後,新人預設不勾選,要重新勾。
  • 送籤檢查的項目(身分證檢查碼、電話與地址格式等)見旅客與個資。
›API 與 CLI 對應
  1. GET /departures/{depId}/submission-preview:每張訂單的人數、旅客姓名、同行組代號與送籤檢查問題。lastGroup 是上次匯出時的組別;沒匯出過或人數變了時為 null。staff 列出已派的隨團人員(guideId、role、status、included、issues)。預覽不解密證件、不留稽核。
  2. PUT /departures/{depId}/submission-staff:帶 guideIds,是要加帶的完整名單,沒列的人一律取消勾選。名單有不在本梯排班的嚮導時回 409。CLI:control submission-staff <depId> --data '{"guideIds":[...]}'。
  3. 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。

相關指南

Command Palette

Search for a command to run...