營運自動化
用 API 或 CLI 執行營運操作,例如批次寄尾款通知、成團、換梯、確認公司費用。每個操作都套用後台的業務規則、權限、模組與稽核。
什麼時候用
- 同一個動作要對很多梯次或訂單做,例如每週寄出尾款通知。
- 要讓排程或 AI agent 代為執行例行工作。
- 要把其他系統的資料同步進來,例如會員或假日表。
只做一兩筆時,直接在後台操作比較快。
事前準備
- 公司已開通「API 與自動化」模組。
用
toko settings modules --json查詢方案模組。回應不含overseas;海外功能屬於tour,依行程的海外旗標啟用。 - 準備憑證:人操作用 CLI 登入,排程用 API 金鑰。見 API 串接基礎。
- 確認憑證代表的角色有該操作的權限,見權限與角色。
可以自動化的流程
| 流程 | 做什麼 | 注意 |
|---|---|---|
| 一筆匯款分攤多單 | 把一筆匯款拆到多張訂單入帳 | 各單金額合計必須等於匯款金額;重試要沿用同一個請求識別碼。 |
| 抽籤建單與備案 | 建立抽籤訂單,再設定有序備案 | 建單時不收備案,建單後另設。 |
| 落選恢復與轉梯 | 強制安置、取消落選單、轉梯、跨行程報價 | 沿用訂單範圍與抽籤限制,不直接改狀態。 |
| 成團與完團 | 確認成團、完團、宣告未成團 | 用這些專用操作,不要直接改梯次狀態。 |
| 尾款與同意書提醒 | 逐單寄尾款通知、催簽同意書、寄訊息 | 檢查每一單的成功、略過與失敗;同意書提醒每呼叫一次就再寄一次。 |
| 登山經歷 | 維護旅客的登山經歷 | 只處理有權限的旅客。 |
| 旅遊契約 | 產生、重發、撤銷契約,取得簽署連結與副本 | 需要契約管理權限。 |
| 團前住宿 | 管理出發前夜住宿與登記連結 | 受住宿容量限制。 |
| 嚮導證照 | 管理證照種類與嚮導證照 | 讀寫證號需要個資權限;附件仍在後台上傳。 |
| 同意書種類與調查題目 | 設定行程要簽的同意書、出團前調查 | 範本版本只能新增;停用題目會保留舊答案。 |
| OP 指派與出團待辦 | 指派梯次 OP、標記待辦完成或不適用 | 只能指派有效的線控或管理員;撤回需填原因。 |
| 出團預設 | 設定行程的出團預設 | 套用到既有梯次時只補缺的項目。 |
| 裝備租期 | 建立裝備租借並指定起訖日 | 需要登山模組。 |
| 送件與額度 | 查詢未中籤次數、預覽與匯出送件名單 | 匯出要有整梯權限,並確認問題清單。 |
| 分潤轉應付 | 把折扣碼分潤轉成應付款 | 需要建立應付款的權限。 |
| 公司費用確認 | 確認草稿狀態的公司費用 | 可帶實際金額。 |
| 訊息階段與範本 | 維護罐頭訊息的階段 | 已被使用的階段只能停用,不能刪除。 |
| 員工凍結 | 凍結或解除凍結員工 | 需要管理角色的權限。 |
| 代收轉付收據 | 開立與查詢旅行業代收轉付收據 | 金額由訂單計算;外部狀態不明時先查詢。 |
| 公司設定與網站內容 | 團號、取消政策、目的地規則、損益分區、網站內容 | 每類設定有各自的寫入入口。 |
| 刪除梯次與重套取消費率 | 刪除沒用到的梯次、把新費率套到既有梯次 | 有訂單或其他紀錄的梯次刪不掉,改成取消;重套費率先預覽再確認。 |
| 假日表批次 | 一次匯入多個假日 | 全部日期先驗證,再一次寫入。 |
每個操作的參數與可執行範例見 CLI 參考。
›API 入口對應
API 路徑均以 /api/v1 開頭。
| 流程 | API 入口 |
|---|---|
| 一筆匯款分攤多單 | orders 的 split-remittance、remittance-lookup。receivingAccountId 必填;重試沿用同一 idempotencyKey。 |
| 抽籤建單與備案 | orders 的 create、backup-choices |
| 落選恢復與轉梯 | orders 的 force-place、cancel-lottery-lost、cancel-failover、release-identity-hold、transfer-departure、cross-trip-quote |
| 成團與完團 | departures 的 confirmation、complete、cancel-group-not-confirmed |
| 尾款與同意書提醒 | departures 的 send-balance-slips、send-consent-reminders;orders 的 send-message |
| 登山經歷 | orders 的 travelers 子路由 |
| 旅遊契約 | orders 的 agreements 子路由 |
| 團前住宿 | departures 的 prep/pretrip-stays;連結可 ensure 或 rotate |
| 嚮導證照 | guide-certificate-types、guides 的 certificates |
| 同意書種類 | consent-kinds |
| 調查題目 | trips 的 survey;departures 的 survey-options |
| OP 指派 | departures 的 prep/ops |
| 待辦完成與不適用 | departures 的 prep/deadlines |
| 出團預設 | trips 的 ops-defaults |
| 裝備租期 | CLI control 的 prep-rental-create |
| 送件與額度 | lottery-filings、departures 的 submission-preview、submission-export |
| 分潤轉應付 | discount-codes 的 profit-shares(payable.create) |
| 公司費用確認 | operating-expenses 的 confirm |
| 訊息階段 | message-template-stages |
| 員工凍結 | staff 的 ban、unban(role.manage) |
| 代收轉付收據 | travelinvoice |
| 公司設定 | settings |
| 網站內容 | settings 的 storefront:模板、內容槽與關於頁在同一交易修改 |
| 刪除梯次 | POST /departures/{depId}/delete(trip.manage) |
| 重套取消費率 | trips 的 cancellation-tiers |
| 假日表批次 | holidays 的 batch |
操作守則
- 先查再寫。 先查資料與權限,確認範圍正確,再送出操作。
- 正式環境寫入要明確確認。 CLI 對正式環境寫入時,要加確認旗標才會送出。
- 看逐筆結果。 批次操作會回報每一筆成功、略過或失敗,不要只看整體成功。
- 重試要小心。 重試仍受業務條件限制。不是每個寄信或外部供應商呼叫都能防止重複,重試前先查目前狀態。
- 範例裡的 ID 要換成你公司的實際 ID。
›CLI 傳入 JSON 的寫法
需要多個欄位的命令用 --data 傳 JSON。加 --json 取得完整 API data;對正式 target 寫入時加 --confirm。
sh
toko members create --data '{"email":"customer@example.com","name":"Example Customer"}' --confirm --json
toko control survey dep_example --json
toko control send-balance-slips dep_example --confirm --json會員查找用 members lookup 或 members search。修改草稿請款用 payment-requests update。題目維護與旅客填答是不同操作:先讀梯次有效題目,再寫旅客答案。
只能在後台做的事
下列操作刻意不開放給 API 或 CLI:
- 會員本人的個資匯出:只能由會員本人登入操作。
- 檔案上傳、銀行對帳單匯入、客人簽署。
- 平台的租戶建置、待辦規則設定、旅客待辦勾稽。
- 人員資料的認領審查:員工先離線核對身分,再逐筆決定,不以證件比對自動認領。
嚮導名冊匯出是給授權外部服務用的專屬入口,只揭露嚮導帶團範圍內的旅客。
訂單換梯
換梯可以用 API 或 CLI 執行,規則與後台訂單頁相同:先預覽、再確認,同一個確認重送不會換兩次。規則、會擋下的情況與換梯後的安排,見換梯與拆單。
›換梯的 API 欄位與錯誤碼
- 命令:
orders transfer-departure。先送mode: "preview"與targetDepartureId,再送mode: "confirm"、原目標、previewToken、固定的requestId與reason。 - 跨行程換梯:預覽與確認都帶
crossTrip: true。先用orders cross-trip-targets <id> --q <關鍵字>找目標,再用orders cross-trip-quote試算。 - 人工調整:預覽與確認帶相同的
adjustment;金額不為零時需要order.adjust。開啟「少收必須經核准」時,非 admin 帶負數回409。 - 同一確認請求重送,回傳同一個
departureChangeId。成功的orderId是保留的訂單。API 版本 2026-11-03 另帶backupOrderId,值與orderId相同;下一個 API 版本移除這個欄位,改讀orderId。 - 人工換梯允許停售或額滿的來源;停售目標只收有位的先到先得梯次。換完不改梯次狀態。
- 來源已出發、已取消、已結團或已占名額不足回
source_unavailable。目標不可轉入或名額不足回unavailable。 - 其他作業正在使用來源或目標梯次時,可能回
stale_preview。 - 預覽的
receipts列出收據現況;receipts.blocked為true時要先處理。確認時仍有阻礙,回receipt_blocked。 - 抽籤:缺抽籤模組或
lottery.manage回forbidden(403)。回寫抽籤結果要帶應募清單的applicationKey:沒帶回 400application_key_required;過期回 409stale_application,重新撈應募清單。 - 仍有備案時回
backup_choices。可用orders backup-choices-update送出空的departureIds清空。
相關指南
批次寄尾款不處理同業單,也不替同業單建立付款連結。回應的 excludedAgencyOrders 是排除的同業單張數,請經同業收款。此數字不計入逐單略過數。