toko

營運自動化

用 API 或 CLI 執行營運操作,例如批次寄尾款通知、成團、換梯、確認公司費用。每個操作都套用後台的業務規則、權限、模組與稽核。

什麼時候用

  • 同一個動作要對很多梯次或訂單做,例如每週寄出尾款通知。
  • 要讓排程或 AI agent 代為執行例行工作。
  • 要把其他系統的資料同步進來,例如會員或假日表。

只做一兩筆時,直接在後台操作比較快。

事前準備

  1. 公司已開通「API 與自動化」模組。 用 toko settings modules --json 查詢方案模組。回應不含 overseas;海外功能屬於 tour,依行程的海外旗標啟用。
  2. 準備憑證:人操作用 CLI 登入,排程用 API 金鑰。見 API 串接基礎。
  3. 確認憑證代表的角色有該操作的權限,見權限與角色。

可以自動化的流程

流程做什麼注意
一筆匯款分攤多單把一筆匯款拆到多張訂單入帳各單金額合計必須等於匯款金額;重試要沿用同一個請求識別碼。
抽籤建單與備案建立抽籤訂單,再設定有序備案建單時不收備案,建單後另設。
落選恢復與轉梯強制安置、取消落選單、轉梯、跨行程報價沿用訂單範圍與抽籤限制,不直接改狀態。
成團與完團確認成團、完團、宣告未成團用這些專用操作,不要直接改梯次狀態。
尾款與同意書提醒逐單寄尾款通知、催簽同意書、寄訊息檢查每一單的成功、略過與失敗;同意書提醒每呼叫一次就再寄一次。
登山經歷維護旅客的登山經歷只處理有權限的旅客。
旅遊契約產生、重發、撤銷契約,取得簽署連結與副本需要契約管理權限。
團前住宿管理出發前夜住宿與登記連結受住宿容量限制。
嚮導證照管理證照種類與嚮導證照讀寫證號需要個資權限;附件仍在後台上傳。
同意書種類與調查題目設定行程要簽的同意書、出團前調查範本版本只能新增;停用題目會保留舊答案。
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:沒帶回 400 application_key_required;過期回 409 stale_application,重新撈應募清單。
  • 仍有備案時回 backup_choices。可用 orders backup-choices-update 送出空的 departureIds 清空。

相關指南

批次寄尾款不處理同業單,也不替同業單建立付款連結。回應的 excludedAgencyOrders 是排除的同業單張數,請經同業收款。此數字不計入逐單略過數。

Command Palette

Search for a command to run...