toko

CLI 參考

進階套組

toko <resource> <verb> 全 435 命令,依領域分類。每條標出對應的 /api/v1 端點與回應欄位;寫入命令對 production target 需 --confirm。按 ⌘K 搜尋。

開始使用

toko CLI 是 API 的命令列版本。你或你的 agent 在終端機操作後台,業務規則、權限與稽核都和後台網頁相同。 CLI 與 API 屬於「API 與自動化」模組,需要平台開通。 行程、梯次、出團準備、帶團排班與成本範本指令另需行程模組(tour)。 未開通時回傳 403 module_disabled。手動建立行程訂單也需要行程模組;獨立訂房建單不受影響。 可用 toko settings modules --json 查詢方案模組。回應不含 overseas;海外功能屬於行程模組,依行程的海外旗標啟用。

需要 Node.js 22 以上(含 npm)。先全域安裝 CLI,再用 toko 執行。不記得命令時,用 help 列出資源,或在資源名稱後加 help 列出它的命令。

安裝與查命令
npm i -g @toko-cloud/cli
toko help
toko orders help

登入

登入走 OAuth device flow。先用 target add 設定租戶網域,再用 login 取得驗證碼,到瀏覽器用後台帳號核准。終端機不輸入密碼。

在 SSH、無瀏覽器環境或給 agent 使用時,加 --no-browser。CLI 只印出驗證碼與核准網址,不自動開瀏覽器。

token 依 target 分開存放,權限沿用你帳號的角色。token 會到期,到期後重新 login。logout 只刪除本機的 token,不撤銷伺服器的工作階段。

登入與登出
toko target add demo https://your-tenant.example.com
toko login
toko whoami
toko logout

輸出格式

加 --json 時,stdout 只有一份 API data JSON,方便管線與 agent 解析。 警告、登入進度與錯誤走 stderr,失敗時 exit code 不是 0。

CSV 匯出加 --json 時改輸出 JSON。對帳單範本加 --out 會寫檔,並回傳 { filename, out }。

JSON 輸出
toko orders list --status pending_payment
toko orders list --status pending_payment --json
toko reconciliation statement template --out ./statement.csv --json

版本

全域安裝預設使用正式版。再次執行安裝命令即可更新。自動化請固定 CLI 的 major:同一個 major 內只新增命令與修正 bug,--json 的輸出形狀不變。

每個 CLI release 內建一個 API 版本,每個請求都用 Toko-Version header 送出,沒有旗標可以改。換內建的 API 版本一定升 major,更新提示會說明輸出形狀會改變,並附 API changelog 的網址。每個 CLI major 用哪個 API 版本,見 API changelog。

內建的 API 版本進入棄用期時,CLI 在 stderr 提示升級:互動終端每天最多一次,非互動模式每次一行,GitHub Actions 裡印 ::warning::。stdout 不變。版本已下架時,CLI 印出升級命令並以非零 exit code 結束。

version check 查詢 npm 新版,不需要登入,也不會安裝。 正式版預設查 latest 通道。互動終端每天最多自動檢查一次;JSON 與 CI 不主動檢查。手動查詢失敗時回傳非零 exit code。

設定與 token 存在 ~/.toko/config.json,可用 TOKO_CLI_HOME 改位置。更新套件會保留設定。

版本選擇
npm i -g @toko-cloud/cli
toko --version
# 1.0.0 (API 2026-11-03)
toko version check --json

# 自動化固定 major
npm i -g @toko-cloud/cli@1

AI agent skill

CLI 內建租戶操作、員工 API 與自建前台指引。專案入口讀取目前 CLI 的內容,更新 CLI 就會更新指引。

複製初始化 prompt,讓 agent 安裝 CLI 並建立入口,見 AI agent 初始化與內建 skill。

建立內建 skill 入口
toko skill install --json
toko skill show

寄信紀錄

預設查詢最近七個台北日期。可依日期、狀態、分類、收件人、梯次、訂單與嚮導篩選,每頁最多 100 筆。

讀取需要 email_history.read,重試需要 email_history.retry。只有 canRetry 為 true 的失敗紀錄能重試。

ID 須使用對應資源的前綴,錯誤 ID 回傳 422。內容可能已遮罩或不可用。密碼重設與啟用信會申請新連結;OTP 須從登入流程重新申請。詳見 寄信紀錄與安全重試。

查詢與安全重試
toko email-history list --status failed --json
toko email-history get <id> --json
toko email-history retry <id> --confirm --json

問題回報

CLI 先顯示草稿,確認後開啟 GitHub 公開的 cli-feedback repo,由你檢查並送出。回報不是匿名的,GitHub 帳號名稱會公開顯示。

自動附帶的資料與無瀏覽器用法,見 AI agent 初始化與內建 skill。

回報問題或提出需求
toko feedback bug
toko feedback feature

帶團期間與綁名

行程使用成對的 --guide-start-day、--guide-end-day,D1 是出發日。 指派使用 --guide-start-date、--guide-end-date 覆寫日期。 省略會保留原值;用 --clear-guide-days 或 --clear-guide-dates 回復預設。 移除或解除綁名須提供 --name-bound-change-reason,換主要隨團人員須提供 --reason。 詳見 嚮導與排班。

嚮導登入政策沿用 settings guide-portal-policy,模式可選 password_totp、password_only 或 email_otp。模式變更會要求全體嚮導重新登入。

命令結構

絕大多數命令都是同一個形狀:toko <resource> <verb> [positional] [--flags]。positional 通常是主鍵 id,flags 是篩選/欄位/選項。

資源命令的全域旗標:--target <name> 單次指定要打的 target、--json 機器可讀輸出、--confirm 對 production 寫入時必帶(見下)。target 設定命令不接受 --target 或 --confirm;help 不接受 --json。

業務命令對應 /api/v1 端點,走相同的權限檢查與稽核。下方參考每條命令都標出對應端點(可點擊跳到 API 參考),回應欄位即該端點的回應。

target 切換
toko target list
toko target use demo
toko orders list --target staging   # 單次覆寫

Production 安全

金流設定使用 settings payment-provider 查詢,settings set-payment-provider 執行明確操作。永豐憑證使用四組 Hash 與 X-KEY;收款與退款能力由平台能力表決定。切換只影響新付款; 原路退款依原收款分配執行,處理中與結果不明不能重送。詳見 付款流程。

把正式環境的 target 標成 production,CLI 就會在任何寫入命令上要求 --confirm,避免手滑打到正式資料。讀取命令不受影響。

未知旗標會在執行命令前被拒絕。CLI 不支援通用的 --dry-run 或 --apply,帶入就會失敗。一般寫入直接執行;嚮導、行程與對帳單匯入省略 --commit 時只驗證,帶入才寫入。--json 不改變寫入行為。

--confirm 只是 client 端的減速丘,不是授權:每個寫入端點都會在 server 重跑權限檢查,權限不足一律回 403 forbidden;owner-scope 也由 server 依你的 token 重算——業務經 CLI 一樣只看得到自己經手的訂單。

production target
toko target add prod https://your-tenant.example.com --production

toko orders mark-paid <id>             # ✗ 需 --confirm
toko orders mark-paid <id> --receiving-account <accountId> --confirm   # ✓

# 原路退款先讀 orders get --json 的 moneyReceiptId
toko orders refund-paid <id> --refund <refundId> --receipt <moneyReceiptId> --confirm
# pending / unknown 尚未出款;核對個別執行證據後才可完成退款

# 取消待執行的退款單(拆單組一起取消,不出款);已核准的匯款單要先確認銀行沒有出款
toko orders refund-cancel <id> --refund <refundId> --reason <原因> --remit-not-sent-verified --confirm

orders refund-paid 只送出系統刷退。原付款超過金流商 API 退款期限、 接近待核對門檻,或退款單採人工模式時,server 會拒絕送出。CLI 不提供人工退刷登錄或執行模式變更,請至後台訂單頁操作。請先閱讀退款期限與人工退刷說明,再依各筆原收款選擇流程。

toko discount-codes

折扣碼:列表、明細、預覽試算、兌換報表

toko discount-codes list

列出所有折扣碼

參數

--json
旗標 · 選填

回應欄位 · data[]

id
string

折扣碼 id(disc_ 前綴)。

code
string

折扣碼字串(客戶結帳輸入用,租戶內唯一)。

label
string

折扣碼顯示名稱(後台辨識用)。

discountType
"fixed" | "percentage"

折扣型別:fixed 定額折抵 / percentage 比例折抵。

discountValue
number

折扣值:fixed 為 TWD 整數,percentage 為百分比數字。

discountBasis
"per_amount" | "per_order" | "per_travelers"

計算方式:per_order 整張訂單折一次 / per_travelers 每 N 位旅客折一次 / per_amount 每滿 N 元折一次。

discountStep
number | null

N:每幾位旅客 / 每滿幾元(TWD);per_order 時為 null。

profitShareType
ProfitShareType | null

分潤型別:fixed 定額 / percentage 比例;null = 無分潤。

profitShareValue
number | null

分潤值:fixed 為 TWD 整數,percentage 為百分比;null = 無分潤。

profitSharePayee
string | null

分潤受款對象(如合作夥伴名稱);null = 無。

isActive
boolean

是否啟用(停用後不可再兌換)。

validFrom
string | null

生效起始時間;null = 無下限。

validUntil
string | null

生效截止時間;null = 無上限。

maxRedemptions
number | null

總兌換次數上限;null = 不限。

redemptionCount
number

已兌換次數(不含已取消訂單)。

minOrderTwd
number | null

最低訂單金額門檻(TWD 整數);null = 無門檻。

minTravelerCount
number | null

最低旅客人數門檻;null = 無門檻。

appliesToAll
boolean

是否適用所有行程(true = 全站,false = 僅限 tripIds 名單)。

maxRedemptionsPerCustomer
number | null

每位客戶兌換次數上限;null = 不限。

allowedPriceChannels
string[] | null

限用的價格通路清單(如 direct / agency);null = 不限。

allowedCustomerTypes
string[] | null

限用的客戶類型清單;null = 不限。

stackable
boolean

保留的旗標,結帳不讀:一張訂單只能套一個折扣碼。

notes
string | null

內部備註;null = 無。

createdAt
string

建立時間。

範例
toko discount-codes list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "label": "…",
      "discountType": "fixed",
      "discountValue": 0,
      "discountBasis": "per_amount",
      "discountStep": 0,
      "profitShareType": null,
      "profitShareValue": 0,
      "profitSharePayee": "…",
      "isActive": true,
      "validFrom": "…",
      "validUntil": "…",
      "maxRedemptions": 0,
      "redemptionCount": 0,
      "minOrderTwd": 0,
      "minTravelerCount": 0,
      "appliesToAll": true,
      "maxRedemptionsPerCustomer": 0,
      "allowedPriceChannels": "…",
      "allowedCustomerTypes": "…",
      "stackable": true,
      "notes": "…",
      "createdAt": "…"
    }
  ]
}
toko discount-codes get

單一折扣碼完整明細

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

折扣碼 id(disc_ 前綴)。

code
string

折扣碼字串(客戶結帳輸入用,租戶內唯一)。

label
string

折扣碼顯示名稱(後台辨識用)。

discountType
"fixed" | "percentage"

折扣型別:fixed 定額折抵 / percentage 比例折抵。

discountValue
number

折扣值:fixed 為 TWD 整數,percentage 為百分比數字。

discountBasis
"per_amount" | "per_order" | "per_travelers"

計算方式:per_order 整張訂單折一次 / per_travelers 每 N 位旅客折一次 / per_amount 每滿 N 元折一次。

discountStep
number | null

N:每幾位旅客 / 每滿幾元(TWD);per_order 時為 null。

profitShareType
ProfitShareType | null

分潤型別:fixed 定額 / percentage 比例;null = 無分潤。

profitShareValue
number | null

分潤值:fixed 為 TWD 整數,percentage 為百分比;null = 無分潤。

profitSharePayee
string | null

分潤受款對象(如合作夥伴名稱);null = 無。

isActive
boolean

是否啟用(停用後不可再兌換)。

validFrom
string | null

生效起始時間;null = 無下限。

validUntil
string | null

生效截止時間;null = 無上限。

maxRedemptions
number | null

總兌換次數上限;null = 不限。

redemptionCount
number

已兌換次數(不含已取消訂單)。

minOrderTwd
number | null

最低訂單金額門檻(TWD 整數);null = 無門檻。

minTravelerCount
number | null

最低旅客人數門檻;null = 無門檻。

appliesToAll
boolean

是否適用所有行程(true = 全站,false = 僅限 tripIds 名單)。

maxRedemptionsPerCustomer
number | null

每位客戶兌換次數上限;null = 不限。

allowedPriceChannels
string[] | null

限用的價格通路清單(如 direct / agency);null = 不限。

allowedCustomerTypes
string[] | null

限用的客戶類型清單;null = 不限。

stackable
boolean

保留的旗標,結帳不讀:一張訂單只能套一個折扣碼。

notes
string | null

內部備註;null = 無。

createdAt
string

建立時間。

tripIds
string[]

限定適用的行程 id 清單(appliesToAll=false 時生效)。

redemptions
object[]

逐筆兌換紀錄。

orderId
string

兌換該折扣碼的訂單 id(ord_ 前綴)。

orderNumber
string

訂單編號(人類可讀流水號)。

codeSnapshot
string

兌換當下的折扣碼字串快照。

originalTotalTwd
number

套用折扣前的原始應收總額(TWD 整數);跨行程換梯後為目標團費。

discountTwd
number

現行折抵金額(TWD 整數);跨行程換梯退出優惠後為 0。

profitShareTwd
number

現行分潤金額(TWD 整數);跨行程換梯退出優惠後為 0。

orderStatus
string

訂單當前狀態。

createdAt
string

兌換(下單)時間。

totalDiscountTwd
number

累計折抵金額合計(TWD 整數)。

totalProfitShareTwd
number

累計分潤金額合計(TWD 整數)。

totalPaidTwd
number

兌換訂單累計已收金額合計(TWD 整數)。

範例
toko discount-codes get '<id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "code": "…",
    "label": "…",
    "discountType": "fixed",
    "discountValue": 0,
    "discountBasis": "per_amount",
    "discountStep": 0,
    "profitShareType": null,
    "profitShareValue": 0,
    "profitSharePayee": "…",
    "isActive": true,
    "validFrom": "…",
    "validUntil": "…",
    "maxRedemptions": 0,
    "redemptionCount": 0,
    "minOrderTwd": 0,
    "minTravelerCount": 0,
    "appliesToAll": true,
    "maxRedemptionsPerCustomer": 0,
    "allowedPriceChannels": "…",
    "allowedCustomerTypes": "…",
    "stackable": true,
    "notes": "…",
    "createdAt": "…",
    "tripIds": [
      "…"
    ],
    "redemptions": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "codeSnapshot": "…",
        "originalTotalTwd": 0,
        "discountTwd": 0,
        "profitShareTwd": 0,
        "orderStatus": "…",
        "createdAt": "…"
      }
    ],
    "totalDiscountTwd": 0,
    "totalProfitShareTwd": 0,
    "totalPaidTwd": 0
  }
}
toko discount-codes preview

預覽試算折抵(唯讀,不消耗名額)

參數

--code <CODE>
旗標 · 必填

欲試算的折扣碼字串

--kind <tour|lodging>
旗標 · 必填

產品種類:tour 行程或 lodging 住宿

--trip-id <id>
旗標 · 選填

行程 id(kind=tour 時必填)

--total <twd>
旗標 · 必填

試算用原始金額(TWD,未折扣前)

--traveler-count <n>
旗標 · 選填

訂單旅客數(行程為旅客數、住宿為入住人數);設有最低人數門檻的碼未帶此值一律拒絕

--price-channel <c>
旗標 · 選填

價格渠道(direct / agency),用於折扣碼資格判定

--customer-type <t>
旗標 · 選填

客戶類型(direct / agency_contact),用於折扣碼資格判定

--user-id <id>
旗標 · 選填

客戶 user id,用於每客戶使用次數限制判定

--json
旗標 · 選填
範例
toko discount-codes preview --code 'example-code' --kind tour --total '1'
回應
{
  "ok": true,
  "data": null
}
toko discount-codes redemptions

折扣碼兌換 / 分潤報表

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

折扣碼 id(disc_ 前綴)。

code
string

折扣碼字串。

label
string

折扣碼顯示名稱。

redemptionCount
number

已兌換次數(不含已取消訂單)。

totalDiscountTwd
number

累計折抵金額合計(TWD 整數)。

totalProfitShareTwd
number

累計分潤金額合計(TWD 整數)。

totalPaidTwd
number

兌換訂單累計已收金額合計(TWD 整數)。

redemptions
object[]

逐筆兌換紀錄。

orderId
string

兌換該折扣碼的訂單 id(ord_ 前綴)。

orderNumber
string

訂單編號(人類可讀流水號)。

codeSnapshot
string

兌換當下的折扣碼字串快照。

originalTotalTwd
number

套用折扣前的原始應收總額(TWD 整數);跨行程換梯後為目標團費。

discountTwd
number

現行折抵金額(TWD 整數);跨行程換梯退出優惠後為 0。

profitShareTwd
number

現行分潤金額(TWD 整數);跨行程換梯退出優惠後為 0。

orderStatus
string

訂單當前狀態。

createdAt
string

兌換(下單)時間。

範例
toko discount-codes redemptions '<id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "code": "…",
    "label": "…",
    "redemptionCount": 0,
    "totalDiscountTwd": 0,
    "totalProfitShareTwd": 0,
    "totalPaidTwd": 0,
    "redemptions": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "codeSnapshot": "…",
        "originalTotalTwd": 0,
        "discountTwd": 0,
        "profitShareTwd": 0,
        "orderStatus": "…",
        "createdAt": "…"
      }
    ]
  }
}
toko discount-codes create

建立折扣碼

參數

--code <C>
旗標 · 必填

折扣碼字串(前台結帳輸入,不分大小寫須唯一)

--label <t>
旗標 · 必填

折扣碼顯示名稱(後台與報表辨識用)

--discount-type <fixed|percentage>
旗標 · 必填

折抵方式:fixed 固定金額(TWD)或 percentage 百分比

--discount-value <n>
旗標 · 必填

折抵數值;fixed 為折抵金額(TWD),percentage 為百分比(1–100)

--discount-basis <per_order|per_travelers|per_amount>
旗標 · 選填

計算方式:per_order 整張訂單折一次(預設)、per_travelers 每 N 位旅客折一次、per_amount 每滿 N 元(折前金額)折一次;後兩者只限 fixed,折扣 = discountValue × 倍數,總額不超過訂單金額

--discount-step <N>
旗標 · 選填

N:每幾位旅客或每滿幾元(TWD);per_order 時須為 null,其餘必填

--profit-share-type <t>
旗標 · 選填

分潤方式:fixed 固定金額或 percentage 百分比;null 為不分潤

--profit-share-value <n>
旗標 · 選填

分潤數值;搭配 profitShareType,percentage 須 1–100,null 為不分潤

--profit-share-payee <t>
旗標 · 選填

分潤對象名稱(如合作推廣者),供出款對帳辨識

--active <true|false>
旗標 · 選填
--valid-from <d>
旗標 · 選填

生效起日(YYYY-MM-DD);留空為不限起日

--valid-until <d>
旗標 · 選填

生效迄日(YYYY-MM-DD);留空為不限迄日

--max-redemptions <n>
旗標 · 選填

全碼可使用總次數上限;null 為不限

--min-order <n>
旗標 · 選填

最低訂單金額門檻(TWD),未達門檻不可套用;null 為不限

--min-traveler-count <n>
旗標 · 選填

最低旅客人數門檻(行程以旅客數、住宿以入住人數計),未達門檻不可套用;null 為不限

--applies-to-all <true|false>
旗標 · 選填

是否適用全部行程;true 時忽略 tripIds

--trip-ids <id,id>
旗標 · 選填

指定可套用的行程 id 清單(appliesToAll=false 時生效)

--max-per-customer <n>
旗標 · 選填
--price-channels <direct,agency>
旗標 · 選填
--customer-types <direct,agency_contact>
旗標 · 選填
--stackable <true|false>
旗標 · 選填

保留的旗標,結帳不讀:一張訂單只能套一個折扣碼

--notes <t>
旗標 · 選填

內部備註(不對外顯示)

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立折扣碼的 id(disc_ 前綴)。

範例
toko discount-codes create --code 'example-code' --label 'example-label' --discount-type fixed --discount-value '1'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko discount-codes update

更新折扣碼(送出完整欄位,未帶旗標的欄位沿用表單預設;計算方式例外,未帶時沿用現值)

參數

<id>位置參數 · 必填
--code <C>
旗標 · 必填

折扣碼字串(前台結帳輸入,不分大小寫須唯一)

--label <t>
旗標 · 必填

折扣碼顯示名稱(後台與報表辨識用)

--discount-type <fixed|percentage>
旗標 · 必填

折抵方式:fixed 固定金額(TWD)或 percentage 百分比

--discount-value <n>
旗標 · 必填

折抵數值;fixed 為折抵金額(TWD),percentage 為百分比(1–100)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko discount-codes update '<id>' --code 'example-code' --label 'example-label' --discount-type fixed --discount-value '1'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko discount-codes set-active

啟用 / 停用折扣碼

參數

<id>位置參數 · 必填
--active <true|false>
旗標 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko discount-codes set-active '<id>' --active true
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko discount-codes profit-shares-convert

執行 discount-codes/profit-shares/convert

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

payableId
string
payableNumber
string
範例
toko discount-codes profit-shares-convert --data '{"orderDiscountIds":["example-orderDiscountIds"],"payeeType":"staff_commission","payeeName":"example-payeeName"}'
回應
{
  "ok": true,
  "data": {
    "payableId": "…",
    "payableNumber": "…"
  }
}
toko discount-codes profit-shares-list

查詢 discount-codes/profit-shares

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

rows
object[]
orderDiscountId
string
orderId
string
orderNumber
string
codeSnapshot
string
profitShareTwd
number
payeeSnapshot
string | null
createdAt
string
summary
object[]
payeeSnapshot
string | null
pendingCount
number
pendingTwd
number
範例
toko discount-codes profit-shares-list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "orderDiscountId": "…",
        "orderId": "…",
        "orderNumber": "…",
        "codeSnapshot": "…",
        "profitShareTwd": 0,
        "payeeSnapshot": "…",
        "createdAt": "…"
      }
    ],
    "summary": [
      {
        "payeeSnapshot": "…",
        "pendingCount": 0,
        "pendingTwd": 0
      }
    ]
  }
}

toko group-codes

團號:碼表(地區/航空)與團號反查

toko group-codes regions

地區碼對照表

參數

--active-only
旗標 · 選填

傳 true 或 1 時只列出啟用中的地區碼

--json
旗標 · 選填

回應欄位 · data[]

code
string

地區代碼(團號組成,通常大寫縮寫,如 YS)。

name
string

地區名稱(如「玉山」)。

isActive
boolean

是否啟用(停用後不可再指派給新梯次)。

displayOrder
number

顯示排序(由小到大)。

usedCount
number

被多少梯次引用 —— UI 鎖頭 / 「使用中 N」。

範例
toko group-codes regions list
回應
{
  "ok": true,
  "data": [
    {
      "code": "…",
      "name": "…",
      "isActive": true,
      "displayOrder": 0,
      "usedCount": 0
    }
  ]
}
toko group-codes airlines

航空碼對照表

參數

--active-only
旗標 · 選填

傳 true 或 1 時只列出啟用中的航空碼

--json
旗標 · 選填

回應欄位 · data[]

code
string

航空公司代碼(團號組成,通常大寫縮寫,如 EG)。

name
string

航空公司名稱。

isActive
boolean

是否啟用(停用後不可再指派給新梯次)。

displayOrder
number

顯示排序(由小到大)。

usedCount
number

被多少梯次引用。

範例
toko group-codes airlines list
回應
{
  "ok": true,
  "data": [
    {
      "code": "…",
      "name": "…",
      "isActive": true,
      "displayOrder": 0,
      "usedCount": 0
    }
  ]
}
toko group-codes lookup

精確團號反查單一梯次

參數

<groupCode>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

梯次 id(dep_ 前綴)。

tripId
string

所屬行程 id(trip_ 前綴)。

tripTitle
string

所屬行程標題。

tripSlug
string

所屬行程網址 slug。

departureDate
string

出發日(ISO 'YYYY-MM-DD')。

groupCode
string

完整團號。

regionCode
string | null

地區代碼;null = 未設。

airlineCode
string | null

航空公司代碼;null = 國內團或未設。

範例
toko group-codes lookup '<groupCode>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "tripId": "…",
    "tripTitle": "…",
    "tripSlug": "…",
    "departureDate": "…",
    "groupCode": "…",
    "regionCode": "…",
    "airlineCode": "…"
  }
}
toko group-codes region-create

新增地區碼

參數

<code>位置參數 · 必填
--name <名>
旗標 · 必填

碼的顯示名稱(如地區或航空公司全名)

--order <n>
旗標 · 選填
--inactive
旗標 · 選填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

新增或更新的地區代碼。

範例
toko group-codes region-create '<code>' --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
toko group-codes region-update

更新地區碼(name / 啟用 / 排序,不改碼)

參數

<code>位置參數 · 必填
--name <名>
旗標 · 必填

碼的顯示名稱(如地區或航空公司全名)

--order <n>
旗標 · 選填
--inactive
旗標 · 選填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

新增或更新的地區代碼。

範例
toko group-codes region-update '<code>' --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
toko group-codes region-delete

刪除沒有梯次引用的地區碼(有引用的只能停用)

參數

<code>位置參數 · 必填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

刪除的地區碼。

範例
toko group-codes region-delete '<code>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
toko group-codes airline-create

新增航空碼

參數

<code>位置參數 · 必填
--name <名>
旗標 · 必填

碼的顯示名稱(如地區或航空公司全名)

--order <n>
旗標 · 選填
--inactive
旗標 · 選填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

新增或更新的航空公司代碼。

範例
toko group-codes airline-create '<code>' --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
toko group-codes airline-update

更新航空碼(name / 啟用 / 排序,不改碼)

參數

<code>位置參數 · 必填
--name <名>
旗標 · 必填

碼的顯示名稱(如地區或航空公司全名)

--order <n>
旗標 · 選填
--inactive
旗標 · 選填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

新增或更新的航空公司代碼。

範例
toko group-codes airline-update '<code>' --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
toko group-codes airline-delete

刪除沒有梯次引用的航空碼(有引用的只能停用)

參數

<code>位置參數 · 必填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

刪除的航空碼。

範例
toko group-codes airline-delete '<code>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}

toko holidays

國定假日 / 補班表:查詢、年度統計

toko holidays list

列出假日 / 補班(可依年度篩選)

參數

--year <2026>
旗標 · 選填

篩選的西元年份(1000..9999);省略則回傳所有年份

--json
旗標 · 選填

回應欄位 · data

rows
object[]

假日列(依日期排序)。

date
string

日期(ISO 'YYYY-MM-DD')。

name
string

名稱(如「國慶日」「補班」)。

isWorkday
boolean

是否為補班日(true = 該日照常上班,false = 放假)。

範例
toko holidays list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "date": "…",
        "name": "…",
        "isWorkday": true
      }
    ]
  }
}
toko holidays stats

某年度假日 / 補班計數

參數

--year <2026>
旗標 · 必填

要統計的西元年份(1000..9999,必填)

--json
旗標 · 選填

回應欄位 · data

holidayCount
number

該年度放假日數。

makeupCount
number

該年度補班日數。

範例
toko holidays stats --year '1000'
回應
{
  "ok": true,
  "data": {
    "holidayCount": 0,
    "makeupCount": 0
  }
}
toko holidays upsert

新增 / 覆寫一筆假日或補班(date 為自然鍵)

參數

--date <2026-10-10>
旗標 · 必填

假日 / 補班日的日期(YYYY-MM-DD,路徑參數),作為該筆紀錄的自然鍵

--name <國慶日>
旗標 · 必填

假日 / 補班日名稱(如「春節」「補行上班」)

--makeup
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko holidays upsert --date '2026-10-13' --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko holidays delete

刪除一筆假日 / 補班

參數

--date <2026-10-10>
旗標 · 必填

要刪除的假日 / 補班日日期(YYYY-MM-DD,路徑參數)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko holidays delete --date '2026-10-13'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko holidays batch

執行 holidays/batch

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

imported
number
範例
toko holidays batch --data '{"rows":[{"date":"2026-10-13","name":"example-name","isWorkday":true}]}'
回應
{
  "ok": true,
  "data": {
    "imported": 0
  }
}

toko images

圖片庫:查詢圖片、行程選單

toko images list

列出/搜尋行程圖片

參數

--trip-id <id>
旗標 · 選填

行程 ID 篩選,僅回傳掛在該行程的圖片

--q <text>
旗標 · 選填

關鍵字,模糊比對行程標題、slug、圖說或網址

--page <n>
旗標 · 選填

分頁頁碼,從 1 起算,預設第 1 頁

--page-size <n>
旗標 · 選填

每頁筆數,上限 200,預設由後端決定

--json
旗標 · 選填

回應欄位 · data

rows
object[]

當頁圖片列。

id
string

圖片資源 id(timg_ 前綴)。

tripId
string | null

所屬行程 id(trip_ 前綴);null = 未歸屬。

tripTitle
string | null

所屬行程標題;null = 未歸屬。

tripSlug
string | null

所屬行程網址 slug;null = 未歸屬。

url
string

圖片公開 URL。

caption
string | null

圖說文字;null = 無。

displayOrder
number

在行程相簿中的排序(由小到大)。

createdAt
string

上傳建立時間。

total
number

符合條件的總筆數(跨頁)。

page
number

目前頁碼(1 起算)。

pageSize
number

每頁筆數。

對應端點GET /api/v1/images
範例
toko images list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "…",
        "tripId": "…",
        "tripTitle": "…",
        "tripSlug": "…",
        "url": "…",
        "caption": "…",
        "displayOrder": 0,
        "createdAt": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}
toko images trips

可掛圖的行程選單(draft + published)

參數

--json
旗標 · 選填

回應欄位 · data[]

id
string

行程 id(trip_ 前綴)。

title
string

行程標題。

範例
toko images trips
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "title": "…"
    }
  ]
}
toko images create

掛圖到行程(以網址)

參數

--trip-id <id>
旗標 · 必填

要掛上此圖片的行程 ID

--url <https://…>
旗標 · 必填

圖片網址(http 或 https),以引用方式掛載,非檔案上傳

--caption <t>
旗標 · 選填

圖片說明文字,選填

--display-order <n>
旗標 · 選填

排序權重,數字越小越前面,預設 0

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立圖片的 id(timg_ 前綴)。

範例
toko images create --trip-id 'example-tripId' --url 'https://example.com'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko images upload

上傳本機圖片到圖庫(JPEG / PNG / WebP,上限 8MB)

參數

<file>位置參數 · 必填
--trip-id <id>
旗標 · 選填

要掛上此圖片的行程 ID,選填;不帶即為未歸屬圖片

--caption <t>
旗標 · 選填

圖片說明文字,選填

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立圖片的 id(timg_ 前綴)。

url
string

圖片網址,可直接填進輪播或封面欄位。

範例
toko images upload '<file>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "url": "…"
  }
}
toko images delete

刪除行程圖片

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko images delete '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko lodging

旅宿:物件、房型、可用量、訂房、統計

toko lodging properties

列出旅宿物件

參數

--json
旗標 · 選填

回應欄位 · data[]

id
object

住宿館 id(prop_ 前綴)。

length
number

Returns the length of a String object.

slug
string

網址 slug(公開站路徑,租戶內唯一)。

name
string

住宿館名稱。

kind
string

類型:hotel 旅館 / camp 營地。

isOverseas
boolean

是否為海外住宿。

location
string | null

地點描述;null = 未設。

description
string | null

簡介文字;null = 未設。

contentMdx
string | null

內文(MDX 原始碼);null = 未設。

facilities
unknown

設施清單(JSON);null = 未設。

coverImageUrl
string | null

封面圖 URL;null = 未設。

usageHint
string

用途:direct 散客直訂 / package 梯次配套 / both 兩者皆可 / internal 不販售(內部據點)。

checkInTime
string | null

入住時間文字(如「15:00」);null = 未設。

checkOutTime
string | null

退房時間文字(如「11:00」);null = 未設。

checkInInfo
string | null

入住須知;null = 未設。

houseRules
string | null

館內規範;null = 未設。

cancellationPolicy
string | null

取消政策;null = 未設。

addressRegion
string | null

地址:縣市/區域;null = 未設。

addressLocality
string | null

地址:鄉鎮/地區;null = 未設。

streetAddress
string | null

街道地址;null = 未設。

postalCode
string | null

郵遞區號;null = 未設。

latitude
number | null

緯度;null = 未設。

longitude
number | null

經度;null = 未設。

phone
string | null

聯絡電話;null = 未設。

petsAllowed
boolean | null

是否允許攜帶寵物;null = 未設。

smokingAllowed
boolean | null

是否允許吸菸;null = 未設。

pretripArrivalFrom
string | null

出發前夜可入住時段的起 'HH:MM';null = 不限。與 `pretripArrivalUntil` 同空同有。

pretripArrivalUntil
string | null

出發前夜可入住時段的迄 'HH:MM';null = 不限。

status
string

狀態:active 啟用 / inactive 停用。

seoTitle
string | null

SEO 標題覆寫;null = 沿用內容欄。

seoDescription
string | null

SEO 描述;null = 未設。

ogImageUrl
string | null

Open Graph 分享圖 URL;null = 未設。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko lodging properties
回應
{
  "ok": true,
  "data": [
    {
      "id": {
        "length": 0
      },
      "slug": "…",
      "name": "…",
      "kind": "…",
      "isOverseas": true,
      "location": "…",
      "description": "…",
      "contentMdx": "…",
      "facilities": "…",
      "coverImageUrl": "…",
      "usageHint": "…",
      "checkInTime": "…",
      "checkOutTime": "…",
      "checkInInfo": "…",
      "houseRules": "…",
      "cancellationPolicy": "…",
      "addressRegion": "…",
      "addressLocality": "…",
      "streetAddress": "…",
      "postalCode": "…",
      "latitude": 0,
      "longitude": 0,
      "phone": "…",
      "petsAllowed": true,
      "smokingAllowed": true,
      "pretripArrivalFrom": "…",
      "pretripArrivalUntil": "…",
      "status": "…",
      "seoTitle": "…",
      "seoDescription": "…",
      "ogImageUrl": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko lodging property

單一旅宿物件

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
object

住宿館 id(prop_ 前綴)。

length
number

Returns the length of a String object.

slug
string

網址 slug(公開站路徑,租戶內唯一)。

name
string

住宿館名稱。

kind
string

類型:hotel 旅館 / camp 營地。

isOverseas
boolean

是否為海外住宿。

location
string | null

地點描述;null = 未設。

description
string | null

簡介文字;null = 未設。

contentMdx
string | null

內文(MDX 原始碼);null = 未設。

facilities
unknown

設施清單(JSON);null = 未設。

coverImageUrl
string | null

封面圖 URL;null = 未設。

usageHint
string

用途:direct 散客直訂 / package 梯次配套 / both 兩者皆可 / internal 不販售(內部據點)。

checkInTime
string | null

入住時間文字(如「15:00」);null = 未設。

checkOutTime
string | null

退房時間文字(如「11:00」);null = 未設。

checkInInfo
string | null

入住須知;null = 未設。

houseRules
string | null

館內規範;null = 未設。

cancellationPolicy
string | null

取消政策;null = 未設。

addressRegion
string | null

地址:縣市/區域;null = 未設。

addressLocality
string | null

地址:鄉鎮/地區;null = 未設。

streetAddress
string | null

街道地址;null = 未設。

postalCode
string | null

郵遞區號;null = 未設。

latitude
number | null

緯度;null = 未設。

longitude
number | null

經度;null = 未設。

phone
string | null

聯絡電話;null = 未設。

petsAllowed
boolean | null

是否允許攜帶寵物;null = 未設。

smokingAllowed
boolean | null

是否允許吸菸;null = 未設。

pretripArrivalFrom
string | null

出發前夜可入住時段的起 'HH:MM';null = 不限。與 `pretripArrivalUntil` 同空同有。

pretripArrivalUntil
string | null

出發前夜可入住時段的迄 'HH:MM';null = 不限。

status
string

狀態:active 啟用 / inactive 停用。

seoTitle
string | null

SEO 標題覆寫;null = 沿用內容欄。

seoDescription
string | null

SEO 描述;null = 未設。

ogImageUrl
string | null

Open Graph 分享圖 URL;null = 未設。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko lodging property '<id>'
回應
{
  "ok": true,
  "data": {
    "id": {
      "length": 0
    },
    "slug": "…",
    "name": "…",
    "kind": "…",
    "isOverseas": true,
    "location": "…",
    "description": "…",
    "contentMdx": "…",
    "facilities": "…",
    "coverImageUrl": "…",
    "usageHint": "…",
    "checkInTime": "…",
    "checkOutTime": "…",
    "checkInInfo": "…",
    "houseRules": "…",
    "cancellationPolicy": "…",
    "addressRegion": "…",
    "addressLocality": "…",
    "streetAddress": "…",
    "postalCode": "…",
    "latitude": 0,
    "longitude": 0,
    "phone": "…",
    "petsAllowed": true,
    "smokingAllowed": true,
    "pretripArrivalFrom": "…",
    "pretripArrivalUntil": "…",
    "status": "…",
    "seoTitle": "…",
    "seoDescription": "…",
    "ogImageUrl": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko lodging room-types

列出某物件的房型

參數

--property <propertyId>
旗標 · 必填
--json
旗標 · 選填

回應欄位 · data[]

id
object

房型 id(rt_ 前綴)。

length
number

Returns the length of a String object.

propertyId
object

所屬住宿館 id(prop_ 前綴)。

length
number

Returns the length of a String object.

name
string

房型名稱。

inventoryUnit
string

庫存單位:room 以房計 / bed 以床位計。

unitsTotal
number

總庫存量(房間數或床位數)。

capacityPerUnit
number

每單位可住人數。

lowAvailabilityThreshold
number | null

低水位提示門檻;null = 不提示。

basePriceTwd
number

底價(TWD 整數,每晚每單位;可被逐晚覆寫)。

description
string | null

房型描述;null = 未設。

facilities
unknown

設施清單(JSON);null = 未設。

bedConfig
unknown

床型配置(JSON);null = 未設。

floorSizeSqm
number | null

房間坪數(平方公尺);null = 未設。

status
string

狀態:active 啟用 / inactive 停用。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko lodging room-types --property '<propertyId>'
回應
{
  "ok": true,
  "data": [
    {
      "id": {
        "length": 0
      },
      "propertyId": {
        "length": 0
      },
      "name": "…",
      "inventoryUnit": "…",
      "unitsTotal": 0,
      "capacityPerUnit": 0,
      "lowAvailabilityThreshold": 0,
      "basePriceTwd": 0,
      "description": "…",
      "facilities": "…",
      "bedConfig": "…",
      "floorSizeSqm": 0,
      "status": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko lodging room-type

單一房型

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
object

房型 id(rt_ 前綴)。

length
number

Returns the length of a String object.

propertyId
object

所屬住宿館 id(prop_ 前綴)。

length
number

Returns the length of a String object.

name
string

房型名稱。

inventoryUnit
string

庫存單位:room 以房計 / bed 以床位計。

unitsTotal
number

總庫存量(房間數或床位數)。

capacityPerUnit
number

每單位可住人數。

lowAvailabilityThreshold
number | null

低水位提示門檻;null = 不提示。

basePriceTwd
number

底價(TWD 整數,每晚每單位;可被逐晚覆寫)。

description
string | null

房型描述;null = 未設。

facilities
unknown

設施清單(JSON);null = 未設。

bedConfig
unknown

床型配置(JSON);null = 未設。

floorSizeSqm
number | null

房間坪數(平方公尺);null = 未設。

status
string

狀態:active 啟用 / inactive 停用。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko lodging room-type '<id>'
回應
{
  "ok": true,
  "data": {
    "id": {
      "length": 0
    },
    "propertyId": {
      "length": 0
    },
    "name": "…",
    "inventoryUnit": "…",
    "unitsTotal": 0,
    "capacityPerUnit": 0,
    "lowAvailabilityThreshold": 0,
    "basePriceTwd": 0,
    "description": "…",
    "facilities": "…",
    "bedConfig": "…",
    "floorSizeSqm": 0,
    "status": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko lodging availability

房型逐夜可用量+價格 [check-in, check-out)

參數

--room-type <id>
旗標 · 必填
--check-in <date>
旗標 · 必填

入住日(YYYY-MM-DD,含此晚)

--check-out <date>
旗標 · 必填

退房日(YYYY-MM-DD,不含此晚,區間最多 60 晚)

--json
旗標 · 選填

回應欄位 · data

available
number

整段住宿期間可訂房間數(各晚剩餘取最小;任一晚關閉則為 0)。

nights
number

住宿晚數。

totalPriceTwd
number

整段期間房價合計(TWD 整數,逐晚牌價加總)。

perNight
object[]

逐晚可售明細。

night
string

該晚日期(ISO 'YYYY-MM-DD')。

capacity
number

該晚可售容量(房間數;有覆寫則用覆寫值,否則房型總數)。

booked
number

該晚已訂數。

remaining
number

該晚剩餘可訂數(capacity − booked,不小於 0)。

priceTwd
number

該晚房價(TWD 整數;有逐晚覆寫則用覆寫值,否則房型底價)。

status
string

該晚販售狀態:open 開放 / closed 關閉。

範例
toko lodging availability --room-type '<id>' --check-in 'example-checkIn' --check-out 'example-checkOut'
回應
{
  "ok": true,
  "data": {
    "available": 0,
    "nights": 0,
    "totalPriceTwd": 0,
    "perNight": [
      {
        "night": "…",
        "capacity": 0,
        "booked": 0,
        "remaining": 0,
        "priceTwd": 0,
        "status": "…"
      }
    ]
  }
}
toko lodging breakdown

逐夜已訂量(直訂 / 套裝 / 集合夜)[from, to)

參數

--room-type <id>
旗標 · 必填
--from <date>
旗標 · 必填

起始日(YYYY-MM-DD,含此晚)

--to <date>
旗標 · 必填

結束日(YYYY-MM-DD,不含此晚)

--json
旗標 · 選填

回應欄位 · data[]

night
string

該晚日期(ISO 'YYYY-MM-DD')。

directBooked
number

該晚散客直訂的已訂數。

packageBooked
number

該晚梯次配套佔用的已訂數。

pretripBooked
number

該晚出發前夜住宿(非販售佔用)的已訂數。

範例
toko lodging breakdown --room-type '<id>' --from 'example-from' --to 'example-to'
回應
{
  "ok": true,
  "data": [
    {
      "night": "…",
      "directBooked": 0,
      "packageBooked": 0,
      "pretripBooked": 0
    }
  ]
}
toko lodging images

列出物件或房型的圖片

參數

--property <id>
旗標 · 選填
--room-type <id>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string

圖片資源 id(pimg_ / rtimg_ 前綴)。

url
string

圖片公開 URL。

caption
string | null

圖說文字;null = 無。

displayOrder
number

相簿中的排序(由小到大)。

範例
toko lodging images --property '<id>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "url": "…",
      "caption": "…",
      "displayOrder": 0
    }
  ]
}
toko lodging bookings

列出旅宿訂房(代訂)

參數

--q <text>
旗標 · 選填

自由文字關鍵字(訂房人、旅宿等)

--status <s>
旗標 · 選填

依顯示狀態篩選(省略則回全部):pending_payment / paid / completed / cancelled / refunded。與列表 badge 同口徑——取消、退款、完成的優先序高於付款軸,所以取消或退款過的單不會出現在付款類的值裡

--json
旗標 · 選填

回應欄位 · data[]

orderId
string

訂單 id(ord_ 前綴)。

orderNumber
string

訂單編號(人類可讀流水號)。

status
string

顯示狀態(派生自三軸,沿用舊欄名供 UI badge / canCancel 相容)。

bookingState
string

訂位軸狀態(如 confirmed / cancelled)。

paymentState
string

付款軸狀態(如 unpaid / partial / paid)。

refundState
string

退款軸狀態。

totalTwd
number

應收總額(TWD 整數,訂單各應收明細加總)。

createdAt
string

訂單建立時間。

bookerName
string

訂購人姓名。

bookerEmail
string

訂購人 email。

propertyId
string

住宿館 id(prop_ 前綴)。

propertyName
string

住宿館名稱。

roomTypeId
string

房型 id(rt_ 前綴)。

roomTypeName
string

房型名稱。

checkIn
string

入住日(ISO 'YYYY-MM-DD')。

checkOut
string

退房日(ISO 'YYYY-MM-DD')。

units
number

訂購房間數。

guestCount
number

入住總人數。

範例
toko lodging bookings
回應
{
  "ok": true,
  "data": [
    {
      "orderId": "…",
      "orderNumber": "…",
      "status": "…",
      "bookingState": "…",
      "paymentState": "…",
      "refundState": "…",
      "totalTwd": 0,
      "createdAt": "…",
      "bookerName": "…",
      "bookerEmail": "…",
      "propertyId": "…",
      "propertyName": "…",
      "roomTypeId": "…",
      "roomTypeName": "…",
      "checkIn": "…",
      "checkOut": "…",
      "units": 0,
      "guestCount": 0
    }
  ]
}
toko lodging booking

單一旅宿訂房明細

參數

<orderId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

orderId
string

訂單 id(ord_ 前綴)。

orderNumber
string

訂單編號(人類可讀流水號)。

status
string

顯示狀態(派生自三軸,沿用舊欄名供 UI badge / canCancel 相容)。

bookingState
string

訂位軸狀態(如 confirmed / cancelled)。

paymentState
string

付款軸狀態(如 unpaid / partial / paid)。

refundState
string

退款軸狀態。

totalTwd
number

應收總額(TWD 整數,訂單各應收明細加總)。

createdAt
string

訂單建立時間。

bookerName
string

訂購人姓名。

bookerEmail
string

訂購人 email。

propertyId
string

住宿館 id(prop_ 前綴)。

propertyName
string

住宿館名稱。

roomTypeId
string

房型 id(rt_ 前綴)。

roomTypeName
string

房型名稱。

checkIn
string

入住日(ISO 'YYYY-MM-DD')。

checkOut
string

退房日(ISO 'YYYY-MM-DD')。

units
number

訂購房間數。

guestCount
number

入住總人數。

範例
toko lodging booking '<orderId>'
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "orderNumber": "…",
    "status": "…",
    "bookingState": "…",
    "paymentState": "…",
    "refundState": "…",
    "totalTwd": 0,
    "createdAt": "…",
    "bookerName": "…",
    "bookerEmail": "…",
    "propertyId": "…",
    "propertyName": "…",
    "roomTypeId": "…",
    "roomTypeName": "…",
    "checkIn": "…",
    "checkOut": "…",
    "units": 0,
    "guestCount": 0
  }
}
toko lodging stats

旅宿 KPI 統計

參數

--json
旗標 · 選填

回應欄位 · data

tonightCheckInUnits
number

今晚入住房間數(Asia/Taipei)。

tonightCheckInGuests
number

今晚入住總人數(Asia/Taipei)。

weekOccupancyPct
number

未來 7 晚住房率(已訂 / 可售,0–100)。

next7AvailableUnits
number

未來 7 晚仍可售的房晚數。

pendingPaymentCount
number

待收款訂單筆數。

pendingPaymentTwd
number

待收款金額合計(TWD 整數)。

範例
toko lodging stats
回應
{
  "ok": true,
  "data": {
    "tonightCheckInUnits": 0,
    "tonightCheckInGuests": 0,
    "weekOccupancyPct": 0,
    "next7AvailableUnits": 0,
    "pendingPaymentCount": 0,
    "pendingPaymentTwd": 0
  }
}
toko lodging property-create

新增旅宿物件(--slug 只有 --usage-hint internal 可省,省略時由名稱產生)

參數

--name <n>
旗標 · 必填

旅宿名稱(對外顯示)

--slug <s>
旗標 · 必填

旅宿代稱(英數與連字號 2-63 字,租戶內唯一,用於網址;大寫自動轉小寫。只有 usageHint=internal 的內部據點可省略,省略時由名稱產生)

--kind <hotel|camp>
旗標 · 選填

旅宿類型:camp 營地/hotel 旅館,預設 hotel

--overseas
旗標 · 選填
--location <l>
旗標 · 選填

所在地點概述(如縣市、區域)

--description <d>
旗標 · 選填

旅宿介紹文字

--usage-hint <direct|package|both|internal>
旗標 · 選填

銷售用途:direct 僅直接訂房/package 僅併入套裝行程/both 兩者皆可/internal 不販售(內部據點,退出所有對客與販售路徑),預設 both

--cover-image-url <u>
旗標 · 選填

封面圖網址(http/https 或本站圖庫資產路徑),用於公開旅宿頁與列表卡片

--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

id
string

新建立住宿館的 id(prop_ 前綴)。

slug
string

實際寫入的網址 slug(留空時由名稱產生,撞名會加尾碼)。

範例
toko lodging property-create --name 'example-name' --slug 'example-slug'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…"
  }
}
toko lodging property-update

更新旅宿物件(patch 語意;只送有帶的欄位。--slug 只有內部據點改得動)

參數

<id>位置參數 · 必填
--name <n>
旗標 · 選填

旅宿名稱(對外顯示)

--slug <s>
旗標 · 選填

旅宿代稱(大寫自動轉小寫)。只有 usageHint=internal 的內部據點改得動,其餘已有公開頁、建立後不可修改

--location <l>
旗標 · 選填

所在地點概述(如縣市、區域)

--description <d>
旗標 · 選填

旅宿介紹文字

--usage-hint <h>
旗標 · 選填

銷售用途:direct 僅直接訂房/package 僅併入套裝行程/both 兩者皆可/internal 不販售(內部據點,退出所有對客與販售路徑)

--facilities <a,b>
旗標 · 選填

設施代碼陣列(須為合法 amenity key;送空陣列代表清空)

--pets <allow|disallow|unset>
旗標 · 選填

是否允許攜帶寵物:allow 允許/disallow 不允許/unset 清除設定,省略則不變更

--smoking <allow|disallow|unset>
旗標 · 選填

是否允許吸菸:allow 允許/disallow 不允許/unset 清除設定,省略則不變更

--seo-title <t>
旗標 · 選填

SEO 標題(送空字串代表清空,退回預設)

--seo-description <d>
旗標 · 選填

SEO 描述(送空字串代表清空,退回預設)

--og-image-url <u>
旗標 · 選填

社群分享圖 URL(http/https 或本站圖庫資產路徑,送空字串代表清空)

--cover-image-url <u>
旗標 · 選填

封面圖網址(http/https 或本站圖庫資產路徑),用於公開旅宿頁與列表卡片;傳 null 或空字串清除

--phone <p>
旗標 · 選填

聯絡電話

--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko lodging property-update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko lodging property-archive

封存旅宿物件(status→inactive)

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko lodging property-archive '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko lodging room-type-create

新增房型

參數

--property <id>
旗標 · 必填
--name <n>
旗標 · 必填

房型名稱(如標準雙人房)

--units-total <n>
旗標 · 必填

此房型可售總單元數(房數或床位數)

--base-price <twd>
旗標 · 必填

每晚每單元基準售價(新台幣)

--inventory-unit <room|bed>
旗標 · 選填

庫存單位:room 以房計/bed 以床位計,預設 room

--capacity-per-unit <n>
旗標 · 選填

每單元可容納人數,預設 1

--bed-type <t>
旗標 · 選填

床型代碼(須為合法 bed type,搭配 bedCount 才生效)

--bed-count <n>
旗標 · 選填

該床型數量(須大於 0 才生效)

--floor-size <sqm>
旗標 · 選填

房間坪數(平方公尺)

--facilities <a,b>
旗標 · 選填

房型設施代碼陣列(須為合法 amenity key)

--description <d>
旗標 · 選填

房型介紹文字

--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

id
string

新建立房型的 id(rt_ 前綴)。

範例
toko lodging room-type-create --property '<id>' --name 'example-name' --units-total '1' --base-price '1'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko lodging room-type-update

更新房型(patch;送 --facilities= 空字串可清空)

參數

<id>位置參數 · 必填
--name <n>
旗標 · 選填

房型名稱(如標準雙人房)

--units-total <n>
旗標 · 選填

此房型可售總單元數(房數或床位數)

--base-price <twd>
旗標 · 選填

每晚每單元基準售價(新台幣)

--inventory-unit <u>
旗標 · 選填

庫存單位:room 以房計/bed 以床位計

--capacity-per-unit <n>
旗標 · 選填

每單元可容納人數

--bed-type <t>
旗標 · 選填

床型代碼(須為合法 bed type,搭配 bedCount 才生效)

--bed-count <n>
旗標 · 選填

該床型數量(須大於 0 才生效)

--floor-size <sqm>
旗標 · 選填

房間坪數(平方公尺)

--facilities <a,b>
旗標 · 選填

房型設施代碼陣列(須為合法 amenity key;送空陣列代表清空)

--description <d>
旗標 · 選填

房型介紹文字

--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko lodging room-type-update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko lodging room-type-archive

封存房型(status→inactive)

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko lodging room-type-archive '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko lodging nights-override

批次覆寫房型一段區間每晚的價/容量/封房 [from, to](inclusive)

參數

--room-type <id>
旗標 · 必填
--from <date>
旗標 · 必填

套用起始日(YYYY-MM-DD,含此日)

--to <date>
旗標 · 必填

套用結束日(YYYY-MM-DD,含此日;須不早於起始日,且區間最長 366 天)

--price <twd>
旗標 · 選填

覆寫的每晚售價(新台幣),省略則不調整價格

--capacity <n>
旗標 · 選填

覆寫的每晚可售單元數,若低於已訂數量會回 409 衝突

--status <open|closed>
旗標 · 選填

每晚開關房狀態:open 開放/closed 封房

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko lodging nights-override --room-type '<id>' --from '2026-10-13' --to '2026-10-13'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko lodging booking-cancel

取消旅宿訂房(釋回保留夜;owner-scope)

參數

<orderId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko lodging booking-cancel '<orderId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko lodging book

代客建立旅宿訂房(訂房人須為既有會員)

參數

--property <id>
旗標 · 必填

旅宿物件 ID

--room-type <id>
旗標 · 必填

房型 ID(須屬於該旅宿物件)

--check-in <date>
旗標 · 必填

入住日(YYYY-MM-DD,含此晚)

--check-out <date>
旗標 · 必填

退房日(YYYY-MM-DD,不含此晚,須晚於入住日)

--units <n>
旗標 · 必填

預訂單元數(房數或床位數,1-50)

--guests <n>
旗標 · 必填
--email <e>
旗標 · 必填
--payment-method <cash|atm|manual>
旗標 · 必填

付款方式:cash 現金/atm 轉帳/manual 其他人工

--receiving-account <id>
旗標 · 選填

收款帳戶 ID(搭配付款方式記帳,可省略)

--notes <t>
旗標 · 選填

代訂備註

--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

orderId
string

新建立住宿訂單的 id(ord_ 前綴)。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;建單與入帳本身已完成。

範例
toko lodging book --property 'example-propertyId' --room-type 'example-roomTypeId' --check-in 'example-checkIn' --check-out 'example-checkOut' --units '1' --guests '1' --email '<e>' --payment-method cash
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "retentionDeferred": true
  }
}
toko lodging image-add

新增物件或房型圖片

參數

--property <id>
旗標 · 選填
--room-type <id>
旗標 · 選填
--url <u>
旗標 · 必填

圖片網址

--caption <c>
旗標 · 選填

圖片說明文字(可省略)

--order <n>
旗標 · 選填
--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

id
string

新建立住宿館圖片的 id(pimg_ 前綴)。

範例
toko lodging image-add --property '<id>' --url 'example-url'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko lodging image-delete

刪除物件或房型圖片

參數

<imageId>位置參數 · 必填
--property
旗標 · 選填
--room-type
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko lodging image-delete '<imageId>' --property
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko trips

行程:查詢、明細、團號梯次、成本範本

toko trips list

列出/搜尋行程

參數

--status <all|published|draft|archived>
旗標 · 選填

依行程狀態篩選(draft 草稿/published 上架/archived 封存)

--q <text>
旗標 · 選填

自由文字搜尋(行程標題/代稱/目的地)

--group-code <prefix>
旗標 · 選填

依團號篩選,列出含該團號梯次的行程

--json
旗標 · 選填

回應欄位 · data[]

adminPinnedAt選填
string | undefined | null

全公司共用的後台釘選時間。

id
string

行程 id(trip_ 前綴)。

slug
string

行程網址 slug。

title
string

行程標題。

destination
string

目的地名稱。

durationDays
number

天數。

guideStartDay選填
number | null | undefined
guideEndDay選填
number | null | undefined
priceFromTwd
number

「NT$ X 起」起價(TWD 整數)。

status
"archived" | "draft" | "published"

上架狀態:draft 草稿 / published 已上架 / archived 封存。

isHidden
boolean

不對外顯示(#1435)。

isLinkOnly
boolean

僅限連結:不進任何列表,行程頁不給搜尋引擎收錄,拿到網址可報名。與 `isHidden` 互斥。

foreignTravelersOnly
boolean

限外籍旅客(issue 1519)。

updatedAt
string

最後更新時間。

isClimbing
boolean

是否登山團(行程層模組旗標)。

isOverseas
boolean

是否海外團(行程層模組旗標)。

hasPreTripNight
boolean

是否有行前集合夜(trips.md §3)。

activeDepartureCount
number

Count of departures with status='selling'.

nextDepartureDate
string | null

Earliest selling departure_date, ISO date string, or null.

representativeGroupCode
string | null

代表團號(group-code §8.2):最新一筆有團號的梯次;無則 null(UI 顯示 —)。

對應端點GET /api/v1/trips
範例
toko trips list
回應
{
  "ok": true,
  "data": [
    {
      "adminPinnedAt": "…",
      "id": "…",
      "slug": "…",
      "title": "…",
      "destination": "…",
      "durationDays": 0,
      "guideStartDay": 0,
      "guideEndDay": 0,
      "priceFromTwd": 0,
      "status": "archived",
      "isHidden": true,
      "isLinkOnly": true,
      "foreignTravelersOnly": true,
      "updatedAt": "…",
      "isClimbing": true,
      "isOverseas": true,
      "hasPreTripNight": true,
      "activeDepartureCount": 0,
      "nextDepartureDate": "…",
      "representativeGroupCode": "…"
    }
  ]
}
toko trips get

單一行程完整明細

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
object

行程 id(trip_ 前綴)。

length
number

Returns the length of a String object.

slug
string

行程網址 slug(公開站路徑)。

title
string

行程標題。

shortName選填
string | null | undefined

內部簡稱(issue 1414);null = 未填。只有後台讀取帶,前台投影不帶。

summary
string | null

一句話摘要;null = 未設。

contentMdx
string | null

行程內文(MDX 原始碼);null = 未設。

lotteryNoticeMdx選填
string | null | undefined
destination
string

目的地名稱。

durationDays
number

天數。

balanceDueDaysBeforeDeparture選填
number | null | undefined

尾款於出發前幾天;null = 未設(出發當天)。前台顯示尾款期限用(trip-pricing §3.1)。

guideStartDay選填
number | null | undefined
guideEndDay選填
number | null | undefined
priceFromTwd
number

「NT$ X 起」起價(TWD 整數)。

coverImageUrl
string | null

封面圖 URL;null = 未設。

status
"archived" | "draft" | "published"

上架狀態:draft 草稿 / published 已上架 / archived 封存。

isHidden
boolean

不對外顯示(#1435):官網看不到、網址 404,後台照常可用。

isLinkOnly
boolean

僅限連結(issue 1351):不進任何列表,行程頁 noindex、不出 JSON-LD,拿到網址可報名。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

isClimbing
boolean

是否登山團(行程層模組旗標)。

isOverseas
boolean

是否海外團(行程層模組旗標)。

equipmentRentalEnabled
boolean

可租借裝備(equipment-inventory §3.1):與登山團旗標疊加,梯次不得覆寫。

hasPreTripNight
boolean

是否有行前集合夜(trips.md §3)。集合日恆為 `departure_date − 1`,不落欄。

meetingDay
number

第幾天集合(issue 1474):1 = 出發日。有行前集合夜時恆為 1。

minGroupSize
number | null

最低成團人數(旅遊契約第 10 條揭露用);null = 不設門檻。

pretripStayRoomTypeId
string | null

出發前夜住宿據點的床位池(ADR 0022 / 0029);null = 不住公司據點。出團不得覆寫。

pretripStayExternalArranged
boolean

出發前夜住宿由公司安排外部住宿(民宿等);效力同旅客自理,僅顯示語意(#431)。

gradeScore
number | null

難度評鑑分數(climbing-screening §3.1);null = 未評級。

difficultyLevel
number | null
tags
string[]
requiresAlpineExperience
boolean

是否要求具備高山經驗(報名審核用)。

isHighAltitude
boolean

行程本身屬高海拔(#2018):結團寫入的登山紀錄依此認列高山經驗。

screeningExempt
boolean

入門免審:不做分數審核,高山經驗硬閘照判。

gradeLabel
string | null

難度標籤(如「B+」);null = 未設。

waitlistEnabled
boolean

候補開關(席滿後仍收候補,lottery-integration §3.5)。

defaultAllocationMode
"fcfs" | "lottery"

預設分配模式(lottery-integration §2.1):新增梯次時 copy-on-create,梯次可覆寫。

lotteryLeadDays選填
number | null | undefined

抽籤日在出發日前幾天(issue 1095);null = 未設。梯次可覆寫;admin-only。

lotteryDrawTime選填
string | null | undefined

抽籤時刻預設(`HH:MM`,issue 1656);null = 未設。梯次可覆寫;admin-only。

lotteryDrawDayOffset選填
number | undefined

抽籤時刻落在哪一天(issue 2041):0 = 抽籤日當天,-1 = 前一天。梯次可覆寫;admin-only。

agreementChangeBufferDays選填
number | null | undefined

抽籤梯次緩衝天數的行程覆寫(issue 1178);null = 沿用公司設定;admin-only。

agreementTravelForm選填
TourAgreementTravelForm | null | undefined

本行程契約的旅遊型態(issue 1178);null = 沿用公司設定;admin-only。

agreementExempt選填
boolean | undefined

此行程不需旅遊契約(issue 1524)。

foreignTravelersOnly
boolean

限外籍旅客(issue 1519):本國旅客不能報名。行程頁對客揭露,所以公開投影也帶。

travelersPerGuide選填
number | null | undefined

每幾位旅客配一位隨團人員(issue 1117);null = 不自動算;admin-only。

defaultGuideCount選填
number | null | undefined

預設需要幾位嚮導(#1377);建梯次沒指定時帶入,0 = 不需嚮導;null = 沒設;admin-only。

defaultCapacity
number | null

新增梯次的預設席次(trips.md §2.1);null = 沒設,表單用固定預設。

meetingTime
string | null

集合時間的行程層預設(HH:mm,台北牆鐘;departure-prep §2.4.1);null = 未設。梯次未填時繼承。

meetingPlace
string | null

集合地點的行程層預設;null = 未設。梯次未填時繼承。

pretripBriefingUrl選填
string | null | undefined

行前說明網址(issue 1618);null = 未填。所有梯次共用;admin-only。

paymentReceivedBody選填
string | null | undefined

收款後通知內文(issue 1743);null = 未填,用範本內文。所有梯次共用;admin-only。

salesCloseDaysBefore
number | null

停止售票預設:出發前 N 天 00:00(trips.md §2.2);null = 行程層不設。

feeInclusions
{ ok: boolean; text: string; }[] | null

團費包含/不包含(前台費用區唯一來源);null = 未設。

notices
string[]

注意事項(前台行程頁顯示);空陣列 = 未設。

suggestedFlights
{ updated: string; ticket: "不含" | "可代訂" | "含"; plans: { name: string; primary: boolean; mode: "flight" | "station"; meetDay: number; meetTime: string; meetPlace: string; flights: { dir: "out" | "ret" | "dom"; ... 6 more ...; arr: string; }[]; airports: string[]; route: string; duration: string; arriveDayBefore: bool...

建議航班(前台航班卡片);null = 未設。

updated
string
ticket
"不含" | "可代訂" | "含"
plans
object[]
name
string
primary
boolean
mode
"flight" | "station"
meetDay
number
meetTime
string
meetPlace
string
flights
object[]
dir
"dom" | "out" | "ret"
flight
string
from
string
to
string
depDay
number
dep
string
arrDay
number
arr
string
airports
string[]
route
string
duration
string
arriveDayBefore
boolean
extraAirlines
object
extraAirports
object
cancellationFeeTiers
CancellationFeeTier[] | null

逐行程退改費階梯覆寫(customer-cancellation §3);**null = 未覆寫**(用租戶預設), `[]` = 本行程不收退改費。兩者語意不同,不可折疊。

manualCancellationRefund
boolean
seoTitle
string | null

SEO 標題覆寫;null = 沿用 title。

seoDescription
string | null

SEO 描述;null = 未設。

ogImageUrl
string | null

Open Graph 分享圖 URL;null = 未設。

images
object[]

行程相簿圖片(依 displayOrder 排序)。

id
string

圖片資源 id(timg_ 前綴)。

url
string

圖片公開 URL。

caption
string | null

圖說文字;null = 無。

displayOrder
number

在行程相簿中的排序(由小到大)。

departures
object[]

Active (selling, future) departures only on the public side; all on admin.

id
string

梯次 id(dep_ 前綴)。

tripId
string

所屬行程 id(trip_ 前綴)。

departureDate
string

出發日(ISO 'YYYY-MM-DD')。

returnDate
string

回程日(ISO 'YYYY-MM-DD')。

priceTwd
number

售價(TWD 整數,未稅牌價)。

capacity
number

名額上限(人數)。

bookedCount
number

已成團佔用名額(人數)。

status
"cancelled" | "closed" | "completed" | "selling"

梯次狀態:selling 販售中 / closed 關閉 / cancelled 取消 / completed 已結團。

notes
string | null

內部備註;null = 無。

allocationMode
"fcfs" | "lottery"

抽籤分配模式(lottery-integration §2.1):fcfs=先到先得 / lottery=抽籤制。

label選填
string | null | undefined

梯次標籤 / 副標(例:「包」「包1」);null = 無;admin-only,公開站不映射。

isPrivate選填
boolean | undefined

不對外販售(前台不顯示、不可自助報名;後台可建單);admin-only,公開站不映射。

agencyPriceTwd選填
number | null | undefined

同業價(TWD 整數);admin-only,公開站不映射。

depositMode選填
DepositMode | null | undefined

訂金規則模式:none 免訂金 / fixed 定額 / percent 比例;admin-only。

depositAmountTwd選填
number | null | undefined

訂金定額(TWD 整數,depositMode=fixed 時適用);admin-only。

depositPercent選填
number | null | undefined

訂金比例(百分比,depositMode=percent 時適用);admin-only。

groupCode選填
string | null | undefined

團號(group-code §3.3);admin-only,公開站不映射。

regionCode選填
string | null | undefined

地區代碼(團號組成);admin-only。

airlineCode選填
string | null | undefined

航空公司代碼(團號組成);admin-only。

promoActive選填
boolean | undefined

梯次促銷是否啟用(trip-pricing);admin-only。

promoPriceTwd選填
number | null | undefined

促銷覆寫售價(TWD 整數);admin-only。

promoAgencyPriceTwd選填
number | null | undefined

促銷覆寫同業價(TWD 整數);admin-only。

salesCloseAt選填
string | undefined | null

逐梯停止售票時間(trips.md §2.2);null = 繼承行程層;admin-only。

effectiveSalesCloseAt選填
string | undefined | null

有效停止售票時間:逐梯值,否則行程層「出發前 N 天 00:00」派生;兩者皆無為 null。 排程到點把 selling → closed 就是看這個值;admin-only。

salesAutoClosedAt選填
string | undefined | null

排程自動關閉的時間;null = 人工關或未關。與 status='closed' 合看;admin-only。

salesClosePassed選填
boolean | undefined

有效停止售票時間是否已到(DB 的 NOW() 判,與排程同一個時鐘);admin-only。

salesOpenAt選填
string | undefined | null

開賣時間(trips.md §2.2a);null = 沒有排程;admin-only。

salesOpenFailedReason選填
string | null | undefined

到點開賣被擋下的原因;null = 沒有失敗;admin-only。

meetingTime選填
string | null | undefined

第 4 條集合時間(牆鐘字串);admin-only。

meetingPlace選填
string | null | undefined

第 4 條集合地點;admin-only。

agreementChangeDays選填
number | null | undefined

可變更第三人期限天數的逐梯覆寫;null = 退回租戶預設(團體契約的抽籤梯次必填);admin-only。

entryDateOffsetDays選填
number | undefined

實際入園日相對出發日的偏移天數(departure-prep §2.6.1);admin-only。

lotteryLeadDays選填
number | null | undefined

抽籤前幾天的逐梯覆寫(issue 1095);null = 繼承行程層;admin-only。

lotteryDrawTime選填
string | null | undefined

抽籤時刻的逐梯覆寫(`HH:MM`,issue 1656);null = 繼承行程層;admin-only。

lotteryDrawDayOffset選填
number | null | undefined

抽籤時刻落在哪一天的逐梯覆寫(issue 2041):0 = 抽籤日當天,-1 = 前一天;null = 繼承行程層; admin-only。

lotteryChangeDays選填
number | null | undefined

抽籤梯次的自動可變更第三人期限(出發前幾天,issue 1178):抽籤前幾天+緩衝天數,或公司抽籤 日期來源推回的天數;算不出來是 null。不看逐梯手填值與分配模式;admin-only。

lotteryDrawDate選填
string | null | undefined

抽籤日(`YYYY-MM-DD`,`lotteryDrawDateSql`,issue 1656);沒有抽籤日為 null。不看分配模式;admin-only。

effectiveLotteryDrawTime選填
string | null | undefined

生效的抽籤時刻(`HH:MM`,`lotteryDrawTimeSql`:時程表時段開始 → 梯次覆寫 → 行程預設); 未設為 null,前台在抽籤日 00:00 截止;admin-only。

lotteryDrawAtDate選填
string | null | undefined

生效抽籤時刻所在的日期(`YYYY-MM-DD`,`lotteryDrawAtDateSql`,issue 2041):抽籤日加日偏移。 時程表時段優先或沒有抽籤時刻時等於 `lotteryDrawDate`;admin-only。

lotteryApplicationClosed選填
boolean | undefined

抽籤梯次已截止申請(前台不收單,issue 1656);admin-only。

requiredGuideCount選填
number | null | undefined

需要的隨團人員數(issue 1117);null = 未填;admin-only。

範例
toko trips get '<id>'
回應
{
  "ok": true,
  "data": {
    "id": {
      "length": 0
    },
    "slug": "…",
    "title": "…",
    "shortName": "…",
    "summary": "…",
    "contentMdx": "…",
    "lotteryNoticeMdx": "…",
    "destination": "…",
    "durationDays": 0,
    "balanceDueDaysBeforeDeparture": 0,
    "guideStartDay": 0,
    "guideEndDay": 0,
    "priceFromTwd": 0,
    "coverImageUrl": "…",
    "status": "archived",
    "isHidden": true,
    "isLinkOnly": true,
    "createdAt": "…",
    "updatedAt": "…",
    "isClimbing": true,
    "isOverseas": true,
    "equipmentRentalEnabled": true,
    "hasPreTripNight": true,
    "meetingDay": 0,
    "minGroupSize": 0,
    "pretripStayRoomTypeId": "…",
    "pretripStayExternalArranged": true,
    "gradeScore": 0,
    "difficultyLevel": 0,
    "tags": [
      "…"
    ],
    "requiresAlpineExperience": true,
    "isHighAltitude": true,
    "screeningExempt": true,
    "gradeLabel": "…",
    "waitlistEnabled": true,
    "defaultAllocationMode": "fcfs",
    "lotteryLeadDays": 0,
    "lotteryDrawTime": "…",
    "lotteryDrawDayOffset": 0,
    "agreementChangeBufferDays": 0,
    "agreementTravelForm": null,
    "agreementExempt": true,
    "foreignTravelersOnly": true,
    "travelersPerGuide": 0,
    "defaultGuideCount": 0,
    "defaultCapacity": 0,
    "meetingTime": "…",
    "meetingPlace": "…",
    "pretripBriefingUrl": "…",
    "paymentReceivedBody": "…",
    "salesCloseDaysBefore": 0,
    "feeInclusions": "…",
    "notices": [
      "…"
    ],
    "suggestedFlights": "不含",
    "cancellationFeeTiers": null,
    "manualCancellationRefund": true,
    "seoTitle": "…",
    "seoDescription": "…",
    "ogImageUrl": "…",
    "images": [
      {
        "id": "…",
        "url": "…",
        "caption": "…",
        "displayOrder": 0
      }
    ],
    "departures": [
      {
        "id": "…",
        "tripId": "…",
        "departureDate": "…",
        "returnDate": "…",
        "priceTwd": 0,
        "capacity": 0,
        "bookedCount": 0,
        "status": "cancelled",
        "notes": "…",
        "allocationMode": "fcfs",
        "label": "…",
        "isPrivate": true,
        "agencyPriceTwd": 0,
        "depositMode": null,
        "depositAmountTwd": 0,
        "depositPercent": 0,
        "groupCode": "…",
        "regionCode": "…",
        "airlineCode": "…",
        "promoActive": true,
        "promoPriceTwd": 0,
        "promoAgencyPriceTwd": 0,
        "salesCloseAt": "…",
        "effectiveSalesCloseAt": "…",
        "salesAutoClosedAt": "…",
        "salesClosePassed": true,
        "salesOpenAt": "…",
        "salesOpenFailedReason": "…",
        "meetingTime": "…",
        "meetingPlace": "…",
        "agreementChangeDays": 0,
        "entryDateOffsetDays": 0,
        "lotteryLeadDays": 0,
        "lotteryDrawTime": "…",
        "lotteryDrawDayOffset": 0,
        "lotteryChangeDays": 0,
        "lotteryDrawDate": "…",
        "effectiveLotteryDrawTime": "…",
        "lotteryDrawAtDate": "…",
        "lotteryApplicationClosed": true,
        "requiredGuideCount": 0
      }
    ]
  }
}
toko trips departures

梯次:查詢(find/search)、建立、編輯、狀態、團號

參數

<tripId>位置參數 · 必填
<departureId>位置參數 · 必填
--group-code <code>
旗標 · 選填

完整團號(自動轉大寫)。格式依租戶團號樣板驗證;未設樣板時為 YY+地區+[航空]+MMDD+序號(如 26EGTK1010A)

--group-code-prefix <prefix>
旗標 · 選填

團號前綴,前綴比對列出多個梯次

--status <s>
旗標 · 選填

梯次狀態(selling 銷售中/closed 關閉/cancelled 取消/completed 完成);省略 = selling,有 salesOpenAt 時 = closed

--region <c>
旗標 · 選填

團號地區來源碼(2–8 碼大寫英數),用於產生團號,可不指定

--airline <c>
旗標 · 選填

團號航空來源碼(2–8 碼大寫英數),用於產生團號,可不指定

--departure-date <d>
旗標 · 選填

出發日期(YYYY-MM-DD)

回應欄位 · data

id
string

新建立梯次的 id(dep_ 前綴)。

範例
toko trips departures find --group-code 'example-groupCode'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko trips create

建立行程

參數

--slug <s>
旗標 · 必填

行程網址代稱(slug),用於前台路徑與後台識別,英數與連字號 2-63 字,大寫自動轉小寫

--title <t>
旗標 · 必填

行程標題,顯示於前台與訂單

--destination <d>
旗標 · 必填

目的地名稱

--duration-days <n>
旗標 · 必填

行程天數

--price-from-twd <n>
旗標 · 必填

起價(新台幣),前台「OOO 元起」顯示用

--summary <t>
旗標 · 選填

行程摘要,前台列表卡片用的一句話簡介

--is-climbing
旗標 · 選填

是否為登山團(啟用登山相關模組欄位)

--is-high-altitude
旗標 · 選填

行程本身是否屬高海拔。結團時旅客的登山紀錄以「屬高海拔或需具備高山經驗」認列高山經驗,之後報名需高山經驗的行程會自動通過。需具備高山經驗的行程一律存成 true,送 false 也一樣

--lottery-notice-mdx <mdx>
旗標 · 選填

登山行程的抽籤須知(MDX);null 清空,省略不變,不改抽籤或付款規則

--status <draft|published|archived>
旗標 · 選填

行程狀態(draft 草稿/published 上架/archived 封存)

--pre-trip-night
旗標 · 選填
--meeting-day <n>
旗標 · 選填

第幾天集合(1 = 出發日,2 = 出發日隔天)。契約第 4 條的集合日照此計算;有行前集合夜時只能是 1,且不能超過行程天數

--guide-start-day <n>
旗標 · 選填

帶團開始日,D1 起算;起訖成對設定,null 清除

--guide-end-day <n>
旗標 · 選填

帶團結束日,含當日;不得超過行程天數,null 清除

--clear-guide-days
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立行程的 id(trip_ 前綴)。

對應端點POST /api/v1/trips
範例
toko trips create --slug 'example-slug' --title 'example-title' --destination 'example-destination' --duration-days '1' --price-from-twd '1'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko trips update

部分更新行程(未帶的欄位不動,含 status)

參數

<id>位置參數 · 必填
--title <t>
旗標 · 選填

行程標題,顯示於前台與訂單

--short-name <t>
旗標 · 選填

內部簡稱(例:嘉明湖三日),只用於後台與 API;null 或空字串清空,省略不變

--slug <s>
旗標 · 選填

行程網址代稱(slug),用於前台路徑與後台識別,英數與連字號 2-63 字,大寫自動轉小寫

--status <s>
旗標 · 選填

行程狀態(draft 草稿/published 上架/archived 封存);省略 = 不動

--price-from-twd <n>
旗標 · 選填

起價(新台幣),前台「OOO 元起」顯示用

--is-climbing
旗標 · 選填

是否為登山團(啟用登山相關模組欄位)

--is-high-altitude
旗標 · 選填

行程本身是否屬高海拔。結團時旅客的登山紀錄以「屬高海拔或需具備高山經驗」認列高山經驗,之後報名需高山經驗的行程會自動通過。需具備高山經驗的行程一律存成 true,送 false 也一樣

--lottery-notice-mdx <mdx>
旗標 · 選填

登山行程的抽籤須知(MDX);null 清空,省略不變,不改抽籤或付款規則

--pre-trip-night
旗標 · 選填
--meeting-day <n>
旗標 · 選填

第幾天集合(1 = 出發日,2 = 出發日隔天)。契約第 4 條的集合日照此計算;有行前集合夜時只能是 1,且不能超過行程天數

--guide-start-day <n>
旗標 · 選填

帶團開始日,D1 起算;起訖成對設定,null 清除

--guide-end-day <n>
旗標 · 選填

帶團結束日,含當日;不得超過行程天數,null 清除

--clear-guide-days
旗標 · 選填
--lottery-draw-day-offset <0|-1>
旗標 · 選填

抽籤時刻落在哪一天:0 = 抽籤日當天(預設),-1 = 抽籤日前一天。只移動前台停收時刻與後台「抽籤 MM/DD HH:MM」標示;抽籤日、關鍵日期、可變更第三人期限、退改費階梯都不變。抽籤時程表有時段時不套用

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko trips update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko trips lottery-notice-templates

抽籤須知範本:查詢、建立、取代與刪除

參數

<id>位置參數 · 必填
--name <name>
旗標 · 選填

範本名稱,可依抽籤天數或路線命名

--content-mdx <mdx>
旗標 · 選填

須知 MDX 內容,可使用 Notice 醒目提醒區塊

回應欄位 · data[]

id
object
length
number

Returns the length of a String object.

name
string
contentMdx
string
createdAt
string
updatedAt
string
範例
toko trips lottery-notice-templates list
回應
{
  "ok": true,
  "data": [
    {
      "id": {
        "length": 0
      },
      "name": "…",
      "contentMdx": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko trips set-lottery-notice

套用須知範本、設定 MDX 或清空行程須知

參數

<tripId>位置參數 · 必填
--template-id <id>
旗標 · 選填
--content-mdx <mdx>
旗標 · 選填

行程詳細內容(MDX 格式),前台行程頁主文

--clear
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
object
length
number

Returns the length of a String object.

name
string
contentMdx
string
createdAt
string
updatedAt
string
範例
toko trips set-lottery-notice '<tripId>' --template-id '<id>'
回應
{
  "ok": true,
  "data": {
    "id": {
      "length": 0
    },
    "name": "…",
    "contentMdx": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko trips set-cost-template

綁定 / 解綁行程的成本範本(可多範本疊加)

參數

<tripId>位置參數 · 必填
--template-ids <id1,id2,…>
旗標 · 選填

要綁定的成本範本 ID 陣列(依序疊加);[] 或省略表示解除全部綁定

--template-id <id>
旗標 · 選填

(向後相容,單一)要綁定的成本範本 ID;null 表示解綁

--unbind
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

範例
toko trips set-cost-template '<tripId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko trips cost-templates

列出可綁定的 active 成本範本

參數

--json
旗標 · 選填

回應欄位 · data[]

id
string

成本範本 id(ct_ 前綴)。

name
string

成本範本名稱。

範例
toko trips cost-templates list-active
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…"
    }
  ]
}
toko trips import

批次匯入行程(.xlsx/.csv;預設 dry-run,--commit 才建檔)

參數

--file <path.xlsx>
旗標 · 必填

上傳檔名,副檔名須為 .xlsx 或 .csv

--commit
旗標 · 選填
--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

filename
string

已匯入的檔名。

result
object

匯入結果(建檔筆數與逐列結果)。

importBatchId
string

本次匯入批次 id(imp_ 前綴),供稽核追溯。

createdTripCount
number

新建行程數。

createdDepartureCount
number

新建梯次數。

skippedCount
number

略過列數(重複/無需匯入)。

errorCount
number

失敗列數。

results
object[]

逐列匯入結果。

rowNumber
number

試算表列號(含表頭列,資料第一列為 2)。

status
"append_departure" | "error" | "new_trip" | "skip"

該列匯入結果:new_trip / append_departure / skip / error。

message
string | null

error / skip 的人話原因(繁中);成功列為空。

tripId選填
string | undefined

建出的 trip id(new_trip 成功時)。

departureId選填
string | undefined

建出的 departure id(new_trip / append_departure 成功時)。

groupCode選填
string | undefined

產生的團號(有地區碼時;航空碼選填)。

incompleteTrips
object[]

本批**新建**行程中,關鍵設定仍為空者(#461)。漏填的三組全是靜默失效(難度分留空 → 審核器不作用;階梯未覆寫 → 套租戶預設那組;訂金不收),結果頁列出並附編輯連結。 只列有缺的行程;補梯次的既有行程不列(匯入不動它的設定)。

tripId
string
slug
string
title
string
missing
"alpine_experience" | "deposit" | "grade_score" | "lottery_lead_days"[]

仍為空的關鍵設定(至少一項)。

範例
toko trips import --file 'example-filename'
回應
{
  "ok": true,
  "data": {
    "filename": "…",
    "result": {
      "importBatchId": "…",
      "createdTripCount": 0,
      "createdDepartureCount": 0,
      "skippedCount": 0,
      "errorCount": 0,
      "results": [
        {
          "rowNumber": 0,
          "status": "append_departure",
          "message": "…",
          "tripId": "…",
          "departureId": "…",
          "groupCode": "…"
        }
      ],
      "incompleteTrips": [
        {
          "tripId": "…",
          "slug": "…",
          "title": "…",
          "missing": [
            "alpine_experience"
          ]
        }
      ]
    }
  }
}
toko trips export

匯出行程為 CSV/JSON(同 list 篩選)

參數

--status <s>
旗標 · 選填

依行程狀態篩選(draft 草稿/published 上架/archived 封存)

--q <t>
旗標 · 選填

自由文字搜尋(行程標題/代稱/目的地)

--group-code <prefix>
旗標 · 選填

依團號篩選,匯出含該團號梯次的行程

--format <csv|json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

rows
object[]

匯出的行程列(套用相同 filter,無分頁)。

adminPinnedAt選填
string | undefined | null

全公司共用的後台釘選時間。

id
string

行程 id(trip_ 前綴)。

slug
string

行程網址 slug。

title
string

行程標題。

destination
string

目的地名稱。

durationDays
number

天數。

guideStartDay選填
number | null | undefined
guideEndDay選填
number | null | undefined
priceFromTwd
number

「NT$ X 起」起價(TWD 整數)。

status
"archived" | "draft" | "published"

上架狀態:draft 草稿 / published 已上架 / archived 封存。

isHidden
boolean

不對外顯示(#1435)。

isLinkOnly
boolean

僅限連結:不進任何列表,行程頁不給搜尋引擎收錄,拿到網址可報名。與 `isHidden` 互斥。

foreignTravelersOnly
boolean

限外籍旅客(issue 1519)。

updatedAt
string

最後更新時間。

isClimbing
boolean

是否登山團(行程層模組旗標)。

isOverseas
boolean

是否海外團(行程層模組旗標)。

hasPreTripNight
boolean

是否有行前集合夜(trips.md §3)。

activeDepartureCount
number

Count of departures with status='selling'.

nextDepartureDate
string | null

Earliest selling departure_date, ISO date string, or null.

representativeGroupCode
string | null

代表團號(group-code §8.2):最新一筆有團號的梯次;無則 null(UI 顯示 —)。

total
number

匯出總筆數。

truncated
boolean

是否因上限被截斷(此端點回全列,恆為 false)。

範例
toko trips export
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "adminPinnedAt": "…",
        "id": "…",
        "slug": "…",
        "title": "…",
        "destination": "…",
        "durationDays": 0,
        "guideStartDay": 0,
        "guideEndDay": 0,
        "priceFromTwd": 0,
        "status": "archived",
        "isHidden": true,
        "isLinkOnly": true,
        "foreignTravelersOnly": true,
        "updatedAt": "…",
        "isClimbing": true,
        "isOverseas": true,
        "hasPreTripNight": true,
        "activeDepartureCount": 0,
        "nextDepartureDate": "…",
        "representativeGroupCode": "…"
      }
    ],
    "total": 0,
    "truncated": true
  }
}
toko trips ops-defaults-update

更新 trips/[id]/ops-defaults

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

defaults
TripOpsDefaults | null
transport
object[]
key
string
description
string | null
vehicleInfo
string | null
fareNote
string | null
catering
object[]
key
string
supplier
string | null
mealPlan
string | null
headcountNote
string | null
insurance
object[]

逐 kind 一列:保險公司與排定辦理日的「出發前 N 個工作天」(issue 1373)。兩欄至少一欄有值; 缺 kind = 該類不預建。保單號永遠逐梯填。`workdaysBefore` 省略 = 不帶排定日。

kind
"climbing" | "liability"
insurer
string | null
workdaysBefore選填
number | undefined
範例
toko trips ops-defaults-update '<id>' --data '{"defaults":{"transport":[{}],"catering":[{}],"insurance":[{"kind":"liability"}]}}'
回應
{
  "ok": true,
  "data": {
    "defaults": null
  }
}
toko trips ops-defaults-list

查詢 trips/[id]/ops-defaults

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

transport
object[]
key
string
description
string | null
vehicleInfo
string | null
fareNote
string | null
catering
object[]
key
string
supplier
string | null
mealPlan
string | null
headcountNote
string | null
insurance
object[]

逐 kind 一列:保險公司與排定辦理日的「出發前 N 個工作天」(issue 1373)。兩欄至少一欄有值; 缺 kind = 該類不預建。保單號永遠逐梯填。`workdaysBefore` 省略 = 不帶排定日。

kind
"climbing" | "liability"
insurer
string | null
workdaysBefore選填
number | undefined
範例
toko trips ops-defaults-list '<id>'
回應
{
  "ok": true,
  "data": {
    "transport": [
      {
        "key": "…",
        "description": "…",
        "vehicleInfo": "…",
        "fareNote": "…"
      }
    ],
    "catering": [
      {
        "key": "…",
        "supplier": "…",
        "mealPlan": "…",
        "headcountNote": "…"
      }
    ],
    "insurance": [
      {
        "kind": "climbing",
        "insurer": "…",
        "workdaysBefore": 0
      }
    ]
  }
}
toko trips survey-options-update

更新 trips/[id]/survey/options/[optionId]

參數

<id>位置參數 · 必填
<optionId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

found
boolean
範例
toko trips survey-options-update '<id>' '<optionId>'
回應
{
  "ok": true,
  "data": {
    "found": true
  }
}
toko trips survey-question-active

執行 trips/[id]/survey/questions/[questionId]/active

參數

<id>位置參數 · 必填
<questionId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

found
boolean
範例
toko trips survey-question-active '<id>' '<questionId>' --data '{"isActive":true}'
回應
{
  "ok": true,
  "data": {
    "found": true
  }
}
toko trips survey-questions-options-create

執行 trips/[id]/survey/questions/[questionId]/options

參數

<id>位置參數 · 必填
<questionId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string
範例
toko trips survey-questions-options-create '<id>' '<questionId>' --data '{"label":"example-label"}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko trips survey-questions-update

更新 trips/[id]/survey/questions/[questionId]

參數

<id>位置參數 · 必填
<questionId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

found
boolean
範例
toko trips survey-questions-update '<id>' '<questionId>'
回應
{
  "ok": true,
  "data": {
    "found": true
  }
}
toko trips survey-questions-create

執行 trips/[id]/survey/questions

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string
範例
toko trips survey-questions-create '<id>' --data '{"kind":"text","label":"example-label"}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko trips survey-list

查詢 trips/[id]/survey

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
tripId
string
kind
"multi" | "quantity" | "single" | "text"
label
string
description
string | null
required
boolean
displayOrder
number
isActive
boolean
options
object[]
id
string
label
string
equipmentItemId
string | null

綁定的裝備主檔品項(issue 240;只有 multi / quantity 題可綁);null = 純文字選項。

displayOrder
number
isActive
boolean
範例
toko trips survey-list '<id>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "tripId": "…",
      "kind": "multi",
      "label": "…",
      "description": "…",
      "required": true,
      "displayOrder": 0,
      "isActive": true,
      "options": [
        {
          "id": "…",
          "label": "…",
          "equipmentItemId": "…",
          "displayOrder": 0,
          "isActive": true
        }
      ]
    }
  ]
}
toko trips cancellation-tiers-preview

執行 trips/cancellation-tiers/preview

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填

回應欄位 · data

changes
object[]

`leadDays` 為 null:首列與租戶預設同門檻,直接重套成租戶預設。

tripId
string
title
string
leadDays
number | null
skipped
object[]

略過的行程(無效列、不收退改費、判斷不出前置天數、租戶預設產不出階梯)。

tripId
string
title
string
reason
"invalid_rows" | "no_fee" | "no_lead_days" | "tenant_unusable"
unchangedCount
number

已經一致或未覆寫,不需要改的行程數。

tenantTiers
object[]

判斷時用的租戶預設。確認寫入時原樣送回,交易內比對它有沒有被改過。

daysBefore
number

距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。

feePercent選填
number | undefined

扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。

feeFixedTwd選填
number | undefined

定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。

onSaleCount
number

`changes` 裡已開賣的行程數:有後台可建單(販售中)、且尚未出發的梯次。

orderCount
number

`changes` 掛著的未結訂單數(`pending_payment` / `confirmed`,一張單只算一次)。 PM 裁示一改全改(issue 538),這些單之後取消會套新階梯。

範例
toko trips cancellation-tiers-preview --data '{"tripIds":["example-tripIds"]}'
回應
{
  "ok": true,
  "data": {
    "changes": [
      {
        "tripId": "…",
        "title": "…",
        "leadDays": 0
      }
    ],
    "skipped": [
      {
        "tripId": "…",
        "title": "…",
        "reason": "invalid_rows"
      }
    ],
    "unchangedCount": 0,
    "tenantTiers": [
      {
        "daysBefore": 0,
        "feePercent": 0
      }
    ],
    "onSaleCount": 0,
    "orderCount": 0
  }
}
toko trips cancellation-tiers-reapply

執行 trips/cancellation-tiers/reapply

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

changes
object[]

`leadDays` 為 null:首列與租戶預設同門檻,直接重套成租戶預設。

tripId
string
title
string
leadDays
number | null
skipped
object[]

略過的行程(無效列、不收退改費、判斷不出前置天數、租戶預設產不出階梯)。

tripId
string
title
string
reason
"invalid_rows" | "no_fee" | "no_lead_days" | "tenant_unusable"
unchangedCount
number

已經一致或未覆寫,不需要改的行程數。

tenantTiers
object[]

判斷時用的租戶預設。確認寫入時原樣送回,交易內比對它有沒有被改過。

daysBefore
number

距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。

feePercent選填
number | undefined

扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。

feeFixedTwd選填
number | undefined

定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。

onSaleCount
number

`changes` 裡已開賣的行程數:有後台可建單(販售中)、且尚未出發的梯次。

orderCount
number

`changes` 掛著的未結訂單數(`pending_payment` / `confirmed`,一張單只算一次)。 PM 裁示一改全改(issue 538),這些單之後取消會套新階梯。

範例
toko trips cancellation-tiers-reapply --data '{"tripIds":["example-tripIds"],"confirmedTripIds":["example-confirmedTripIds"],"confirmedTenantTiers":[{"daysBefore":0,"feePercent":100}]}'
回應
{
  "ok": true,
  "data": {
    "changes": [
      {
        "tripId": "…",
        "title": "…",
        "leadDays": 0
      }
    ],
    "skipped": [
      {
        "tripId": "…",
        "title": "…",
        "reason": "invalid_rows"
      }
    ],
    "unchangedCount": 0,
    "tenantTiers": [
      {
        "daysBefore": 0,
        "feePercent": 0
      }
    ],
    "onSaleCount": 0,
    "orderCount": 0
  }
}

toko agencies

同業:查詢、明細、指派候選、匯出

toko agencies list

列出/篩選同業

參數

--status <active|archived>
旗標 · 選填

同業狀態篩選(active 啟用中/archived 已封存;省略為全部)

--owner <userId>
旗標 · 選填

負責業務篩選(傳明確使用者 ID;none=只列尚未指派負責業務者;all 或省略=全部)

--has-tax-id <yes|no>
旗標 · 選填

是否有統一編號篩選(yes 僅列有統編者/no 僅列無統編者)

--json
旗標 · 選填

回應欄位 · data[]

id
string

同業 id(前綴 `agc_`)。

name
string

同業公司名 / 個人團主名稱。

taxId
string | null

統一編號(個人團主可留空)。

contactName
string | null

主要聯絡人姓名(未填 → null)。

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

address
string | null

公司地址(未填 → null)。

paymentTerm
string | null

帳期 / 結算方式(自由文字,例:'月結 30 天')。

paymentDueRule
{ kind: "monthly"; day: number; } | { kind: "after_departure"; days: number; } | { kind: "after_order"; days: number; } | null
ownerUserId
string | null

負責業務 user id(NULL = 未指派)。

ownerName
string | null

負責業務顯示名;未指派為 null。

status
"active" | "archived"

同業狀態:active 啟用中 / archived 已封存。

note
string | null

內部備註(未填 → null)。

orderCount
number

累計訂單數(COUNT orders WHERE agency_id = id)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko agencies list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "taxId": "…",
      "contactName": "…",
      "phone": "…",
      "email": "…",
      "address": "…",
      "paymentTerm": "…",
      "paymentDueRule": {
        "kind": "monthly",
        "day": 10
      },
      "ownerUserId": "…",
      "ownerName": "…",
      "status": "active",
      "note": "…",
      "orderCount": 0,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko agencies get

單一同業完整明細

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

同業 id(前綴 `agc_`)。

name
string

同業公司名 / 個人團主名稱。

taxId
string | null

統一編號(個人團主可留空)。

contactName
string | null

主要聯絡人姓名(未填 → null)。

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

address
string | null

公司地址(未填 → null)。

paymentTerm
string | null

帳期 / 結算方式(自由文字,例:'月結 30 天')。

paymentDueRule
{ kind: "monthly"; day: number; } | { kind: "after_departure"; days: number; } | { kind: "after_order"; days: number; } | null
ownerUserId
string | null

負責業務 user id(NULL = 未指派)。

ownerName
string | null

負責業務顯示名;未指派為 null。

status
"active" | "archived"

同業狀態:active 啟用中 / archived 已封存。

note
string | null

內部備註(未填 → null)。

orderCount
number

累計訂單數(COUNT orders WHERE agency_id = id)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko agencies get '<id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "taxId": "…",
    "contactName": "…",
    "phone": "…",
    "email": "…",
    "address": "…",
    "paymentTerm": "…",
    "paymentDueRule": {
      "kind": "monthly",
      "day": 10
    },
    "ownerUserId": "…",
    "ownerName": "…",
    "status": "active",
    "note": "…",
    "orderCount": 0,
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko agencies assignable-staff

負責業務指派候選清單

參數

--json
旗標 · 選填

回應欄位 · data[]

userId
string

員工使用者 id(可作為負責業務指派的 ownerUserId)。

name
string

員工顯示名。

role
string

角色代碼(admin / sales / op / accountant)。

範例
toko agencies assignable-staff
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "name": "…",
      "role": "…"
    }
  ]
}
toko agencies export

匯出同業名單(當前篩選視圖)

參數

--status <active|archived>
旗標 · 選填

同業狀態篩選(active 啟用中/archived 已封存;省略為全部)

--owner <userId>
旗標 · 選填

負責業務篩選(傳明確使用者 ID;none=只列尚未指派負責業務者;all 或省略=全部)

--has-tax-id <yes|no>
旗標 · 選填

是否有統一編號篩選(yes 僅列有統編者/no 僅列無統編者)

--json
旗標 · 選填

回應欄位 · data

rows
object[]

同業匯出資料列(依 owner 篩選後的全表快照,供試算表匯出)。

id
string

同業 id(前綴 `agc_`)。

name
string

同業公司名 / 個人團主名稱。

taxId
string | null

統一編號(個人團主可留空)。

contactName
string | null

主要聯絡人姓名(未填 → null)。

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

address
string | null

公司地址(未填 → null)。

paymentTerm
string | null

帳期 / 結算方式(自由文字,例:'月結 30 天')。

paymentDueRule
{ kind: "monthly"; day: number; } | { kind: "after_departure"; days: number; } | { kind: "after_order"; days: number; } | null
ownerUserId
string | null

負責業務 user id(NULL = 未指派)。

ownerName
string | null

負責業務顯示名;未指派為 null。

status
"active" | "archived"

同業狀態:active 啟用中 / archived 已封存。

note
string | null

內部備註(未填 → null)。

orderCount
number

累計訂單數(COUNT orders WHERE agency_id = id)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko agencies export
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "…",
        "name": "…",
        "taxId": "…",
        "contactName": "…",
        "phone": "…",
        "email": "…",
        "address": "…",
        "paymentTerm": "…",
        "paymentDueRule": {
          "kind": "monthly",
          "day": 10
        },
        "ownerUserId": "…",
        "ownerName": "…",
        "status": "active",
        "note": "…",
        "orderCount": 0,
        "createdAt": "…",
        "updatedAt": "…"
      }
    ]
  }
}
toko agencies create

新增同業(鏡射 createAgency;agency.manage)

參數

--name <name>
旗標 · 必填

同業公司名稱(B2B 旅行社或個人團主名稱)

--tax-id <t>
旗標 · 選填

統一編號(選填)

--contact-name <n>
旗標 · 選填

主要聯絡人姓名(選填)

--phone <p>
旗標 · 選填

聯絡電話(選填)

--email <e>
旗標 · 選填

聯絡 Email(選填;留空字串視為未填)

--address <a>
旗標 · 選填

公司地址(選填)

--payment-term <t>
旗標 · 選填

付款條件/帳期約定(選填,如月結 30 天)

--owner <userId>
旗標 · 選填

指派的負責業務使用者 ID(選填)

--status <active|archived>
旗標 · 選填

同業狀態(active 啟用中/archived 已封存;預設 active)

--note <t>
旗標 · 選填

內部備註(選填)

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立同業的 ID(agc_ 前綴)。

範例
toko agencies create --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko agencies update

更新同業(真 partial;鏡射 updateAgency;agency.manage)

參數

<id>位置參數 · 必填
--name <n>
旗標 · 選填

同業公司名稱(省略則不更動)

--tax-id <t>
旗標 · 選填

統一編號(省略則不更動)

--contact-name <n>
旗標 · 選填

主要聯絡人姓名(省略則不更動)

--phone <p>
旗標 · 選填

聯絡電話(省略則不更動)

--email <e>
旗標 · 選填

聯絡 Email(省略則不更動;空字串視為清空)

--address <a>
旗標 · 選填

公司地址(省略則不更動)

--payment-term <t>
旗標 · 選填

付款條件/帳期約定(省略則不更動)

--owner <userId>
旗標 · 選填

指派的負責業務使用者 ID(省略則不更動)

--status <active|archived>
旗標 · 選填

同業狀態(active 啟用中/archived 已封存;省略則不更動)

--note <t>
旗標 · 選填

內部備註(省略則不更動)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:同業資料已更新。

範例
toko agencies update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko agencies archive

下架同業(鏡射 setAgencyStatus archived;agency.manage)

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:同業啟用/停用狀態已更新。

範例
toko agencies archive '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko agencies restore

上架同業(鏡射 setAgencyStatus active;agency.manage)

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:同業啟用/停用狀態已更新。

範例
toko agencies restore '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko members

會員(客戶):查詢、明細、統計

toko members list

列出/搜尋會員

參數

--q <text>
旗標 · 選填

關鍵字,模糊比對會員姓名、Email 或電話

--county <縣市>
旗標 · 選填

縣市篩選,僅回傳通訊地址在該縣市的會員

--year <yyyy>
旗標 · 選填

加入年份(西元四位數),僅回傳該年註冊的會員

--page <n>
旗標 · 選填

分頁頁碼,從 1 起算,預設第 1 頁

--page-size <n>
旗標 · 選填

每頁筆數,上限 200,預設由後端決定

--json
旗標 · 選填

回應欄位 · data

rows
object[]

當前頁的會員列。

userId
string

會員(顧客)的 user id。

email
string

會員 Email(登入帳號)。

name
string

會員姓名。

createdAt
string

會員註冊時間。

phone
string | null

聯絡電話(未填 → null)。

address
string | null

通訊地址(未填 → null)。

birthDate
string | null

生日 YYYY-MM-DD(未填 → null)。

orderCount
number

累計訂單數(含所有狀態與 kind)。

paidOrderCount
number

成交訂單數(未取消,且已付清或已完成)。

totalSpent
number

累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。

lastOrderAt
string | null

最後一筆訂單建立時間(無訂單 → null)。

pdpaSignedAt
string | null

最新版 PDPA 同意書簽署時間(未簽 → null)。

anonymizedAt
string | null

PDPA 匿名化時間;非空 = 已匿名化。

createdByUserId
string | null

後台代建者 user id(member-admin-create);null = 客戶自助註冊。

createdByName
string | null

代建者姓名(join `user`);自助註冊 → null。

total
number

符合篩選的會員總數。

page
number

當前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

範例
toko members list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "userId": "…",
        "email": "…",
        "name": "…",
        "createdAt": "…",
        "phone": "…",
        "address": "…",
        "birthDate": "…",
        "orderCount": 0,
        "paidOrderCount": 0,
        "totalSpent": 0,
        "lastOrderAt": "…",
        "pdpaSignedAt": "…",
        "anonymizedAt": "…",
        "createdByUserId": "…",
        "createdByName": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}
toko members get

單一會員完整明細(含訂單/同意紀錄)

參數

<userId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

profile
object

會員基本資料 + 訂單彙整。

userId
string

會員(顧客)的 user id。

email
string

會員 Email(登入帳號)。

name
string

會員姓名。

createdAt
string

會員註冊時間。

phone
string | null

聯絡電話(未填 → null)。

address
string | null

通訊地址(未填 → null)。

birthDate
string | null

生日 YYYY-MM-DD(未填 → null)。

orderCount
number

累計訂單數(含所有狀態與 kind)。

paidOrderCount
number

成交訂單數(未取消,且已付清或已完成)。

totalSpent
number

累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。

lastOrderAt
string | null

最後一筆訂單建立時間(無訂單 → null)。

pdpaSignedAt
string | null

最新版 PDPA 同意書簽署時間(未簽 → null)。

anonymizedAt
string | null

PDPA 匿名化時間;非空 = 已匿名化。

createdByUserId
string | null

後台代建者 user id(member-admin-create);null = 客戶自助註冊。

createdByName
string | null

代建者姓名(join `user`);自助註冊 → null。

orders
object[]

近期訂單列表(上限 50 筆,含 lodging)。

id
string

訂單 id。

orderNumber
string

人類可讀訂單編號。

status
string

金流模型 v2:deriveOrderDisplayStatus(booking/payment/refund) 派生的單一顯示狀態。

total
number

該會員所有訂單的應收總額(TWD 整數)。

createdAt
string

訂單建立時間。

tripTitle
string

行程 / 產品標題。

consents
object[]

已簽署的同意書紀錄(上限 50 筆)。

id
string

簽署紀錄 id。

kind
string

同意書類型:系統種類(pdpa / tour_agreement / cancellation_policy / refund_policy) 或租戶自訂種類的 id(`cnsk_…`)。

kindLabel
string | null

自訂種類的名稱;系統種類為 null。

travelerName
string | null

代簽時被代簽旅客的姓名(逐旅客的自訂同意書);本人簽署為 null。

version
number

簽署當下的範本版本號。

signedAt
string

簽署時間。

ipAddress
string | null

簽署時來源 IP(未記錄 → null)。

範例
toko members get '<userId>'
回應
{
  "ok": true,
  "data": {
    "profile": {
      "userId": "…",
      "email": "…",
      "name": "…",
      "createdAt": "…",
      "phone": "…",
      "address": "…",
      "birthDate": "…",
      "orderCount": 0,
      "paidOrderCount": 0,
      "totalSpent": 0,
      "lastOrderAt": "…",
      "pdpaSignedAt": "…",
      "anonymizedAt": "…",
      "createdByUserId": "…",
      "createdByName": "…"
    },
    "orders": [
      {
        "id": "…",
        "orderNumber": "…",
        "status": "…",
        "total": 0,
        "createdAt": "…",
        "tripTitle": "…"
      }
    ],
    "consents": [
      {
        "id": "…",
        "kind": "…",
        "kindLabel": "…",
        "travelerName": "…",
        "version": 0,
        "signedAt": "…",
        "ipAddress": "…"
      }
    ]
  }
}
toko members stats

會員 KPI 統計

參數

--json
旗標 · 選填

回應欄位 · data

totalMembers
number

會員(顧客)總數(排除員工帳號)。

newThisMonth
number

本月新增會員數(自助 + 代建)。

newThisMonthStaffCreated
number

本月新增中由後台代建的數量(member-admin-create §4)。

staffCreated
number

累計由後台代建的會員數(`member_profiles.created_by_user_id IS NOT NULL`)。

withOrders
number

有下過訂單的會員數。

averageOrders
number

平均訂單數(只計有訂單者,避免零訂單稀釋)。

範例
toko members stats
回應
{
  "ok": true,
  "data": {
    "totalMembers": 0,
    "newThisMonth": 0,
    "newThisMonthStaffCreated": 0,
    "staffCreated": 0,
    "withOrders": 0,
    "averageOrders": 0
  }
}
toko members expiry-flags

標記護照即將到期的會員(給定 userId 批次)

參數

--ids <u1,u2,…>
旗標 · 必填

以逗號分隔的會員使用者 ID 批次,上限 200 個,回傳其中護照即將到期者

--json
旗標 · 選填

回應欄位 · data

userIds
string[]

證件即將到期(或已過期)需提醒的會員 user id 清單。

範例
toko members expiry-flags --ids 'example-ids'
回應
{
  "ok": true,
  "data": {
    "userIds": [
      "…"
    ]
  }
}
toko members anonymize

PDPA 匿名化會員(不可逆:抹除 PII + 封鎖登入 + 撤銷憑證)

參數

<userId>位置參數 · 必填
--reason <t>
旗標 · 選填

匿名化原因,記入稽核紀錄備查

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:會員個資已匿名化(PDPA 刪除權)。

範例
toko members anonymize '<userId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko members create

建立會員並寄啟用信

參數

--email <value>
旗標 · 必填

會員登入 Email,也是啟用信的收件地址

--name <value>
旗標 · 必填

會員姓名

--phone <value>
旗標 · 選填

聯絡電話(選填)

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

userId
string

新建會員的使用者 ID。

email
string

正規化(小寫)後的登入 Email。

name
string

會員姓名。

activationSent
boolean

啟用信是否已送出請求;false 時請客戶在登入頁走「忘記密碼」取得設定密碼連結。

範例
toko members create --email 'customer@example.com' --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "userId": "…",
    "email": "…",
    "name": "…",
    "activationSent": true
  }
}
toko members lookup

以完整 Email 查詢建單帳號

參數

--email <value>
旗標 · 必填

訂購人 Email,完整比對、不分大小寫

--json
旗標 · 選填
範例
toko members lookup --email 'customer@example.com'
回應
{
  "ok": true,
  "data": "…"
}
toko members line-user-id-set

把官方 LINE 機器人蒐集的 LINE userId 綁到會員

參數

<id>位置參數 · 必填
--line-user-id <value>
旗標 · 必填

LINE userId:U 開頭加 32 碼小寫十六進位

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko members line-user-id-set '<id>' --line-user-id 'U0123456789abcdef0123456789abcdef'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko members line-user-id-clear

解除會員的 LINE userId 綁定

參數

<id>位置參數 · 必填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko members line-user-id-clear '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko members by-line-user-id

以 LINE userId 比對會員

參數

--line-user-id <value>
旗標 · 必填

LINE userId:U 開頭加 32 碼小寫十六進位

--json
旗標 · 選填
範例
toko members by-line-user-id --line-user-id 'U0123456789abcdef0123456789abcdef'
回應
{
  "ok": true,
  "data": "…"
}

toko orders

訂單:查詢、明細、統計

toko orders list

列出/搜尋訂單

參數

--status <s>
旗標 · 選填

依訂單顯示狀態篩選(如 pending、paid、cancelled)

--q <text>
旗標 · 選填

關鍵字搜尋(訂單編號、訂購人姓名或 Email 等)

--date-from <d>
旗標 · 選填

出發日期區間起(格式 YYYY-MM-DD,含當日)

--date-to <d>
旗標 · 選填

出發日期區間迄(格式 YYYY-MM-DD,含當日)

--page <n>
旗標 · 選填

頁碼,從 1 起算,預設第 1 頁

--json
旗標 · 選填

回應欄位 · data

rows
object[]

當前頁的訂單列(每筆商品明細一列)。

accounting
object

Display accounting amounts. The cash ledger remains unchanged.

orderReceivableTwd
number | null
cancellationFeePending
boolean
cancellationFeeTwd
number | null
refundFeesTwd
number | null

Completed administrative fees. Excludes bank fees.

percentageFeeTwd
number | null
fixedAdminFeeTwd
number | null
changeFeeTwd
number | null
unclassifiedFeeTwd
number | null

Unclassified historical fees remain separate.

refundRemainingTwd
number | null
cancelledCash
CancelledCash | null

已取消訂單的對帳現金(issue 1974):保留款轉移與現金收退分開算。 未取消的訂單為 null。

collectedTwd
number

已收現金:客人實際付進本單的錢,不含保留款轉入。

heldCashTransferredTwd
number

轉成保留款的淨額:保留款轉出減轉入。這筆錢還在保留款,或已折抵到別張訂單。 負數表示本單是用保留款折抵的(轉入多於轉出)。

customerRefundedTwd
number

已退給客人的現金:退款、刷退與沖正,不含保留款轉出與匯款手續費。

cancellationFeeDueTwd
number

客人還欠的退改費。應收不含這筆。0 = 沒有欠款。

kind
"lodging" | "tour"
id
string

訂單 id(前綴 `ord_`)。

orderNumber
string

人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。

bookingState
string

預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。

paymentState
string

付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。

refundState
string

退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。

grossReceivableTwd
number

應收(TWD 整數,派生自應收分類帳)。

collectedTwd
number

收到現金(TWD 整數,派生),含保留款轉入。已取消訂單對帳讀 `accounting.cancelledCash.collectedTwd`,那個數字不含保留款轉入(issue 1974)。

customerCashAppliedTwd
number

客戶現金淨套用(收款減已退現金,TWD 整數,派生)。

refundableCashTwd
number

可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。

outstandingTwd
number

未收(應收減客戶現金淨套用,TWD 整數,派生)。

partySize
number

參團人數(tour 訂單)。

createdAt
string

訂單建立時間。

notes
string | null

訂單備註(未填 → null)。

userId
string

下單客戶的 user id(同庫 user 表)。

userName
string

下單客戶顯示名。

userEmail
string

下單客戶 Email。

primaryTravelerName
string | null

主要旅客姓名(is_primary,未登記 → null)。

primaryTravelerPhone
string | null

主要旅客電話(未登記 → null)。

tripId
string

行程 id(tour 訂單經梯次反查;lodging 為空字串)。

tripTitle
string

行程 / 產品標題。

tripShortName
string | null

行程內部簡稱(issue 1414);未填或訂房訂單為 null。

tripSlug
string

行程 slug。

departureId
string

梯次 id(tour 訂單;lodging 為空字串)。

departureDate
string

出發日 YYYY-MM-DD(lodging 為入住日)。

returnDate
string

回程日 YYYY-MM-DD(lodging 為退房日)。

assignedToUserId
string | null

派發給哪位業務的 user id(未派發 → null)。

assigneeName
string | null

承辦業務顯示名(未派發 / 查無 → null)。

assignmentStatus
string

派發狀態:unassigned / assigned / reassigned / pending_review。

assignedAt
string | null

最近一次派發時間(未派發 → null)。

assignedByUserId
string | null

執行派發者的 user id(未派發 → null)。

createdByUserId
string | null

S5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.

pendingConsent
boolean

是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。

roomingStatus
"assigned" | "needs_single" | "registered" | "unregistered"

分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。

lotteryState
string | null

抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。

failoverFromOrderId
string | null

備案訂單所對應的原訂單 ID。

isOverdue
boolean

是否有已到期、尚未收齊的收款計畫。

receiptAllocationNeedsReorder
boolean

收據分配要重排(issue 1942):公司收據加總超過應收。訂單列表 `?receipt=needs_reorder` 與工作台待辦同一個口徑。

total
number

符合篩選的訂單總數(DISTINCT 訂單,非列數)。

page
number

當前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

對應端點GET /api/v1/orders
範例
toko orders list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "accounting": {
          "orderReceivableTwd": 0,
          "cancellationFeePending": true,
          "cancellationFeeTwd": 0,
          "refundFeesTwd": 0,
          "percentageFeeTwd": 0,
          "fixedAdminFeeTwd": 0,
          "changeFeeTwd": 0,
          "unclassifiedFeeTwd": 0,
          "refundRemainingTwd": 0,
          "cancelledCash": null
        },
        "kind": "lodging",
        "id": "…",
        "orderNumber": "…",
        "bookingState": "…",
        "paymentState": "…",
        "refundState": "…",
        "grossReceivableTwd": 0,
        "collectedTwd": 0,
        "customerCashAppliedTwd": 0,
        "refundableCashTwd": 0,
        "outstandingTwd": 0,
        "partySize": 0,
        "createdAt": "…",
        "notes": "…",
        "userId": "…",
        "userName": "…",
        "userEmail": "…",
        "primaryTravelerName": "…",
        "primaryTravelerPhone": "…",
        "tripId": "…",
        "tripTitle": "…",
        "tripShortName": "…",
        "tripSlug": "…",
        "departureId": "…",
        "departureDate": "…",
        "returnDate": "…",
        "assignedToUserId": "…",
        "assigneeName": "…",
        "assignmentStatus": "…",
        "assignedAt": "…",
        "assignedByUserId": "…",
        "createdByUserId": "…",
        "pendingConsent": true,
        "roomingStatus": "assigned",
        "lotteryState": "…",
        "lotteryWaitlisted": true,
        "failoverFromOrderId": "…",
        "isOverdue": true,
        "receiptAllocationNeedsReorder": true
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}
toko orders get

單一訂單完整明細

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

participationVersion
number
departureChanges
object[]
id
string
participationVersion
number
actorName
string
reason
string
createdAt
string
snapshot
object
documents
object
agreementEnabled
boolean
versioningReady
boolean
agreementCount
number
agreementPending
number
agreementHistory
number
consents
object[]
label
string
version
number
pending
number
retained
number
due
boolean
passportExpiryWarnings
number
fingerprint
string
crossTrip選填
CrossTripChangeSnapshot | undefined
sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
price_twd
number | null
agency_price_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
promo_active
boolean | null
promo_price_twd
number | null
promo_agency_price_twd
number | null
trip
object
direct_price_twd
number | null
agency_price_twd
number | null
price_from_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
deposit_basis
DepositBasis | null

schema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。

unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

basis
"per_amount" | "per_travelers"
step
number

N:每幾位旅客 / 每滿幾元。

unitTwd
number

每次折多少(碼的折扣值)。

units
number

折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
selfService選填
SelfServiceChangeSnapshot | undefined
repricing
object

The target fare at its current price. Same shape as a cross-trip quote, without answers.

sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
trip
object
unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
fee
object
tier
CancellationFeeTier | null
daysBefore
number

距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。

feePercent選填
number | undefined

扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。

feeFixedTwd選填
number | undefined

定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。

amountTwd
number
description
string

charge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。

surplus
"keep_overpaid" | "refund_draft"
remitFeeTwd
number
lottery選填
LotteryChangeSnapshot | undefined
sourceMode
string
targetMode
string
stateBefore
string | null
stateAfter
"applied" | "won" | null

`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.

placement選填
true | undefined
failover選填
Omit<LotteryFailoverStep, "applicationKey"> | undefined

Set when the backup failover made the change. A general target confirms the seat (`won`).

skipped
object[]

Backup choices that the failover skipped before this one.

rank
number
departureId
string
reason
"identity_missing" | "not_same_trip" | "price_changed" | "roster_invalid" | "unavailable"
notFormed選填
boolean | undefined
notFormedDepartureId選填
string | undefined
hitRank
number

Rank of the backup choice that this step tries.

remainingDepartureIds
string[]

Backup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.

applicationKeyBefore
string
applicationId選填
string | undefined

Set on confirmation: the new application uses the departure change ID.

legacyChain選填
LegacyChainNode[] | undefined
effectiveCreditTwd選填
number | undefined
policyTotalTwd選填
number | undefined
refundDrafts選填
{ id: string; orderId: string; amountTwd: number; }[] | undefined
participationVersion
number
equipment
object
blocked
boolean
rentals
object[]
rentalId
string
rentalCode
string
departureId
string | null
rentStartDate
string | null
rentEndDate
string | null
returnState
string
reconState
string
deliveredAt
string | null
depositClearedAt
string | null
rentTotalTwd
number

租借單的租金與押金合計。只是租借單的事實,換梯不搬這些錢。

depositTotalTwd
number
replacesRentalId
string | null
ready
boolean
blocker
string | null
lines
object[]
itemId
string
name
string | null
quantity
number
committedQuantity
number
paymentWindowStartedAt選填
string | undefined
sourceFingerprint
string
rosterFingerprint
string
source
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
target
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
arrangements選填
DepartureChangeArrangements | undefined
roomFeeBeforeTwd
number
roomFeeAfterTwd
number
otherRoomOrderCount
number
otherRoomFeeDeltaTwd
number
otherRefundDraftTwd
number
releasedRoomCount
number
releasedPretripStayCount
number
tasks
object[]
travelerId
string
kind
"pretrip_stay" | "room" | "survey"
label
string
fingerprint
string
totalTwd
number
unitPriceTwd
number
discountTwd
number
chargeLines
object[]
id
string
type
string
amount_twd
number
description
string
depositTwd
number
balanceTwd
number
balanceDueAt
string | null
receipts
object
blocked
boolean
receipts
object[]
id
string
merchantOrderNo
string
status
string
invoiceNumber
string | null
invoiceTransNo
string | null
submitted
boolean
operationPending
boolean
lastError
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
totalAmtTwd
number
updatedAt
string
resolution
"cancel_scheduled" | "invalidate" | "none" | "reconcile" | "reprepare"
target
object
tourName
string
tourNo
string | null
tourDate
string
totalAmtTwd
number
collectedTwd
number
returnedTwd
number
paidRefundFeesTwd
number
customerCashAppliedTwd
number
outstandingTwd
number
refundHeadroom
object
grossReceivableTwd
number

當前應收。

refundableCashTwd
number

可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。

assessedCancellationFeeTwd
number

此實收單保留的退改費;舊資料沿用人工核算基準。

openRefundGrossTwd
number

同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。

openRefundCount
number

同單其他未執行退款的張數。

openReceivableReductionTwd
number

同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。

carriedToLiveBackupsTwd
number

已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。

assessmentPending
boolean

人工核算單、退改費尚未核算。

baseTwd
number

額度基準 = 可退現金 − 上面三項扣減,下限 0。

surplusDisposition選填
"refund" | "retain" | undefined
retainedFundId選填
string | undefined
overpaymentRefundTwd
number
depositOutstandingTwd
number
nextPaymentPurpose
"full" | "deposit" | "balance" | null
nextPaymentTwd
number
moneyFingerprint
string
refundDraftId選填
string | undefined
legacyChain
{ collectedTwd: number; returnedTwd: number; paidRefundFeesTwd: number; effectiveCreditTwd: number; refundableTwd: number; openRefundCount: number; nodes: { orderId: string; orderNumber: string; collectedTwd: number; returnedTwd: number; openRefundCount: number; }[]; } | null
collectedTwd
number
returnedTwd
number
paidRefundFeesTwd
number
effectiveCreditTwd
number
refundableTwd
number
openRefundCount
number
nodes
object[]
orderId
string
orderNumber
string
collectedTwd
number
returnedTwd
number
openRefundCount
number
arrangements
{ departureId: string; tasks: ArrangementTask[]; } | null

Current arrangement tasks after a departure change. Null means this order has no departure change.

departureId
string
tasks
object[]
travelerId
string
kind
"pretrip_stay" | "room" | "survey"
label
string
receiptAllocation
object

收據分配表:一列對一張收據。公司收據列(`isOrderer: false`,有統編)依序在前,最後一列固定是 訂購人個人收據(`isOrderer: true`,沒有統編,金額=應收減公司收據加總,最低 0;0 表示不開)。 `needsReorder: true` 表示收據分配要重排:公司收據加總超過應收,`excessTwd` 是超過的金額。 `personalEmail` 是訂購人個人收據另填的寄送 Email,null 表示用訂購人帳號的 Email。

rows
object[]

公司收據列依序,最後一列固定是訂購人個人收據。

isOrderer
boolean

true = 訂購人個人收據(沒有統編、金額由系統算)。

buyerName
string
buyerUbn
string | null

統編。訂購人個人收據為 null。

email
string
amountTwd
number
receivableTwd
number

推導時用的應收。

companyTotalTwd
number
needsReorder
boolean

收據分配要重排:公司收據加總超過應收。應收變少時先從個人收據列扣,扣到 0 還超過 就是這個狀態。

excessTwd
number

公司收據加總超過應收的差額。沒有超過時為 0。

personalEmail
string | null
actions
object

訂單可行動作。每個動作是 `{ ok: true }`(部分動作另帶欄位,例:`cancel.path`、 `createRefund.headroom`)或 `{ ok: false, reason }`。`reason` 沿用對應寫入端點的 原因碼;`forbidden` 表示呼叫者沒有該動作的權限。

cancel
Availability<CancelBlockReason, { path: CancelPath; }>

`cancelOrder` / `cancelLodgingBooking` / `cancelFailoverChildOrder` / `cancelLotteryLostOrder`(依 `path`)。`lottery_lost` 的權限是 lottery.manage 加抽籤模組。

transferDeparture
Availability<DepartureChangeFailure, object>

General departure change with completed payment records. The selected target is checked during preview and confirmation.

adjust
Availability<"ORDER_TERMINAL", object>

掛帳 / 折讓 / 沖正(`applyManualAdjustment` / `reverseChargeLine`)。

editTravelers
TravelerEditAvailability

旅客新增 / 編輯 / 移除(`addTraveler` / `updateTraveler` / `removeTraveler`)。名單凍結中 回 `EDIT_WINDOW_CLOSED` 加 `rosterFreezeUnlockable: true`(見 `TravelerEditAvailability`)。

editRooming
Availability<"ORDER_TERMINAL", object>

分房需求登記(`updateRoomingPreference`)。

markPaid
Availability<ManualPaymentBlockReason, object>

手動登記收款(`markOrderManuallyPaid`)。`settled`:寫入端回冪等成功、不入帳。

collectCancellationFee選填
Availability<"not_eligible", { dueTwd: number; collectedTwd: number; }> | undefined

Record actual cancellation fee collections without reopening the booking.

balancePayment
Availability<BalanceGateReason, { remainingTwd: number; }>

補尾款連結 / 繳款單(`prepareBalancePayment`,可收分期的 `balance_link` 收款入口)。

balanceSlip
Availability<BalanceGateReason, { remainingTwd: number; }>

寄尾款繳款單(`sendBalanceSlipInTx`,可收分期的 `balance_slip` 收款入口)。訂金制同 `balancePayment`,全額單收全額列的餘額(issue 1522)。

payLink
Availability<BalanceGateReason, { remainingTwd: number; }>

自填金額付款連結(`issueOrderPayLink`,可收分期的 `pay_link` 收款入口,issue 1487)。已付訂金時同 `balancePayment`; 訂金未付時掛目前這一期,`remainingTwd` 是這一期的餘額。

createRefund
Availability<never, { headroom: RefundHeadroom; }>

建立退款。只看權限;金額上限與「為何是 0」在 `headroom`(`describeNoHeadroom`), 與建立 / 送審 / 標記已付三道 guard 讀同一份可退額度。

splitTraveler
Availability<SplitTravelerBlockReason, { otherDepartures: boolean; }>

拆出旅客(`splitTraveler`)。`otherDepartures`:能不能拆到別梯;整單不能換梯時只能同梯另開單。 名單凍結時拆到別梯要帶 `acknowledgeRosterFreeze: true`(見 `editTravelers.rosterFreezeUnlockable`)。旅客、款項與目標梯次的資格在寫入端鎖內重驗。

withdrawTraveler
Availability<WithdrawSourceBlockReason, { rosterFreeze: boolean; }>

旅客退出(`withdrawTraveler`,issue 2056):非主要旅客退出,系統減席、減應收、收取消費、 退款或保留。`rosterFreeze`:出發前 6 天內,要帶 `acknowledgeRosterFreeze: true`。 不能做時 `reason` 是原單的守門(款項、附加費用、抽籤未中籤等),按鈕旁照原因說明。

heldCashTransfer
Availability<HeldCashTransferBlockReason, object>

用保留款折抵,本單是轉入目標(`transferHeldCash`)。來源單在寫入端鎖內重驗。

reduceReceivable
Availability<ReduceReceivableBlockReason, object>

直接減少應收:折讓、沖正原始應收、跨行程換梯的負數調整(`assertDirectAdjustmentAllowed`)。 「折讓必須經核准」開啟時,沒有核准權的人回 `APPROVAL_REQUIRED`。

requestDiscount
Availability<never, object>

手動少收申請(`requestManualDiscount`)。

decideDiscount
Availability<"ORDER_TERMINAL", object>

核准或拒絕手動少收申請(`decideManualDiscount`)。核准權與 `canApproveAllowance` 同一條。

requestFeeWaiver
Availability<never, object>

申請減免退改費(`requestCancellationFeeWaiver`,#1621)。權限同建立退款單。

decideFeeWaiver
Availability<never, object>

核准或拒絕退改費減免。核准權同少收申請(`canApproveAllowance`+order.adjust)。

revokeReceipt
Availability<never, object>

撤銷或申請撤銷人工收款(`revokeManualReceipt` / `requestManualReceiptRevocation`)。只看權限, 不看這張單有沒有人工收款登記;逐筆的撤銷條件在寫入端。

submitRefund
Availability<never, object>

退款草稿送審(`submitRefund`)。退款單本身的狀態閘在寫入端。

cancelRefund
Availability<never, object>

退款草稿作廢(`cancelRefund`)。

approveRefund
Availability<never, object>

核准退款(`approveRefund`)。

rejectRefund
Availability<never, object>

駁回退款(`rejectRefund`)。

markRefundPaid
Availability<never, object>

標記退款已付與綠界刷退(`markRefundPaid`)。

assign
Availability<never, object>

派發:待審派發單走首次派發(`assignOrder`,order.assign),其他單走重派 (`reassignOrder`,order.reassign)。

updateOrder
Availability<never, object>

訂單層的其他更新(order.update):解除實名占用、代登登山紀錄、護照、同意書、 重寄信件、跨行程換梯報價。

reviewScreening
Availability<never, object>

審核登山資格(screening.review)。

manageAgreement
Availability<never, object>

管理旅遊契約(tour_agreement.manage)。

viewAgreementEvidence
Availability<never, object>

檢視旅遊契約簽署證據(tour_agreement.evidence)。

revealPii
Availability<never, object>

顯示證號全碼、檢視護照影本(order.reveal_pii)。

readConversation
Availability<never, object>

讀訂單對話(order_conversation.read)。

editReceiptAllocation
Availability<never, object>

修改收據分配表(`saveOrderReceiptAllocation`,issue 1942)。小編(order.update)與會計 (invoice.issue)都能改,訂單狀態不限制。

accounting
object

Display accounting amounts. The cash ledger remains unchanged.

orderReceivableTwd
number | null
cancellationFeePending
boolean
cancellationFeeTwd
number | null
refundFeesTwd
number | null

Completed administrative fees. Excludes bank fees.

percentageFeeTwd
number | null
fixedAdminFeeTwd
number | null
changeFeeTwd
number | null
unclassifiedFeeTwd
number | null

Unclassified historical fees remain separate.

refundRemainingTwd
number | null
cancelledCash
CancelledCash | null

已取消訂單的對帳現金(issue 1974):保留款轉移與現金收退分開算。 未取消的訂單為 null。

collectedTwd
number

已收現金:客人實際付進本單的錢,不含保留款轉入。

heldCashTransferredTwd
number

轉成保留款的淨額:保留款轉出減轉入。這筆錢還在保留款,或已折抵到別張訂單。 負數表示本單是用保留款折抵的(轉入多於轉出)。

customerRefundedTwd
number

已退給客人的現金:退款、刷退與沖正,不含保留款轉出與匯款手續費。

cancellationFeeDueTwd
number

客人還欠的退改費。應收不含這筆。0 = 沒有欠款。

kind
"lodging" | "tour"

訂單種類(kind-agnostic 外殼)。'tour' 用既有 tour 區塊(梯次/分房/登山審核); 'lodging' 隱藏 tour-only 區、改顯示住宿 header(見 `lodging`)。共用的金流/旅客/ 派發/同意書區塊兩者皆 order-scoped 通用。

id
string

訂單 id(前綴 `ord_`)。

orderNumber
string

人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。

bookingState
string

預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。

paymentState
string

付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。

refundState
string

退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。

grossReceivableTwd
number

應收(TWD 整數,派生自應收分類帳)。

collectedTwd
number

收到現金(TWD 整數,派生),含保留款轉入。已取消訂單對帳讀 `accounting.cancelledCash.collectedTwd`,那個數字不含保留款轉入(issue 1974)。

customerCashAppliedTwd
number

客戶現金淨套用(收款減已退現金,TWD 整數,派生)。

refundableCashTwd
number

可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。

outstandingTwd
number

未收(應收減客戶現金淨套用,TWD 整數,派生)。

partySize
number

參團人數(tour 訂單)。

createdAt
string

訂單建立時間。

notes
string | null

訂單備註(未填 → null)。

userId
string

下單客戶的 user id(同庫 user 表)。

userName
string

下單客戶顯示名。

userEmail
string

下單客戶 Email。

primaryTravelerName
string | null

主要旅客姓名(is_primary,未登記 → null)。

primaryTravelerPhone
string | null

主要旅客電話(未登記 → null)。

tripId
string

行程 id(tour 訂單經梯次反查;lodging 為空字串)。

tripTitle
string

行程 / 產品標題。

tripShortName
string | null

行程內部簡稱(issue 1414);未填或訂房訂單為 null。

tripSlug
string

行程 slug。

departureId
string

梯次 id(tour 訂單;lodging 為空字串)。

departureDate
string

出發日 YYYY-MM-DD(lodging 為入住日)。

returnDate
string

回程日 YYYY-MM-DD(lodging 為退房日)。

assignedToUserId
string | null

派發給哪位業務的 user id(未派發 → null)。

assigneeName
string | null

承辦業務顯示名(未派發 / 查無 → null)。

assignmentStatus
string

派發狀態:unassigned / assigned / reassigned / pending_review。

assignedAt
string | null

最近一次派發時間(未派發 → null)。

assignedByUserId
string | null

執行派發者的 user id(未派發 → null)。

createdByUserId
string | null

S5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.

pendingConsent
boolean

是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。

roomingStatus
"assigned" | "needs_single" | "registered" | "unregistered"

分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。

lotteryState
string | null

抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。

failoverFromOrderId
string | null

備案訂單所對應的原訂單 ID。

isOverdue
boolean

是否有已到期、尚未收齊的收款計畫。

receiptAllocationNeedsReorder
boolean

收據分配要重排(issue 1942):公司收據加總超過應收。訂單列表 `?receipt=needs_reorder` 與工作台待辦同一個口徑。

cancellationFeeTwd
number | null

取消時公司留下的錢:退改費加上已付、不退的換梯手續費(customer-cancellation §8.9)。 NULL = 尚未核算,0 = 已核算且扣 0;兩者不可互換。

cancellationChangeFeeTwd
number | null

`cancellationFeeTwd` 裡屬於已付換梯手續費、不退的部分(customer-cancellation §8.9)。 退改費 = `cancellationFeeTwd` − 這筆。null = 沒有。

administrativeFeeItems
object[]

已核准的退改費減免合計(#1621)。`cancellationFeeTwd` 已是減免後的數字。0 = 沒有減免。

amountTwd
number
incomeDate
string
reason
string
cancellationFeeTier
CancellationFeeTier | null
daysBefore
number

距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。

feePercent選填
number | undefined

扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。

feeFixedTwd選填
number | undefined

定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。

cancellationIncomeDate
string | null
paidRefundRemitFeesTwd
number
cancellationFeeWaivedTwd
number
staffNote
string | null

承辦備註(issue 1659,`orders.staff_note`)。只給後台;null = 沒有備註。

cancellationRefundPending
boolean
cancellationMoney
object

取消單現金與未執行退款摘要。

openRefundCount
number

未執行退款單張數。

openRefundAmountTwd
number

未執行退款單的實際退款金額合計。

openRefundAdminFeesTwd
number

未執行退款單的**行政手續費**合計(`refunds.admin_fee_twd`)。與匯款手續費分成兩欄,顯示面 才叫得出名字 —— 合併成一個「手續費」會把這筆行政費講成匯款費。

openRefundRemitFeesTwd
number

未執行退款單的**匯款手續費**合計(`refunds.remit_fee_twd`;spec 稱轉帳費,§3.4)。

retainedCashTwd
number

可退現金扣退改費;無未執行退款單且退改費已核算時,與保留款帳同口徑。

uncoveredCashTwd
number

未執行退款單沒蓋到的可退現金(issue 2055)。未取消的訂單與沒有未執行退款單時是 0。 大於 0 時要補開退款,工作台「多付待處理」也計入。

heldCashAppliedTo
object[]

本單的錢折抵到的其他訂單(issue 1974):直接轉到別張訂單,或經本單建立的保留款折抵。 折抵回本單的不列。未取消的訂單為空陣列。

orderId
string
orderNumber
string
amountTwd
number
heldCashRefundedTwd
number

從本單保留款退給客人的金額。

heldCashRefundFeesTwd
number

從本單保留款退款時,已認列的行政手續費與匯款手續費。

tripIsOverseas
boolean

行程是否出國(`trips.is_overseas`;lodging 為 false)。旅客編輯器據此顯示英文姓名 / 國籍欄(#459)。

tripCancellationFeeTiers
CancellationFeeTier[] | null

行程自己的退改階梯(`trips.cancellation_fee_tiers` 解析後);null = 未覆寫,沿用租戶預設。 實際生效的階梯由呼叫端用 `resolveFeeTiers` 合成,與取消時同一個優先順序。

agencyPaymentDueDate
string | null

客戶分類:同業單(`orders.agency_id`)帶同業名稱;直客單為 null。

agency
{ id: string; name: string; contactName: string | null; phone: string | null; consentConfirmed: { at: Date; byName: string | null; } | null; } | null
id
string
name
string
contactName
string | null

同業主檔的聯絡窗口(#1782)。訂單頁顯示「聯絡窗口」,訂購人不變。

phone
string | null
consentConfirmed
{ at: Date; byName: string | null; } | null

「同業已代為取得旅客同意」的勾選(#1479)。沒有勾選時為 null。

at
string
byName
string | null
pdpaManualSigned
boolean

PDPA 同意書有人工標記已簽(舊系統或紙本,#1913)。進度條據此不寫「已簽署」。

departureLabel
string | null

梯次標籤 / 副標(issue 509 ①;lodging 為 null)。訂單頁的「梯次」欄接在日期後顯示。

lodging
AdminLodgingHeader | null

lodging 住宿 header(房型/住期/房數/人數);tour 為 null。

propertyName
string
propertySlug
string
roomTypeName
string
checkIn
string

入住日 YYYY-MM-DD。

checkOut
string

退房日 YYYY-MM-DD(不含當晚)。

units
number
guestCount
number
travelers
object[]

旅客名單(含 PII 遮罩欄;主要旅客排前)。

id
string

旅客 id(前綴 `trv_`)。

fullName
string

旅客姓名。

idNumberMask
string | null

遮罩碼(jsonb→mask,零解密);NULL = 未填。全碼走 reveal action(Task 7)。

passportNoMask
string | null

護照號碼遮罩碼(零解密);NULL = 未填。全碼走 order-scoped reveal。

birthDate
string | null

生日 YYYY-MM-DD(未填 → null)。

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

lineId
string | null

LINE ID(未填 → null)。明文。

lineDisplayName
string | null
englishName
string | null

英文姓名(#459,海外團;未填 → null)。明文,已 normalize 大寫。

nationality
string | null

國籍(#459,海外團;未填 → null)。明文。

passportExpiryDate
string | null

護照效期(#609,海外團;未填 → null)`YYYY-MM-DD`。明文 date 欄。

emergencyContactName
string | null

緊急聯絡人姓名(未填 → null)。

emergencyContactPhone
string | null

緊急聯絡人電話(未填 → null)。

isPrimary
boolean

是否為主要旅客(訂單聯絡人)。

gender
string | null

性別(分房硬約束 + 顯示):'male'|'female'|'other'|null。明文。

roomPreference
string | null

分房房型偏好(下單登記)。

roommatePref
string | null

指定房友 / 特殊需求自由文字。

diet
string | null

飲食需求(葷素)明文;null = 未填。非 PII,不走 reveal。

medicalNotes
string | null

醫療 / 過敏 / 病史備註明文;null = 未填。非 PII,不走 reveal。

address
string | null

通訊地址(未填 → null)。

roomLabel
string | null

團控已排房號的房間 label(null = 待團控分房)。

chargeLines
object[]

應收分類帳(itemized)。

id
string

應收明細列 id。

type
string

應收類型:base(原始價)/ room_upgrade(房升補款)/ adjustment / failover_deposit_credit 等。

amountTwd
number

金額(TWD 整數,signed;credit / 沖銷為負)。

description
string

明細說明文字。

sourceType
string

來源:system(系統派生)/ manual(人工登錄)等。

reversesChargeLineId
string | null

若為沖銷列,指向被沖銷的應收明細列 id(否則 null)。

createdByUserId
string | null

開立這筆費用列的使用者 id;系統派生或匯入列為 null。

createdAt
string

建立時間。

transactions
object[]

現金分類帳。

id
string

現金交易列 id。

direction
string

金流方向:in(收款)/ out(退款、扣款、沖銷)。

type
string

交易類型:payment / refund / chargeback / reversal。

amountTwd
number

交易金額(TWD 整數,正值)。

feeTwd
number

金流商手續費(TWD 整數)。

netTwd
number

淨額 = amount − fee(TWD 整數)。

provider
string

金流商:manual / ecpay / test 等。

paymentChannel
string

收款通路與付款方式。缺少線上付款方式時明確標示未知。

providerTradeNo
string | null

金流商交易序號(manual 入帳可能為 null)。

merchantTradeNo
string | null

The merchant order reference of this transaction's payment attempt.

moneyReceiptId
string | null

Public receipt ID for a proven money-core binding. Unbound historical rows retain null.

refundId
string | null

若屬退款,指向 refunds 列 id(否則 null)。

bankReference
string | null

銀行參考號:手動收款是客人的匯款後五碼,退款是匯款憑證號(未填為 null)。

remittanceId
string | null

同源匯款關聯鍵:這列來自一筆拆到多張訂單的匯款時非 null,同一筆匯款的各列共用同一個值。

registrationId
string | null

登記收款的批次鍵(#1411):撤銷人工收款時,原收款與反向紀錄共用同一個值。

bankCreditedOn
string | null

入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填,其他為 null。

overTheCounter
boolean

臨櫃存款(沒有末五碼)。

receivingAccountName
string | null

收款帳戶顯示名稱(未歸戶為 null)。

transferCounterpartOrderId
string | null

保留款轉移(`type='transfer'`,issue 1407)的對方訂單:轉出列指向目標單,轉入列指向 來源單。其他列為 null。

transferCounterpartOrderNumber
string | null

對方訂單編號(同上)。

transferActorName
string | null

執行這次保留款轉移的員工名稱(取自稽核紀錄;其他列為 null)。

occurredAt
string

交易發生時間。

schedules
object[]

收款計畫(current + historical)。

id
string

收款計畫列 id。

purpose
string

用途:full(全額)/ deposit(訂金)/ balance(尾款)/ adjustment(補款)。

targetAmountTwd
number

應收目標金額(TWD 整數)。

status
string

計畫狀態:open(未收齊)/ satisfied(已收齊)。

appliedTwd
number

已套用到此列的現金(H3 唯一基準 `appliedCashForSchedule`;含 replaces 鏈)。

dueAt
string | null

到期日(null = 未設)。

sequence
number

排序序號(deposit → balance → adjustment)。

intents
object[]

付款意圖(+ 最新 attempt)。

id
string
purpose
string
amountTwd
number
status
string
scheduleId
string | null
invalidationReason
string | null

Reason for closing this checkout. departure_change permits a verified late payment.

invalidatedAmountTwd
number | null

Original checkout amount in TWD when the intent became invalid.

attemptProvider
string | null
attemptMethod
string | null
attemptStatus
string | null
bankCode
string | null
virtualAccount
string | null
payExpireAt
string | null
refunds
object[]

退款工作流。

id
string
refundNumber
string
status
"approved" | "cancelled" | "draft" | "failed" | "paid" | "processing" | "submitted"
refundKind
string
amountTwd
number
method
string
reason
string
createdAt
string
paidAt
string | null
executionMethod
string | null

執行方式:chargeback 刷退 / remit 匯出;未定為 null(customer-cancellation §3.4)。

gatewayExecutionMode選填
"manual" | "api" | undefined
remitFeeTwd
number

轉帳費(按單一次;remit 才有值)。承辦核放時可調降。

splitGroupId
string | null

拆單組(#1406):同一筆退款拆成刷退+匯款時,各張共用。null = 沒有拆單。

gatewayLocked
boolean

原路退刷 claim 已佔但無成功紀錄 = DoAction 結果不明,退款單被鎖住(mark-paid 一律 回 GATEWAY_IN_FLIGHT_OR_UNKNOWN)。判準取 clearRefundGatewayClaim 的 NOT_LOCKED 守衛 (別在 UI 端重刻)再加狀態閘:已 paid / cancelled 的殘留 claim 不該露出解鎖入口。

gatewayNeedsReview
boolean

近 90 天已完成帳務且明確記錄自動退刷降級,供對帳辨識;不提供重試入口。

payee
{ accountName: string | null; bankCode: string | null; branchCode: string | null; accountNumber: string | null; } | null

收款人四欄(匯款單才有值)。付款前承辦可改(issue 1698)。含完整帳號:`/api/v1` 對沒有 `refund.create` 權限的呼叫者回 null,和後台訂單頁的顯示條件相同。

accountName
string | null
bankCode
string | null
branchCode
string | null
accountNumber
string | null
consents
object[]
kind
string
kindLabel
string | null

自訂種類的名稱(#586);系統種類為 null,由畫面依 `kind` 查標籤。

version
number
signedAt
string
signerName
string | null

送出的帳號。逐旅客的自訂同意書是代簽人(訂購人)。

travelerName
string | null

被代簽旅客的姓名;訂單層簽署為 null。旅客列移除後也是 null(紀錄本身仍在)。

travelerId
string | null

被代簽旅客的 id(無 FK,旅客移除後仍保留作證據)。

ipAddress
string | null
auditLog
object[]
id
string
action
string
actorUserId
string | null
actorUserName
string | null
metadata
unknown
ipAddress
string | null
createdAt
string
orderDiscount
AdminOrderDiscountRow | null
codeSnapshot
string
originalTotalTwd
number
discountTwd
number
profitShareTwd
number
profitSharePayeeSnapshot
string | null
範例
toko orders get '<id>'
回應
{
  "ok": true,
  "data": {
    "participationVersion": 0,
    "departureChanges": [
      {
        "id": "…",
        "participationVersion": 0,
        "actorName": "…",
        "reason": "…",
        "createdAt": "…",
        "snapshot": {
          "documents": {
            "agreementEnabled": true,
            "versioningReady": true,
            "agreementCount": 0,
            "agreementPending": 0,
            "agreementHistory": 0,
            "consents": [
              {
                "label": "…",
                "version": 0,
                "pending": 0,
                "retained": 0,
                "due": true
              }
            ],
            "passportExpiryWarnings": 0,
            "fingerprint": "…"
          },
          "crossTrip": "…",
          "selfService": "…",
          "lottery": "…",
          "legacyChain": "…",
          "effectiveCreditTwd": 0,
          "policyTotalTwd": 0,
          "refundDrafts": "…",
          "participationVersion": 0,
          "equipment": {
            "blocked": true,
            "rentals": [
              {
                "rentalId": "…",
                "rentalCode": "…",
                "departureId": "…",
                "rentStartDate": "…",
                "rentEndDate": "…",
                "returnState": "…",
                "reconState": "…",
                "deliveredAt": "…",
                "depositClearedAt": "…",
                "rentTotalTwd": 0,
                "depositTotalTwd": 0,
                "replacesRentalId": "…",
                "ready": true,
                "blocker": "…",
                "lines": [
                  {
                    "itemId": "…",
                    "name": "…",
                    "quantity": 0,
                    "committedQuantity": 0
                  }
                ]
              }
            ]
          },
          "paymentWindowStartedAt": "…",
          "sourceFingerprint": "…",
          "rosterFingerprint": "…",
          "source": {
            "id": "…",
            "trip_id": "…",
            "departure_date": "…",
            "return_date": "…",
            "status": "…",
            "allocation_mode": "…",
            "price_twd": 0,
            "label": "…",
            "deposit_mode": null,
            "deposit_amount_twd": 0,
            "deposit_percent": 0
          },
          "target": {
            "id": "…",
            "trip_id": "…",
            "departure_date": "…",
            "return_date": "…",
            "status": "…",
            "allocation_mode": "…",
            "price_twd": 0,
            "label": "…",
            "deposit_mode": null,
            "deposit_amount_twd": 0,
            "deposit_percent": 0
          },
          "arrangements": "…",
          "totalTwd": 0,
          "unitPriceTwd": 0,
          "discountTwd": 0,
          "chargeLines": [
            {
              "id": "…",
              "type": "…",
              "amount_twd": 0,
              "description": "…"
            }
          ],
          "depositTwd": 0,
          "balanceTwd": 0,
          "balanceDueAt": "…",
          "receipts": {
            "blocked": true,
            "receipts": [
              {
                "id": "…",
                "merchantOrderNo": "…",
                "status": "…",
                "invoiceNumber": "…",
                "invoiceTransNo": "…",
                "submitted": true,
                "operationPending": true,
                "lastError": "…",
                "tourName": "…",
                "tourNo": "…",
                "tourDate": "…",
                "totalAmtTwd": 0,
                "updatedAt": "…",
                "resolution": "cancel_scheduled"
              }
            ],
            "target": {
              "tourName": "…",
              "tourNo": "…",
              "tourDate": "…",
              "totalAmtTwd": 0
            }
          },
          "collectedTwd": 0,
          "returnedTwd": 0,
          "paidRefundFeesTwd": 0,
          "customerCashAppliedTwd": 0,
          "outstandingTwd": 0,
          "refundHeadroom": {
            "grossReceivableTwd": 0,
            "refundableCashTwd": 0,
            "assessedCancellationFeeTwd": 0,
            "openRefundGrossTwd": 0,
            "openRefundCount": 0,
            "openReceivableReductionTwd": 0,
            "carriedToLiveBackupsTwd": 0,
            "assessmentPending": true,
            "baseTwd": 0
          },
          "surplusDisposition": "refund",
          "retainedFundId": "…",
          "overpaymentRefundTwd": 0,
          "depositOutstandingTwd": 0,
          "nextPaymentPurpose": "full",
          "nextPaymentTwd": 0,
          "moneyFingerprint": "…",
          "refundDraftId": "…"
        }
      }
    ],
    "legacyChain": "…",
    "arrangements": {
      "departureId": "dep_example",
      "tasks": [
        {
          "travelerId": "trv_example",
          "kind": "room",
          "label": "尚未分房,保留原房型與房友偏好"
        }
      ]
    },
    "receiptAllocation": {
      "rows": [
        {
          "isOrderer": false,
          "buyerName": "範例股份有限公司",
          "buyerUbn": "22099131",
          "email": "ap@example.com",
          "amountTwd": 3000
        },
        {
          "isOrderer": true,
          "buyerName": "王小明",
          "buyerUbn": null,
          "email": "customer@example.com",
          "amountTwd": 6000
        }
      ],
      "receivableTwd": 9000,
      "companyTotalTwd": 3000,
      "needsReorder": false,
      "excessTwd": 0,
      "personalEmail": null
    },
    "actions": {
      "cancel": {
        "ok": true,
        "path": "tour"
      },
      "transferDeparture": {
        "ok": false,
        "reason": "unsupported"
      },
      "adjust": {
        "ok": true
      },
      "editTravelers": {
        "ok": false,
        "reason": "EDIT_WINDOW_CLOSED",
        "rosterFreezeUnlockable": true
      },
      "editRooming": {
        "ok": true
      },
      "markPaid": {
        "ok": true
      },
      "balancePayment": {
        "ok": false,
        "reason": "not_deposit_paid"
      },
      "balanceSlip": {
        "ok": true,
        "remainingTwd": 9000
      },
      "createRefund": {
        "ok": false,
        "reason": "forbidden"
      },
      "splitTraveler": {
        "ok": true,
        "otherDepartures": false
      },
      "withdrawTraveler": {
        "ok": true,
        "rosterFreeze": false
      },
      "heldCashTransfer": {
        "ok": false,
        "reason": "over_outstanding"
      },
      "reduceReceivable": {
        "ok": false,
        "reason": "APPROVAL_REQUIRED"
      },
      "approveRefund": {
        "ok": false,
        "reason": "forbidden"
      },
      "editReceiptAllocation": {
        "ok": true
      }
    },
    "accounting": {
      "orderReceivableTwd": 0,
      "cancellationFeePending": true,
      "cancellationFeeTwd": 0,
      "refundFeesTwd": 0,
      "percentageFeeTwd": 0,
      "fixedAdminFeeTwd": 0,
      "changeFeeTwd": 0,
      "unclassifiedFeeTwd": 0,
      "refundRemainingTwd": 0,
      "cancelledCash": null
    },
    "kind": "lodging",
    "id": "…",
    "orderNumber": "…",
    "bookingState": "…",
    "paymentState": "…",
    "refundState": "…",
    "grossReceivableTwd": 0,
    "collectedTwd": 0,
    "customerCashAppliedTwd": 0,
    "refundableCashTwd": 0,
    "outstandingTwd": 0,
    "partySize": 0,
    "createdAt": "…",
    "notes": "…",
    "userId": "…",
    "userName": "…",
    "userEmail": "…",
    "primaryTravelerName": "…",
    "primaryTravelerPhone": "…",
    "tripId": "…",
    "tripTitle": "…",
    "tripShortName": "…",
    "tripSlug": "…",
    "departureId": "…",
    "departureDate": "…",
    "returnDate": "…",
    "assignedToUserId": "…",
    "assigneeName": "…",
    "assignmentStatus": "…",
    "assignedAt": "…",
    "assignedByUserId": "…",
    "createdByUserId": "…",
    "pendingConsent": true,
    "roomingStatus": "assigned",
    "lotteryState": "…",
    "lotteryWaitlisted": true,
    "failoverFromOrderId": "…",
    "isOverdue": true,
    "receiptAllocationNeedsReorder": true,
    "cancellationFeeTwd": 0,
    "cancellationChangeFeeTwd": 0,
    "administrativeFeeItems": [
      {
        "amountTwd": 0,
        "incomeDate": "…",
        "reason": "…"
      }
    ],
    "cancellationFeeTier": null,
    "cancellationIncomeDate": "…",
    "paidRefundRemitFeesTwd": 0,
    "cancellationFeeWaivedTwd": 0,
    "staffNote": "…",
    "cancellationRefundPending": true,
    "cancellationMoney": {
      "openRefundCount": 0,
      "openRefundAmountTwd": 0,
      "openRefundAdminFeesTwd": 0,
      "openRefundRemitFeesTwd": 0,
      "retainedCashTwd": 0,
      "uncoveredCashTwd": 0,
      "heldCashAppliedTo": [
        {
          "orderId": "…",
          "orderNumber": "…",
          "amountTwd": 0
        }
      ],
      "heldCashRefundedTwd": 0,
      "heldCashRefundFeesTwd": 0
    },
    "tripIsOverseas": true,
    "tripCancellationFeeTiers": null,
    "agencyPaymentDueDate": "…",
    "agency": "…",
    "pdpaManualSigned": true,
    "departureLabel": "…",
    "lodging": null,
    "travelers": [
      {
        "id": "…",
        "fullName": "…",
        "idNumberMask": "…",
        "passportNoMask": "…",
        "birthDate": "…",
        "phone": "…",
        "email": "…",
        "lineId": "…",
        "lineDisplayName": "…",
        "englishName": "…",
        "nationality": "…",
        "passportExpiryDate": "…",
        "emergencyContactName": "…",
        "emergencyContactPhone": "…",
        "isPrimary": true,
        "gender": "…",
        "roomPreference": "…",
        "roommatePref": "…",
        "diet": "…",
        "medicalNotes": "…",
        "address": "…",
        "roomLabel": "…"
      }
    ],
    "chargeLines": [
      {
        "id": "…",
        "type": "…",
        "amountTwd": 0,
        "description": "…",
        "sourceType": "…",
        "reversesChargeLineId": "…",
        "createdByUserId": "…",
        "createdAt": "…"
      }
    ],
    "transactions": [
      {
        "id": "…",
        "direction": "…",
        "type": "…",
        "amountTwd": 0,
        "feeTwd": 0,
        "netTwd": 0,
        "provider": "…",
        "paymentChannel": "…",
        "providerTradeNo": "…",
        "merchantTradeNo": "…",
        "moneyReceiptId": "…",
        "refundId": "…",
        "bankReference": "…",
        "remittanceId": "…",
        "registrationId": "…",
        "bankCreditedOn": "…",
        "overTheCounter": true,
        "receivingAccountName": "…",
        "transferCounterpartOrderId": "…",
        "transferCounterpartOrderNumber": "…",
        "transferActorName": "…",
        "occurredAt": "…"
      }
    ],
    "schedules": [
      {
        "id": "…",
        "purpose": "…",
        "targetAmountTwd": 0,
        "status": "…",
        "appliedTwd": 0,
        "dueAt": "…",
        "sequence": 0
      }
    ],
    "intents": [
      {
        "id": "…",
        "purpose": "…",
        "amountTwd": 0,
        "status": "…",
        "scheduleId": "…",
        "invalidationReason": "…",
        "invalidatedAmountTwd": 0,
        "attemptProvider": "…",
        "attemptMethod": "…",
        "attemptStatus": "…",
        "bankCode": "…",
        "virtualAccount": "…",
        "payExpireAt": "…"
      }
    ],
    "refunds": [
      {
        "id": "…",
        "refundNumber": "…",
        "status": "approved",
        "refundKind": "…",
        "amountTwd": 0,
        "method": "…",
        "reason": "…",
        "createdAt": "…",
        "paidAt": "…",
        "executionMethod": "…",
        "gatewayExecutionMode": "manual",
        "remitFeeTwd": 0,
        "splitGroupId": "…",
        "gatewayLocked": true,
        "gatewayNeedsReview": true,
        "payee": {
          "accountName": "王小明",
          "bankCode": "812",
          "branchCode": "0011",
          "accountNumber": "00012345678901"
        }
      }
    ],
    "consents": [
      {
        "kind": "…",
        "kindLabel": "…",
        "version": 0,
        "signedAt": "…",
        "signerName": "…",
        "travelerName": "…",
        "travelerId": "…",
        "ipAddress": "…"
      }
    ],
    "auditLog": [
      {
        "id": "…",
        "action": "…",
        "actorUserId": "…",
        "actorUserName": "…",
        "metadata": "…",
        "ipAddress": "…",
        "createdAt": "…"
      }
    ],
    "orderDiscount": null
  }
}
toko orders reveal

顯示旅客證號/護照全碼(owner-scope;寫 traveler.decrypt 稽核)

參數

<orderId>位置參數 · 必填
<travelerId>位置參數 · 必填
--field <idNumber|passportNo>
旗標 · 必填

欲顯示全碼的個資欄位:idNumber 身分證字號、passportNo 護照號碼

--json
旗標 · 選填

回應欄位 · data

field
"idNumber" | "passportNo"

本次解密的欄位:idNumber 身分證字號 / passportNo 護照號碼。

value
string | null

解密後的證件明碼;null = 該欄未填。每次呼叫都會寫入解密稽核紀錄。

範例
toko orders reveal '<orderId>' '<travelerId>' --field idNumber
回應
{
  "ok": true,
  "data": {
    "field": "idNumber",
    "value": "…"
  }
}
toko orders create

代客 K 單(手動建立 tour 訂單;訂購人須為既有會員;一般後台證件可後補;受管制抽籤需證件,受限名額需身分證)

參數

--trip <id>
旗標 · 必填

行程 ID

--departure <id>
旗標 · 必填

梯次 ID,決定佔位的出發團

--email <e>
旗標 · 必填
--party-size <n>
旗標 · 必填

報名人數,決定佔位數,須為 1 至 20 之間整數

--payment-method <cash|atm|manual>
旗標 · 必填

收款方式:cash 現金、atm 轉帳、manual 人工

--travelers <json>
旗標 · 必填

旅客名單,筆數須與報名人數一致。每筆至少要有 fullName,一般後台證件可後補;受管制抽籤需 idNumber 或 passportNo,受限名額需 idNumber;birthDate 若給值須為存在的 YYYY-MM-DD 日期;climbingRecords 可代填該旅客的登山經歷(label 必填、gradeScore 0–20 僅存參考且不計分、climbedOn YYYY-MM-DD、durationValue+durationUnit、hasAlpineExperience;每位最多 20 筆),掛在該旅客本人身上、不掛帳號,須啟用登山模組,否則回 403

--customer-type <direct|agency>
旗標 · 選填

客戶類型:direct 直客、agency 同業,預設直客

--agency-id <agc_id>
旗標 · 選填

同業 ID(agc_ 前綴),把這張單掛到該同業。只在 customerType=agency 時接受;須為啟用中的同業,否則回 422

--payment-plan <full|deposit>
旗標 · 選填

付款方案:full 全額、deposit 訂金,預設全額

--receiving-account <id>
旗標 · 選填

收款帳戶 ID,指定本筆款項入帳的帳戶

--assignee <userId>
旗標 · 選填

指定業績歸屬業務的使用者 ID,省略或等於自己則歸屬建單者;指定他人需具備訂單指派權限

--discount-code <code>
旗標 · 選填

優惠碼;由建單流程驗證並套用折扣,無效時拒絕建單

--notes <t>
旗標 · 選填

訂單備註

--allow-domestic-travelers
旗標 · 選填

行程限外籍旅客時仍要建立:true 放行國籍空白或台灣的旅客,並留稽核紀錄。省略時這類旅客回 422

--confirm-unverified-member <userId>
旗標 · 選填

訂購人帳號 Email 未驗證時,確認是客人本人的帳號:填該帳號的使用者 ID(GET /api/v1/members/lookup 的 userId)。缺少或對不上回 422 member_unverified_needs_confirm;確認後建單會留稽核紀錄並寄啟用信

--waitlist-if-sold-out
旗標 · 選填

梯次額滿時改建候補單:true 時額滿的梯次照樣建單,但訂單不佔名額、不能付款,排進該梯次的候補(與官網候補同一條隊,依建單先後)。有人釋出名額時系統依序遞補,並寄付款通知給客人。不看行程是否開放前台候補。抽籤梯次、不對外販售的梯次、人數大於梯次總名額時回 409 waitlist_unavailable;不能與 paymentMethod=cash 或手動折扣同用。省略時額滿回 409

--confirm
對 production target 寫入時必帶

回應欄位 · data

orderId
string

新建立訂單的 ID(ord_ 前綴)。

orderNumber
string

訂單編號(租戶內流水序號,對外顯示用)。

waitlisted
boolean

true = 梯次額滿,依 waitlistIfSoldOut 建成候補單:不佔名額、遞補前不能付款。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。

warnings
object[]

建單成功、但有資料沒存時的提醒;沒有時為空陣列。

code
"climbing_records_skipped"

climbing_records_skipped:旅客未填證件,代填的登山經歷沒有儲存。

message
string

給人看的提醒文字。

travelers
object[]

沒存的旅客:index 是 travelers 的位置(從 0 起算),skippedCount 是沒存的筆數。

index
number

旅客在輸入 travelers 的位置,從 0 起算。

fullName
string

旅客姓名(輸入值去掉前後空白)。

skippedCount
number

這位旅客沒存的登山經歷筆數。

範例
toko orders create --trip 'example-tripId' --departure 'example-departureId' --email '<e>' --party-size '1' --payment-method cash --travelers '[{"fullName":"Example Traveler","passportNo":"EX1234567"}]'
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "orderNumber": "…",
    "waitlisted": true,
    "retentionDeferred": true,
    "warnings": [
      {
        "code": "climbing_records_skipped",
        "message": "…",
        "travelers": [
          {
            "index": 0,
            "fullName": "…",
            "skippedCount": 0
          }
        ]
      }
    ]
  }
}
toko orders mark-paid

登記人工收款;可指定部分金額,省略金額則結清待收

參數

<id>位置參數 · 必填
--amount-twd <n>
旗標 · 選填

本次收款金額,TWD 正整數;省略則結清全部待收餘額

--idempotency-key <key>
旗標 · 選填

收款冪等鍵,8 至 64 字英數或連字號;重送同鍵不重複入帳

--bank-reference <t>
旗標 · 選填

匯款後五碼或銀行交易參考號,上限 40 字

--bank-credited-on <YYYY-MM-DD>
旗標 · 選填

入帳日期 YYYY-MM-DD;收款帳戶是銀行時必填

--over-the-counter
旗標 · 選填

臨櫃存款;銀行帳戶勾選後免填匯款後五碼

--provider-trade-no <t>
旗標 · 選填

金流訂單編號;收款帳戶是第三方金流時必填

--note <t>
旗標 · 選填

對帳備註,記錄人工核款說明

--receiving-account <id>
旗標 · 必填

收款帳戶 ID,指定本筆款項入帳的帳戶

--confirm
對 production target 寫入時必帶

回應欄位 · data

idempotent
boolean

true = 此請求已入帳或訂單已結清,本次未重複入帳。

collectedTwd
number

本次入帳金額;冪等重送為 0。

customerCashAppliedTwd
number

入帳後已收現金淨額。

outstandingTwd
number

入帳後待收餘額。

paymentState
"deposit_paid" | "overpaid" | "paid" | "partially_paid" | "unpaid"

入帳後付款狀態。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。

範例
toko orders mark-paid '<id>' --receiving-account 'example-receivingAccountId'
回應
{
  "ok": true,
  "data": {
    "idempotent": true,
    "collectedTwd": 0,
    "customerCashAppliedTwd": 0,
    "outstandingTwd": 0,
    "paymentState": "deposit_paid",
    "retentionDeferred": true
  }
}
toko orders cancel

依取消政策釋回席次;退款草稿掛實際收款單

參數

<id>位置參數 · 必填
--reason <t>
旗標 · 選填

取消事由說明

--cancellation-reason <admin|customer_request|no_show|other>
旗標 · 選填

取消政策事由;新單與舊鏈使用相同政策

--disposition <refund|keep>
旗標 · 選填

可退款項的去向:refund 開退款草稿,keep 留在原單成為保留款。admin 不帶時為 keep(退改費記 0);customer_request 不帶時照舊退款;其他事由不可帶;舊鏈只能 refund

--acknowledge-pending-remittance
旗標 · 選填

訂單有待確認的匯款回報時仍要取消。不帶時回 409 pending_remittance,請先確認或退回回報

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:訂單已取消(座位釋出、booking_state 轉 cancelled)。

refunds
object[]
orderId
string
orderNumber
string
refundId
string
refundNumber
string
amountTwd
number
remitFeeTwd選填
number | undefined
retentionDeferred
boolean

true = 回訪來源尚未同步,每日排程會補做;取消本身已完成。

範例
toko orders cancel '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "refunds": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "refundId": "…",
        "refundNumber": "…",
        "amountTwd": 0,
        "remitFeeTwd": 0
      }
    ],
    "retentionDeferred": true
  }
}
toko orders adjust

掛帳:加收 / 折讓(append charge line + 重算金流)

參數

<id>位置參數 · 必填
--kind <surcharge|allowance>
旗標 · 必填

調整類型:surcharge 加收、allowance 減免

--amount <twd>
旗標 · 必填

調整金額(新台幣,正整數)

--description <t>
旗標 · 必填

調整事由說明

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:訂單金額調整已套用。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。

範例
toko orders adjust '<id>' --kind surcharge --amount '1' --description 'example-description'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}
toko orders reverse

沖正既有應收項目(append reversal line)

參數

<id>位置參數 · 必填
--charge-line <id>
旗標 · 必填

欲沖正的應收項目(charge line)ID

--description <t>
旗標 · 必填

沖正事由說明

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:訂單已沖銷(沖回應收與已認列項)。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。

範例
toko orders reverse '<id>' --charge-line 'example-chargeLineId' --description 'example-description'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}
toko orders refund-create

建立並送審客戶退款(draft→submitted)

參數

<orderId>位置參數 · 必填
--amount <twd>
旗標 · 必填

退款總金額(新台幣,正整數)

--reason <t>
旗標 · 必填

退款事由說明

--kind <receivable_reduction|overpayment_return>
旗標 · 必填
--execution-method <m>
旗標 · 選填

退款執行方式:chargeback 原路退刷、remit 銀行匯款

--origin-account <id>
旗標 · 選填

出款來源帳戶 ID(匯款退款時指定)

--admin-fee <n>
旗標 · 選填

手續費/行政費(新台幣,非負整數)

--remit-fee <n>
旗標 · 選填

匯款轉帳費(新台幣,非負整數)

--payee-name <n>
旗標 · 選填
--payee-bank <c>
旗標 · 選填

受款銀行代碼(匯款退款時填寫)

--payee-branch <c>
旗標 · 選填

受款分行代碼(匯款退款時選填,4 碼數字;須存在於銀行/分行對照表,否則回 409 查無此分行)

--payee-account <n>
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

退款單 id(前綴 `rfnd_`)。

refundNumber
string

人類可讀退款單號。

status
"approved" | "cancelled" | "draft" | "failed" | "paid" | "processing" | "submitted"

退款工作流狀態:draft → submitted → approved → processing → paid。

範例
toko orders refund-create '<orderId>' --amount '1' --reason 'example-reason' --kind receivable_reduction
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "refundNumber": "…",
    "status": "approved"
  }
}
toko orders refund-approve

核准退款(責任分離:非建單人)

參數

<orderId>位置參數 · 必填
--refund <refundId>
旗標 · 必填

退款單 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:退款申請已核准。

範例
toko orders refund-approve '<orderId>' --refund 'example-refundId'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders refund-reject

退件退款(submitted→cancelled)

參數

<orderId>位置參數 · 必填
--refund <refundId>
旗標 · 必填

退款單 ID

--reason <t>
旗標 · 選填

退件事由說明

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:退款申請已駁回。

範例
toko orders refund-reject '<orderId>' --refund 'example-refundId'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders refund-cancel

取消待執行的退款單(拆單組一起取消,釋放可退額度;不出款)

參數

<orderId>位置參數 · 必填
--refund <refundId>
旗標 · 必填

退款單 ID

--reason <t>
旗標 · 必填

取消原因(必填,寫進稽核日誌)

--remit-not-sent-verified
旗標 · 選填

已確認這筆匯款沒有送出銀行轉帳,或銀行已退件(取消已核准的匯款單時必填 true)

--gateway-no-application-verified
旗標 · 選填

已確認金流商沒有受理申請、處理中或已完成的退款(取消已核准的人工刷退時必填 true)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:退款單已取消(拆單組一起),可退額度回到訂單。

範例
toko orders refund-cancel '<orderId>' --refund 'example-refundId' --reason 'example-reason'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders refund-paid

登記退款出款或送出原路退款;未明結果保留核對

參數

<orderId>位置參數 · 必填
--refund <refundId>
旗標 · 必填

退款單 ID

--receipt <id>
旗標 · 選填

原路退刷必填:公開金流核心的原信用卡收款 ID

--allocations <json>
旗標 · 選填

首次送出時固定跨商卡款分配;總額必須等於退款金額

--retry-of <id>
旗標 · 選填

重試時填已確認安全失敗的前次執行 ID

--bank-ref <t>
旗標 · 選填

出款的銀行交易參考號(匯款憑證)

--receiving-account <id>
旗標 · 選填

出款帳戶 ID;remit 退款須指定具匯款能力的帳戶

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

指令已處理;pending 或 unknown 不代表已退款。

gateway
"downgraded" | "not_applicable" | "pending" | "skipped_no_charge" | "succeeded" | "unknown"

pending:已受理;unknown:結果不明;succeeded:已確認個別退款;not_applicable:非刷退或既有已付紀錄。

skipReason
RefundGatewaySkipReason | null

新執行不降級記帳;此相容欄位為 null。

providerRefundNo
string | null

已確認的個別退款編號;未完成時為 null。

retentionDeferred
boolean

true = 回訪來源尚未同步,每日排程會補做;退款帳務本身已完成。

範例
toko orders refund-paid '<orderId>' --refund 'example-refundId'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "gateway": "downgraded",
    "skipReason": null,
    "providerRefundNo": "…",
    "retentionDeferred": true
  }
}
toko orders refund-unlock

解除原路退刷鎖定(DoAction 結果不明時 refund-paid 會被擋下)

參數

<orderId>位置參數 · 必填
--refund <refundId>
旗標 · 必填

退款單 ID

--note <查證依據>
旗標 · 必填

查證依據(必填,寫進稽核日誌)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:退刷鎖定已解除,退款單可重新標記已退(會再送一次退刷)。執行方式建單後 不可改,要改走人工匯款得另建一張 remit 退款單。

範例
toko orders refund-unlock '<orderId>' --refund 'example-refundId' --note 'example-note'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders assign

指派訂單給承辦業務(首派;pending_review→assigned)

參數

<id>位置參數 · 必填
--assignee <userId>
旗標 · 必填

受派業務的使用者 ID

--request-id <key>
旗標 · 必填

提交識別;重送同一提交時沿用此值

--reason <t>
旗標 · 選填

派發事由說明(上限 500 字)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:訂單已指派承辦。

idempotent
boolean

true = 原提交已完成,或受派者相同,本次沒有再次派發。

範例
toko orders assign '<id>' --assignee 'example-assigneeUserId' --request-id '2026-10-13'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "idempotent": true
  }
}
toko orders reassign

重新指派已派發訂單(admin-only;→reassigned)

參數

<id>位置參數 · 必填
--assignee <userId>
旗標 · 必填

重新指派的承接業務使用者 ID

--request-id <key>
旗標 · 必填

提交識別;重送同一提交時沿用此值

--reason <t>
旗標 · 選填

重派事由說明(上限 500 字)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:訂單已改派承辦。

idempotent
boolean

true = 原提交已完成,或受派者相同,本次沒有再次派發。

範例
toko orders reassign '<id>' --assignee 'example-assigneeUserId' --request-id '2026-10-13'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "idempotent": true
  }
}
toko orders bulk-assign

批次把多張訂單派給同一位業務(all-or-nothing)

參數

--assignee <userId>
旗標 · 必填

受派業務的使用者 ID(所有訂單派給同一人)

--orders <id,id,...>
旗標 · 必填
--request-id <key>
旗標 · 必填

提交識別;重送同一批次時沿用此值

--reason <t>
旗標 · 選填

派發事由說明(上限 500 字)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:批次指派已執行。

assignedCount
number

成功指派的訂單筆數。

skippedCount
number

略過的訂單筆數(如已指派或不在可指派範圍)。

範例
toko orders bulk-assign --assignee 'example-assigneeUserId' --orders '<id,id,...>' --request-id '2026-10-13'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "assignedCount": 0,
    "skippedCount": 0
  }
}
toko orders review-screening

人工核可/駁回登山資格審核,可帶範本寄信(駁回不自動退單)

參數

<id>位置參數 · 必填
--decision <approve|reject>
旗標 · 必填

登山資格審核裁決:approve 核可、reject 駁回

--disposition <resupplement|switch_trip|refund>
旗標 · 選填

駁回必填:resupplement 補件、switch_trip 換團、refund 退費;不自動取消或退款

--template-id <id>
旗標 · 選填

裁決後寄送的訊息範本 ID;核可與駁回都可帶。省略不寄信,寄信失敗不回滾裁決

--traveler-id <id>
旗標 · 選填

只裁決這一位旅客;省略 = 該單所有待審旅客一起裁決

--redecide
旗標 · 選填

重新裁決一列正在漂移的已人工裁決紀錄(需指名 travelerId);預設 false

--note <t>
旗標 · 選填

審核註記說明(上限 500 字);寄信時填入範本的 {{補充說明}}

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:名單複核結果已登錄。

followUpState
unknown

處置後追蹤狀態;退費或核可為 null。

emailSent
boolean

通知已加入寄送佇列;false 包含未選範本或寄送失敗。

範例
toko orders review-screening '<id>' --decision approve
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "followUpState": "…",
    "emailSent": true
  }
}
toko orders resolve-screening-follow-up

客人回覆並完成處置後,結束本單資格審核追蹤

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定 true:本單的待回覆審核追蹤已完成。

範例
toko orders resolve-screening-follow-up '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders traveler-add

新增旅客到訂單(owner-scope;出發前 7 天凍結,--acknowledge-roster-freeze 確認後放行;一般後台證件可後補;受管制抽籤或受限名額仍需證件)

參數

<orderId>位置參數 · 必填
--full-name <n>
旗標 · 必填

旅客全名,須與證件一致;新增旅客時必填,更新時可省略

--phone <p>
旗標 · 選填

旅客聯絡電話

--email <e>
旗標 · 選填

旅客電子郵件

--line-id <l>
旗標 · 選填

旅客 LINE ID

--english-name <n>
旗標 · 選填

英文姓名,須與護照一致(大寫英文、空白、連字號、逗號),否則回 422;海外團用

--nationality <n>
旗標 · 選填

國籍使用 ISO 3166-1 alpha-2 代碼;新增時省略代表 TW、更新時省略不改,空字串或 null 代表國籍未知,未知國名回 422

--birth-date <d>
旗標 · 選填

旅客出生日期(格式 YYYY-MM-DD)

--gender <male|female|other>
旗標 · 選填

旅客性別:male 男、female 女、other 其他

--id-number <n>
旗標 · 選填

身分證字號,屬個資將加密保存

--passport-no <n>
旗標 · 選填

護照號碼,屬個資將加密保存

--passport-expiry <d>
旗標 · 選填

護照效期(格式 YYYY-MM-DD);海外團效期提醒用

--room-pref <t>
旗標 · 選填

房型偏好(用於分房作業)

--roommate-pref <t>
旗標 · 選填

指定同住室友(用於分房作業)

--emergency-name <n>
旗標 · 選填
--emergency-phone <p>
旗標 · 選填
--address <a>
旗標 · 選填

旅客通訊地址

--acknowledge-roster-freeze
旗標 · 選填

員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:旅客已新增至訂單。

travelerId
string

新建立旅客的 ID(trv_ 前綴)。

範例
toko orders traveler-add '<orderId>' --full-name 'example-fullName'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "travelerId": "…"
  }
}
toko orders traveler-update

更新旅客資料(owner-scope;出發前 7 天凍結,--acknowledge-roster-freeze 確認後放行)

參數

<orderId>位置參數 · 必填
<travelerId>位置參數 · 必填
--full-name <n>
旗標 · 選填

旅客全名,須與證件一致;新增旅客時必填,更新時可省略

--phone <p>
旗標 · 選填

旅客聯絡電話

--email <e>
旗標 · 選填

旅客電子郵件

--line-id <l>
旗標 · 選填

旅客 LINE ID

--english-name <n>
旗標 · 選填

英文姓名,須與護照一致(大寫英文、空白、連字號、逗號),否則回 422;海外團用

--nationality <n>
旗標 · 選填

國籍使用 ISO 3166-1 alpha-2 代碼;新增時省略代表 TW、更新時省略不改,空字串或 null 代表國籍未知,未知國名回 422

--birth-date <d>
旗標 · 選填

旅客出生日期(格式 YYYY-MM-DD)

--gender <g>
旗標 · 選填

旅客性別:male 男、female 女、other 其他

--id-number <n>
旗標 · 選填

身分證字號,屬個資將加密保存

--passport-no <n>
旗標 · 選填

護照號碼,屬個資將加密保存

--passport-expiry <d>
旗標 · 選填

護照效期(格式 YYYY-MM-DD);海外團效期提醒用

--room-pref <t>
旗標 · 選填

房型偏好(用於分房作業)

--roommate-pref <t>
旗標 · 選填

指定同住室友(用於分房作業)

--emergency-name <n>
旗標 · 選填
--emergency-phone <p>
旗標 · 選填
--address <a>
旗標 · 選填

旅客通訊地址

--acknowledge-roster-freeze
旗標 · 選填

員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:旅客資料已更新。

範例
toko orders traveler-update '<orderId>' '<travelerId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders traveler-remove

移除旅客(owner-scope;至少保留一位、不可移主要聯絡人;出發前 7 天凍結,--acknowledge-roster-freeze 確認後放行)

參數

<orderId>位置參數 · 必填
<travelerId>位置參數 · 必填
--acknowledge-roster-freeze
旗標 · 選填

員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:旅客已自訂單移除。

範例
toko orders traveler-remove '<orderId>' '<travelerId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders rooming-pref

更新旅客分房需求(房型偏好/指定室友;owner-scope)

參數

<orderId>位置參數 · 必填
<travelerId>位置參數 · 必填
--room-pref <t>
旗標 · 選填

房型偏好(用於分房作業)

--roommate-pref <t>
旗標 · 選填

指定同住室友(用於分房作業)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:旅客分房設定已更新。

範例
toko orders rooming-pref '<orderId>' '<travelerId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders stats

訂單 KPI 統計

參數

--json
旗標 · 選填

回應欄位 · data

pendingPayment
number

待付款訂單數(未取消 / 未完成 / 未退款且 payment_state=unpaid)。

depositPaid
number

已付訂金訂單數(payment_state=deposit_paid)。

paid
number

已收齊訂單數(payment_state in paid/overpaid)。

cancelled
number

已取消訂單數(booking_state=cancelled)。

refunded
number

有退款的訂單數(refund_state in refunded/partially_refunded)。

completed
number

已完成訂單數(booking_state=completed)。

thisMonthPaidTwd
number

本月實收現金(payment_transactions direction=in 加總,TWD 整數)。

thisMonthNewOrders
number

本月新建訂單數。

thisMonthCancelled
number

本月取消訂單數(依 `cancelled_at` 計,台北月界)。不依 `updated_at` —— 取消之後的 退款或備註會把單推到錯的月份。`cancelled_at IS NULL` 的單任何月份都不計。

範例
toko orders stats
回應
{
  "ok": true,
  "data": {
    "pendingPayment": 0,
    "depositPaid": 0,
    "paid": 0,
    "cancelled": 0,
    "refunded": 0,
    "completed": 0,
    "thisMonthPaidTwd": 0,
    "thisMonthNewOrders": 0,
    "thisMonthCancelled": 0
  }
}
toko orders export

匯出訂單為 CSV/JSON(同 list 篩選 + owner-scope;取全頁)

參數

--status <s>
旗標 · 選填

依訂單顯示狀態篩選(如 pending、paid、cancelled)

--date-from <d>
旗標 · 選填

出發日期區間起(格式 YYYY-MM-DD,含當日)

--date-to <d>
旗標 · 選填

出發日期區間迄(格式 YYYY-MM-DD,含當日)

--q <t>
旗標 · 選填

關鍵字搜尋(訂單編號、訂購人姓名或 Email 等)

--assignment <a>
旗標 · 選填

依派發狀態篩選(如 unassigned、assigned)

--rooming <r>
旗標 · 選填

依分房狀態篩選

--agency-id <id>
旗標 · 選填

依合作旅行社 ID 篩選(同業單)

--format <csv|json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

rows
object[]

符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。

accounting
object

Display accounting amounts. The cash ledger remains unchanged.

orderReceivableTwd
number | null
cancellationFeePending
boolean
cancellationFeeTwd
number | null
refundFeesTwd
number | null

Completed administrative fees. Excludes bank fees.

percentageFeeTwd
number | null
fixedAdminFeeTwd
number | null
changeFeeTwd
number | null
unclassifiedFeeTwd
number | null

Unclassified historical fees remain separate.

refundRemainingTwd
number | null
cancelledCash
CancelledCash | null

已取消訂單的對帳現金(issue 1974):保留款轉移與現金收退分開算。 未取消的訂單為 null。

collectedTwd
number

已收現金:客人實際付進本單的錢,不含保留款轉入。

heldCashTransferredTwd
number

轉成保留款的淨額:保留款轉出減轉入。這筆錢還在保留款,或已折抵到別張訂單。 負數表示本單是用保留款折抵的(轉入多於轉出)。

customerRefundedTwd
number

已退給客人的現金:退款、刷退與沖正,不含保留款轉出與匯款手續費。

cancellationFeeDueTwd
number

客人還欠的退改費。應收不含這筆。0 = 沒有欠款。

kind
"lodging" | "tour"
id
string

訂單 id(前綴 `ord_`)。

orderNumber
string

人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。

bookingState
string

預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。

paymentState
string

付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。

refundState
string

退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。

grossReceivableTwd
number

應收(TWD 整數,派生自應收分類帳)。

collectedTwd
number

收到現金(TWD 整數,派生),含保留款轉入。已取消訂單對帳讀 `accounting.cancelledCash.collectedTwd`,那個數字不含保留款轉入(issue 1974)。

customerCashAppliedTwd
number

客戶現金淨套用(收款減已退現金,TWD 整數,派生)。

refundableCashTwd
number

可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。

outstandingTwd
number

未收(應收減客戶現金淨套用,TWD 整數,派生)。

partySize
number

參團人數(tour 訂單)。

createdAt
string

訂單建立時間。

notes
string | null

訂單備註(未填 → null)。

userId
string

下單客戶的 user id(同庫 user 表)。

userName
string

下單客戶顯示名。

userEmail
string

下單客戶 Email。

primaryTravelerName
string | null

主要旅客姓名(is_primary,未登記 → null)。

primaryTravelerPhone
string | null

主要旅客電話(未登記 → null)。

tripId
string

行程 id(tour 訂單經梯次反查;lodging 為空字串)。

tripTitle
string

行程 / 產品標題。

tripShortName
string | null

行程內部簡稱(issue 1414);未填或訂房訂單為 null。

tripSlug
string

行程 slug。

departureId
string

梯次 id(tour 訂單;lodging 為空字串)。

departureDate
string

出發日 YYYY-MM-DD(lodging 為入住日)。

returnDate
string

回程日 YYYY-MM-DD(lodging 為退房日)。

assignedToUserId
string | null

派發給哪位業務的 user id(未派發 → null)。

assigneeName
string | null

承辦業務顯示名(未派發 / 查無 → null)。

assignmentStatus
string

派發狀態:unassigned / assigned / reassigned / pending_review。

assignedAt
string | null

最近一次派發時間(未派發 → null)。

assignedByUserId
string | null

執行派發者的 user id(未派發 → null)。

createdByUserId
string | null

S5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.

pendingConsent
boolean

是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。

roomingStatus
"assigned" | "needs_single" | "registered" | "unregistered"

分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。

lotteryState
string | null

抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。

failoverFromOrderId
string | null

備案訂單所對應的原訂單 ID。

isOverdue
boolean

是否有已到期、尚未收齊的收款計畫。

receiptAllocationNeedsReorder
boolean

收據分配要重排(issue 1942):公司收據加總超過應收。訂單列表 `?receipt=needs_reorder` 與工作台待辦同一個口徑。

total
number

符合篩選條件的總筆數。

truncated
boolean

是否因達安全上限而截斷(true 表未回傳完整結果,呼叫端應提示)。

範例
toko orders export
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "accounting": {
          "orderReceivableTwd": 0,
          "cancellationFeePending": true,
          "cancellationFeeTwd": 0,
          "refundFeesTwd": 0,
          "percentageFeeTwd": 0,
          "fixedAdminFeeTwd": 0,
          "changeFeeTwd": 0,
          "unclassifiedFeeTwd": 0,
          "refundRemainingTwd": 0,
          "cancelledCash": null
        },
        "kind": "lodging",
        "id": "…",
        "orderNumber": "…",
        "bookingState": "…",
        "paymentState": "…",
        "refundState": "…",
        "grossReceivableTwd": 0,
        "collectedTwd": 0,
        "customerCashAppliedTwd": 0,
        "refundableCashTwd": 0,
        "outstandingTwd": 0,
        "partySize": 0,
        "createdAt": "…",
        "notes": "…",
        "userId": "…",
        "userName": "…",
        "userEmail": "…",
        "primaryTravelerName": "…",
        "primaryTravelerPhone": "…",
        "tripId": "…",
        "tripTitle": "…",
        "tripShortName": "…",
        "tripSlug": "…",
        "departureId": "…",
        "departureDate": "…",
        "returnDate": "…",
        "assignedToUserId": "…",
        "assigneeName": "…",
        "assignmentStatus": "…",
        "assignedAt": "…",
        "assignedByUserId": "…",
        "createdByUserId": "…",
        "pendingConsent": true,
        "roomingStatus": "assigned",
        "lotteryState": "…",
        "lotteryWaitlisted": true,
        "failoverFromOrderId": "…",
        "isOverdue": true,
        "receiptAllocationNeedsReorder": true
      }
    ],
    "total": 0,
    "truncated": true
  }
}
toko orders claim

認領待派發訂單

參數

<id>位置參數 · 必填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:訂單已由當前承辦認領。

範例
toko orders claim '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders message-preview

預覽訂單罐頭訊息

參數

<id>位置參數 · 必填
--template <value>
旗標 · 選填

訊息範本 ID(line 或 email 通道皆可)

--json
旗標 · 選填

回應欄位 · data

channel
string

範本通道:line 或 email。

subject
string

代入本訂單變數後的標題(email 為信件主旨)。

body
string

代入本訂單變數後的內文。

missingVars
string[]

範本引用但本訂單沒有值的變數名;成品裡仍是 `{{變數}}` 原樣,貼出前要手動處理。

範例
toko orders message-preview '<id>'
回應
{
  "ok": true,
  "data": {
    "channel": "…",
    "subject": "…",
    "body": "…",
    "missingVars": [
      "…"
    ]
  }
}
toko orders discount-preview

依建單定價試算折扣

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填
範例
toko orders discount-preview
回應
{
  "ok": true,
  "data": "…"
}
toko orders quote

試算 K 單金額(含訂金與尾款)

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

quote
object

金額試算:單價、小計、折扣、總計、實際付款方案與訂金 / 尾款。

unitPriceTwd
number
partySize
number
subtotalTwd
number

折前小計 = 單價 × 人數。

discountTwd
number
totalTwd
number

折後總計,也就是訂單應收。

paymentPlan
"deposit" | "full"

實際採用的付款方案:訂金方案拆不出尾款時改成全額。

depositDueTwd
number
balanceDueTwd
number
discount
ManualOrderQuoteDiscount

優惠碼結果:none 沒有碼 / applied 已折抵 / rejected 被拒(帶 reason,數字不折)。

範例
toko orders quote
回應
{
  "ok": true,
  "data": {
    "quote": {
      "unitPriceTwd": 0,
      "partySize": 0,
      "subtotalTwd": 0,
      "discountTwd": 0,
      "totalTwd": 0,
      "paymentPlan": "deposit",
      "depositDueTwd": 0,
      "balanceDueTwd": 0
    },
    "discount": "…"
  }
}
toko orders remit-accounts

取得訂單收款帳戶候選

參數

--json
旗標 · 選填

回應欄位 · data[]

id
string

收款帳戶 ID(標記已退款時當出款帳戶帶入)。

code
string

帳戶代碼(租戶自訂短碼)。

displayName
string

顯示名稱(下拉選項用)。

範例
toko orders remit-accounts
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…"
    }
  ]
}
toko orders agreements-reissue

執行 orders/[id]/agreements/[agreementId]/reissue

參數

<id>位置參數 · 必填
<agreementId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko orders agreements-reissue '<id>' '<agreementId>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko orders agreements-resend-copy

執行 orders/[id]/agreements/[agreementId]/resend-copy

參數

<id>位置參數 · 必填
<agreementId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

delivery
"failed" | "no_email" | "queued" | "sent"
範例
toko orders agreements-resend-copy '<id>' '<agreementId>'
回應
{
  "ok": true,
  "data": {
    "delivery": "failed"
  }
}
toko orders agreements-resign

重新簽署已簽契約:舊版標為已由新版取代,產生新契約並寄簽署信

參數

<id>位置參數 · 必填
<agreementId>位置參數 · 必填
--data <'{"reason":"traveler_error","note":"..."}'>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
newAgreementId
string
範例
toko orders agreements-resign '<id>' '<agreementId>' --data '{"reason":"traveler_error"}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "newAgreementId": "…"
  }
}
toko orders agreements-revoke

執行 orders/[id]/agreements/[agreementId]/revoke

參數

<id>位置參數 · 必填
<agreementId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko orders agreements-revoke '<id>' '<agreementId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko orders agreements-generate

執行 orders/[id]/agreements/generate

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

skipped
SyncSkipReason | null

整單層級略過原因;null = 有處理逐旅客。

issued
string[]
revoked
string[]
failures
object[]
travelerId
string
travelerName
string
reason
"missing_vars" | "no_email" | "unknown_vars"
vars
string[]
missingTemplateTypes
"domestic_group" | "domestic_individual" | "overseas_group" | "overseas_individual"[]

這張單上「行程類型對得到種類、但該種類沒有範本」的契約種類(#585)。非空 = 那些梯次 fail-closed 不產生,既有待簽列也已撤銷。呼叫端必須顯示,否則就成了第 6 種靜默失效。

範例
toko orders agreements-generate '<id>'
回應
{
  "ok": true,
  "data": {
    "skipped": null,
    "issued": [
      "…"
    ],
    "revoked": [
      "…"
    ],
    "failures": [
      {
        "travelerId": "…",
        "travelerName": "…",
        "reason": "missing_vars",
        "vars": [
          "…"
        ]
      }
    ],
    "missingTemplateTypes": [
      "domestic_group"
    ]
  }
}
toko orders agreements-list

查詢 orders/[id]/agreements

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
orderId
string
departureId
string
departureDate
string

梯次出發日(ISO date);一張單多梯時用來標示這份契約屬哪一梯。

participationVersion選填
number | undefined
isCurrent選填
boolean | undefined
travelerId
string | null
travelerName
string | null
status
"pending" | "revoked" | "signed" | "superseded"
templateVersion
number
contractDate
string
providedAt
string
tokenExpiresAt
string
signedAt
string | null
signerName
string | null
signerIp
string | null
article32Agreed
boolean | null
signingPayload
Record<string, unknown> | null
evidenceSha256
string | null
contentSha256
string
hasPdf
boolean
deliveredAt
string | null
deliveryAddress
string | null
revokedAt
string | null
revokeReason
string | null
supersededAt
string | null

已由新版取代的時間、理由與承辦補充(#2054);非 superseded 列為 null。

supersedeReason
"traveler_error" | "traveler_request" | "staff_correction" | null
supersedeNote
string | null
supersededById
string | null

取代這一份的新契約 id(superseded 列才有)。

supersedesId
string | null

這一份取代的舊契約 id(重新簽署產生的新列才有)。

lastSyncedAt
string | null

sync 最後檢視時間(排程漂移訊號的基準)。

範例
toko orders agreements-list '<id>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "orderId": "…",
      "departureId": "…",
      "departureDate": "…",
      "participationVersion": 0,
      "isCurrent": true,
      "travelerId": "…",
      "travelerName": "…",
      "status": "pending",
      "templateVersion": 0,
      "contractDate": "…",
      "providedAt": "…",
      "tokenExpiresAt": "…",
      "signedAt": "…",
      "signerName": "…",
      "signerIp": "…",
      "article32Agreed": true,
      "signingPayload": "…",
      "evidenceSha256": "…",
      "contentSha256": "…",
      "hasPdf": true,
      "deliveredAt": "…",
      "deliveryAddress": "…",
      "revokedAt": "…",
      "revokeReason": "…",
      "supersededAt": "…",
      "supersedeReason": "traveler_error",
      "supersedeNote": "…",
      "supersededById": "…",
      "supersedesId": "…",
      "lastSyncedAt": "…"
    }
  ]
}
toko orders backup-choices-update

更新 orders/[id]/backup-choices

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
chosen
string[]
範例
toko orders backup-choices-update '<id>' --data '{"departureIds":["example-departureIds"]}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "chosen": [
      "…"
    ]
  }
}
toko orders cancel-failover

執行 orders/[id]/cancel-failover

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
headOrderId
string

鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。

refunds
object[]

實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。

orderId
string
orderNumber
string
refundId
string
refundError
string | null

需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。

refundTotals
object

本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。

amountTwd
number
adminFeeTwd
number
remitFeeTwd
number
filingFee
FilingFeeBreakdown | null

逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。

totalTwd
number

逐旅客費率的加總。

lines
object[]

逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。

seq
number
feeTwd
number

這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。

travelerName
string | null

送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 null —— `traveler_id` 是不帶 FK 的快照 id,join 不到是合法狀態。

範例
toko orders cancel-failover '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "headOrderId": "…",
    "refunds": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "refundId": "…"
      }
    ],
    "refundError": "…",
    "refundTotals": {
      "amountTwd": 0,
      "adminFeeTwd": 0,
      "remitFeeTwd": 0
    },
    "filingFee": null
  }
}
toko orders cancel-lottery-lost

執行 orders/[id]/cancel-lottery-lost

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
notified
"failed" | "no_recipient" | "no_template" | "sent" | "skipped"
headOrderId
string

鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。

refunds
object[]

實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。

orderId
string
orderNumber
string
refundId
string
refundError
string | null

需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。

refundTotals
object

本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。

amountTwd
number
adminFeeTwd
number
remitFeeTwd
number
filingFee
FilingFeeBreakdown | null

逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。

totalTwd
number

逐旅客費率的加總。

lines
object[]

逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。

seq
number
feeTwd
number

這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。

travelerName
string | null

送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 null —— `traveler_id` 是不帶 FK 的快照 id,join 不到是合法狀態。

範例
toko orders cancel-lottery-lost '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "notified": "failed",
    "headOrderId": "…",
    "refunds": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "refundId": "…"
      }
    ],
    "refundError": "…",
    "refundTotals": {
      "amountTwd": 0,
      "adminFeeTwd": 0,
      "remitFeeTwd": 0
    },
    "filingFee": null
  }
}
toko orders force-place

執行 orders/[id]/force-place

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

retentionDeferred
boolean

true = 回訪來源或期間尚未同步,每日排程會補做;安置本身已完成。

ok
true
orderId
string
departureChangeId
string
範例
toko orders force-place '<id>' --data '{"targetDepartureId":"example-targetDepartureId"}'
回應
{
  "ok": true,
  "data": {
    "retentionDeferred": true,
    "ok": "…",
    "orderId": "…",
    "departureChangeId": "…"
  }
}
toko orders release-identity-hold

執行 orders/[id]/release-identity-hold

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko orders release-identity-hold '<id>' --data '{"reason":"example-reason"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko orders send-balance-slip

執行 orders/[id]/send-balance-slip

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
emailSent
boolean

True when this call adds a queue entry. Delivery is still pending.

outcome
"already_sent" | "no_recipient" | "no_template" | "queued"

The queue result for this request.

範例
toko orders send-balance-slip '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "emailSent": true,
    "outcome": "queued"
  }
}
toko orders send-message

執行 orders/[id]/send-message

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko orders send-message '<id>' --data '{"templateId":"example-templateId"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko orders split-traveler

預覽或確認拆出旅客:一位旅客搬到新訂單,可同梯或換到同行程別梯

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
orderId
string
preview選填
TravelerSplitPreview | undefined

Present after a preview. Send its previewToken on the confirmation.

previewToken
string
sourceOrderId
string
travelerId
string
travelerName
string
sourceDepartureId
string
targetDepartureId
string
sameDeparture
boolean
unitPriceTwd
number
money
object
sourceReceivableBeforeTwd
number
sourceReceivableAfterTwd
number
newReceivableTwd
number
suggestedTransferTwd
number

系統建議值:依應收比例分配原單的有效已付款(§3.5)。

maxTransferTwd
number
transferTwd
number
transferOverridden
boolean
sourceOverpaymentTwd
number

拆出後原單多收、要開溢收退款草稿的金額。

keptOnSourceTwd
object

留在原單、不分攤的折扣、人工調整與房型升等合計(§6 M2)。

discountTwd
number
adjustmentTwd
number
roomUpgradeTwd
number
newOrderSchedules
object
firstPurpose
"deposit" | "full"
depositTwd
number
balanceTwd
number
depositOutstandingTwd
number
nextPurpose
"full" | "deposit" | "balance" | null
nextTwd
number
newOrderBalanceDueAt
string | null
clears
object

這位旅客目前在分房、同行組裡;拆出後清空。

room
boolean
companionGroup
boolean
newOrderId選填
string | undefined
newOrderNumber選填
string | undefined
splitId選填
string | undefined
transferTwd選填
number | undefined
refundDraftId選填
string | null | undefined

Overpayment refund draft on the source order. null = no overpayment.

idempotent選填
boolean | undefined

true = a retry of a completed request.

departureChange選填
{ ok: true; departureChangeId: string; } | { ok: false; reason: DepartureChangeFailure; } | undefined

The departure change of the new order, for another target departure. On failure the split stays done and the new order stays on the source departure.

範例
toko orders split-traveler '<id>' --data '{"travelerId":"example-travelerId"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "orderId": "…",
    "preview": "…",
    "newOrderId": "…",
    "newOrderNumber": "…",
    "splitId": "…",
    "transferTwd": 0,
    "refundDraftId": "…",
    "idempotent": true,
    "departureChange": "…"
  }
}
toko orders withdraw-traveler

預覽或確認旅客退出:減一席、減一人應收、收取消費,再退款或轉保留款

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
orderId
string
preview選填
TravelerWithdrawPreview | undefined

Present after a preview. Send its previewToken on the confirmation.

previewToken
string
orderId
string
travelerId
string
travelerName
string
departureId
string
shareTwd
number

這位旅客的團費份額(成交單價;搬入舊單用每人單價)。

daysUntilDeparture
number
tier
CancellationFeeTier | null
daysBefore
number

距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。

feePercent選填
number | undefined

扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。

feeFixedTwd選填
number | undefined

定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。

feeBasis
string

命中級距連基準的人話(`成交總額的 80%`/`每人 NT$ 200`)。

tierFeeTwd
number

階梯照章算出的取消費。

feeTwd
number

取消費:照章金額,上限是這位旅客分到的已付款。減免前的金額。

waiverTwd
number

減免金額。

waiverDirect
boolean

true=減免當下生效;false=減免進少收待核,先照取消費全額退出。

netFeeTwd
number

實收取消費:直接生效的減免已扣掉。

paidShareTwd
number

這位旅客分到的已付款(依應收比例)。

transferTwd
number

轉到退出新單的錢:實收取消費加上可退金額。

refundableTwd
number

可退金額(尚未扣退款單的轉帳費)。

receivableBeforeTwd
number
receivableAfterTwd
number
outstandingAfterTwd
number

退出後原單還要收的錢。

sourceOverpaidAfterTwd
number

退出後原單仍多收的錢。原單本來多收超過這位旅客的已付款時才大於 0;確認時在原單開溢收 退款草稿,與拆出相同(§3.5)。

rosterFrozen
boolean

出發前 6 天內(名單凍結)。

lottery
boolean

抽籤單:提醒入園證與保險名單要另外處理。

holdAvailable
boolean

這張單能不能把可退金額轉成保留款。

clears
object
room
boolean
companionGroup
boolean
withdrawalId選填
string | undefined

Withdrawal record ID.

withdrawalOrderId選填
string | undefined

Cancelled order that holds the cancellation fee and the refund. Not in daily order lists.

feeTwd選填
number | undefined

Cancellation fee that the company keeps.

refundableTwd選填
number | undefined

Refundable amount before the remittance fee.

disposition選填
"refund" | "keep" | null | undefined

Where the refundable amount went. null = nothing to refund.

refundIds選填
string[] | undefined

Refund drafts on the withdrawal order.

retainedFundId選填
string | null | undefined

Retained fund for the orderer, when disposition is keep.

waiver選填
{ requestId: string; amountTwd: number; applied: boolean; } | null | undefined

Fee waiver request. applied=false = waits for underpayment approval.

requestId
string
amountTwd
number
applied
boolean
idempotent選填
boolean | undefined

true = a retry of a completed request.

範例
toko orders withdraw-traveler '<id>' --data '{"travelerId":"example-travelerId"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "orderId": "…",
    "preview": "…",
    "withdrawalId": "…",
    "withdrawalOrderId": "…",
    "feeTwd": 0,
    "refundableTwd": 0,
    "disposition": "refund",
    "refundIds": "…",
    "retainedFundId": "…",
    "waiver": "…",
    "idempotent": true
  }
}
toko orders transfer-departure

預覽或確認訂單原地換梯;跨行程目標帶 crossTrip

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
orderId
string
departureChangeId選填
string | undefined
preview選填
DepartureChangePreview | undefined

Includes current document requirements, retained consents, and passport expiry warnings.

canRetainSurplus選填
boolean | undefined
arrangements
object
roomFeeBeforeTwd
number
roomFeeAfterTwd
number
otherRoomOrderCount
number
otherRoomFeeDeltaTwd
number
otherRefundDraftTwd
number
releasedRoomCount
number
releasedPretripStayCount
number
tasks
object[]
travelerId
string
kind
"pretrip_stay" | "room" | "survey"
label
string
fingerprint
string
previewToken
string
paymentWindowHours
number | null
expiresAt
string
documents
object
agreementEnabled
boolean
versioningReady
boolean
agreementCount
number
agreementPending
number
agreementHistory
number
consents
object[]
label
string
version
number
pending
number
retained
number
due
boolean
passportExpiryWarnings
number
fingerprint
string
crossTrip選填
CrossTripChangeSnapshot | undefined
sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
price_twd
number | null
agency_price_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
promo_active
boolean | null
promo_price_twd
number | null
promo_agency_price_twd
number | null
trip
object
direct_price_twd
number | null
agency_price_twd
number | null
price_from_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
deposit_basis
DepositBasis | null

schema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。

unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

basis
"per_amount" | "per_travelers"
step
number

N:每幾位旅客 / 每滿幾元。

unitTwd
number

每次折多少(碼的折扣值)。

units
number

折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
selfService選填
SelfServiceChangeSnapshot | undefined
repricing
object

The target fare at its current price. Same shape as a cross-trip quote, without answers.

sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
price_twd
number | null
agency_price_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
promo_active
boolean | null
promo_price_twd
number | null
promo_agency_price_twd
number | null
trip
object
direct_price_twd
number | null
agency_price_twd
number | null
price_from_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
deposit_basis
DepositBasis | null

schema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。

unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

basis
"per_amount" | "per_travelers"
step
number

N:每幾位旅客 / 每滿幾元。

unitTwd
number

每次折多少(碼的折扣值)。

units
number

折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
fee
object
tier
CancellationFeeTier | null
daysBefore
number

距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。

feePercent選填
number | undefined

扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。

feeFixedTwd選填
number | undefined

定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。

amountTwd
number
description
string

charge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。

surplus
"keep_overpaid" | "refund_draft"
remitFeeTwd
number
lottery選填
LotteryChangeSnapshot | undefined
sourceMode
string
targetMode
string
stateBefore
string | null
stateAfter
"applied" | "won" | null

`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.

placement選填
true | undefined
failover選填
Omit<LotteryFailoverStep, "applicationKey"> | undefined

Set when the backup failover made the change. A general target confirms the seat (`won`).

skipped
object[]

Backup choices that the failover skipped before this one.

rank
number
departureId
string
reason
"identity_missing" | "not_same_trip" | "price_changed" | "roster_invalid" | "unavailable"
notFormed選填
boolean | undefined
notFormedDepartureId選填
string | undefined
hitRank
number

Rank of the backup choice that this step tries.

remainingDepartureIds
string[]

Backup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.

applicationKeyBefore
string
applicationId選填
string | undefined

Set on confirmation: the new application uses the departure change ID.

legacyChain選填
LegacyChainNode[] | undefined
effectiveCreditTwd選填
number | undefined
policyTotalTwd選填
number | undefined
refundDrafts選填
{ id: string; orderId: string; amountTwd: number; }[] | undefined
participationVersion
number
equipment
object
blocked
boolean
rentals
object[]
rentalId
string
rentalCode
string
departureId
string | null
rentStartDate
string | null
rentEndDate
string | null
returnState
string
reconState
string
deliveredAt
string | null
depositClearedAt
string | null
rentTotalTwd
number

租借單的租金與押金合計。只是租借單的事實,換梯不搬這些錢。

depositTotalTwd
number
replacesRentalId
string | null
ready
boolean
blocker
string | null
lines
object[]
itemId
string
name
string | null
quantity
number
committedQuantity
number
paymentWindowStartedAt選填
string | undefined
sourceFingerprint
string
rosterFingerprint
string
source
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
target
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
totalTwd
number
unitPriceTwd
number
discountTwd
number
chargeLines
object[]
id
string
type
string
amount_twd
number
description
string
depositTwd
number
balanceTwd
number
balanceDueAt
string | null
receipts
object
blocked
boolean
receipts
object[]
id
string
merchantOrderNo
string
status
string
invoiceNumber
string | null
invoiceTransNo
string | null
submitted
boolean
operationPending
boolean
lastError
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
totalAmtTwd
number
updatedAt
string
resolution
"cancel_scheduled" | "invalidate" | "none" | "reconcile" | "reprepare"
target
object
tourName
string
tourNo
string | null
tourDate
string
totalAmtTwd
number
collectedTwd
number
returnedTwd
number
paidRefundFeesTwd
number
customerCashAppliedTwd
number
outstandingTwd
number
refundHeadroom
object
grossReceivableTwd
number

當前應收。

refundableCashTwd
number

可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。

assessedCancellationFeeTwd
number

此實收單保留的退改費;舊資料沿用人工核算基準。

openRefundGrossTwd
number

同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。

openRefundCount
number

同單其他未執行退款的張數。

openReceivableReductionTwd
number

同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。

carriedToLiveBackupsTwd
number

已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。

assessmentPending
boolean

人工核算單、退改費尚未核算。

baseTwd
number

額度基準 = 可退現金 − 上面三項扣減,下限 0。

surplusDisposition選填
"refund" | "retain" | undefined
retainedFundId選填
string | undefined
overpaymentRefundTwd
number
depositOutstandingTwd
number
nextPaymentPurpose
"full" | "deposit" | "balance" | null
nextPaymentTwd
number
moneyFingerprint
string
refundDraftId選填
string | undefined
retentionDeferred選填
boolean | undefined

true = 回訪期間尚未同步,每日排程會補做;換梯本身已完成。

範例
toko orders transfer-departure '<id>' --data '{"targetDepartureId":"example-targetDepartureId"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "orderId": "…",
    "departureChangeId": "…",
    "preview": "…",
    "retentionDeferred": true
  }
}
toko orders cross-trip-targets

搜尋跨行程換梯的目標梯次(最多 50 筆)

參數

<id>位置參數 · 必填
--q <value>
旗標 · 選填

搜尋行程名稱、日期、梯次標籤或 ID;最多回傳 50 筆

--json
旗標 · 選填

回應欄位 · data[]

departureId
string
label
string
範例
toko orders cross-trip-targets '<id>'
回應
{
  "ok": true,
  "data": [
    {
      "departureId": "…",
      "label": "…"
    }
  ]
}
toko orders cross-trip-quote

試算跨行程換梯報價,不改訂單

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填

回應欄位 · data

quote
object
orderId
string
participationVersion
number
sourceVersion
string
quoteFingerprint
string
quotedAt
string
expiresAt
string
confirmationAvailable
boolean

True when this order can continue to the departure change preview.

source
object
departureId
string
tripId
string
title
string
date
string
target
object
departureId
string
tripId
string
title
string
date
string
priceChannel
"agency" | "direct"
priceSource
"departure" | "legacy" | "promo" | "trip"
partySize
number
originalFareTwd
number
targetFareTwd
number
originalDiscountTwd
number
targetDiscountTwd
number
originalProfitShareTwd
number
targetProfitShareTwd
number
discount
object
code
string | null
status
"applied" | "none" | "rejected"
reason
DiscountReason | null
existingLines
object[]
id
string
type
string
description
string
amountTwd
number
category
"adjustment" | "ancillary" | "discount" | "fare"
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null | undefined
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
originalReceivableTwd
number
targetReceivableTwd
number
differenceTwd
number
collectedTwd
number
returnedCashTwd
number
paidRefundFeesTwd
number
effectivePaidTwd
number
outstandingTwd
number
refundableTwd
number
overpaymentRefundTwd
number
depositTargetTwd
number
depositOutstandingTwd
number
balanceOutstandingTwd
number
depositDueAt
string | null
balanceDueAt
string | null

Null when the target is a lottery departure: the due date is set at the win.

tasks
string[]
blockers
string[]
範例
toko orders cross-trip-quote '<id>' --data '{"targetDepartureId":"example-targetDepartureId"}'
回應
{
  "ok": true,
  "data": {
    "quote": {
      "orderId": "…",
      "participationVersion": 0,
      "sourceVersion": "…",
      "quoteFingerprint": "…",
      "quotedAt": "…",
      "expiresAt": "…",
      "confirmationAvailable": true,
      "source": {
        "departureId": "…",
        "tripId": "…",
        "title": "…",
        "date": "…"
      },
      "target": {
        "departureId": "…",
        "tripId": "…",
        "title": "…",
        "date": "…"
      },
      "priceChannel": "agency",
      "priceSource": "departure",
      "partySize": 0,
      "originalFareTwd": 0,
      "targetFareTwd": 0,
      "originalDiscountTwd": 0,
      "targetDiscountTwd": 0,
      "originalProfitShareTwd": 0,
      "targetProfitShareTwd": 0,
      "discount": {
        "code": "…",
        "status": "applied",
        "reason": null
      },
      "existingLines": [
        {
          "id": "…",
          "type": "…",
          "description": "…",
          "amountTwd": 0,
          "category": "adjustment"
        }
      ],
      "adjustment": "price_hold",
      "originalReceivableTwd": 0,
      "targetReceivableTwd": 0,
      "differenceTwd": 0,
      "collectedTwd": 0,
      "returnedCashTwd": 0,
      "paidRefundFeesTwd": 0,
      "effectivePaidTwd": 0,
      "outstandingTwd": 0,
      "refundableTwd": 0,
      "overpaymentRefundTwd": 0,
      "depositTargetTwd": 0,
      "depositOutstandingTwd": 0,
      "balanceOutstandingTwd": 0,
      "depositDueAt": "…",
      "balanceDueAt": "…",
      "tasks": [
        "…"
      ],
      "blockers": [
        "…"
      ]
    }
  }
}
toko orders climbing-record-delete

刪除 orders/[id]/travelers/[travelerId]/climbing-records/[recordId]

參數

<id>位置參數 · 必填
<travelerId>位置參數 · 必填
<recordId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko orders climbing-record-delete '<id>' '<travelerId>' '<recordId>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko orders climbing-records-list

查詢 orders/[id]/travelers/[travelerId]/climbing-records

參數

<id>位置參數 · 必填
<travelerId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
label
string
gradeScore
number | null
systemGradeScore
number | null
hasAlpineExperience
boolean
climbedOn
string | null
durationValue
number | null

完成時間(自填,選填);未填兩欄皆 null。

durationUnit
"day" | "hour" | null
createdAt
string
範例
toko orders climbing-records-list '<id>' '<travelerId>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "label": "…",
      "gradeScore": 0,
      "systemGradeScore": 0,
      "hasAlpineExperience": true,
      "climbedOn": "…",
      "durationValue": 0,
      "durationUnit": "day",
      "createdAt": "…"
    }
  ]
}
toko orders climbing-record-add

執行 orders/[id]/travelers/[travelerId]/climbing-records

參數

<id>位置參數 · 必填
<travelerId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
recordId
string
範例
toko orders climbing-record-add '<id>' '<travelerId>' --data '{"label":"example-label"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "recordId": "…"
  }
}
toko orders remittance-lookup

查詢 orders/remittance-lookup

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填

回應欄位 · data

orderId
string
orderNumber
string
customerName
string
tripTitle
string | null
outstandingTwd
number
bookingState
string
paymentState
"deposit_paid" | "overpaid" | "paid" | "partially_paid" | "unpaid"
範例
toko orders remittance-lookup --data '{"orderNumber":"example-orderNumber"}'
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "orderNumber": "…",
    "customerName": "…",
    "tripTitle": "…",
    "outstandingTwd": 0,
    "bookingState": "…",
    "paymentState": "deposit_paid"
  }
}
toko orders split-remittance

執行 orders/split-remittance

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

retentionDeferred
boolean
ok
true
idempotent
boolean
remittanceId
string
orders
object[]
orderId
string
orderNumber
string
collectedTwd
number
customerCashAppliedTwd
number
outstandingTwd
number
paymentState
"deposit_paid" | "overpaid" | "paid" | "partially_paid" | "unpaid"
範例
toko orders split-remittance --data '{"totalTwd":3000,"allocations":[{"orderId":"ord_example1","amountTwd":1000},{"orderId":"ord_example2","amountTwd":2000}],"idempotencyKey":"split-20261013-001","receivingAccountId":"rcv_example"}'
回應
{
  "ok": true,
  "data": {
    "retentionDeferred": true,
    "ok": "…",
    "idempotent": true,
    "remittanceId": "…",
    "orders": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "collectedTwd": 0,
        "customerCashAppliedTwd": 0,
        "outstandingTwd": 0,
        "paymentState": "deposit_paid"
      }
    ]
  }
}

toko control

團控:梯次列表、名單、驗證、分房、財務、報表

toko control departures

近期梯次主列表(團控面板)

參數

--range <future_60|future_90|future_180|future_365|this_month|next_month|custom>
旗標 · 選填

時間視窗:future_60 / future_90 / future_180(預設)/ future_365(未來 N 天)、this_month(本月)、next_month(下個月)、custom(自訂,配 from / to)

--from <YYYY-MM-DD>
旗標 · 選填

自訂區間起日 YYYY-MM-DD(含),range=custom 時必填

--to <YYYY-MM-DD>
旗標 · 選填

自訂區間迄日 YYYY-MM-DD(含),range=custom 時必填;from ≤ to,最長 731 天,超過回 400

--trip <id>
旗標 · 選填

行程 ID,只看該行程的梯次

--status <s>
旗標 · 選填

梯次狀態篩選(如 open / closed)

--attention
旗標 · 選填

設為 true 時只回傳需要關注的梯次:有人未結清、有訂單未簽同意書,或有缺件(已成團未派主要隨團人員、未派承辦、隨團人員不足(已成團、需要數已填且確認人數少於需要數)、期限逾期或將到期、資料待補或資格待審、未分房)。已結束的梯次預設不列;同時指定 status 時,那些梯次只看付款與同意書

--mine
旗標 · 選填

設為 true 時只回傳我是承辦小編的梯次;只對 op / admin 生效,其他角色忽略

--json
旗標 · 選填

回應欄位 · data[]

id
string

梯次 id。

tripId
string

所屬行程 id。

tripTitle
string

行程名稱。

tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

hasPreTripNight
boolean

行程有行前集合夜:出發日前一晚集合(trips.md §3)。

tripSlug
string

行程公開頁網址代稱(slug)。

groupCode
string | null

團號(可空)。

label
string | null

梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);null = 無。

isPrivate
boolean

不對外販售(issue 509 ①):前台藏、後台照建。

customerCancelPausedAt
string | null

暫停客人自助取消的時間 ISO 字串(issue 1808);null = 未暫停。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

capacity
number

團位容量(總名額)。

bookedCount
number

已佔位人數。

status
string

梯次狀態(如 open 開放/closed 關閉)。

salesOpenAt
string | null

排定的開賣時間 ISO 字串;null = 沒排程(trips.md §2.2a,issue 1643)。

salesOpenFailedReason
string | null

自動開賣被擋下的原因;null = 沒失敗。

confirmedAt
string | null

成團時間 ISO 字串;null = 尚未成團(group-confirmation §2,與 status 正交)。

minGroupSize
number | null

行程層最低成團人數門檻;null = 未設門檻(不提示達標)。

allocationMode
"fcfs" | "lottery"

佔位模式:fcfs 先到先得/lottery 抽籤。

leaderNames
string[]

已排主要隨團人員姓名(confirmed + tentative 皆列;空 = 未指派)。

assistantNames
string[]

已排協作 / 助教姓名(空 = 未指派協作)。

nameBoundGuideNames
string[]

Names on assignments that require a reason for replacement or removal.

confirmedLeaderCount
number

已確認(status='confirmed')的主要隨團人員人數;0 = 沒有確認的主要隨團人員(tentative 不算)。

confirmedGuideCount
number

已確認(status='confirmed')的主要+協同人數合計(issue 1117 的「已派」)。

permitSwappedCount
number

已確認指派中勾了「已換領」的人數(issue 1731)。

requiredGuideCount
number | null

需要的隨團人員數;null = 未填(issue 1117)。

notes
string | null

梯次備註(集合上下車點、代收註記…;null = 無)。

opNames
string[]

承辦小編姓名;空陣列不代表本梯不需承辦。

opNotRequiredReason選填
string | null | undefined

明確標記本梯不需承辦的原因;null = 未標記。

priceTwd
number

定價(TWD)。

agencyPriceTwd
number | null

同業/旅行社報價(TWD;未設為 null)。

promoActive
boolean

是否有進行中的促銷價。

promoPriceTwd
number | null

促銷價(TWD;無促銷為 null)。

promoAgencyPriceTwd
number | null

同業促銷價(TWD;無促銷為 null)。

daysUntilDeparture
number

距出發天數(負值表示已出發)。

salesClosePassed選填
boolean | undefined

有效停止售票時間已過(同 `updateDepartureStatus` 的守衛)。true 時改回售票中一定被拒, 梯次總覽的「恢復售票」改成停用並寫原因(issue 1654)。省略視同 false。

travelerCount
number

旅客總人數(未取消訂單的 party_size 加總)。

paidCount
number

已付款人數(party_size 加總;不含取消)。

pendingCount
number

未結清人數(未付/部分付/已付訂金;不含取消)= unpaidCount + balanceDueCount。

unpaidCount
number

完全未付人數(payment_state = unpaid;不含取消)。

balanceDueCount
number

待收尾款人數(已付部分或訂金、還沒付清:partially_paid / deposit_paid;不含取消)。

cancelledCount
number

已取消人數(僅供參考,不計入總數)。

confirmedOrderCount
number

已確認、還沒完成的訂單數(`booking_state = confirmed`,筆數不是人數)。結團把它們改成已完成。 狀態已完成的梯次這個值大於 0,代表梯次沒經過結團就變成已完成,要再結團一次。

ordersWithoutConsent
number

尚未簽署同意書(PDPA)的訂單數。

codedRevenueTwd
number

有折扣訂單的應收營收合計(TWD;排除取消/退款)。

discountTotalTwd
number

折扣金額合計(TWD)。

profitShareTotalTwd
number

利潤分潤金額合計(TWD)。

lottery
DepartureLottery | null

梯次層抽籤結果:`result` 為 none(未送件)/pending(待抽籤)/waitlisted(備取中)/ won(已中籤)/lost(未中籤),`waitlistedCount` 為同梯還在備取的張數。先到先得梯次為 null。

result
"lost" | "none" | "pending" | "waitlisted" | "won"
waitlistedCount
number
lotteryWaitlistEnabled
boolean

行程開了「抽籤結果含備取」(issue 1691):抽籤梯次才出現「備取」標記鍵。

stage
"cancelled" | "closed" | "confirming" | "departed" | "enrolling" | "prep" | "rooming" | "sales_closed"

生命週期階段。

metThreshold
boolean

已達最低成團人數;門檻未設時為 false。

rooming
DepartureRooming | null

分房進度;null = 這一梯不用分房(通鋪團或沒有房)。

roomCount
number
assignedCount
number
totalTravelers
number
範例
toko control departures
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "tripId": "…",
      "tripTitle": "…",
      "tripShortName": "…",
      "hasPreTripNight": true,
      "tripSlug": "…",
      "groupCode": "…",
      "label": "…",
      "isPrivate": true,
      "customerCancelPausedAt": "…",
      "departureDate": "…",
      "returnDate": "…",
      "capacity": 0,
      "bookedCount": 0,
      "status": "…",
      "salesOpenAt": "…",
      "salesOpenFailedReason": "…",
      "confirmedAt": "…",
      "minGroupSize": 0,
      "allocationMode": "fcfs",
      "leaderNames": [
        "…"
      ],
      "assistantNames": [
        "…"
      ],
      "nameBoundGuideNames": [
        "…"
      ],
      "confirmedLeaderCount": 0,
      "confirmedGuideCount": 0,
      "permitSwappedCount": 0,
      "requiredGuideCount": 0,
      "notes": "…",
      "opNames": [
        "…"
      ],
      "opNotRequiredReason": "…",
      "priceTwd": 0,
      "agencyPriceTwd": 0,
      "promoActive": true,
      "promoPriceTwd": 0,
      "promoAgencyPriceTwd": 0,
      "daysUntilDeparture": 0,
      "salesClosePassed": true,
      "travelerCount": 0,
      "paidCount": 0,
      "pendingCount": 0,
      "unpaidCount": 0,
      "balanceDueCount": 0,
      "cancelledCount": 0,
      "confirmedOrderCount": 0,
      "ordersWithoutConsent": 0,
      "codedRevenueTwd": 0,
      "discountTotalTwd": 0,
      "profitShareTotalTwd": 0,
      "lottery": null,
      "lotteryWaitlistEnabled": true,
      "stage": "cancelled",
      "metThreshold": true,
      "rooming": null
    }
  ]
}
toko control deadlines

跨梯次到期待辦(團控期限頁)

參數

--range <today|all>
旗標 · 選填

today = 只列逾期、超級緊急、可以開始三級;all(預設)= 再加注意準備

--horizon <1-30>
旗標 · 選填
--scope <all|unassigned>
旗標 · 選填

all(預設)= 全公司;unassigned = 只看尚未指派承辦的梯次

--anomalies
旗標 · 選填

設為 true 時一併回傳日期設定異常(規則適用卻沒有日期列);預設 false

--json
旗標 · 選填

回應欄位 · data

today
string
horizon
number
range
"all" | "today"
rows
object[]
softDate
string | null
hardDate
string
source
"generated" | "manual"
dayMode
"calendar" | "month_same_day" | "workday"

梯次期限列存的 day_mode(產生或人工寫入當下解析出的有效規則)。距離單位:`workday` 算工作天, 其他模式(含 `month_same_day`)算日曆天。

hardDistance
number
softDistance
number | null
urgency
"critical" | "overdue" | "start" | "upcoming"
lotteryDraw
LotteryDrawInfo | null

期限日取自抽籤時程表時的時段與原抽籤日(lottery-schedule spec §3.5)。

slotStart
string | null
slotEnd
string | null
firstDrawDate
string | null
label
string
departureId
string
tripId
string
tripTitle
string
tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

groupCode
string | null
departureDate
string
opNames
string[]

承辦小編姓名(依姓名排序);空陣列 = 未指派。

typeKey
string
anomalies
object[]

`anomalies: false` 時恆為空陣列。

label
string
departureId
string
tripId
string
tripTitle
string
tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

groupCode
string | null
departureDate
string
opNames
string[]

承辦小編姓名(依姓名排序);空陣列 = 未指派。

typeKey
string
counts
object
overdue
number
critical
number
start
number
upcoming
number
missingHolidayYears
number[]

未逾期的工作天事項「今天 → 硬 deadline」之間假日表未維護年度的聯集。

範例
toko control deadlines
回應
{
  "ok": true,
  "data": {
    "today": "…",
    "horizon": 0,
    "range": "all",
    "rows": [
      {
        "softDate": "…",
        "hardDate": "…",
        "source": "generated",
        "dayMode": "calendar",
        "hardDistance": 0,
        "softDistance": 0,
        "urgency": "critical",
        "lotteryDraw": null,
        "label": "…",
        "departureId": "…",
        "tripId": "…",
        "tripTitle": "…",
        "tripShortName": "…",
        "groupCode": "…",
        "departureDate": "…",
        "opNames": [
          "…"
        ],
        "typeKey": "…"
      }
    ],
    "anomalies": [
      {
        "label": "…",
        "departureId": "…",
        "tripId": "…",
        "tripTitle": "…",
        "tripShortName": "…",
        "groupCode": "…",
        "departureDate": "…",
        "opNames": [
          "…"
        ],
        "typeKey": "…"
      }
    ],
    "counts": {
      "overdue": 0,
      "critical": 0,
      "start": 0,
      "upcoming": 0
    },
    "missingHolidayYears": [
      0
    ]
  }
}
toko control manifest

梯次旅客名單

參數

<depId>位置參數 · 必填
--include-cancelled
旗標 · 選填

是否也列出已取消訂單的旅客(true/false);省略則不列

--json
旗標 · 選填

回應欄位 · data[]

orderReceivableTwd
number | null

**整單**會計應收(TWD,不是每人分攤)。同一張單的每一列都帶同一個數字。 未取消=訂單應收。已取消=`cancellationFeeTwd`+`refundFeesTwd`:取消時訂單應收 歸零,公司留下的是這兩筆錢。匯款費屬於已退,不含在應收內。 null=退改費尚未核算(見 `cancellationFeePending`)。

cancellationFeePending
boolean

true=已取消、退改費尚未核算、手上還有可退現金:整單應收還定不下來。

cancellationFeeTwd
number | null

已取消單留下的退改費(整單)。未取消=null;尚未核算=null。

refundFeesTwd
number | null

Completed administrative fees. Excludes bank fees. 已取消單已執行退款的行政手續費(不含匯款手續費)(整單)。未取消=null。

percentageFeeTwd
number | null
fixedAdminFeeTwd
number | null
changeFeeTwd
number | null
unclassifiedFeeTwd
number | null

Unclassified historical fees remain separate.

refundRemainingTwd
number | null
travelerId
string

旅客 id。外部系統用它對人,不靠姓名。

orderId
string

所屬訂單 id。

orderNumber
string

所屬訂單編號。

travelerName
string

旅客姓名。

phone
string

聯絡電話。

email
string

聯絡 Email。

isPrimary
boolean

是否為該訂單的主要聯絡人(訂購人)。

gender
"male" | "female" | "other" | null

性別(明文 enum-like):'male'|'female'|'other'|null(未填)。

birthDate
string | null

生日 ISO `YYYY-MM-DD`;null = 未填。

diet
string | null

飲食需求(葷素)明文;null = 未填。

medicalNotes
string | null

醫療 / 過敏 / 病史備註明文;null = 未填。

specialNeeds
string | null

「飲食 · 特殊需求」欄的合併顯示字串(diet + medical_notes,以 ` · ` 併接)。 結構化欄落地後改吃 diet / medical_notes(不再湊 roommate_pref —— 分房需求回歸分房面板)。 兩者皆空 → null。

staffNote
string | null

該訂單的承辦備註(issue 1659,`orders.staff_note`)。同一張單的每位旅客列帶同一份; null = 沒有備註。與 `specialNeeds` 分開,不併進飲食 / 過敏字串。

emergencyContactName
string | null

緊急聯絡人姓名;null = 未填。

emergencyContactPhone
string | null

緊急聯絡人電話;null = 未填。

consentPending
boolean

該訂單是否仍缺最新版 PDPA 同意書(per-order,同訂單所有旅客共享此旗標)。 true = 未簽 / 只簽過舊版;與 dashboard KPI、催簽 badge 同一述詞。

orderStatus
string

Single display status (派生自三軸,與 deriveOrderDisplayStatus 同 precedence)。

amount
number

每人分攤的應收(整單應收 ÷ 人數,四捨五入,TWD)。加總可能差幾元;對帳用 `orderReceivableTwd`。

companionGroupId
string | null

本梯次的同行組 id(departure-prep §2.11);null = 不屬任何組。

companionGroupCode
string | null

同行組代號(A、B…);null = 不屬任何組。

companionGroupColor
number | null

同行組顏色序號(0 起);null = 不屬任何組。

climbingExperience
object[]

登山經歷(新到舊)。登山模組未啟用時恆為空陣列。

label
string

行程 / 山岳名稱(自填為自由文字;order 來源 = 行程名稱快照)。

climbedOn
string | null

約略完成日 `YYYY-MM-DD`;null = 未填。

source
"order" | "self"

來源:order = 完團後系統沉澱;self = 會員自填或承辦代填。

範例
toko control manifest '<depId>'
回應
{
  "ok": true,
  "data": [
    {
      "orderReceivableTwd": 0,
      "cancellationFeePending": true,
      "cancellationFeeTwd": 0,
      "refundFeesTwd": 0,
      "percentageFeeTwd": 0,
      "fixedAdminFeeTwd": 0,
      "changeFeeTwd": 0,
      "unclassifiedFeeTwd": 0,
      "refundRemainingTwd": 0,
      "travelerId": "…",
      "orderId": "…",
      "orderNumber": "…",
      "travelerName": "…",
      "phone": "…",
      "email": "…",
      "isPrimary": true,
      "gender": "male",
      "birthDate": "…",
      "diet": "…",
      "medicalNotes": "…",
      "specialNeeds": "…",
      "staffNote": "…",
      "emergencyContactName": "…",
      "emergencyContactPhone": "…",
      "consentPending": true,
      "orderStatus": "…",
      "amount": 0,
      "companionGroupId": "…",
      "companionGroupCode": "…",
      "companionGroupColor": 0,
      "climbingExperience": [
        {
          "label": "…",
          "climbedOn": "…",
          "source": "order"
        }
      ]
    }
  ]
}
toko control prep

出團準備整包(隨團人員、派車、餐食、住宿、租借、證件、待辦、投保)

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

departureId
string

梯次 id。

guides
object[]

隨團人員指派(leader 在前),含指派狀態。

id
string

指派紀錄 id。

guideId
string

被指派的嚮導 id。

guideName
string

被指派的嚮導姓名。

role
"assistant" | "leader"

指派角色:leader 主要隨團人員/assistant 協同。

status
"confirmed" | "tentative"

指派狀態:tentative 預塞暫定/confirmed 正式確認。

guideStartDate
string | null
guideEndDate
string | null
effectiveStartDate
string
effectiveEndDate
string
isNameBound
boolean
permitSwappedAt
string | null

勾「已換領」的時間(ISO);null = 未勾(issue 1731)。

permitSwappedByName
string | null

勾「已換領」的人的名稱;帳號已刪或未勾時為 null。

transport
object[]

派車紀錄。

id
string
description
string | null
driverName
string | null
driverId
string | null
driverPhone
string | null
licensePlate
string | null
vehicleType
string | null
vehicleInfo
string | null
fareNote
string | null
status
"arranged" | "driver_pending" | "pending"
catering
object[]

餐食紀錄。

id
string
supplier
string | null
mealPlan
string | null
headcountNote
string | null
status
"arranged" | "pending"
pretripStay
{ declaration: PreTripStayDeclaration; registrations: PreTripStayRegistrationRow[]; } | null

出發前夜住宿:宣告 + 全部登記(含已釋回列,看 releaseReason)。人數與性別彙總由 呼叫端從登記列算。訂房模組未啟用或行程沒指定據點時為 null。

declaration
object
id
string | null

實體列 id;**尚未實體化時為 null**(ADR 0022)。分頁的顯示條件是行程設定,不是這一列, 所以「有分頁但還沒有列」是正常狀態,第一筆登記或第一次發名單連結才會把它建出來。

departureId
string
departureDate
string
propertyId
string
propertyName
string
roomTypeId
string
roomTypeName
string
tripRoomTypeId
string | null

行程當下指定的床位池;null = 行程已改回旅客自理。**與 `roomTypeId` 不同時,這個出團 走的是實體化當下那一份**(ADR 0022 的 Consequence:畫面要說得出這件事)。

stayNight
string

住宿夜 = 出發日前一晚(由 departure_date 現算,非讀 `check_in` 欄)。

rosterLinkExpiresAt
string | null

只讓後台判斷是否已有有效連結;token 本體不進 server render。

rosterLinkActive
boolean
departureConfirmed
boolean

成團(`departures.confirmed_at` 有值)。旅客自助登記連結只在成團後可產生(issue 463)。

registrations
object[]
id
string
travelerId
string | null
role
"traveler" | "leader" | "other" | "guide" | undefined
fullName
string

活動登記現讀 travelers;旅客退團刪除後顯示不含 PII 的佔位文字。

gender
string | null
phone
string | null
orderNumber
string | null
orderCancelled
boolean

訂單是否已取消;T8 後對應登記應同時帶 releaseReason。

arrivalTime
string | null
night
string
cleaningFeeCollectedAt
string | null
cleaningFeeCollectedByName
string | null
releaseReason
PreTripStayReleaseReason | null
releasedAt
string | null
rentals
object[]

本梯裝備租借單(含明細)。登山未對此梯生效時為空陣列。

orderOnDeparture
boolean

Whether the order currently includes this rental departure.

deliveredAt選填
string | undefined | null
awaitingDelivery
boolean

還沒實際交付(issue 1917):沒有交付時間,或交付時間只是舊資料回填(= 建單時間)且起日 在今天之後的預留單。後台依這個欄位顯示交付動作,不只看 `deliveredAt` 有沒有值。

depositClearedAt選填
string | undefined | null
id
string

租借單 id(equipmentRental_ 前綴)。

rentalCode
string

人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。

orderId
string

掛載的訂單 id。

orderNumber
string | null

訂單編號;無對應訂單時為 null。

departureId
string | null

綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。

departureLabel
string | null

梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。

renterName
string | null

租借人姓名(可空)。

rentStartDate
string | null

租期起日(YYYY-MM-DD;可空)。

rentEndDate
string | null

租期迄日(YYYY-MM-DD;可空)。

returnedAt
string | null

歸還驗收時間(尚未歸還為 null)。

returnState
"cancelled" | "overdue" | "rented" | "returned"

歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。

inspectedAt
string | null

驗收時間(尚未驗收為 null)。

damageCostTwd
number | null

破損/遺失賠償金額(TWD;無為 null)。

reconState
"deposit_pending" | "pending" | "reconciled"

對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。

cancelledAt
string | null

取消時間(未取消為 null)。

cancelReason
string | null

取消原因(未取消為 null)。

notes
string | null

備註(可空)。

createdAt
string

建單時間。

updatedAt
string

最後更新時間。

lines
object[]

租借明細(借出的品項清單)。

id
string

租借明細 id(equipmentRentalLine_ 前綴)。

equipmentItemId
string

借出的裝備主檔品項 id。

itemName
string | null

裝備品項目前的名稱。

quantity
number

借出數量。

rentPriceTwdSnapshot
number

成交單位總價快照(每日單價 × 計價日數;TWD)。

depositTwdSnapshot
number

成交每件押金快照(TWD,不乘天數)。

returnedQuantity
number | null

已歸還數量(尚未歸還為 null)。

rentTotalTwd
number

成交租金合計(Σ rent snapshot × qty)。

depositTotalTwd
number

成交押金合計(Σ deposit snapshot × qty)。

rentCollectedAt
string | null

租金已收時間(未收為 null)。

rentCollectedByName
string | null

勾記租金已收的經手人姓名(遷移標記的單為 null)。

rentCollectedVia
RentCollectedVia | null

租金在哪裡收:onsite 現場收;order_payment 遷移前隨訂單付款收進公司戶頭。

depositCollectedAt
string | null

押金已收時間(未收為 null)。

depositCollectedByName
string | null

勾記押金已收的經手人姓名。

depositSettledAt
string | null

押金結清(退還或沒收)時間(未結清為 null)。

depositSettledByName
string | null

登記押金結清的經手人姓名。

depositRefundedTwd
number | null

退還客人的押金(TWD;未結清為 null)。

depositForfeitedTwd
number | null

沒收的押金(TWD;未結清為 null)。

documents
object[]

證件追蹤(只回既有列)。登山未對此梯生效時為空陣列。

id
string
docType
string

證件種類 key(`departure_document_types.key`)。

applyStatus
"applying" | "approved" | "todo"
fileReady
boolean
uploadedToCloud
boolean
fileUri
string | null
appliedAt
string | null
approvedAt
string | null
note
string | null
notApplicableAt
string | null

標「本團不需要」的時間;null = 沒標。

notApplicableByUserId
string | null
notApplicableReason
string | null

不需要的原因;有標記才有值。

checklist
object[]

團層級出團待辦(出團前在前,含已勾或有狀態文字但事後停用的項目),每項帶狀態文字。

id
string | null

勾稽列 id;null = 目錄有此項但本梯次還沒有勾稽列。

itemKey
string
label
string
phase
"post" | "pre"

目錄階段。UI 依此分「出團前」「出團後」兩區;完成分母只計 'pre'。

isActive
boolean

目錄啟用狀態。false 只可能出現在「已勾但事後停用」的列(見 listChecklist)。

required
boolean

這一梯要做:項目啟用中,而且行程沒設定或有勾選(issue 1369)。false 的列只因為本梯已勾、 寫過字或標過不適用才列出,不計入進度。

checkedAt
string | null
checkedByUserId
string | null
checkedByName
string | null

勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。

note
string | null

狀態文字(issue 1245);null = 沒有字。與勾選彼此獨立。

noteUpdatedAt
string | null

最後寫字的時間;沒有字時為 null。

noteUpdatedByUserId
string | null

最後寫字的人;沒有字或帳號刪除後為 null。

noteUpdatedByName
string | null

最後寫字的人的顯示名(同 `checkedByName`,帳號刪除後為 null)。

notApplicableAt
string | null

標「本團不適用」的時間;null = 沒標(issue 1369)。

notApplicableByName
string | null

標記者的顯示名;帳號刪除後為 null。

notApplicableReason
string | null

不適用的原因;有標記才有值。

travelerChecks
object

旅客層級出團待辦:欄(items)+ 已勾的格(checks)+ 有狀態文字的格(notes),都以 travelerId 對人。勾選與狀態文字彼此獨立,所以分兩份稀疏清單。

items
object[]
itemKey
string
label
string
isActive
boolean

false 只可能出現在「已勾或寫過字但事後停用」的項目。

checks
object[]
travelerId
string
itemKey
string
checkedAt
string
checkedByUserId
string | null
checkedByName
string | null

勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。

notes
object[]
travelerId
string
itemKey
string
note
string
noteUpdatedAt
string
noteUpdatedByUserId
string | null
noteUpdatedByName
string | null

最後寫字的人的顯示名(帳號刪除後為 null)。

insurance
object[]

投保(旅責險 / 登山險兩軸,依 kind 分)。

id
string
kind
"climbing" | "liability"
insurer
string | null
policyNo
string | null
status
"done" | "pending"
scheduledDate
string | null

排定日 'YYYY-MM-DD'(可以開始辦的日,不是死線);null = 未排定。

insuredCount
number | null

投保人數;null = 未填。

note
string | null
updatedAt
string

列的版本:最後寫入時間,UTC ISO、到微秒。改列時當 `expectedUpdatedAt` 送回, 期間有別人寫過就拒絕,免得用頁面舊值蓋掉別人的寫入。

範例
toko control prep '<depId>'
回應
{
  "ok": true,
  "data": {
    "departureId": "…",
    "guides": [
      {
        "id": "…",
        "guideId": "…",
        "guideName": "…",
        "role": "assistant",
        "status": "confirmed",
        "guideStartDate": "…",
        "guideEndDate": "…",
        "effectiveStartDate": "…",
        "effectiveEndDate": "…",
        "isNameBound": true,
        "permitSwappedAt": "…",
        "permitSwappedByName": "…"
      }
    ],
    "transport": [
      {
        "id": "…",
        "description": "…",
        "driverName": "…",
        "driverId": "…",
        "driverPhone": "…",
        "licensePlate": "…",
        "vehicleType": "…",
        "vehicleInfo": "…",
        "fareNote": "…",
        "status": "arranged"
      }
    ],
    "catering": [
      {
        "id": "…",
        "supplier": "…",
        "mealPlan": "…",
        "headcountNote": "…",
        "status": "arranged"
      }
    ],
    "pretripStay": null,
    "rentals": [
      {
        "orderOnDeparture": true,
        "deliveredAt": "…",
        "awaitingDelivery": true,
        "depositClearedAt": "…",
        "id": "…",
        "rentalCode": "…",
        "orderId": "…",
        "orderNumber": "…",
        "departureId": "…",
        "departureLabel": "…",
        "renterName": "…",
        "rentStartDate": "…",
        "rentEndDate": "…",
        "returnedAt": "…",
        "returnState": "cancelled",
        "inspectedAt": "…",
        "damageCostTwd": 0,
        "reconState": "deposit_pending",
        "cancelledAt": "…",
        "cancelReason": "…",
        "notes": "…",
        "createdAt": "…",
        "updatedAt": "…",
        "lines": [
          {
            "id": "…",
            "equipmentItemId": "…",
            "itemName": "…",
            "quantity": 0,
            "rentPriceTwdSnapshot": 0,
            "depositTwdSnapshot": 0,
            "returnedQuantity": 0
          }
        ],
        "rentTotalTwd": 0,
        "depositTotalTwd": 0,
        "rentCollectedAt": "…",
        "rentCollectedByName": "…",
        "rentCollectedVia": null,
        "depositCollectedAt": "…",
        "depositCollectedByName": "…",
        "depositSettledAt": "…",
        "depositSettledByName": "…",
        "depositRefundedTwd": 0,
        "depositForfeitedTwd": 0
      }
    ],
    "documents": [
      {
        "id": "…",
        "docType": "…",
        "applyStatus": "applying",
        "fileReady": true,
        "uploadedToCloud": true,
        "fileUri": "…",
        "appliedAt": "…",
        "approvedAt": "…",
        "note": "…",
        "notApplicableAt": "…",
        "notApplicableByUserId": "…",
        "notApplicableReason": "…"
      }
    ],
    "checklist": [
      {
        "id": "…",
        "itemKey": "…",
        "label": "…",
        "phase": "post",
        "isActive": true,
        "required": true,
        "checkedAt": "…",
        "checkedByUserId": "…",
        "checkedByName": "…",
        "note": "…",
        "noteUpdatedAt": "…",
        "noteUpdatedByUserId": "…",
        "noteUpdatedByName": "…",
        "notApplicableAt": "…",
        "notApplicableByName": "…",
        "notApplicableReason": "…"
      }
    ],
    "travelerChecks": {
      "items": [
        {
          "itemKey": "…",
          "label": "…",
          "isActive": true
        }
      ],
      "checks": [
        {
          "travelerId": "…",
          "itemKey": "…",
          "checkedAt": "…",
          "checkedByUserId": "…",
          "checkedByName": "…"
        }
      ],
      "notes": [
        {
          "travelerId": "…",
          "itemKey": "…",
          "note": "…",
          "noteUpdatedAt": "…",
          "noteUpdatedByUserId": "…",
          "noteUpdatedByName": "…"
        }
      ]
    },
    "insurance": [
      {
        "id": "…",
        "kind": "climbing",
        "insurer": "…",
        "policyNo": "…",
        "status": "done",
        "scheduledDate": "…",
        "insuredCount": 0,
        "note": "…",
        "updatedAt": "…"
      }
    ]
  }
}
toko control validation

梯次旅客資料驗證摘要

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data[]

orderId
string

訂單 id。

orderNumber
string

訂單編號。

errorCount
number

該訂單的 error(必補缺漏)項目數。

warningCount
number

該訂單的 warning(建議補齊)項目數。

incompleteTravelerCount
number

至少有一項 error 或 warning 的旅客數(資料待補人數)。

errorTravelerCount
number

含 error 的旅客數(出團前置紅標用)。

範例
toko control validation '<depId>'
回應
{
  "ok": true,
  "data": [
    {
      "orderId": "…",
      "orderNumber": "…",
      "errorCount": 0,
      "warningCount": 0,
      "incompleteTravelerCount": 0,
      "errorTravelerCount": 0
    }
  ]
}
toko control lottery-orders

梯次抽籤訂單清單

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data[]

orderId
string

訂單 id。

orderNumber
string

訂單編號。

customerName
string

訂購人姓名。

partySize
number

佔位人數。

lotteryState
"applied" | "won" | "lost" | null

抽籤狀態:applied 已應募/won 中籤/lost 未中籤。null = 落在受管制抽籤梯次但沒標 應募的單(後台 K 單、事後改成抽籤的梯次)——只因抽籤實名制占用而被列出(§3.7)。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。 只有 `lotteryState='applied'` 時可能為 true。

applicationKey
string

Current application (`lotteryApplicationKey`). A decision sends it back to reject an old page.

undoDecisionId選填
string | null | undefined

Latest reversible decision. The write entry checks later work under the order lock.

backupChoiceCount
number

客人自選的有序備案筆數(order_backup_choices;0 = 無備案)。

collectedTwd
number

已收現金(payment_transactions direction='in');抽籤未中安置時的訂金結轉基準。

failoverFromOrderId
string | null

落腳譜系:本單若是由某主單 force-place / cascade 落腳而成立的備案單,指向原主單 id。 null = 本單即主單(非備案落腳單)。供線控從備案列回溯主單。

awaitingPlacement
boolean

true when lottery_state='lost' and still active (not cancelled). Means backup cascade exhausted — awaiting manual placement or explicit cancel.

identityHoldPending
boolean

是否仍占用抽籤實名資格。為 true 時可顯示「解除實名占用」動作。

identityHoldReleased
boolean

抽籤實名占用是否已由線控手動解除。

failover
LotteryFailoverSummary | null

最近一次未中籤自動轉備案:`placed` 落腳、`reapplied` 重新應募、`stopped` 停止並待人工安置。 `blocker` 為停止原因,null=清單走完。`skipped` 列被跳過的順位與原因。null=未曾自動轉備案。

outcome
"placed" | "reapplied" | "stopped"

placed = a general backup took the order; reapplied = a new application; stopped = awaits placement.

blocker
LotteryFailoverBlocker | null

Why the failover stopped. null = every backup choice was tried. Only for `stopped`.

skipped
object[]

Backup choices that the failover skipped, in rank order.

rank
number
departureId
string
reason
"identity_missing" | "not_same_trip" | "price_changed" | "roster_invalid" | "unavailable"
範例
toko control lottery-orders '<depId>'
回應
{
  "ok": true,
  "data": [
    {
      "orderId": "…",
      "orderNumber": "…",
      "customerName": "…",
      "partySize": 0,
      "lotteryState": "applied",
      "lotteryWaitlisted": true,
      "applicationKey": "…",
      "undoDecisionId": "…",
      "backupChoiceCount": 0,
      "collectedTwd": 0,
      "failoverFromOrderId": "…",
      "awaitingPlacement": true,
      "identityHoldPending": true,
      "identityHoldReleased": true,
      "failover": null
    }
  ]
}
toko control rooms

梯次分房檢視

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

departure
object

梯次表頭(id/起訖日/行程名/容量等)。

id
string

梯次 id(dep_ 前綴)。

departureDate
string

出發日(ISO 'YYYY-MM-DD')。

returnDate
string

回程日(ISO 'YYYY-MM-DD')。

tripTitle
string

所屬行程標題。

tripSlug
string

所屬行程網址 slug。

capacity
number

名額上限(人數)。

bookedCount
number

已成團佔用名額(人數)。

rooms
object[]

此梯次的所有房間(含入住旅客)。

id
string

房間 id。

roomLabel
string

房號/房間標籤。

roomType
string

房型(如 single 單人/double 雙人/dorm 通舖)。

bedCount
number

床位數。

bedConfig
string | null

床位配置說明(可空)。

accommodationName
string | null

住宿名稱(梯次配套派生房才有;可空)。

accommodationDate
string | null

住宿日期(YYYY-MM-DD;可空)。

baseCostTwd
number

房間底價成本(TWD)。

upgradeFeeTwd
number

房型升等補款(TWD)。

notes
string | null

備註(可空)。

departureLodgingId
string | null

null = 手動建立的房;non-null = 梯次配套自動派生房的來源 ID。

assignedTravelers
object[]

已入住此房的旅客。

id
string

旅客 id。

fullName
string

旅客姓名。

orderId
string

所屬訂單 id。

orderNumber
string

所屬訂單編號。

isPrimary
boolean

是否為該訂單的主要聯絡人(訂購人)。

gender
string | null

性別(分房 gender 衝突偵測用):'male'|'female'|'other'|null。

roomPreference
string | null

下單登記的房型偏好(chip 上顯示配房意向 badge)。

roommatePref
string | null

指定房友 id / 特殊需求自由文字。

companionGroup
CompanionGroupRef | null

本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。

groupId
string
code
string

代號(A、B…,第 27 組起 AA)。

colorIndex
number

顏色序號(0 起,循環)。UI 用它挑色票。

unassignedTravelers
object[]

尚未分房的旅客清單。

assignedElsewhere選填
boolean | undefined

True when the traveler has a room in another departure.

id
string

旅客 id。

fullName
string

旅客姓名。

orderId
string

所屬訂單 id。

orderNumber
string

所屬訂單編號。

isPrimary
boolean

是否為該訂單的主要聯絡人(訂購人)。

gender
string | null

性別:'male'|'female'|'other'|null。

birthDate選填
string | undefined

出生日期(YYYY-MM-DD;可空)。

roomPreference
string | null

下單登記的房型偏好(auto-pair 起點提示)。

roommatePref
string | null

指定房友 id / 特殊需求自由文字。

companionGroup
CompanionGroupRef | null

本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。

groupId
string
code
string

代號(A、B…,第 27 組起 AA)。

colorIndex
number

顏色序號(0 起,循環)。UI 用它挑色票。

stats
object

分房統計彙總(總人數/已分房數/房間數/升等補款合計)。

totalTravelers
number

此梯次旅客總人數。

assignedCount
number

已分配房間的旅客數。

roomCount
number

房間數。

totalUpgradeFee
number

升等補款合計(TWD 整數)。

範例
toko control rooms '<depId>'
回應
{
  "ok": true,
  "data": {
    "departure": {
      "id": "…",
      "departureDate": "…",
      "returnDate": "…",
      "tripTitle": "…",
      "tripSlug": "…",
      "capacity": 0,
      "bookedCount": 0
    },
    "rooms": [
      {
        "id": "…",
        "roomLabel": "…",
        "roomType": "…",
        "bedCount": 0,
        "bedConfig": "…",
        "accommodationName": "…",
        "accommodationDate": "…",
        "baseCostTwd": 0,
        "upgradeFeeTwd": 0,
        "notes": "…",
        "departureLodgingId": "…",
        "assignedTravelers": [
          {
            "id": "…",
            "fullName": "…",
            "orderId": "…",
            "orderNumber": "…",
            "isPrimary": true,
            "gender": "…",
            "roomPreference": "…",
            "roommatePref": "…",
            "companionGroup": null
          }
        ]
      }
    ],
    "unassignedTravelers": [
      {
        "assignedElsewhere": true,
        "id": "…",
        "fullName": "…",
        "orderId": "…",
        "orderNumber": "…",
        "isPrimary": true,
        "gender": "…",
        "birthDate": "…",
        "roomPreference": "…",
        "roommatePref": "…",
        "companionGroup": null
      }
    ],
    "stats": {
      "totalTravelers": 0,
      "assignedCount": 0,
      "roomCount": 0,
      "totalUpgradeFee": 0
    }
  }
}
toko control room-stats

多梯次分房進度統計

參數

<depId>位置參數 · 必填
--json
旗標 · 選填
範例
toko control room-stats '<depId>'
回應
{
  "ok": true,
  "data": {}
}
toko control finance

梯次財務摘要(唯讀)

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

header
object

梯次表頭(團號/行程名/出發日等基本資訊)。

id
string

梯次 id(dep_ 前綴)。

tripTitle
string

所屬行程標題。

tripSlug
string

所屬行程網址 slug。

departureDate
string

出發日(ISO 'YYYY-MM-DD')。

returnDate
string

回程日(ISO 'YYYY-MM-DD')。

finance
object

應收/已收金額彙整(TWD)。

receivableTwd
number

梯次應收:tour 訂單的攤提份額(order-money/allocation;排除已取消單)。 **含代收暫收款**(裝備押金等)—— 客人確實欠這筆錢,收款計畫與待收都照它走。 要「本團收入」請用 revenueTwd,不要拿這個當收入(issue #578)。

custodialTwd
number

應收之中的代收暫收款份額(裝備押金等;要退還,不是收入)。

revenueTwd
number

本團收入 = 應收 − 代收暫收款。毛利、損益、月報表一律用這個。

collectedTwd
number

實收:tour 訂單 payment_transactions(direction='in') 的攤提份額。

cashReturnedTwd
number

客戶現金退回(refund/chargeback/reversal)的攤提份額。

netCollectedTwd
number

已收淨額 = 實收 − 退回。

outstandingTwd
number

待收 = 應收 − (實收 − 退回),floor 0。

costTwd
number

成本:departure_costs 真實額(房費另計,見成本登記簿)。

costBilledTwd
number

已轉請款成本。

costUnbilledTwd
number

未轉請款成本;不含即付(當下已付、不轉請款)。

anomalyOrderCount
number

異常單數:overpaid / partially_refunded / refund pending 的 tour 訂單。

cost
object

成本彙整(各類直接成本合計,TWD)。

totalTwd
number

內帳真實成本合計(TWD 整數,各成本列金額加總)。

billedTwd
number

已轉請款的成本合計(TWD 整數)。

paidOnSpotTwd
number

即付的成本合計(TWD 整數):當下已付,不轉請款。

unbilledTwd
number

尚未轉請款的成本合計(TWD 整數);不含即付列。

declarableTwd
number

外帳可申報金額合計(TWD 整數,各列憑證金額加總)。

nonDeclarableTwd
number

無憑證的不可申報成本合計(TWD 整數,逐列取 金額−憑證 的正值,不可跨列抵減)。

count
number

成本列筆數。

範例
toko control finance '<depId>'
回應
{
  "ok": true,
  "data": {
    "header": {
      "id": "…",
      "tripTitle": "…",
      "tripSlug": "…",
      "departureDate": "…",
      "returnDate": "…"
    },
    "finance": {
      "receivableTwd": 0,
      "custodialTwd": 0,
      "revenueTwd": 0,
      "collectedTwd": 0,
      "cashReturnedTwd": 0,
      "netCollectedTwd": 0,
      "outstandingTwd": 0,
      "costTwd": 0,
      "costBilledTwd": 0,
      "costUnbilledTwd": 0,
      "anomalyOrderCount": 0
    },
    "cost": {
      "totalTwd": 0,
      "billedTwd": 0,
      "paidOnSpotTwd": 0,
      "unbilledTwd": 0,
      "declarableTwd": 0,
      "nonDeclarableTwd": 0,
      "count": 0
    }
  }
}
toko control supplier-payments

梯次的付款登記(唯讀)

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

departureId
string
payments
object[]
id
string
departureId
string
groupCode
string | null

團號;未產生為 null。

tripTitle
string
departureDate
string

出發日(YYYY-MM-DD)。

paidOn
string

付款日期(YYYY-MM-DD)。

handlerUserId
string
handlerName
string

經手人姓名。

receivingAccountId
string

付款渠道(收款帳戶 ID)。

channelName
string

付款帳戶名稱(例:小編機)。

payee
string

付給誰/項目。

note
string | null

說明;未填為 null。

amountTwd
number

金額(TWD 整數);退費為負數。

createdAt
string

登記時間(ISO 8601,UTC)。

updatedAt
string

最後修改時間(ISO 8601,UTC)。

totalTwd
number
範例
toko control supplier-payments '<depId>'
回應
{
  "ok": true,
  "data": {
    "departureId": "…",
    "payments": [
      {
        "id": "…",
        "departureId": "…",
        "groupCode": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "paidOn": "…",
        "handlerUserId": "…",
        "handlerName": "…",
        "receivingAccountId": "…",
        "channelName": "…",
        "payee": "…",
        "note": "…",
        "amountTwd": 0,
        "createdAt": "…",
        "updatedAt": "…"
      }
    ],
    "totalTwd": 0
  }
}
toko control supplier-payments-range

依付款日期區間查全部梯次的付款登記(唯讀)

參數

--from <YYYY-MM-DD>
旗標 · 必填

付款日期起日(YYYY-MM-DD,含)

--to <YYYY-MM-DD>
旗標 · 必填

付款日期迄日(YYYY-MM-DD,含);區間最多 366 天

--json
旗標 · 選填

回應欄位 · data

from
string
to
string
payments
object[]
id
string
departureId
string
groupCode
string | null

團號;未產生為 null。

tripTitle
string
departureDate
string

出發日(YYYY-MM-DD)。

paidOn
string

付款日期(YYYY-MM-DD)。

handlerUserId
string
handlerName
string

經手人姓名。

receivingAccountId
string

付款渠道(收款帳戶 ID)。

channelName
string

付款帳戶名稱(例:小編機)。

payee
string

付給誰/項目。

note
string | null

說明;未填為 null。

amountTwd
number

金額(TWD 整數);退費為負數。

createdAt
string

登記時間(ISO 8601,UTC)。

updatedAt
string

最後修改時間(ISO 8601,UTC)。

totalTwd
number
範例
toko control supplier-payments-range --from 'example-from' --to 'example-to'
回應
{
  "ok": true,
  "data": {
    "from": "…",
    "to": "…",
    "payments": [
      {
        "id": "…",
        "departureId": "…",
        "groupCode": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "paidOn": "…",
        "handlerUserId": "…",
        "handlerName": "…",
        "receivingAccountId": "…",
        "channelName": "…",
        "payee": "…",
        "note": "…",
        "amountTwd": 0,
        "createdAt": "…",
        "updatedAt": "…"
      }
    ],
    "totalTwd": 0
  }
}
toko control template-costs

梯次成本範本列

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data[]

id
string

梯次成本列 ID。

category
string

成本分類(如 交通 / 餐費 / 保險)。

vendorName
string | null

供應商 / 廠商名(可空)。

description
string | null

摘要說明(可空)。

amountTwd
number

內帳成本金額(TWD;數量 × 單價派生)。

invoiceAmountTwd
number

報帳/發票金額(TWD;is_declarable=true 時同步 amount,否則 0)。

isDeclarable
boolean

是否有合法憑證可報帳(開發票)。

quantityMode
QuantityMode | null

數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。

headcountComponents
HeadcountComponent[] | null

headcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。

groupDivisor
number | null

headcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。

quantity
number | null

實際套用的數量(依 quantityMode 派生)。

unitPriceTwd
number | null

內帳單價(TWD;外幣列可為 null)。

currency
string

幣別('TWD' = 台幣列)。

unitPriceForeign
number | null

外幣單價;TWD 列 null。

foreignAmount
number | null

外幣金額快照 = unit_price_foreign × quantity;TWD 列 null。

internalRate
string | null

內帳匯率快照(numeric 字串);TWD 列 null。

externalRate
string | null

外帳匯率快照(numeric 字串);TWD 列 null。

isManualOverride
boolean

是否為線控手動改寫(true 時重算會跳過此列,不覆蓋手改值)。

payableId
string | null

已轉請款 → 鎖定(不可手改 / 重算)。

範例
toko control template-costs '<depId>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "category": "…",
      "vendorName": "…",
      "description": "…",
      "amountTwd": 0,
      "invoiceAmountTwd": 0,
      "isDeclarable": true,
      "quantityMode": null,
      "headcountComponents": null,
      "groupDivisor": 0,
      "quantity": 0,
      "unitPriceTwd": 0,
      "currency": "…",
      "unitPriceForeign": 0,
      "foreignAmount": 0,
      "internalRate": "…",
      "externalRate": "…",
      "isManualOverride": true,
      "payableId": "…"
    }
  ]
}
toko control manifest-export

梯次旅客名單匯出(csv|json)

參數

<depId>位置參數 · 必填
--format <csv|json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

orderReceivableTwd
number | null

**整單**會計應收(TWD,不是每人分攤)。同一張單的每一列都帶同一個數字。 未取消=訂單應收。已取消=`cancellationFeeTwd`+`refundFeesTwd`:取消時訂單應收 歸零,公司留下的是這兩筆錢。匯款費屬於已退,不含在應收內。 null=退改費尚未核算(見 `cancellationFeePending`)。

cancellationFeePending
boolean

true=已取消、退改費尚未核算、手上還有可退現金:整單應收還定不下來。

cancellationFeeTwd
number | null

已取消單留下的退改費(整單)。未取消=null;尚未核算=null。

refundFeesTwd
number | null

Completed administrative fees. Excludes bank fees. 已取消單已執行退款的行政手續費(不含匯款手續費)(整單)。未取消=null。

percentageFeeTwd
number | null
fixedAdminFeeTwd
number | null
changeFeeTwd
number | null
unclassifiedFeeTwd
number | null

Unclassified historical fees remain separate.

refundRemainingTwd
number | null
travelerId
string

旅客 id。外部系統用它對人,不靠姓名。

orderId
string

所屬訂單 id。

orderNumber
string

所屬訂單編號。

travelerName
string

旅客姓名。

phone
string

聯絡電話。

email
string

聯絡 Email。

isPrimary
boolean

是否為該訂單的主要聯絡人(訂購人)。

gender
"male" | "female" | "other" | null

性別(明文 enum-like):'male'|'female'|'other'|null(未填)。

birthDate
string | null

生日 ISO `YYYY-MM-DD`;null = 未填。

diet
string | null

飲食需求(葷素)明文;null = 未填。

medicalNotes
string | null

醫療 / 過敏 / 病史備註明文;null = 未填。

specialNeeds
string | null

「飲食 · 特殊需求」欄的合併顯示字串(diet + medical_notes,以 ` · ` 併接)。 結構化欄落地後改吃 diet / medical_notes(不再湊 roommate_pref —— 分房需求回歸分房面板)。 兩者皆空 → null。

staffNote
string | null

該訂單的承辦備註(issue 1659,`orders.staff_note`)。同一張單的每位旅客列帶同一份; null = 沒有備註。與 `specialNeeds` 分開,不併進飲食 / 過敏字串。

emergencyContactName
string | null

緊急聯絡人姓名;null = 未填。

emergencyContactPhone
string | null

緊急聯絡人電話;null = 未填。

consentPending
boolean

該訂單是否仍缺最新版 PDPA 同意書(per-order,同訂單所有旅客共享此旗標)。 true = 未簽 / 只簽過舊版;與 dashboard KPI、催簽 badge 同一述詞。

orderStatus
string

Single display status (派生自三軸,與 deriveOrderDisplayStatus 同 precedence)。

amount
number

每人分攤的應收(整單應收 ÷ 人數,四捨五入,TWD)。加總可能差幾元;對帳用 `orderReceivableTwd`。

companionGroupId
string | null

本梯次的同行組 id(departure-prep §2.11);null = 不屬任何組。

companionGroupCode
string | null

同行組代號(A、B…);null = 不屬任何組。

companionGroupColor
number | null

同行組顏色序號(0 起);null = 不屬任何組。

climbingExperience
object[]

登山經歷(新到舊)。登山模組未啟用時恆為空陣列。

label
string

行程 / 山岳名稱(自填為自由文字;order 來源 = 行程名稱快照)。

climbedOn
string | null

約略完成日 `YYYY-MM-DD`;null = 未填。

source
"order" | "self"

來源:order = 完團後系統沉澱;self = 會員自填或承辦代填。

範例
toko control manifest-export '<depId>'
回應
{
  "ok": true,
  "data": [
    {
      "orderReceivableTwd": 0,
      "cancellationFeePending": true,
      "cancellationFeeTwd": 0,
      "refundFeesTwd": 0,
      "percentageFeeTwd": 0,
      "fixedAdminFeeTwd": 0,
      "changeFeeTwd": 0,
      "unclassifiedFeeTwd": 0,
      "refundRemainingTwd": 0,
      "travelerId": "…",
      "orderId": "…",
      "orderNumber": "…",
      "travelerName": "…",
      "phone": "…",
      "email": "…",
      "isPrimary": true,
      "gender": "male",
      "birthDate": "…",
      "diet": "…",
      "medicalNotes": "…",
      "specialNeeds": "…",
      "staffNote": "…",
      "emergencyContactName": "…",
      "emergencyContactPhone": "…",
      "consentPending": true,
      "orderStatus": "…",
      "amount": 0,
      "companionGroupId": "…",
      "companionGroupCode": "…",
      "companionGroupColor": 0,
      "climbingExperience": [
        {
          "label": "…",
          "climbedOn": "…",
          "source": "order"
        }
      ]
    }
  ]
}
toko control rooming-export

分房表匯出(csv|json)

參數

<depId>位置參數 · 必填
--format <csv|json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

travelerId
string

旅客 id。外部系統用它對人,不靠姓名。

fullName
string

旅客姓名。

gender
string

性別(中文標籤:男/女/其他)。

roomLabel
string

房號/房間標籤(未排房為「未分房」)。

bedInfo
string

床位資訊(房型中文標籤 + 床位)。

roommates
string

同房其他旅客姓名(依房號分組派生)。

specialRequest
string

特殊需求(房友偏好等自由文字)。

contactSummary
string

聯絡摘要(電話已遮罩,只露末 3 碼)。

範例
toko control rooming-export '<depId>'
回應
{
  "ok": true,
  "data": [
    {
      "travelerId": "…",
      "fullName": "…",
      "gender": "…",
      "roomLabel": "…",
      "bedInfo": "…",
      "roommates": "…",
      "specialRequest": "…",
      "contactSummary": "…"
    }
  ]
}
toko control cost-add

登記梯次成本(現場作業)

參數

<depId>位置參數 · 必填
--category <c>
旗標 · 必填

成本科目類別,決定歸入哪個分類帳

--amount <twd>
旗標 · 必填

成本金額(台幣,整數)

--vendor <v>
旗標 · 選填

供應商/受款對象名稱

--desc <t>
旗標 · 選填

成本說明備註

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的梯次成本列 id。

範例
toko control cost-add '<depId>' --category 'example-category' --amount '1'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control cost-update

編輯梯次成本(會計)

參數

<depId>位置參數 · 必填
--cost <costId>
旗標 · 必填

成本列 ID

--category <c>
旗標 · 必填

成本科目類別,決定歸入哪個分類帳

--amount <twd>
旗標 · 必填

成本金額(台幣,整數)

--vendor <v>
旗標 · 選填

供應商/受款對象名稱

--desc <t>
旗標 · 選填

成本說明備註

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

範例
toko control cost-update '<depId>' --cost 'example-costId' --category 'example-category' --amount '1'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control cost-rm

刪除梯次成本(會計)

參數

<depId>位置參數 · 必填
--cost <costId>
旗標 · 必填

成本列 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

範例
toko control cost-rm '<depId>' --cost 'example-costId'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control template-apply

套用行程綁定範本到本梯次(冪等)

參數

<depId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

套用成功旗標,恆為 true。

inserted
number

本次新補插入的範本成本行數(冪等,已存在的不重複插)。

skippedForeign
number

因匯率未備妥而跳過的外幣行數。補齊匯率後再套用,會自動補上這些行。

範例
toko control template-apply '<depId>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "inserted": 0,
    "skippedForeign": 0
  }
}
toko control template-override

手改某範本成本列金額(停自動重算)

參數

<depId>位置參數 · 必填
--id <costId>
旗標 · 必填

範本成本列 ID

--amount <twd>
旗標 · 必填

手動指定的成本金額(台幣),設定後停止自動重算

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

手改金額成功旗標,恆為 true。

範例
toko control template-override '<depId>' --id 'example-id' --amount '1'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control template-clear-override

重設範本成本列為範本算法(清手改鎖)

參數

<depId>位置參數 · 必填
--id <costId>
旗標 · 必填

範本成本列 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

清除手改鎖並重算成功旗標,恆為 true。

範例
toko control template-clear-override '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control cost-to-payable

成本轉請款(建立 payable)

參數

<depId>位置參數 · 必填
--cost-ids <a,b>
旗標 · 必填

要轉成請款單的成本列 ID 清單,至少一筆

--payee-type <supplier|guide|staff_commission|other>
旗標 · 必填

受款人類型:supplier(供應商)/ guide(領隊)/ staff_commission(員工佣金)/ other(其他)

--payee-name <n>
旗標 · 必填

受款人姓名/戶名(必填)

--bank-account <x>
旗標 · 選填
--bank-name <x>
旗標 · 選填
--tax-id <x>
旗標 · 選填
--submit
旗標 · 選填

設為 true 時建立後立即送出核簽,否則僅存為草稿

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

轉請款成功旗標,恆為 true。

payableId
string

新建立的出款單(payable)id。

payableNumber
string

出款單編號。

範例
toko control cost-to-payable '<depId>' --cost-ids '["example-costIds"]' --payee-type supplier --payee-name 'example-payeeName'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "payableId": "…",
    "payableNumber": "…"
  }
}
toko control room-add

建立梯次房間

參數

<depId>位置參數 · 必填
--label <l>
旗標 · 必填
--type <t>
旗標 · 必填
--beds <n>
旗標 · 必填
--base-cost <x>
旗標 · 選填

房間基本成本(台幣),預設 0

--upgrade-fee <x>
旗標 · 選填

房型升等補款金額(台幣),預設 0

--notes <t>
旗標 · 選填

房間備註

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的房間 id。

範例
toko control room-add '<depId>' --label '<l>' --type '<t>' --beds '1'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control room-update

編輯房間

參數

<depId>位置參數 · 必填
--room <roomId>
旗標 · 必填
--label <l>
旗標 · 選填
--type <t>
旗標 · 選填
--beds <n>
旗標 · 選填
--notes <t>
旗標 · 選填

房間備註;給 null 清空、未給則不變

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

範例
toko control room-update '<depId>' --room '<roomId>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}
toko control room-rm

刪除房間

參數

<depId>位置參數 · 必填
--room <roomId>
旗標 · 必填

房間 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

範例
toko control room-rm '<depId>' --room 'example-roomId'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control room-assign

指派旅客進房

參數

--room <roomId>
旗標 · 必填

目標房間 ID,旅客將被指派入住此房

--traveler <travelerId>
旗標 · 必填

欲指派的旅客 ID,須與房間屬於同一梯次

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

指派入房成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

範例
toko control room-assign --room 'example-roomId' --traveler 'example-travelerId'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}
toko control room-unassign

把旅客移出房間

參數

--traveler <travelerId>
旗標 · 必填

欲移出房間的旅客 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

移出房間成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

範例
toko control room-unassign --traveler 'example-travelerId'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}
toko control room-auto-pair-preview

auto-pair 建議分組預覽(純讀取;供 apply 取 travelerIds)

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

suggestion
object

auto-pair 引擎產出的分房建議(未寫入,供線控確認)。

groups
object[]

建議的分房組合(每組一間房,含旅客與需確認註記)。

kind
"auto_same_gender" | "roommate_request" | "single" | "special_request"
travelerIds
string[]
needsConfirmation選填
boolean | undefined

需線控人工確認(跨性別指定房友 / gender='other')。

note選填
string | undefined

給線控看的提示(特殊需求原文、超過床數、單人房卻又指名房友…)。

unmatched
object[]

無法安全自動配對、待人工處理的旅客。

travelerId
string
reason
"gender_missing" | "needs_confirmation" | "no_same_gender_pair"
names
object

travelerId → 顯示名(建議分組渲染用)。

範例
toko control room-auto-pair-preview '<depId>'
回應
{
  "ok": true,
  "data": {
    "suggestion": {
      "groups": [
        {
          "kind": "auto_same_gender",
          "travelerIds": [
            "…"
          ],
          "needsConfirmation": true,
          "note": "…"
        }
      ],
      "unmatched": [
        {
          "travelerId": "…",
          "reason": "gender_missing"
        }
      ]
    },
    "names": "…"
  }
}
toko control room-auto-pair-apply

套用 auto-pair 建議分組(單一交易建房+整組指派)

參數

<depId>位置參數 · 必填
--travelers <a,b,c>
旗標 · 必填
--type <shared>
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

套用成功旗標,恆為 true。

roomId
string

建議分組寫入後所在的房間 id。

travelerIds
string[]

被排入該房的旅客 id 清單。

範例
toko control room-auto-pair-apply '<depId>' --travelers '<a,b,c>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "roomId": "…",
    "travelerIds": [
      "…"
    ]
  }
}
toko control lottery-resolve

抽籤手動裁決(won|lost)

參數

<orderId>位置參數 · 必填
--outcome <won|lost>
旗標 · 必填

抽籤裁決結果:won 中籤確認、lost 未中籤(啟動備案或取消)

--application-key <key>
旗標 · 選填

Application key from lottery-orders. A new application requires it: without it the result is application_key_required (400). A replaced key fails with stale_application (409).

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:抽籤結果已登錄。

outcome
"lost" | "won"

抽籤結果:won 中籤 / lost 未中籤。

balanceNotice
LotteryWonBalanceNotice | null

中籤後的尾款通知(lost 為 null):sent 已寄出、already_sent 之前寄過、 not_eligible 沒有待收尾款、no_template 租戶沒有啟用中的收尾款範本、 no_recipient 沒有收件人(同業單或訂購人沒有 email)、failed 寄送失敗。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。

範例
toko control lottery-resolve '<orderId>' --outcome won
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "outcome": "lost",
    "balanceNotice": null,
    "retentionDeferred": true
  }
}
toko control lottery-set-mode

設定梯次分配模式(fcfs|lottery)

參數

<depId>位置參數 · 必填
--mode <fcfs|lottery>
旗標 · 必填

分配模式:fcfs(先到先得)或 lottery(抽籤)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

departureId
string

被更新的梯次 id。

mode
"fcfs" | "lottery"

更新後的佔位模式:fcfs 先到先得/lottery 抽籤。

範例
toko control lottery-set-mode '<depId>' --mode fcfs
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "departureId": "…",
    "mode": "fcfs"
  }
}
toko control prep-checklist

設定出團待辦項勾選

參數

<depId>位置參數 · 必填
--item <key>
旗標 · 必填

出團待辦項目的代碼

--checked <true|false>
旗標 · 必填

該檢查項目是否已完成勾選

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

設定成功旗標,恆為 true。

id
string

出團待辦勾稽紀錄 id。

範例
toko control prep-checklist '<depId>' --item 'example-itemKey' --checked true
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control prep-document

upsert 證件追蹤狀態

參數

<depId>位置參數 · 必填
--type <docType>
旗標 · 必填
--apply-status <todo|applying|approved>
旗標 · 選填

申辦狀態:todo(待辦)/ applying(申請中)/ approved(已核准)

--file-ready <true|false>
旗標 · 選填

文件檔案是否已備妥

--note <t>
旗標 · 選填

備註;給 null 清空

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

upsert 成功旗標,恆為 true。

id
string

證件追蹤紀錄 id。

範例
toko control prep-document '<depId>' --type '<docType>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control prep-deadlines

設定梯次期限警戒(登山專屬;部分更新,--clear 清除)

參數

<depId>位置參數 · 必填
--set <key=YYYY-MM-DD>
旗標 · 選填
--clear <key>
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

設定成功旗標,恆為 true。

departureId
string

被設定期限的梯次 id。

deadlines
object

本次套用的硬 deadline 異動(key → 日期;null = 已清除)。寫入的列來源為 manual。

softDates
object

本次套用的軟日期異動(key → 日期;null = 已清空)。

範例
toko control prep-deadlines '<depId>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "departureId": "…",
    "deadlines": "…",
    "softDates": "…"
  }
}
toko control prep-equipment-need

upsert 裝備需求數

參數

<depId>位置參數 · 必填
--item <equipmentItemId>
旗標 · 必填
--qty <n>
旗標 · 必填
--note <t>
旗標 · 選填

需求備註;給 null 清空

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

upsert 成功旗標,恆為 true。

id
string

裝備需求紀錄 id。

範例
toko control prep-equipment-need '<depId>' --item '<equipmentItemId>' --qty '1'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control prep-equipment-need-rm

刪除裝備需求列

參數

<depId>位置參數 · 必填
--id <needId>
旗標 · 必填

裝備需求列 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

範例
toko control prep-equipment-need-rm '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-guide-assign

指派嚮導到梯次

參數

<depId>位置參數 · 必填
--guide <guideId>
旗標 · 必填
--role <leader|assistant>
旗標 · 必填

指派角色:leader(主要隨團人員)或 assistant(協同)

--status <tentative|confirmed>
旗標 · 選填

指派狀態:tentative(暫定)或 confirmed(已確認)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

指派成功旗標,恆為 true。

id
string

指派紀錄 id。

範例
toko control prep-guide-assign '<depId>' --guide '<guideId>' --role leader
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control prep-rental

從裝備需求開租借單(含金流接入)

參數

<depId>位置參數 · 必填
--order <orderId>
旗標 · 必填

租借單所屬的訂單 ID

--lines <itemId:qty,itemId:qty>
旗標 · 必填

租借品項明細(品項 + 數量),數量需大於 0 才計入

--renter <n>
旗標 · 選填

租借人姓名;給 null 清空

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

開單成功旗標,恆為 true。

rentalId
string

新開立的裝備租借單 id。

範例
toko control prep-rental '<depId>' --order 'example-orderId' --lines '[{"itemId":"example-itemId","qty":1}]'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "rentalId": "…"
  }
}
toko control prep-insurance-add

新增投保紀錄

參數

<depId>位置參數 · 必填
--kind <k>
旗標 · 必填

保險種類:liability(旅責險)/ climbing(登山險)

--insurer <i>
旗標 · 選填

保險公司名稱

--policy-no <p>
旗標 · 選填

保單號碼

--status <s>
旗標 · 選填

投保狀態,預設 pending

--scheduled-date <YYYY-MM-DD>
旗標 · 選填

排定日 YYYY-MM-DD(旅責:排定辦理日;登山:排定送出日)。可以開始辦的日,不是死線;省略 = 未填

--insured-count <n>
旗標 · 選填

投保人數;省略 = 未填

--note <t>
旗標 · 選填

備註;給 null 清空

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的投保紀錄 id。

範例
toko control prep-insurance-add '<depId>' --kind 'example-kind'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control prep-insurance-update

更新投保紀錄(只改有帶的欄位,其他欄不動)

參數

<depId>位置參數 · 必填
--id <insId>
旗標 · 必填

投保紀錄 ID

--insurer <i>
旗標 · 選填

保險公司名稱;省略不動,給 null 清空

--policy-no <p>
旗標 · 選填

保單號碼;省略不動,給 null 清空

--status <s>
旗標 · 選填

投保狀態(pending / done);省略不動

--scheduled-date <YYYY-MM-DD>
旗標 · 選填

排定日 YYYY-MM-DD(旅責:排定辦理日;登山:排定送出日)。可以開始辦的日,不是死線;省略不動,給 null 清空

--insured-count <n>
旗標 · 選填

投保人數;省略不動,給 null 清空

--note <t>
旗標 · 選填

備註;省略不動,給 null 清空

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

範例
toko control prep-insurance-update '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-insurance-rm

刪除投保紀錄

參數

<depId>位置參數 · 必填
--id <insId>
旗標 · 必填

投保紀錄 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

範例
toko control prep-insurance-rm '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-transport-add

新增派車紀錄

參數

<depId>位置參數 · 必填
--desc <t>
旗標 · 選填

派車說明(如路線、接送地點)

--driver <d>
旗標 · 選填
--vehicle <v>
旗標 · 選填
--fare-note <f>
旗標 · 選填

車資備註

--status <s>
旗標 · 選填

派車狀態 pending / driver_pending / arranged,預設 pending

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的派車紀錄 id。

範例
toko control prep-transport-add '<depId>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control prep-transport-update

更新派車紀錄(只改有帶的欄位,其他欄不動)

參數

<depId>位置參數 · 必填
--id <tId>
旗標 · 必填

派車紀錄 ID

--desc <t>
旗標 · 選填

派車說明(如路線、接送地點);省略不動,給 null 清空

--driver <d>
旗標 · 選填
--vehicle <v>
旗標 · 選填
--fare-note <f>
旗標 · 選填

車資備註;省略不動,給 null 清空

--status <s>
旗標 · 選填

派車狀態(pending / driver_pending / arranged);省略不動

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

範例
toko control prep-transport-update '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-transport-rm

刪除派車紀錄

參數

<depId>位置參數 · 必填
--id <tId>
旗標 · 必填

派車紀錄 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

範例
toko control prep-transport-rm '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-catering-add

新增餐食紀錄

參數

<depId>位置參數 · 必填
--supplier <s>
旗標 · 選填

餐食供應商名稱

--meal-plan <m>
旗標 · 選填

餐食安排說明(如餐數、菜色)

--headcount-note <h>
旗標 · 選填

人數備註(如素食、特殊餐需求)

--status <s>
旗標 · 選填

餐食安排狀態,預設 pending

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的餐食紀錄 id。

範例
toko control prep-catering-add '<depId>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko control prep-catering-update

更新餐食紀錄(只改有帶的欄位,其他欄不動)

參數

<depId>位置參數 · 必填
--id <cId>
旗標 · 必填

餐食紀錄 ID

--supplier <s>
旗標 · 選填

餐食供應商名稱;省略不動,給 null 清空

--meal-plan <m>
旗標 · 選填

餐食安排說明(如餐數、菜色);省略不動,給 null 清空

--headcount-note <h>
旗標 · 選填

人數備註(如素食、特殊餐需求);省略不動,給 null 清空

--status <s>
旗標 · 選填

餐食安排狀態(pending / arranged);省略不動

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

範例
toko control prep-catering-update '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-catering-rm

刪除餐食紀錄

參數

<depId>位置參數 · 必填
--id <cId>
旗標 · 必填

餐食紀錄 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

範例
toko control prep-catering-rm '<depId>' --id 'example-id'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control survey

取得梯次有效問卷

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data[]

id
string
kind
"multi" | "quantity" | "single" | "text"
label
string
description
string | null
required
boolean
options
object[]
id
string
label
string
disabled
boolean

本梯次停用(新答案不可選;既有答案保留並標示)。

範例
toko control survey '<id>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "kind": "multi",
      "label": "…",
      "description": "…",
      "required": true,
      "options": [
        {
          "id": "…",
          "label": "…",
          "disabled": true
        }
      ]
    }
  ]
}
toko control prep-deadlines-recompute

重算梯次期限

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

departureId
string

被重算的梯次 id。

rows
object[]

各事項的公式結果;written=false 表示該列是人工覆寫、本次未動。

key
string
label
string
softDate
string
deadlineDate
string
written
boolean

false = 該列是人工覆寫、本次未動(includeManual=false)。

missingHolidayYears
number[]
skipped
object[]

規則無法套用而略過的事項(key / label / 原因)。

key
string
label
string
message
string
missingHolidayYears
number[]

假日表未維護、但工作天回推觸及的年度;非空即「假日資料不完整」。

removed
string[]

被清掉的事項 key:規則已停用或算不出公式值;還原時連人工列一起移除。

範例
toko control prep-deadlines-recompute '<id>'
回應
{
  "ok": true,
  "data": {
    "departureId": "…",
    "rows": [
      {
        "key": "…",
        "label": "…",
        "softDate": "…",
        "deadlineDate": "…",
        "written": true,
        "missingHolidayYears": [
          0
        ]
      }
    ],
    "skipped": [
      {
        "key": "…",
        "label": "…",
        "message": "…"
      }
    ],
    "missingHolidayYears": [
      0
    ],
    "removed": [
      "…"
    ]
  }
}
toko control prep-op-remove

刪除 departure-op-assignments/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
departureId
string
userId
string
範例
toko control prep-op-remove '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "departureId": "…",
    "userId": "…"
  }
}
toko control cancel-group-not-confirmed

執行 departures/[depId]/cancel-group-not-confirmed

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

backupSucceeded
number

Orders moved to a backup in this batch.

held
number

Orders placed in the holding area in this batch.

skipped
object[]

Orders left unchanged, with a reason for staff.

orderId
string
orderNumber
string
reason
string
orderResults
object[]

Each order result for the batch audit.

orderId
string
orderNumber
string
outcome
"backup" | "held" | "skipped"
reason選填
string | undefined
cancelled
number

本次完成未成團處理的訂單數。

alreadyCancelled
number

已完成未成團處理、本次不重複處理的訂單數(重跑時的正常值)。

emailed
number

本次寄出(信進了佇列)的通知數。

emailSkippedAlreadySent
number

已寄過通知、本次略過的訂單數。

emailSkippedNoTemplate
number

取消成立但沒寄成,因為租戶沒有啟用中的「未成團通知」範本。**不留 claim** —— 設好範本後重按同一顆按鈕會補寄。

emailSkippedNoRecipient
number

取消成立但沒寄成,因為訂購人沒有 email。**與缺範本分開數**:缺範本的後續動作是 去設範本再按一次,這種按幾次都沒用,要改走電話或其他管道。混成一個數字等於叫 承辦對這張單做一件永遠不會生效的事。

unprocessedDepartureIneligible
number

因**梯次**中途失格(被標記成團 / 已結團)而未處理的訂單數 —— 含發現當下那張與 其後全部未跑到的單。>0 = 這批提早中止。刻意**不併進其他數字**:那些的後續動作是 去看那張單,這種是去看梯次。

crossDepartureSkipped
object[]

**跨梯訂單**:同時掛在本梯與別梯的單,一律不碰(見批次說明)。清單而不是計數 —— 這些單要承辦逐張人工處理,沒有訂單號等於沒有回報。

orderId
string
orderNumber
string
failed
number

**取消**沒成立的訂單數(其餘訂單不受影響)。**只數 `phase='cancel'`** —— 取消已經 commit、只是通知寄不出去的單不算,那張單真的取消了,把它報成失敗等於對線控謊稱 「這張還沒取消」,而他會去做一件已經做完的事。

failures
object[]

失敗清單(辨識到訂單號)。`phase` 分「取消沒成立」與「取消成立但通知炸了」—— 後續動作完全不同。**不帶例外訊息**:DB 例外會帶表名 / 約束名 / 衝突鍵的值(可能 含 email),那些留 server log,不經 server action 回瀏覽器。

orderId
string
orderNumber
string
phase
"cancel" | "notify"
selectedNotEligible
object[]

**只有選單版會有值**:選了、但不在本梯名單上的單(不掛在本梯、已出團、或已被其他 事由取消)—— 一張都沒動。清單而不是計數,理由同 `crossDepartureSkipped`。整梯版恆為空。

orderId
string
orderNumber
string
範例
toko control cancel-group-not-confirmed '<depId>'
回應
{
  "ok": true,
  "data": {
    "backupSucceeded": 0,
    "held": 0,
    "skipped": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "reason": "…"
      }
    ],
    "orderResults": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "outcome": "backup",
        "reason": "…"
      }
    ],
    "cancelled": 0,
    "alreadyCancelled": 0,
    "emailed": 0,
    "emailSkippedAlreadySent": 0,
    "emailSkippedNoTemplate": 0,
    "emailSkippedNoRecipient": 0,
    "unprocessedDepartureIneligible": 0,
    "crossDepartureSkipped": [
      {
        "orderId": "…",
        "orderNumber": "…"
      }
    ],
    "failed": 0,
    "failures": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "phase": "cancel"
      }
    ],
    "selectedNotEligible": [
      {
        "orderId": "…",
        "orderNumber": "…"
      }
    ]
  }
}
toko control complete

執行 departures/[depId]/complete

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko control complete '<depId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control confirmation-create

執行 departures/[depId]/confirmation

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko control confirmation-create '<depId>' --data '{"confirmed":true}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control delete

執行 departures/[depId]/delete

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko control delete '<depId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-deadlines-done

執行 departures/[depId]/prep/deadlines/done

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

changed
boolean
範例
toko control prep-deadlines-done '<depId>' --data '{"typeKey":"example-typeKey","done":true}'
回應
{
  "ok": true,
  "data": {
    "changed": true
  }
}
toko control prep-deadlines-not-applicable

執行 departures/[depId]/prep/deadlines/not-applicable

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

changed
boolean
reason
string | null
範例
toko control prep-deadlines-not-applicable '<depId>' --data '{"typeKey":"example-typeKey","notApplicable":true}'
回應
{
  "ok": true,
  "data": {
    "changed": true,
    "reason": "…"
  }
}
toko control prep-ops-defaults-apply

執行 departures/[depId]/prep/ops-defaults/apply

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

transport
number
catering
number
insurance
number
範例
toko control prep-ops-defaults-apply '<depId>'
回應
{
  "ok": true,
  "data": {
    "transport": 0,
    "catering": 0,
    "insurance": 0
  }
}
toko control prep-ops-list

查詢 departures/[depId]/prep/ops

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

assignments
object[]
id
string
userId
string
userName
string
candidates
object[]
id
string
name
string
範例
toko control prep-ops-list '<depId>'
回應
{
  "ok": true,
  "data": {
    "assignments": [
      {
        "id": "…",
        "userId": "…",
        "userName": "…"
      }
    ],
    "candidates": [
      {
        "id": "…",
        "name": "…"
      }
    ]
  }
}
toko control prep-ops-assign

執行 departures/[depId]/prep/ops

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
id
string
created
boolean

true = 這次真的新增;false = 命中既有列(idempotent)。

範例
toko control prep-ops-assign '<depId>' --data '{"userId":"example-userId"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…",
    "created": true
  }
}
toko control prep-pretrip-stays-arrival

執行 departures/[depId]/prep/pretrip-stays/[registrationId]/arrival

參數

<depId>位置參數 · 必填
<registrationId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko control prep-pretrip-stays-arrival '<depId>' '<registrationId>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko control prep-pretrip-stays-cancel

執行 departures/[depId]/prep/pretrip-stays/[registrationId]/cancel

參數

<depId>位置參數 · 必填
<registrationId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko control prep-pretrip-stays-cancel '<depId>' '<registrationId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-pretrip-stays-cleaning-fee

執行 departures/[depId]/prep/pretrip-stays/[registrationId]/cleaning-fee

參數

<depId>位置參數 · 必填
<registrationId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko control prep-pretrip-stays-cleaning-fee '<depId>' '<registrationId>' --data '{"collected":true}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko control prep-pretrip-stays-create

執行 departures/[depId]/prep/pretrip-stays

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
registrationId
string
範例
toko control prep-pretrip-stays-create '<depId>' --data '{"travelerId":"example-travelerId"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "registrationId": "…"
  }
}
toko control send-balance-slips

執行 departures/[depId]/send-balance-slips

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

sent
number

真的寄出(信進了佇列)的訂單數。

excludedAgencyOrders
number

同業單不寄信、不建連結,請經同業收款。

skipped
number

逐單略過數 = `skippedAlreadySent` + `skippedNoTemplate` + `skippedNoRecipient` + `skippedNotEligible`。 **不含**因梯次失格而中止未跑到的單(那些在 `unsentDepartureIneligible`)。

skippedAlreadySent
number

略過細分:已寄過(claim 命中)。重跑仍會略過,正常。

skippedNoTemplate
number

略過細分:連結已建但租戶沒有啟用中的「收尾款」範本而沒寄成。這種略過**不留 claim** —— 補設範本後重跑同一批次會補寄。

skippedNoRecipient
number

略過細分:連結已建但沒有收件人而沒寄成。訂購人沒有 email。補設範本不會補寄,承辦要另行聯繫。

skippedNotEligible
number

略過細分:撈出來之後才發現不符資格(尾款已結清 / 期間被取消)。

unsentDepartureIneligible
number

因**梯次**中途失格(被取消 / 被退回成團)而未寄的訂單數 —— 含發現當下那張與其後 全部未跑到的單。>0 = 這批提早中止。刻意**不併進 `skipped`**:那三種略過的後續動作 是去看那張單,這種是去看梯次。

failed
number

例外中斷的訂單數(其餘訂單不受影響)。

failures
object[]

失敗清單(辨識到訂單號)。`reason` 只給分類字串 —— DB 例外訊息會帶表名 / 約束名 / 衝突鍵的值(可能含 email),那些留 server log,不經 server action 回瀏覽器。

orderId
string
orderNumber
string
reason
"internal_error"
noCandidates
BalanceSlipIneligibleBreakdown | null

本梯沒有任何符合條件的單時,各張單為什麼不符(#1456);有符合的單時 null。 結果全是 0 時,承辦要看得出是「沒有符合的單」,不是「按了沒反應」。

total
number

本梯的訂單數(含已取消)。

cancelled
number
waitlisted
number

候補中(還沒有席位)。

lotteryNotWon
number

抽籤梯次未中籤。

unpaid
number
partiallyPaid
number

已付款但未付足訂金。

paid
number

已付清(含溢收)。

other
number
範例
toko control send-balance-slips '<depId>'
回應
{
  "ok": true,
  "data": {
    "sent": 0,
    "excludedAgencyOrders": 0,
    "skipped": 0,
    "skippedAlreadySent": 0,
    "skippedNoTemplate": 0,
    "skippedNoRecipient": 0,
    "skippedNotEligible": 0,
    "unsentDepartureIneligible": 0,
    "failed": 0,
    "failures": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "reason": "internal_error"
      }
    ],
    "noCandidates": null
  }
}
toko control submission-export

執行 departures/[depId]/submission-export

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

kind
"toko.departure-submission"
v
1
exportedAt
string

匯出時間(ISO 8601,UTC)。承辦貼上後用來核對不是上一梯的資料。

trip
object
code
string
name
string
departure
object
groupCode
string | null

團號;還沒產生時為 null。

entryDate
string

入園日 = 出發日 + 入園日偏移。

startDate
string

出發日 YYYY-MM-DD。

endDate
string

回程日 YYYY-MM-DD。

groups
object[]
no
number
travelers
object[]
name
string
gender
string
birthDate
string
idNumber
string
phone
string
email
string
address
string
emergencyName
string
emergencyPhone
string
validation
string
orderNumber
string
passportNo
string
nationality
string
nationalityName
string
passportFile
SubmissionPassportFile | null

護照影本的下載網址(passport-ocr §0.5)。沒有影本時為 null。網址 30 分鐘到期, 兌換時另要登入身分與 `departure.submission_export`。

url
string
contentType
string
expiresAt
string

網址到期時間(ISO 8601,UTC)。

staff
object[]

加帶的隨團人員,不屬於任何一組(issue 1416)。沒勾任何人為空陣列。

kind
"staff"
guideId
string
role
"assistant" | "leader"

leader 主要/assistant 協同。

status
"confirmed" | "tentative"

tentative 預塞/confirmed 正式。

englishName
string

英文姓名(與護照一致);未填為空字串。

name
string
phone
string
email
string
address
string
gender
string
birthDate
string
idNumber
string
emergencyName
string
emergencyPhone
string
validation
string
passportNo
string
nationality
string
nationalityName
string
counts
object

送件人數:客人(各組合計)+隨團。

travelers
number
staff
number
total
number
source
object
tool
"toko"
範例
toko control submission-export '<depId>' --data '{"assignments":[{"orderId":"example-orderId","group":1}],"acknowledgedIssueCount":1}'
回應
{
  "ok": true,
  "data": {
    "kind": "toko.departure-submission",
    "v": "…",
    "exportedAt": "…",
    "trip": {
      "code": "…",
      "name": "…"
    },
    "departure": {
      "groupCode": "…",
      "entryDate": "…",
      "startDate": "…",
      "endDate": "…"
    },
    "groups": [
      {
        "no": 0,
        "travelers": [
          {
            "name": "…",
            "gender": "…",
            "birthDate": "…",
            "idNumber": "…",
            "phone": "…",
            "email": "…",
            "address": "…",
            "emergencyName": "…",
            "emergencyPhone": "…",
            "validation": "…",
            "orderNumber": "…",
            "passportNo": "…",
            "nationality": "…",
            "nationalityName": "…",
            "passportFile": null
          }
        ]
      }
    ],
    "staff": [
      {
        "kind": "staff",
        "guideId": "…",
        "role": "assistant",
        "status": "confirmed",
        "englishName": "…",
        "name": "…",
        "phone": "…",
        "email": "…",
        "address": "…",
        "gender": "…",
        "birthDate": "…",
        "idNumber": "…",
        "emergencyName": "…",
        "emergencyPhone": "…",
        "validation": "…",
        "passportNo": "…",
        "nationality": "…",
        "nationalityName": "…"
      }
    ],
    "counts": {
      "travelers": 0,
      "staff": 0,
      "total": 0
    },
    "source": {
      "tool": "toko"
    }
  }
}
toko control submission-staff

設定 departures/[depId]/submission-staff

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

guideIds
string[]
範例
toko control submission-staff '<depId>' --data '{"guideIds":["example-guideIds"]}'
回應
{
  "ok": true,
  "data": {
    "guideIds": [
      "…"
    ]
  }
}
toko control submission-preview

查詢 departures/[depId]/submission-preview

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

departure
object
departureId
string
groupCode
string | null

團號;還沒產生時為 null。

tripCode
string

行程的中性代碼(slug)。

tripTitle
string
startDate
string

出發日 YYYY-MM-DD。

endDate
string

回程日 YYYY-MM-DD。

entryDate
string

入園日 = 出發日 + 入園日偏移。

entryDateOffsetDays
number
orders
object[]
orderId
string
orderNumber
string
leadName
string | null

主要聯絡人(訂單第一位旅客)姓名,讓承辦認得是哪一張單。

travelerCount
number
travelers
object[]

這張單的全部旅客,順序同匯出。`companionGroup` 是旅客在本梯次的同行組(§2.11), 給承辦當「誰跟誰一夥」的提示,跨訂單也對得上(issue 1171)。

name
string | null
companionGroup
CompanionGroupRef | null
groupId
string
code
string

代號(A、B…,第 27 組起 AA)。

colorIndex
number

顏色序號(0 起,循環)。UI 用它挑色票。

lastGroup
SubmissionLastGroup | null

上一次匯出時這張單的組別(已重編)。`null` = 沒有可沿用的紀錄:沒匯出過、這張單 當時不在梯次上、或人數變了。

group
number | null
issues
object[]

有驗證問題的旅客;沒有問題的旅客不列。

travelerName
string | null
messages
string[]
staff
object[]

這一梯的全部已派隨團人員,`included` = 已勾加帶進送籤名單(issue 1416)。

assignmentId
string

指派紀錄 id。

guideId
string
nickname
string

暱稱(後台顯示名)。

legalName
string | null

正式姓名;未填為 null(送籤檢查會列「姓名未填」)。

role
"assistant" | "leader"

leader 主要/assistant 協同。

status
"confirmed" | "tentative"

tentative 預塞/confirmed 正式。

included
boolean

已勾「加帶進送籤名單」。

issues
string[]

送籤檢查問題(資料待補);沒有問題為空陣列。

範例
toko control submission-preview '<depId>'
回應
{
  "ok": true,
  "data": {
    "departure": {
      "departureId": "…",
      "groupCode": "…",
      "tripCode": "…",
      "tripTitle": "…",
      "startDate": "…",
      "endDate": "…",
      "entryDate": "…",
      "entryDateOffsetDays": 0
    },
    "orders": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "leadName": "…",
        "travelerCount": 0,
        "travelers": [
          {
            "name": "…",
            "companionGroup": null
          }
        ],
        "lastGroup": null,
        "issues": [
          {
            "travelerName": "…",
            "messages": [
              "…"
            ]
          }
        ]
      }
    ],
    "staff": [
      {
        "assignmentId": "…",
        "guideId": "…",
        "nickname": "…",
        "legalName": "…",
        "role": "assistant",
        "status": "confirmed",
        "included": true,
        "issues": [
          "…"
        ]
      }
    ]
  }
}
toko control survey-options-update

更新 departures/[depId]/survey-options/[optionId]

參數

<depId>位置參數 · 必填
<optionId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko control survey-options-update '<depId>' '<optionId>' --data '{"disabled":true}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko control backup-candidates

查詢同一行程的備案梯次及定價

參數

<depId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

main
object
status選填
string | undefined
id
string
tripId
string
departureDate
string
returnDate
string
priceTwd
number

牌價 `departures.price_twd`(備案同價的基準)。

agencyPriceTwd
number

同業通路有效單價(見 `effectiveAgencyUnitPrice`)。

capacity
number
bookedCount
number
allocationMode
"fcfs" | "lottery"
label
string | null

梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。

isPrivate
boolean

不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。

candidates
object[]
status選填
string | undefined
id
string
tripId
string
departureDate
string
returnDate
string
priceTwd
number

牌價 `departures.price_twd`(備案同價的基準)。

agencyPriceTwd
number

同業通路有效單價(見 `effectiveAgencyUnitPrice`)。

capacity
number
bookedCount
number
allocationMode
"fcfs" | "lottery"
label
string | null

梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。

isPrivate
boolean

不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。

範例
toko control backup-candidates '<depId>'
回應
{
  "ok": true,
  "data": {
    "main": {
      "status": "…",
      "id": "…",
      "tripId": "…",
      "departureDate": "…",
      "returnDate": "…",
      "priceTwd": 0,
      "agencyPriceTwd": 0,
      "capacity": 0,
      "bookedCount": 0,
      "allocationMode": "fcfs",
      "label": "…",
      "isPrivate": true
    },
    "candidates": [
      {
        "status": "…",
        "id": "…",
        "tripId": "…",
        "departureDate": "…",
        "returnDate": "…",
        "priceTwd": 0,
        "agencyPriceTwd": 0,
        "capacity": 0,
        "bookedCount": 0,
        "allocationMode": "fcfs",
        "label": "…",
        "isPrivate": true
      }
    ]
  }
}
toko control prep-rental-create

依指定租期開立裝備租借單

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

開單成功旗標,恆為 true。

rentalId
string

新開立的裝備租借單 id。

範例
toko control prep-rental-create '<depId>' --data '{"orderId":"example-orderId","lines":[{"itemId":"example-itemId","qty":1}]}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "rentalId": "…"
  }
}
toko control permit-list

列出梯次的申請單(入園/入山/山屋)

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

範例
toko control permit-list '<depId>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "departureId": "…",
      "office": "forestry",
      "officeLabel": "…",
      "route": "…",
      "groupLabel": "…",
      "partySize": 0,
      "entryDate": "…",
      "exitDate": "…",
      "teamName": "…",
      "applicantName": "…",
      "applicantIdNumberMask": "…",
      "applicantAccount": "…",
      "leaderKind": "traveler",
      "leaderGuideId": "…",
      "leaderTravelerId": "…",
      "leaderName": "…",
      "leaderIdNumberMask": "…",
      "leaderChangedAt": "…",
      "applicationNo": "…",
      "oneStopSerial": "…",
      "caseNo": "…",
      "submittedAt": "…",
      "status": "approved",
      "statusNote": "…",
      "checkedAt": "…",
      "siteDetail": "…",
      "waitlistRank": 0,
      "eligibility": "granted",
      "eligibilityNote": "…",
      "bedNumbers": "…",
      "paymentDueAt": "…",
      "latestMailSummary": "…",
      "replacesId": "…",
      "replacedById": "…",
      "orderIds": [
        "…"
      ],
      "fileCount": 0,
      "version": 0,
      "createdAt": "…",
      "updatedAt": "…",
      "createdByUserId": "…"
    }
  ]
}
toko control permit-create

建一張申請單(重送帶 replacesId)

參數

<depId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

application
object

建立後的申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

applied
object

每個有帶的欄位是否套用。

created
boolean

是否建了新單;冪等重送時沿用第一次的值。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

範例
toko control permit-create '<depId>' --data '{"office":"one_stop","officeLabel":"example-officeLabel","route":"example-route"}'
回應
{
  "ok": true,
  "data": {
    "application": {
      "id": "…",
      "departureId": "…",
      "office": "forestry",
      "officeLabel": "…",
      "route": "…",
      "groupLabel": "…",
      "partySize": 0,
      "entryDate": "…",
      "exitDate": "…",
      "teamName": "…",
      "applicantName": "…",
      "applicantIdNumberMask": "…",
      "applicantAccount": "…",
      "leaderKind": "traveler",
      "leaderGuideId": "…",
      "leaderTravelerId": "…",
      "leaderName": "…",
      "leaderIdNumberMask": "…",
      "leaderChangedAt": "…",
      "applicationNo": "…",
      "oneStopSerial": "…",
      "caseNo": "…",
      "submittedAt": "…",
      "status": "approved",
      "statusNote": "…",
      "checkedAt": "…",
      "siteDetail": "…",
      "waitlistRank": 0,
      "eligibility": "granted",
      "eligibilityNote": "…",
      "bedNumbers": "…",
      "paymentDueAt": "…",
      "latestMailSummary": "…",
      "replacesId": "…",
      "replacedById": "…",
      "orderIds": [
        "…"
      ],
      "fileCount": 0,
      "version": 0,
      "createdAt": "…",
      "updatedAt": "…",
      "createdByUserId": "…"
    },
    "applied": "…",
    "created": true,
    "replayed": true
  }
}
toko control permit-get

查詢申請單詳情、證件檔與歷程

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

application
object

申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

files
object[]

證件檔清單。檔案本身只能從後台下載。

id
string

證件檔 ID(pmf_ 前綴)。

kind
"bed_permit" | "entry_permit" | "mountain_permit" | "other" | "site_snapshot"

檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。

contentType
string

檔案類型:application/pdf、image/png 或 image/jpeg。

sizeBytes
number

檔案大小(位元組)。

sha256
string

檔案的 sha256(hex)。

originalName
string | null

原始檔名。

uploadedAt
string

上傳時間。

uploadedByUserId
string | null

上傳者的使用者 ID。

source
"api" | "staff"

來源:staff(後台)或 api(送籤台)。

events
object[]

歷程,新的在前。身分證只有遮罩值。

id
string

歷程 ID(pme_ 前綴)。

kind
"cancel_reported" | "created" | "file_added" | "file_removed" | "leader_changed" | "pii_revealed" | "renumbered" | "status_changed" | "status_forced" | "status_ignored" | "superseded" | "updated"

歷程種類,例:created、status_changed、status_ignored、renumbered。

source
"api" | "staff"

來源:staff(後台)或 api(送籤台)。

actorUserId
string | null

寫入者的使用者 ID。

actorName
string | null

寫入者的姓名。

apiKeyId
string | null

送籤台寫入時的 API 金鑰 ID。

apiKeyName
string | null

寫入的 API 金鑰名稱;金鑰已刪為 null。

changes
object

改了什麼:{ 欄位: { from, to } }。身分證只有遮罩值。 領隊是嚮導或旅客時,歷程只存來源 id;讀取時補上來源目前的姓名與遮罩。 補的欄是 `name`、`idNumber`;建單歷程是 `leaderName`、`leaderIdNumber`。 去識別化的旅客顯示去識別化後的名字。

reason
string | null

原因(強制覆蓋、作廢)。

createdAt
string

寫入時間。

範例
toko control permit-get '<id>'
回應
{
  "ok": true,
  "data": {
    "application": {
      "id": "…",
      "departureId": "…",
      "office": "forestry",
      "officeLabel": "…",
      "route": "…",
      "groupLabel": "…",
      "partySize": 0,
      "entryDate": "…",
      "exitDate": "…",
      "teamName": "…",
      "applicantName": "…",
      "applicantIdNumberMask": "…",
      "applicantAccount": "…",
      "leaderKind": "traveler",
      "leaderGuideId": "…",
      "leaderTravelerId": "…",
      "leaderName": "…",
      "leaderIdNumberMask": "…",
      "leaderChangedAt": "…",
      "applicationNo": "…",
      "oneStopSerial": "…",
      "caseNo": "…",
      "submittedAt": "…",
      "status": "approved",
      "statusNote": "…",
      "checkedAt": "…",
      "siteDetail": "…",
      "waitlistRank": 0,
      "eligibility": "granted",
      "eligibilityNote": "…",
      "bedNumbers": "…",
      "paymentDueAt": "…",
      "latestMailSummary": "…",
      "replacesId": "…",
      "replacedById": "…",
      "orderIds": [
        "…"
      ],
      "fileCount": 0,
      "version": 0,
      "createdAt": "…",
      "updatedAt": "…",
      "createdByUserId": "…"
    },
    "files": [
      {
        "id": "…",
        "kind": "bed_permit",
        "contentType": "…",
        "sizeBytes": 0,
        "sha256": "…",
        "originalName": "…",
        "uploadedAt": "…",
        "uploadedByUserId": "…",
        "source": "api"
      }
    ],
    "events": [
      {
        "id": "…",
        "kind": "cancel_reported",
        "source": "api",
        "actorUserId": "…",
        "actorName": "…",
        "apiKeyId": "…",
        "apiKeyName": "…",
        "changes": "…",
        "reason": "…",
        "createdAt": "…"
      }
    ]
  }
}
toko control permit-update

部分更新申請單(弱狀態不覆蓋強狀態)

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

application
object

更新後的申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

applied
object

每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。

created
boolean

PATCH 恆為 false。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

範例
toko control permit-update '<id>' --data '{"office":"one_stop","officeLabel":"example-officeLabel","route":"example-route"}'
回應
{
  "ok": true,
  "data": {
    "application": {
      "id": "…",
      "departureId": "…",
      "office": "forestry",
      "officeLabel": "…",
      "route": "…",
      "groupLabel": "…",
      "partySize": 0,
      "entryDate": "…",
      "exitDate": "…",
      "teamName": "…",
      "applicantName": "…",
      "applicantIdNumberMask": "…",
      "applicantAccount": "…",
      "leaderKind": "traveler",
      "leaderGuideId": "…",
      "leaderTravelerId": "…",
      "leaderName": "…",
      "leaderIdNumberMask": "…",
      "leaderChangedAt": "…",
      "applicationNo": "…",
      "oneStopSerial": "…",
      "caseNo": "…",
      "submittedAt": "…",
      "status": "approved",
      "statusNote": "…",
      "checkedAt": "…",
      "siteDetail": "…",
      "waitlistRank": 0,
      "eligibility": "granted",
      "eligibilityNote": "…",
      "bedNumbers": "…",
      "paymentDueAt": "…",
      "latestMailSummary": "…",
      "replacesId": "…",
      "replacedById": "…",
      "orderIds": [
        "…"
      ],
      "fileCount": 0,
      "version": 0,
      "createdAt": "…",
      "updatedAt": "…",
      "createdByUserId": "…"
    },
    "applied": "…",
    "created": true,
    "replayed": true
  }
}
toko control permit-lookup

用申請編號或梯次+申請處+組別找申請單

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

範例
toko control permit-lookup
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "departureId": "…",
    "office": "forestry",
    "officeLabel": "…",
    "route": "…",
    "groupLabel": "…",
    "partySize": 0,
    "entryDate": "…",
    "exitDate": "…",
    "teamName": "…",
    "applicantName": "…",
    "applicantIdNumberMask": "…",
    "applicantAccount": "…",
    "leaderKind": "traveler",
    "leaderGuideId": "…",
    "leaderTravelerId": "…",
    "leaderName": "…",
    "leaderIdNumberMask": "…",
    "leaderChangedAt": "…",
    "applicationNo": "…",
    "oneStopSerial": "…",
    "caseNo": "…",
    "submittedAt": "…",
    "status": "approved",
    "statusNote": "…",
    "checkedAt": "…",
    "siteDetail": "…",
    "waitlistRank": 0,
    "eligibility": "granted",
    "eligibilityNote": "…",
    "bedNumbers": "…",
    "paymentDueAt": "…",
    "latestMailSummary": "…",
    "replacesId": "…",
    "replacedById": "…",
    "orderIds": [
      "…"
    ],
    "fileCount": 0,
    "version": 0,
    "createdAt": "…",
    "updatedAt": "…",
    "createdByUserId": "…"
  }
}
toko control permit-sync

送籤台寫回申請單:找到就更新,找不到就建

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

application
object

更新或新建後的申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

applied
object

每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。

created
boolean

這次是否建了新單。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

範例
toko control permit-sync --data '{"match":{}}'
回應
{
  "ok": true,
  "data": {
    "application": {
      "id": "…",
      "departureId": "…",
      "office": "forestry",
      "officeLabel": "…",
      "route": "…",
      "groupLabel": "…",
      "partySize": 0,
      "entryDate": "…",
      "exitDate": "…",
      "teamName": "…",
      "applicantName": "…",
      "applicantIdNumberMask": "…",
      "applicantAccount": "…",
      "leaderKind": "traveler",
      "leaderGuideId": "…",
      "leaderTravelerId": "…",
      "leaderName": "…",
      "leaderIdNumberMask": "…",
      "leaderChangedAt": "…",
      "applicationNo": "…",
      "oneStopSerial": "…",
      "caseNo": "…",
      "submittedAt": "…",
      "status": "approved",
      "statusNote": "…",
      "checkedAt": "…",
      "siteDetail": "…",
      "waitlistRank": 0,
      "eligibility": "granted",
      "eligibilityNote": "…",
      "bedNumbers": "…",
      "paymentDueAt": "…",
      "latestMailSummary": "…",
      "replacesId": "…",
      "replacedById": "…",
      "orderIds": [
        "…"
      ],
      "fileCount": 0,
      "version": 0,
      "createdAt": "…",
      "updatedAt": "…",
      "createdByUserId": "…"
    },
    "applied": "…",
    "created": true,
    "replayed": true
  }
}
toko control permit-file-upload

上傳申請單的證件檔(base64)

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

file
object

證件檔資訊。

id
string

證件檔 ID(pmf_ 前綴)。

kind
"bed_permit" | "entry_permit" | "mountain_permit" | "other" | "site_snapshot"

檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。

contentType
string

檔案類型:application/pdf、image/png 或 image/jpeg。

sizeBytes
number

檔案大小(位元組)。

sha256
string

檔案的 sha256(hex)。

originalName
string | null

原始檔名。

uploadedAt
string

上傳時間。

uploadedByUserId
string | null

上傳者的使用者 ID。

source
"api" | "staff"

來源:staff(後台)或 api(送籤台)。

created
boolean

false = 這張單已有同一個檔案,沒有再存一份。

範例
toko control permit-file-upload '<id>' --data '{"kind":"entry_permit","contentBase64":"example-contentBase64"}'
回應
{
  "ok": true,
  "data": {
    "file": {
      "id": "…",
      "kind": "bed_permit",
      "contentType": "…",
      "sizeBytes": 0,
      "sha256": "…",
      "originalName": "…",
      "uploadedAt": "…",
      "uploadedByUserId": "…",
      "source": "api"
    },
    "created": true
  }
}
toko control permit-reveal

顯示申請人或領隊的身分證全碼(寫稽核)

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

field
"applicantIdNumber" | "leaderIdNumber"

本次顯示的欄位。

value
string | null

身分證全碼;null = 這一欄沒有值。每次呼叫都會寫入解密稽核紀錄。

範例
toko control permit-reveal '<id>' --data '{"field":"applicantIdNumber"}'
回應
{
  "ok": true,
  "data": {
    "field": "applicantIdNumber",
    "value": "…"
  }
}
toko control permit-cancel-list

列出還沒完成的申請單取消請求(只讀)

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

requests
object[]

還沒完成的請求,依截止時間排序。

id
string

取消請求 ID(pcr_ 前綴)。

applicationId
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

kind
"cancel_application" | "remove_travelers"

cancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。

trigger
"departure_changed" | "order_cancelled" | "traveler_removed"

觸發點:order_cancelled / departure_changed / traveler_removed。

orderId
string | null

觸發的訂單 ID。

orderNumber
string | null

觸發的訂單編號。

travelers
object[]

離開的旅客:只有 id、姓名與身分證遮罩。

id
string
name
string
idNumberMask
string | null
status
"claimed" | "done" | "pending"

pending(待處理)/ claimed(送籤台已取走)/ done(已完成)。

attempts
number

送籤台回報失敗的次數。

claimedAt
string | null

送籤台取走的時間。

resultNote
string | null

最近一次回報的說明。

dueAt
string

最晚要完成的時間:入園日前一天的台北時間 12:00。

createdAt
string

建立時間。

completedAt
string | null

完成時間。

application
object

申請單摘要,送籤台到站方找單用。

office
"forestry" | "one_stop" | "other" | "police"

申請處。

officeLabel
string | null

申請處名稱(office = other 時有值)。

applicationNo
string | null

申請編號。

groupLabel
string | null

組別。

entryDate
string | null

入園日(YYYY-MM-DD)。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

申請單目前的狀態。

範例
toko control permit-cancel-list
回應
{
  "ok": true,
  "data": {
    "requests": [
      {
        "id": "…",
        "applicationId": "…",
        "departureId": "…",
        "kind": "cancel_application",
        "trigger": "departure_changed",
        "orderId": "…",
        "orderNumber": "…",
        "travelers": [
          {
            "id": "…",
            "name": "…",
            "idNumberMask": "…"
          }
        ],
        "status": "claimed",
        "attempts": 0,
        "claimedAt": "…",
        "resultNote": "…",
        "dueAt": "…",
        "createdAt": "…",
        "completedAt": "…",
        "application": {
          "office": "forestry",
          "officeLabel": "…",
          "applicationNo": "…",
          "groupLabel": "…",
          "entryDate": "…",
          "status": "approved"
        }
      }
    ]
  }
}
toko control permit-cancel-claim

取走待處理的申請單取消請求(會標成已取走)

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

requests
object[]

這次取走的請求,已標成 claimed。

id
string

取消請求 ID(pcr_ 前綴)。

applicationId
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

kind
"cancel_application" | "remove_travelers"

cancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。

trigger
"departure_changed" | "order_cancelled" | "traveler_removed"

觸發點:order_cancelled / departure_changed / traveler_removed。

orderId
string | null

觸發的訂單 ID。

orderNumber
string | null

觸發的訂單編號。

travelers
object[]

離開的旅客:只有 id、姓名與身分證遮罩。

id
string
name
string
idNumberMask
string | null
status
"claimed" | "done" | "pending"

pending(待處理)/ claimed(送籤台已取走)/ done(已完成)。

attempts
number

送籤台回報失敗的次數。

claimedAt
string | null

送籤台取走的時間。

resultNote
string | null

最近一次回報的說明。

dueAt
string

最晚要完成的時間:入園日前一天的台北時間 12:00。

createdAt
string

建立時間。

completedAt
string | null

完成時間。

application
object

申請單摘要,送籤台到站方找單用。

office
"forestry" | "one_stop" | "other" | "police"

申請處。

officeLabel
string | null

申請處名稱(office = other 時有值)。

applicationNo
string | null

申請編號。

groupLabel
string | null

組別。

entryDate
string | null

入園日(YYYY-MM-DD)。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

申請單目前的狀態。

範例
toko control permit-cancel-claim
回應
{
  "ok": true,
  "data": {
    "requests": [
      {
        "id": "…",
        "applicationId": "…",
        "departureId": "…",
        "kind": "cancel_application",
        "trigger": "departure_changed",
        "orderId": "…",
        "orderNumber": "…",
        "travelers": [
          {
            "id": "…",
            "name": "…",
            "idNumberMask": "…"
          }
        ],
        "status": "claimed",
        "attempts": 0,
        "claimedAt": "…",
        "resultNote": "…",
        "dueAt": "…",
        "createdAt": "…",
        "completedAt": "…",
        "application": {
          "office": "forestry",
          "officeLabel": "…",
          "applicationNo": "…",
          "groupLabel": "…",
          "entryDate": "…",
          "status": "approved"
        }
      }
    ]
  }
}
toko control permit-cancel-result

回報申請單取消請求的結果(done 或 failed)

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

request
object

回報後的請求。

id
string

取消請求 ID(pcr_ 前綴)。

applicationId
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

kind
"cancel_application" | "remove_travelers"

cancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。

trigger
"departure_changed" | "order_cancelled" | "traveler_removed"

觸發點:order_cancelled / departure_changed / traveler_removed。

orderId
string | null

觸發的訂單 ID。

orderNumber
string | null

觸發的訂單編號。

travelers
object[]

離開的旅客:只有 id、姓名與身分證遮罩。

id
string
name
string
idNumberMask
string | null
status
"claimed" | "done" | "pending"

pending(待處理)/ claimed(送籤台已取走)/ done(已完成)。

attempts
number

送籤台回報失敗的次數。

claimedAt
string | null

送籤台取走的時間。

resultNote
string | null

最近一次回報的說明。

dueAt
string

最晚要完成的時間:入園日前一天的台北時間 12:00。

createdAt
string

建立時間。

completedAt
string | null

完成時間。

application
object

申請單摘要,送籤台到站方找單用。

office
"forestry" | "one_stop" | "other" | "police"

申請處。

officeLabel
string | null

申請處名稱(office = other 時有值)。

applicationNo
string | null

申請編號。

groupLabel
string | null

組別。

entryDate
string | null

入園日(YYYY-MM-DD)。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

申請單目前的狀態。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

範例
toko control permit-cancel-result '<id>' --data '{"result":"done"}'
回應
{
  "ok": true,
  "data": {
    "request": {
      "id": "…",
      "applicationId": "…",
      "departureId": "…",
      "kind": "cancel_application",
      "trigger": "departure_changed",
      "orderId": "…",
      "orderNumber": "…",
      "travelers": [
        {
          "id": "…",
          "name": "…",
          "idNumberMask": "…"
        }
      ],
      "status": "claimed",
      "attempts": 0,
      "claimedAt": "…",
      "resultNote": "…",
      "dueAt": "…",
      "createdAt": "…",
      "completedAt": "…",
      "application": {
        "office": "forestry",
        "officeLabel": "…",
        "applicationNo": "…",
        "groupLabel": "…",
        "entryDate": "…",
        "status": "approved"
      }
    },
    "replayed": true
  }
}

toko equipment

裝備租借:品項主檔(依租期查可借量)、租借單

toko equipment items

裝備品項主檔:list / get / create / update

參數

<id>位置參數 · 必填
--active-only
旗標 · 選填

只列出啟用中(可租借)的品項

--rent-from <d>
旗標 · 選填

可租量計算的租期起日 YYYY-MM-DD(含);未給 = 今天

--rent-to <d>
旗標 · 選填

可租量計算的租期迄日 YYYY-MM-DD(含);只給起日時視為一直租下去

--name <n>
旗標 · 選填

裝備品項名稱

--total <n>
旗標 · 選填

總庫存數量

--rent-price <twd>
旗標 · 選填

每日租金(台幣)

--active
旗標 · 選填

只列出啟用中(可租借)的品項

--inactive
旗標 · 選填

回應欄位 · data[]

id
string

裝備主檔品項 id(equipmentItem_ 前綴)。

name
string

品名。

category
string | null

分類(如帳篷/睡袋/爐具;未分類為 null)。

spec
string | null

規格描述(尺寸/型號等;可空)。

rentPriceTwd
number

每日租金單價(TWD)。

depositTwd
number

每件押金(TWD)。

totalCount
number

庫存總件數。

outCount
number

目前在外件數:已交付未歸還(不含尚未開始的預留)加上歸還時的短少件。由租借明細導出。

maintenanceCount
number

維修中件數(不可借出)。

inStockCount
number

目前在倉可借件數 = 總數 − 維修 − 目前在外(不小於 0)。

availableCount
number

指定租期可借件數 = 總數 − 維修 − 期間內任一天的最高占用(不小於 0)。沒有指定租期時 看今天。占用含尚未交付的預留、逾期未還與短少件。

isActive
boolean

是否啟用(可租借)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

範例
toko equipment items list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "category": "…",
      "spec": "…",
      "rentPriceTwd": 0,
      "depositTwd": 0,
      "totalCount": 0,
      "outCount": 0,
      "maintenanceCount": 0,
      "inStockCount": 0,
      "availableCount": 0,
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko equipment rentals

租借單:list / get / order-options / create / set-dates / return / cancel / mark-overdue

參數

<id>位置參數 · 必填
<rentalId>位置參數 · 必填
--return-state <s>
旗標 · 選填

依歸還狀態篩選:rented 在租中、returned 已歸還、overdue 逾期、cancelled 已取消

--recon-state <s>
旗標 · 選填

依驗收結算狀態篩選:pending 待驗收、reconciled 已結算、deposit_pending 待退押金

--order-id <id>
旗標 · 選填

只列出綁定此訂單 ID 的租借單

--departure-id <id>
旗標 · 選填

只列出綁定此梯次 ID 的租借單

--equipment-item-id <id>
旗標 · 選填

只列出含此裝備品項的租借單

--rent-from <d>
旗標 · 選填

租期區間起(含),格式 YYYY-MM-DD。判準是租期與區間**重疊**,跨月的單兩個月都查得到

--rent-to <d>
旗標 · 選填

租期區間迄(含),格式 YYYY-MM-DD

--limit <n>
旗標 · 選填

回傳訂單筆數上限(最多 200,預設取最近多筆)

--line <itemId>:<qty>
旗標 · 選填

租借明細清單(至少一筆品項)

--start <d>
旗標 · 選填
--end <d>
旗標 · 選填
--damage-cost <twd>
旗標 · 選填

損壞賠償金額(台幣,選填)

--reason <原因>
旗標 · 選填

取消原因(必填;只留在租借單與稽核紀錄,不會印在客人的收據上)

回應欄位 · data[]

moneyMarks
object
rent
RentMark | null

租金標記;null=沒有要收的租金(已取消且沒收過,或租金為 0)。 `state`:due 未收、done 已收、refund_due 單已取消但租金已收(要退)。

deposit
DepositMark | null

押金標記;null=押金為 0,或已取消且沒收過押金。 `state`:due 未收、held 已收待退、done 已結清(帶退還額與沒收額)。

orderOnDeparture
boolean

Whether the order currently includes this rental departure.

deliveredAt選填
string | undefined | null
awaitingDelivery
boolean

還沒實際交付(issue 1917):沒有交付時間,或交付時間只是舊資料回填(= 建單時間)且起日 在今天之後的預留單。後台依這個欄位顯示交付動作,不只看 `deliveredAt` 有沒有值。

depositClearedAt選填
string | undefined | null
id
string

租借單 id(equipmentRental_ 前綴)。

rentalCode
string

人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。

orderId
string

掛載的訂單 id。

orderNumber
string | null

訂單編號;無對應訂單時為 null。

departureId
string | null

綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。

departureLabel
string | null

梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。

renterName
string | null

租借人姓名(可空)。

rentStartDate
string | null

租期起日(YYYY-MM-DD;可空)。

rentEndDate
string | null

租期迄日(YYYY-MM-DD;可空)。

returnedAt
string | null

歸還驗收時間(尚未歸還為 null)。

returnState
"cancelled" | "overdue" | "rented" | "returned"

歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。

inspectedAt
string | null

驗收時間(尚未驗收為 null)。

damageCostTwd
number | null

破損/遺失賠償金額(TWD;無為 null)。

reconState
"deposit_pending" | "pending" | "reconciled"

對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。

cancelledAt
string | null

取消時間(未取消為 null)。

cancelReason
string | null

取消原因(未取消為 null)。

notes
string | null

備註(可空)。

createdAt
string

建單時間。

updatedAt
string

最後更新時間。

lines
object[]

租借明細(借出的品項清單)。

id
string

租借明細 id(equipmentRentalLine_ 前綴)。

equipmentItemId
string

借出的裝備主檔品項 id。

itemName
string | null

裝備品項目前的名稱。

quantity
number

借出數量。

rentPriceTwdSnapshot
number

成交單位總價快照(每日單價 × 計價日數;TWD)。

depositTwdSnapshot
number

成交每件押金快照(TWD,不乘天數)。

returnedQuantity
number | null

已歸還數量(尚未歸還為 null)。

rentTotalTwd
number

成交租金合計(Σ rent snapshot × qty)。

depositTotalTwd
number

成交押金合計(Σ deposit snapshot × qty)。

rentCollectedAt
string | null

租金已收時間(未收為 null)。

rentCollectedByName
string | null

勾記租金已收的經手人姓名(遷移標記的單為 null)。

rentCollectedVia
RentCollectedVia | null

租金在哪裡收:onsite 現場收;order_payment 遷移前隨訂單付款收進公司戶頭。

depositCollectedAt
string | null

押金已收時間(未收為 null)。

depositCollectedByName
string | null

勾記押金已收的經手人姓名。

depositSettledAt
string | null

押金結清(退還或沒收)時間(未結清為 null)。

depositSettledByName
string | null

登記押金結清的經手人姓名。

depositRefundedTwd
number | null

退還客人的押金(TWD;未結清為 null)。

depositForfeitedTwd
number | null

沒收的押金(TWD;未結清為 null)。

範例
toko equipment rentals list
回應
{
  "ok": true,
  "data": [
    {
      "moneyMarks": {
        "rent": {
          "state": "done",
          "reason": "collected"
        },
        "deposit": {
          "state": "held",
          "reason": "held"
        }
      },
      "orderOnDeparture": true,
      "deliveredAt": "…",
      "awaitingDelivery": true,
      "depositClearedAt": "…",
      "id": "…",
      "rentalCode": "…",
      "orderId": "…",
      "orderNumber": "…",
      "departureId": "…",
      "departureLabel": "…",
      "renterName": "…",
      "rentStartDate": "…",
      "rentEndDate": "…",
      "returnedAt": "…",
      "returnState": "cancelled",
      "inspectedAt": "…",
      "damageCostTwd": 0,
      "reconState": "deposit_pending",
      "cancelledAt": "…",
      "cancelReason": "…",
      "notes": "…",
      "createdAt": "…",
      "updatedAt": "…",
      "lines": [
        {
          "id": "…",
          "equipmentItemId": "…",
          "itemName": "…",
          "quantity": 0,
          "rentPriceTwdSnapshot": 0,
          "depositTwdSnapshot": 0,
          "returnedQuantity": 0
        }
      ],
      "rentTotalTwd": 0,
      "depositTotalTwd": 0,
      "rentCollectedAt": "…",
      "rentCollectedByName": "…",
      "rentCollectedVia": null,
      "depositCollectedAt": "…",
      "depositCollectedByName": "…",
      "depositSettledAt": "…",
      "depositSettledByName": "…",
      "depositRefundedTwd": 0,
      "depositForfeitedTwd": 0
    }
  ]
}

toko guide-roster

帶團排班:名冊載量、月梯次、檔期衝突

toko guide-roster guides

名冊 + 該月帶團載量

參數

--month <YYYY-MM>
旗標 · 必填

查詢月份(YYYY-MM 格式)

--include-inactive
旗標 · 選填

是否一併列出已停用的嚮導(預設不列出)

--json
旗標 · 選填

回應欄位 · data[]

id
string

嚮導 id。

name
string

嚮導姓名。

rosterRole
"assistant" | "both" | "leader"

名冊職能:leader 主要隨團人員/assistant 協同/both 皆可。

specialties
string[]

可帶路線 / 專長;未設為空陣列。

status
string

嚮導狀態:active 啟用/inactive 停用。

internalNote
string | null

內部備註(只給後台看,派團時參考);null = 沒填,或檢視者沒有 `guide.read`。

maxDaysPerMonth
number | null

單一曆月實際帶團天數上限(跨月梯次按實際日期拆分計入各月);NULL = 不限。

monthDays
number

視窗涵蓋月份內 confirmed 指派實際落在月內的帶團天數合計。

monthTrips
number

視窗涵蓋月份內有帶團日的 confirmed 梯次數(每梯只算一次)。

hasTentative
boolean

視窗涵蓋月份內是否含 tentative(預塞)指派。

availability
"full" | "open" | "tentative"

派生載量狀態:任一涵蓋月達上限即 full。

monthLoads
object[]

視窗涵蓋的每個曆月的載量(依時間排序)。

month
string

曆月 `YYYY-MM`。

days
number

該月 confirmed 指派實際落在月內的帶團天數。

trips
number

該月有帶團日的 confirmed 梯次數(跨月梯次在兩個月各算一次)。

hasTentative
boolean

該月是否有 tentative(預塞)指派佔用日期。

availability
"full" | "open" | "tentative"

該月的派生載量狀態。

範例
toko guide-roster guides --month '2026-10'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "rosterRole": "assistant",
      "specialties": [
        "…"
      ],
      "status": "…",
      "internalNote": "…",
      "maxDaysPerMonth": 0,
      "monthDays": 0,
      "monthTrips": 0,
      "hasTentative": true,
      "availability": "full",
      "monthLoads": [
        {
          "month": "…",
          "days": 0,
          "trips": 0,
          "hasTentative": true,
          "availability": "full"
        }
      ]
    }
  ]
}
toko guide-roster departures

該月梯次 + 已排指派

參數

--month <YYYY-MM>
旗標 · 必填

查詢月份(YYYY-MM 格式)

--include-cancelled
旗標 · 選填

是否一併納入已取消的梯次(預設不納入)

--json
旗標 · 選填

回應欄位 · data[]

id
string

梯次 id。

tripId
string

所屬行程 id。

tripTitle
string

行程名稱。

tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

label
string | null

梯次標籤 / 副標(issue 509 ①);null = 無。排班下拉靠它分辨同日兩梯。

groupCode
string | null

團號(group-code spec §3.3);null = 尚未產生。排班 UI 用它指認梯次。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

days
number

帶團天數(含頭尾)。

capacity
number

團位容量(總名額)。

bookedCount
number

已成團報名人數。

status
string

梯次狀態(如 open 開放/full 已滿/cancelled 已取消)。

assignments
object[]

該梯次所有指派(leader 在前)。

id
string

指派紀錄 id。

guideId
string

被指派的嚮導 id。

guideName
string

被指派的嚮導姓名。

role
"assistant" | "leader"

指派角色:leader 主要隨團人員/assistant 協同。

status
"confirmed" | "tentative"

指派狀態:tentative 預塞暫定/confirmed 正式確認。

guideStartDate
string | null
guideEndDate
string | null
effectiveStartDate
string
effectiveEndDate
string
isNameBound
boolean
permitSwappedAt
string | null

勾「已換領」的時間(ISO);null = 未勾(issue 1731)。

permitSwappedByName
string | null

勾「已換領」的人的名稱;帳號已刪或未勾時為 null。

範例
toko guide-roster departures --month '2026-10'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "tripId": "…",
      "tripTitle": "…",
      "tripShortName": "…",
      "label": "…",
      "groupCode": "…",
      "departureDate": "…",
      "returnDate": "…",
      "days": 0,
      "capacity": 0,
      "bookedCount": 0,
      "status": "…",
      "assignments": [
        {
          "id": "…",
          "guideId": "…",
          "guideName": "…",
          "role": "assistant",
          "status": "confirmed",
          "guideStartDate": "…",
          "guideEndDate": "…",
          "effectiveStartDate": "…",
          "effectiveEndDate": "…",
          "isNameBound": true,
          "permitSwappedAt": "…",
          "permitSwappedByName": "…"
        }
      ]
    }
  ]
}
toko guide-roster conflicts

該月檔期衝突偵測

參數

--month <YYYY-MM>
旗標 · 必填

查詢月份(YYYY-MM 格式)

--json
旗標 · 選填

回應欄位 · data[]

guideId
string

發生衝突的嚮導 id。

guideName
string

發生衝突的嚮導姓名。

a
object

衝突梯次之一(含梯次 id/行程名/起訖日)。

departureId
string

梯次 id。

tripTitle
string

行程名稱。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

b
object

與 a 日期重疊的另一梯次(含梯次 id/行程名/起訖日)。

departureId
string

梯次 id。

tripTitle
string

行程名稱。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

範例
toko guide-roster conflicts --month '2026-10'
回應
{
  "ok": true,
  "data": [
    {
      "guideId": "…",
      "guideName": "…",
      "a": {
        "departureId": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "returnDate": "…"
      },
      "b": {
        "departureId": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "returnDate": "…"
      }
    }
  ]
}
toko guide-roster check-conflict

撞期預檢(指定梯次×嚮導)

參數

--departure <id>
旗標 · 必填

欲指派的目標梯次 ID

--guide <id>
旗標 · 必填
--guide-start-date <YYYY-MM-DD>
旗標 · 選填

預計帶團開始日期;與結束日期成對

--guide-end-date <YYYY-MM-DD>
旗標 · 選填

預計帶團結束日期;與開始日期成對

--json
旗標 · 選填
範例
toko guide-roster check-conflict --departure 'example-departureId' --guide '<id>'
回應
{
  "ok": true,
  "data": null
}
toko guide-roster assign

指派 / 重派嚮導到梯次(upsert)

參數

--departure <id>
旗標 · 必填

指派的目標梯次 ID

--guide <id>
旗標 · 必填
--role <leader|assistant>
旗標 · 必填

指派角色(leader 主要隨團人員/assistant 協同)

--status <tentative|confirmed>
旗標 · 必填

指派狀態(tentative 預塞暫定/confirmed 正式確認)

--guide-start-date <YYYY-MM-DD>
旗標 · 選填

帶團開始日期;與結束日期成對,null 回復行程預設

--guide-end-date <YYYY-MM-DD>
旗標 · 選填

帶團結束日期;與開始日期成對

--clear-guide-dates
旗標 · 選填
--name-bound
旗標 · 選填

解除綁名或變更綁名角色的原因

--name-bound-change-reason <text>
旗標 · 選填

解除綁名或變更綁名角色的原因

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立(或重派後)的指派紀錄 id。

範例
toko guide-roster assign --departure 'example-departureId' --guide '<id>' --role leader --status tentative
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko guide-roster confirm

正式確認某筆指派

參數

<assignmentId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

確認成功旗標,恆為 true。

範例
toko guide-roster confirm '<assignmentId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko guide-roster remove

移除某筆指派

參數

<assignmentId>位置參數 · 必填
--name-bound-change-reason <text>
旗標 · 選填

移除綁名指派的原因(查詢參數)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

移除成功旗標,恆為 true。

範例
toko guide-roster remove '<assignmentId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko guide-roster change-leader

換主要隨團人員(升任新人為 confirmed leader)

參數

--departure <id>
旗標 · 必填

要換主要隨團人員的目標梯次 ID

--to <guideId>
旗標 · 必填

新任主要隨團人員的嚮導 ID

--reason <t>
旗標 · 必填

換人的原因(必填,記入稽核)

--from <guideId>
旗標 · 選填

原主要隨團人員的嚮導 ID(選填;省略表示該梯次原本沒有)

--guide-start-date <YYYY-MM-DD>
旗標 · 選填

新任主要隨團人員帶團開始日期

--guide-end-date <YYYY-MM-DD>
旗標 · 選填

新任主要隨團人員帶團結束日期

--clear-guide-dates
旗標 · 選填
--name-bound
旗標 · 選填

變更綁名原因;省略時使用換人原因

--name-bound-change-reason <text>
旗標 · 選填

變更綁名原因;省略時使用換人原因

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新任 leader 的指派紀錄 id。

removedGuideIds
string[]

被移除的舊 leader 嚮導 id 清單(DB 權威)。

範例
toko guide-roster change-leader --departure 'example-departureId' --to 'example-toGuideId' --reason 'example-reason'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "removedGuideIds": [
      "…"
    ]
  }
}

toko guides

嚮導:查詢、明細、投保個資、批次匯入

toko guides list

列出/搜尋嚮導

參數

--status <all|active|inactive>
旗標 · 選填

嚮導狀態篩選(all 全部/active 啟用/inactive 停用)

--q <text>
旗標 · 選填

關鍵字搜尋(比對嚮導姓名等欄位)

--page <n>
旗標 · 選填

頁碼(從 1 起算)

--page-size <n>
旗標 · 選填

每頁筆數(上限 200)

--json
旗標 · 選填
對應端點GET /api/v1/guides
範例
toko guides list
回應
{
  "ok": true,
  "data": "…"
}
toko guides get

單一嚮導明細(依 id 或 --slug)

參數

<id>位置參數 · 必填
--slug <slug>
旗標 · 選填

依嚮導公開頁網址代稱(slug)精確查單筆(選填)

--json
旗標 · 選填

回應欄位 · data

id
string

嚮導 id(guide_ 前綴)。

name
string

嚮導姓名。

slug
string

公開頁網址代稱(slug;小寫英數與連字號)。

bio
string | null

簡介/經歷(可空)。

avatarUrl
string | null

大頭照圖片網址(可空)。

specialties
string[]

專長領域清單。

careerStartYear
number | null

入行年份(西元年;可空)。

yearsExperience
number | null

帶團年資(年數;由入行年份與台北今年推算,唯讀;可空)。

contactPhone
string | null

聯絡電話(可空)。

contactEmail
string | null

聯絡 Email(可空)。

status
"active" | "inactive"

嚮導狀態:active 啟用/inactive 停用。

categoryId
string | null

嚮導分類 id(gcat_ 前綴;名稱與順序見 guide-categories)。null = 未分類。

internalNote
string | null

內部備註(只給後台看,前台不顯示;可空)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

範例
toko guides get '<id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "slug": "…",
    "bio": "…",
    "avatarUrl": "…",
    "specialties": [
      "…"
    ],
    "careerStartYear": 0,
    "yearsExperience": 0,
    "contactPhone": "…",
    "contactEmail": "…",
    "status": "active",
    "categoryId": "…",
    "internalNote": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko guides create

建立嚮導(建檔)

參數

--name <name>
旗標 · 必填

嚮導姓名

--slug <s>
旗標 · 選填

公開頁網址代稱(選填,英數與連字號;大寫自動轉小寫,省略則由姓名產生)

--bio <t>
旗標 · 選填

嚮導簡介/經歷(選填)

--avatar-url <u>
旗標 · 選填

大頭照圖片網址(選填,http/https 或本站圖庫資產路徑)

--specialties <a,b,c>
旗標 · 選填

專長領域(選填,以逗號分隔多項)

--career-start-year <YYYY>
旗標 · 選填

入行年份(西元年,1900~今年;選填)。年資由系統推算,回應的 yearsExperience 唯讀

--contact-phone <p>
旗標 · 選填

聯絡電話(選填)

--contact-email <e>
旗標 · 選填

聯絡 Email(選填)

--status <active|inactive>
旗標 · 選填

嚮導狀態(active 啟用/inactive 停用;預設 active)

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立的嚮導 id。

slug
string

嚮導公開頁網址代稱(未帶則系統自動產生)。

範例
toko guides create --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…"
  }
}
toko guides update

更新嚮導(建檔編輯;只送有帶的欄位)

參數

<id>位置參數 · 必填
--name <n>
旗標 · 選填

嚮導姓名(省略則不更動)

--slug <s>
旗標 · 選填

公開頁網址代稱(英數與連字號;大寫自動轉小寫,省略則不更動)

--bio <t>
旗標 · 選填

嚮導簡介/經歷(省略則不更動)

--avatar-url <u>
旗標 · 選填

大頭照圖片網址(http/https 或本站圖庫資產路徑;省略則不更動)

--specialties <a,b,c>
旗標 · 選填

專長領域(以逗號分隔多項;省略則不更動)

--career-start-year <YYYY>
旗標 · 選填

入行年份(西元年,1900~今年;省略則不更動)。年資由系統推算,回應的 yearsExperience 唯讀

--contact-phone <p>
旗標 · 選填

聯絡電話(省略則不更動)

--contact-email <e>
旗標 · 選填

聯絡 Email(省略則不更動)

--status <active|inactive>
旗標 · 選填

嚮導狀態(active 啟用/inactive 停用;省略則不更動)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

範例
toko guides update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko guides archive

封存嚮導(status→inactive;重啟用請用 guides update --status active)

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

封存成功旗標,恆為 true。

範例
toko guides archive '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko guides invite-account

開通嚮導 portal 登入帳號(寄啟用信到嚮導資料的聯絡 Email)

參數

<id>位置參數 · 必填
--name <n>
旗標 · 必填

嚮導帳號的顯示姓名

--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

email
string

已開通登入帳號的 Email(= 嚮導資料的聯絡 Email)。

activationSent
boolean

是否已寄出啟用信。false 時帳號仍已建立,請嚮導在登入頁走「忘記密碼」。

範例
toko guides invite-account '<id>' --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "email": "…",
    "activationSent": true
  }
}
toko guides pii

嚮導投保個資(遮罩後;需 guide_pii.read)

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

legalName
string | null

正式姓名。

gender
string | null

性別 male / female / other;未填為 null。

emergencyContactName
string | null
emergencyContactPhone
string | null
englishName
string | null

英文姓名(與護照一致)。

idNumberMask
string | null

身分證遮罩(例:*******789);null = 未填。

passportNoMask
string | null

護照號碼遮罩;null = 未填。

birthDate
string | null

生日(YYYY-MM-DD)。

nationality
string | null

國籍;空值 = 本國。

address
string | null

通訊地址。

範例
toko guides pii '<id>'
回應
{
  "ok": true,
  "data": {
    "legalName": "…",
    "gender": "…",
    "emergencyContactName": "…",
    "emergencyContactPhone": "…",
    "englishName": "…",
    "idNumberMask": "…",
    "passportNoMask": "…",
    "birthDate": "…",
    "nationality": "…",
    "address": "…"
  }
}
toko guides pii-update

更新嚮導投保個資(只送有帶的欄位;需 guide_pii.manage)

參數

<id>位置參數 · 必填
--legal-name <n>
旗標 · 選填
--gender <male|female|other>
旗標 · 選填
--emergency-contact-name <n>
旗標 · 選填
--emergency-contact-phone <p>
旗標 · 選填
--english-name <n>
旗標 · 選填
--id-number <x>
旗標 · 選填
--passport-no <x>
旗標 · 選填
--birth-date <YYYY-MM-DD>
旗標 · 選填
--nationality <n>
旗標 · 選填
--address <a>
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

changedFields
"address" | "birthDate" | "emergencyContactName" | "emergencyContactPhone" | "englishName" | "gender" | "idNumber" | "legalName" | "nationality" | "passportNo"[]

這次實際寫入的欄位。

範例
toko guides pii-update '<id>'
回應
{
  "ok": true,
  "data": {
    "changedFields": [
      "address"
    ]
  }
}
toko guides reveal

顯示嚮導證件全碼(寫 guide.decrypt 稽核;需 guide_pii.read)

參數

<id>位置參數 · 必填
--field <idNumber|passportNo>
旗標 · 必填

欲顯示全碼的證件欄位:idNumber 身分證字號、passportNo 護照號碼

--json
旗標 · 選填

回應欄位 · data

field
"idNumber" | "passportNo"

本次解密的欄位:idNumber 身分證字號 / passportNo 護照號碼。

value
string | null

解密後的證件全碼;null = 該欄未填。每次呼叫都會寫入解密稽核紀錄。

範例
toko guides reveal '<id>' --field idNumber
回應
{
  "ok": true,
  "data": {
    "field": "idNumber",
    "value": "…"
  }
}
toko guides import

批次匯入嚮導(.xlsx/.csv;預設 dry-run,--commit 才寫入)

參數

--file <path.xlsx>
旗標 · 必填

上傳檔名,副檔名須為 .xlsx 或 .csv

--commit
旗標 · 選填
--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

filename
string

已匯入的檔名。

result
object

匯入結果(新建 / 更新 / 失敗筆數與逐列結果)。

created
number

新建筆數。

updated
number

更新筆數。

failed
number

失敗筆數(含 dry-run 就是 error 的列)。

rows
object[]

逐列結果。

rowNumber
number

試算表列號。

status
"created" | "error" | "updated"

created 已建立 / updated 已更新 / error 失敗未寫入。

guideId
string | null

寫入的嚮導 id(成功列;部分寫入的失敗列也帶,指出哪位嚮導已被改過)。

name
string

暱稱。

message
string | null

失敗原因(error 列)。

範例
toko guides import --file 'example-filename'
回應
{
  "ok": true,
  "data": {
    "filename": "…",
    "result": {
      "created": 0,
      "updated": 0,
      "failed": 0,
      "rows": [
        {
          "rowNumber": 0,
          "status": "created",
          "guideId": "…",
          "name": "…",
          "message": "…"
        }
      ]
    }
  }
}
toko guides certificate-types-update

更新 guide-certificate-types/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko guides certificate-types-update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko guides certificate-types-delete

刪除 guide-certificate-types/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
removed
object
name
string
範例
toko guides certificate-types-delete '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "removed": {
      "name": "…"
    }
  }
}
toko guides certificate-types-list

查詢 guide-certificate-types

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
name
string
sortOrder
number
isActive
boolean

停用 = 不供新證照選用(既有證照不受影響)。

certificateCount
number

引用此類別的證照數(>0 時不可刪,只可停用)。

範例
toko guides certificate-types-list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "sortOrder": 0,
      "isActive": true,
      "certificateCount": 0
    }
  ]
}
toko guides certificate-types-create

執行 guide-certificate-types

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
id
string
範例
toko guides certificate-types-create --data '{"name":"example-name"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}
toko guides categories-update

更新 guide-categories/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko guides categories-update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko guides categories-delete

刪除 guide-categories/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
removed
object
name
string
範例
toko guides categories-delete '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "removed": {
      "name": "…"
    }
  }
}
toko guides categories-list

查詢 guide-categories

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
name
string
sortOrder
number
isActive
boolean

停用 = 不供新選用(既有嚮導照舊顯示這個分類)。

guideCount
number

引用此分類的嚮導數(>0 時不可刪,只可停用)。

範例
toko guides categories-list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "sortOrder": 0,
      "isActive": true,
      "guideCount": 0
    }
  ]
}
toko guides categories-create

執行 guide-categories

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
id
string
範例
toko guides categories-create --data '{"name":"example-name"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}
toko guides certificate-update

更新 guides/[id]/certificates/[certificateId]

參數

<id>位置參數 · 必填
<certificateId>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
id
string
範例
toko guides certificate-update '<id>' '<certificateId>' --data '{"typeId":"example-typeId","issuedOn":"2026-10-13","expiresOn":"2026-10-13"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}
toko guides certificate-delete

刪除 guides/[id]/certificates/[certificateId]

參數

<id>位置參數 · 必填
<certificateId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko guides certificate-delete '<id>' '<certificateId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko guides certificates-list

查詢 guides/[id]/certificates

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
typeId
string
typeName
string
certNumber
string | null

證號(明文)。只給 guide_pii.read 看,其餘讀者由呼叫端清成 null。

issuedOn
string
expiresOn
string | null

NULL = 終身有效。

attachmentUrl
string | null

私有掃描件 URL(/api/assets 以 guide_pii.read 閘讀取)。

hasPii
boolean

有沒有證號或掃描件。不看 `withPii` 一律照實回(只露有無、不露值), 讓 UI 對沒有 guide_pii.manage 的人藏起這一列的刪除鍵(刪整列 = 清掉兩欄)。

範例
toko guides certificates-list '<id>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "typeId": "…",
      "typeName": "…",
      "certNumber": "…",
      "issuedOn": "…",
      "expiresOn": "…",
      "attachmentUrl": "…",
      "hasPii": true
    }
  ]
}
toko guides certificates-create

執行 guides/[id]/certificates

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
id
string
範例
toko guides certificates-create '<id>' --data '{"typeId":"example-typeId","issuedOn":"2026-10-13","expiresOn":"2026-10-13"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}

toko journal

旅誌:查詢、明細、作者選項

toko journal list

列出/搜尋手記

參數

--status <draft|published|archived>
旗標 · 選填

依狀態篩選:all 全部、draft 草稿、published 已發佈、archived 已封存

--q <text>
旗標 · 選填

關鍵字搜尋(標題/內容)

--page <n>
旗標 · 選填

頁碼(從 1 起)

--page-size <n>
旗標 · 選填

每頁筆數(上限 200)

--json
旗標 · 選填

回應欄位 · data

rows
object[]

本頁的手記文章列表。

id
string

手記文章 id(journalPost_ 前綴)。

slug
string

文章公開頁網址代稱(slug)。

title
string

文章標題。

excerpt
string | null

摘要(列表/SEO 用;可空)。

coverImageUrl
string | null

封面圖網址(可空)。

contentMdx
string

內文原始 MDX 內容。

authorGuideId
`guide_${string}` | null

作者嚮導 id(未指定作者時 null)。

length
number

Returns the length of a String object.

seoTitle
string | null

SEO 標題(覆寫 <title>;可空)。

seoDescription
string | null

SEO 描述(meta description;可空)。

ogImageUrl
string | null

Open Graph 分享圖網址(可空)。

status
"archived" | "draft" | "published"

文章狀態:draft 草稿/published 已發佈/archived 已封存。

publishedAt
string | null

首次發佈時間(尚未發佈為 null)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

total
number

符合條件的文章總數(跨頁)。

page
number

目前頁碼(從 1 起)。

pageSize
number

每頁筆數。

範例
toko journal list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "…",
        "slug": "…",
        "title": "…",
        "excerpt": "…",
        "coverImageUrl": "…",
        "contentMdx": "…",
        "authorGuideId": "…",
        "seoTitle": "…",
        "seoDescription": "…",
        "ogImageUrl": "…",
        "status": "archived",
        "publishedAt": "…",
        "createdAt": "…",
        "updatedAt": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}
toko journal get

單一手記完整明細

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

手記文章 id(journalPost_ 前綴)。

slug
string

文章公開頁網址代稱(slug)。

title
string

文章標題。

excerpt
string | null

摘要(列表/SEO 用;可空)。

coverImageUrl
string | null

封面圖網址(可空)。

contentMdx
string

內文原始 MDX 內容。

authorGuideId
`guide_${string}` | null

作者嚮導 id(未指定作者時 null)。

length
number

Returns the length of a String object.

seoTitle
string | null

SEO 標題(覆寫 <title>;可空)。

seoDescription
string | null

SEO 描述(meta description;可空)。

ogImageUrl
string | null

Open Graph 分享圖網址(可空)。

status
"archived" | "draft" | "published"

文章狀態:draft 草稿/published 已發佈/archived 已封存。

publishedAt
string | null

首次發佈時間(尚未發佈為 null)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

範例
toko journal get '<id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…",
    "title": "…",
    "excerpt": "…",
    "coverImageUrl": "…",
    "contentMdx": "…",
    "authorGuideId": "…",
    "seoTitle": "…",
    "seoDescription": "…",
    "ogImageUrl": "…",
    "status": "archived",
    "publishedAt": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko journal authors

可選作者(active 嚮導)清單

參數

--json
旗標 · 選填

回應欄位 · data[]

value
string

作者嚮導 id(作為選項值)。

label
string

顯示用的嚮導姓名。

範例
toko journal authors
回應
{
  "ok": true,
  "data": [
    {
      "value": "…",
      "label": "…"
    }
  ]
}
toko journal create

建立手記

參數

--title <t>
旗標 · 必填

手記標題,顯示於前台與後台列表

--content-mdx <md>
旗標 · 必填

內文(MDX 格式)

--slug <s>
旗標 · 選填

網址代稱(slug);僅小寫英數與連字號,省略時由系統依標題產生

--excerpt <e>
旗標 · 選填

摘要,列表與分享預覽用;null 清除

--cover-image-url <url>
旗標 · 選填

封面圖網址(http/https 或本站圖庫資產路徑);null 清除

--author-guide-id <id>
旗標 · 選填

作者嚮導 ID;null 表示無指定作者

--seo-title <t>
旗標 · 選填

SEO 標題,省略時用 title;null 清除

--seo-description <d>
旗標 · 選填

SEO 描述(meta description);null 清除

--og-image-url <url>
旗標 · 選填

Open Graph 分享圖網址(http/https 或本站圖庫資產路徑);null 清除

--status <draft|published|archived>
旗標 · 選填

發佈狀態:draft 草稿、published 已發佈、archived 已封存

--json
旗標 · 選填

回應欄位 · data

id
string

新建立的手記文章 id。

slug
string

文章公開頁網址代稱(slug)。

範例
toko journal create --title 'example-title' --content-mdx 'example-contentMdx'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…"
  }
}
toko journal update

更新手記(整體取代,欄位比照建立)

參數

<id>位置參數 · 必填
--title <t>
旗標 · 必填

手記標題,顯示於前台與後台列表

--content-mdx <md>
旗標 · 必填

內文(MDX 格式)

--slug <s>
旗標 · 選填

網址代稱(slug);僅小寫英數與連字號,省略時由系統依標題產生

--excerpt <e>
旗標 · 選填

摘要,列表與分享預覽用;null 清除

--cover-image-url <url>
旗標 · 選填

封面圖網址(http/https 或本站圖庫資產路徑);null 清除

--author-guide-id <id>
旗標 · 選填

作者嚮導 ID;null 表示無指定作者

--seo-title <t>
旗標 · 選填

SEO 標題,省略時用 title;null 清除

--seo-description <d>
旗標 · 選填

SEO 描述(meta description);null 清除

--og-image-url <url>
旗標 · 選填

Open Graph 分享圖網址(http/https 或本站圖庫資產路徑);null 清除

--status <...>
旗標 · 選填

發佈狀態:draft 草稿、published 已發佈、archived 已封存;省略時沿用現值

--json
旗標 · 選填

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

範例
toko journal update '<id>' --title 'example-title' --content-mdx 'example-contentMdx'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko journal archive

封存手記

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

ok
boolean

封存成功旗標,恆為 true。

範例
toko journal archive '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko exchange-rates

牌告匯率:列出、解析

toko exchange-rates list

列出牌告匯率(台銀 bot + manual 覆蓋)

參數

--currency <JPY>
旗標 · 選填

幣別篩選(ISO 4217 三碼,如 JPY / USD);省略則回傳所有幣別

--month-from <2026-05>
旗標 · 選填

起始月份(YYYY-MM,含當月);省略則不設下界

--month-to <2026-06>
旗標 · 選填

結束月份(YYYY-MM,含當月);省略則不設上界

--json
旗標 · 選填

回應欄位 · data[]

id
string

匯率牌價列 ID。

rateDate
string

掛牌日期('YYYY-MM-DD',Asia/Taipei)。

currency
string

ISO 4217('JPY' / 'IDR' / 'USD'…)。

cashBuy
string | null

各報價 canonical「1 外幣 = ? 台幣」(numeric → 字串原值保精度;NULL = 該幣別無此報價)。

cashSell
string | null

現金賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。

spotBuy
string | null

即期買入匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。

spotSell
string | null

即期賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。

source
"bot" | "manual"

牌價來源:bot 台銀自動抓取 / manual 租戶手動覆蓋。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko exchange-rates list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "rateDate": "…",
      "currency": "…",
      "cashBuy": "…",
      "cashSell": "…",
      "spotBuy": "…",
      "spotSell": "…",
      "source": "bot",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko exchange-rates resolve

解析某幣別某日報價(manual 優先 + carry-forward)

參數

--currency <JPY>
旗標 · 必填

要換算的外幣幣別(ISO 4217 三碼,如 JPY / USD)

--date <2026-06-30>
旗標 · 必填

換算基準日期(YYYY-MM-DD),套用手動優先 + 往前承接的解析規則

--quote <spot_sell>
旗標 · 選填

報價類型:cash_buy 現金買入、cash_sell 現金賣出、spot_buy 即期買入、spot_sell 即期賣出;省略預設 spot_sell

--json
旗標 · 選填

回應欄位 · data

currency
string

換算的外幣幣別(ISO 4217 三碼)。

date
string

換算基準日期(YYYY-MM-DD)。

quote
"cash_buy" | "cash_sell" | "spot_buy" | "spot_sell"

使用的報價類型(cash_buy / cash_sell / spot_buy / spot_sell)。

rate
string | null

解析出的匯率「1 外幣 = ? 台幣」(字串保精度);查無適用牌價為 null。

範例
toko exchange-rates resolve --currency 'example-currency' --date '2026-10-13'
回應
{
  "ok": true,
  "data": {
    "currency": "…",
    "date": "…",
    "quote": "cash_buy",
    "rate": "…"
  }
}
toko exchange-rates set-manual

手動覆蓋某日某幣別匯率(source=manual,可重存覆蓋)

參數

--date <2026-06-30>
旗標 · 必填
--currency <JPY>
旗標 · 必填

幣別(ISO 4217 三碼大寫,如 JPY / USD)

--cash-buy <n>
旗標 · 選填

現金買入匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

--cash-sell <n>
旗標 · 選填

現金賣出匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

--spot-buy <n>
旗標 · 選填

即期買入匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

--spot-sell <n>
旗標 · 選填

即期賣出匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否覆蓋寫入成功。

id
string

寫入 / 更新的 manual 匯率牌價列 ID。

範例
toko exchange-rates set-manual --date '<2026-06-30>' --currency 'TWD'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

toko payment-requests

對外應付請款單:查詢、明細、統計、廠商建議

toko payment-requests list

列出/搜尋對外應付請款單

參數

--status <draft|submitted|approved|paid|rejected|cancelled|all>
旗標 · 選填

依狀態篩選(draft 草稿 / submitted 已送審 / approved 已核准 / paid 已付款 / rejected 已退件 / cancelled 已取消 / all 全部)

--payee-type <supplier|guide|staff_commission|other|all>
旗標 · 選填

依收款對象類型篩選(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他 / all 全部)

--departure <id>
旗標 · 選填

依關聯梯次 id 篩選

--created-by <userId>
旗標 · 選填

依建單人 user id 篩選

--q <text>
旗標 · 選填

關鍵字搜尋(請款單號、收款對象名稱等)

--page <n>
旗標 · 選填

頁碼(從 1 起算)

--page-size <n>
旗標 · 選填

每頁筆數(上限 200)

--json
旗標 · 選填

回應欄位 · data

rows
object[]

本頁請款單列。

id
string

請款單 ID。

requestNumber
string

請款單號(人可讀,每租戶流水號)。

status
"approved" | "cancelled" | "draft" | "paid" | "rejected" | "submitted"

核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。

payeeType
"guide" | "other" | "staff_commission" | "supplier"

收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。

payeeName
string

收款對象名稱。

amountTwd
number

請款總額(TWD 整數;= 細項小計合計,代扣稅前)。

netAmountTwd
number

實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。

taxAmountTwd
number

代扣稅額(TWD 整數)。

departureId
string | null

關聯梯次 ID;未歸屬特定出團為 null。

departureLabel
string | null

關聯梯次顯示標籤(行程名稱+出發日);無則為 null。

description
string

請款單摘要說明。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string

建單人 user ID。

createdByName
string | null

建單人姓名;查無為 null。

paidAt
string | null

標記付款完成時間;未付為 null。

submittedAt
string | null

送審時間;未送審為 null。

approvedAt
string | null

核准時間;未核准為 null。

paperSignedBy
string | null

紙本簽核人;未簽為 null。

total
number

符合篩選條件的總筆數(跨全部分頁)。

page
number

目前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

範例
toko payment-requests list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "…",
        "requestNumber": "…",
        "status": "approved",
        "payeeType": "guide",
        "payeeName": "…",
        "amountTwd": 0,
        "netAmountTwd": 0,
        "taxAmountTwd": 0,
        "departureId": "…",
        "departureLabel": "…",
        "description": "…",
        "createdAt": "…",
        "updatedAt": "…",
        "createdByUserId": "…",
        "createdByName": "…",
        "paidAt": "…",
        "submittedAt": "…",
        "approvedAt": "…",
        "paperSignedBy": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}
toko payment-requests get

單一請款單完整明細

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

payeeBankAccount
string | null

收款銀行帳號。

payeeBankName
string | null

收款銀行名稱。

payeeBankBranch
string | null

收款銀行分行。

payeeTaxId
string | null

收款對象統一編號 / 稅籍編號。

submittedByUserId
string | null

送審人 user ID;未送審為 null。

submissionEventId
string | null

Audit event for the current submission.

submittedByName
string | null

送審人姓名;無則為 null。

approvedByUserId
string | null

核准人 user ID;未核准為 null。

approvedByName
string | null

核准人姓名;無則為 null。

paidByUserId
string | null

標記付款人 user ID;未付為 null。

paidByName
string | null

標記付款人姓名;無則為 null。

rejectedAt
string | null

退件時間;未退件為 null。

rejectedByName
string | null

退件人姓名;無則為 null。

rejectionReason
string | null

退件原因;無則為 null。

cancelledAt
string | null

取消時間;未取消為 null。

cancelledByName
string | null

取消人姓名;無則為 null。

cancellationReason
string | null

取消原因;無則為 null。

pdfGeneratedAt
string | null

請款單 PDF 產生時間;未產生為 null。

paperPrintedAt
string | null

紙本列印時間;未列印為 null。

bankReference
string | null

銀行匯款交易參考號(付款後回填);無則為 null。

sourceType
string | null

來源類別(`departure_cost` 梯次成本 / `profit_share` 折扣碼分潤 / `migration` 匯入); 手動建單為 null。**非 null = 細項與來源列連動,不可編輯**(見 `updatePaymentRequest`)。

items
object[]

請款細項清單。

id
string

請款細項 ID。

category
string

細項類別(如住宿、交通、餐食)。

description
string

細項說明。

quantity
number

數量。

unitPriceTwd
number

單價(TWD 整數;負值表折讓)。

totalTwd
number

細項小計(TWD 整數;= 數量 × 單價)。

notes
string | null

細項備註;無則為 null。

sortOrder
number

顯示排序(由小到大)。

audit
object[]

稽核軌跡(狀態機每次轉移一筆,時間新到舊或建立序)。

id
string

稽核記錄 ID。

action
string

動作代號(如 payable.create、payable.submit、payable.approve)。

createdAt
string

動作發生時間。

actorUserId
string | null

操作者 user ID;系統動作為 null。

actorName
string | null

操作者姓名;無則為 null。

metadata
unknown

動作附帶的結構化資料(欄位隨 action 而定)。

ipAddress
string | null

操作來源 IP;無則為 null。

id
string

請款單 ID。

requestNumber
string

請款單號(人可讀,每租戶流水號)。

status
"approved" | "cancelled" | "draft" | "paid" | "rejected" | "submitted"

核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。

payeeType
"guide" | "other" | "staff_commission" | "supplier"

收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。

payeeName
string

收款對象名稱。

amountTwd
number

請款總額(TWD 整數;= 細項小計合計,代扣稅前)。

netAmountTwd
number

實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。

taxAmountTwd
number

代扣稅額(TWD 整數)。

departureId
string | null

關聯梯次 ID;未歸屬特定出團為 null。

departureLabel
string | null

關聯梯次顯示標籤(行程名稱+出發日);無則為 null。

description
string

請款單摘要說明。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string

建單人 user ID。

createdByName
string | null

建單人姓名;查無為 null。

paidAt
string | null

標記付款完成時間;未付為 null。

submittedAt
string | null

送審時間;未送審為 null。

approvedAt
string | null

核准時間;未核准為 null。

paperSignedBy
string | null

紙本簽核人;未簽為 null。

範例
toko payment-requests get '<id>'
回應
{
  "ok": true,
  "data": {
    "payeeBankAccount": "…",
    "payeeBankName": "…",
    "payeeBankBranch": "…",
    "payeeTaxId": "…",
    "submittedByUserId": "…",
    "submissionEventId": "…",
    "submittedByName": "…",
    "approvedByUserId": "…",
    "approvedByName": "…",
    "paidByUserId": "…",
    "paidByName": "…",
    "rejectedAt": "…",
    "rejectedByName": "…",
    "rejectionReason": "…",
    "cancelledAt": "…",
    "cancelledByName": "…",
    "cancellationReason": "…",
    "pdfGeneratedAt": "…",
    "paperPrintedAt": "…",
    "bankReference": "…",
    "sourceType": "…",
    "items": [
      {
        "id": "…",
        "category": "…",
        "description": "…",
        "quantity": 0,
        "unitPriceTwd": 0,
        "totalTwd": 0,
        "notes": "…",
        "sortOrder": 0
      }
    ],
    "audit": [
      {
        "id": "…",
        "action": "…",
        "createdAt": "…",
        "actorUserId": "…",
        "actorName": "…",
        "metadata": "…",
        "ipAddress": "…"
      }
    ],
    "id": "…",
    "requestNumber": "…",
    "status": "approved",
    "payeeType": "guide",
    "payeeName": "…",
    "amountTwd": 0,
    "netAmountTwd": 0,
    "taxAmountTwd": 0,
    "departureId": "…",
    "departureLabel": "…",
    "description": "…",
    "createdAt": "…",
    "updatedAt": "…",
    "createdByUserId": "…",
    "createdByName": "…",
    "paidAt": "…",
    "submittedAt": "…",
    "approvedAt": "…",
    "paperSignedBy": "…"
  }
}
toko payment-requests stats

對外應付請款單 KPI 統計

參數

--json
旗標 · 選填

回應欄位 · data

draftCount
number

草稿狀態的請款單數。

submittedCount
number

已送審待核准的請款單數。

approvedCount
number

已核准待付款的請款單數。

paidCount
number

已付款的請款單數。

thisMonthPaidCount
number

本月已付款的請款單數。

thisMonthAmount
number

本月已付款的實付淨額合計(TWD 整數;台北月起算)。

totalApprovedAmount
number

已核准未付的實付淨額合計(TWD 整數;待出款金額)。

範例
toko payment-requests stats
回應
{
  "ok": true,
  "data": {
    "draftCount": 0,
    "submittedCount": 0,
    "approvedCount": 0,
    "paidCount": 0,
    "thisMonthPaidCount": 0,
    "thisMonthAmount": 0,
    "totalApprovedAmount": 0
  }
}
toko payment-requests suggest-items

由梯次住宿成本推導供應商請款細項建議

參數

--departure <id>
旗標 · 必填

梯次 id;用於推導該梯次住宿供應商的請款細項建議

--json
旗標 · 選填

回應欄位 · data[]

category
string

建議的請款細項類別(如住宿)。

description
string

建議的細項說明(住宿廠商 × 房型 × 晚數)。

quantity
number

建議數量(間數 × 晚數)。

unitPriceTwd
number

建議單價(TWD 整數;每間每晚成本)。

totalTwd
number

建議小計(TWD 整數;= 數量 × 單價)。

suggestedPayee
string | null

建議的收款對象(住宿供應商名稱);查無為 null。

範例
toko payment-requests suggest-items --departure 'example-departureId'
回應
{
  "ok": true,
  "data": [
    {
      "category": "…",
      "description": "…",
      "quantity": 0,
      "unitPriceTwd": 0,
      "totalTwd": 0,
      "suggestedPayee": "…"
    }
  ]
}
toko payment-requests create

建立對外應付請款單(draft,或 --submit 同步送審)

參數

<cat:desc:qty:price[:notes]>位置參數 · 必填
--payee-type <supplier|guide|staff_commission|other>
旗標 · 必填

收款對象類型(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他)

--payee-name <n>
旗標 · 必填

收款對象名稱

--description <d>
旗標 · 必填

請款單摘要說明

--tax <n>
旗標 · 選填

稅額(TWD),未填視為 0

--departure <id>
旗標 · 選填

關聯梯次 id(將此請款歸屬至特定出團)

--bank-account <n>
旗標 · 選填
--bank-name <n>
旗標 · 選填
--bank-branch <n>
旗標 · 選填
--tax-id <n>
旗標 · 選填
--submit
旗標 · 選填

是否建立後立即送審(true 則同交易送出,跳過草稿)

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立請款單的 id。

requestNumber
string

新建立請款單的單號(人可讀)。

status
"approved" | "cancelled" | "draft" | "paid" | "rejected" | "submitted"

建立後狀態(draft,或 submitImmediately 時為 submitted)。

範例
toko payment-requests create '<cat:desc:qty:price[:notes]>' --payee-type supplier --payee-name 'example-payeeName' --description 'example-description'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "requestNumber": "…",
    "status": "approved"
  }
}
toko payment-requests approve

核可請款單(submitted→approved;責任分離,需 payable.approve)

參數

<id>位置參數 · 必填
--operation-id <id>
旗標 · 必填

同次操作重試須沿用的識別

--submission-id <submissionEventId>
旗標 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

原核准操作已完成;重試不代表目前狀態。

範例
toko payment-requests approve '<id>' --operation-id 'payable-approve-20261023-001' --submission-id '<submissionEventId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payment-requests submit

送審請款單(draft→submitted)

參數

<id>位置參數 · 必填
--operation-id <id>
旗標 · 必填

同次操作重試須沿用的識別

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

原送審操作已完成;重試不代表目前狀態。

範例
toko payment-requests submit '<id>' --operation-id 'payable-submit-20261023-001'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payment-requests reject

退件請款單(submitted→draft)

參數

<id>位置參數 · 必填
--reason <text>
旗標 · 必填

退件原因(必填,回饋給建單人)

--operation-id <id>
旗標 · 必填

同次操作重試須沿用的識別

--submission-id <submissionEventId>
旗標 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

原退回操作已完成;重試不代表目前狀態。

範例
toko payment-requests reject '<id>' --reason 'Please check the request details.' --operation-id 'payable-reject-20261023-001' --submission-id '<submissionEventId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payment-requests mark-paid

標記請款單已付(approved→paid)

參數

<id>位置參數 · 必填
--bank-reference <ref>
旗標 · 必填

網銀交易序號 / 轉帳憑證號(必填)

--receiving-account <id>
旗標 · 選填

出款帳戶 id(從哪個收款帳戶付出)

--paper-signed-by <name>
旗標 · 選填

紙本簽核人姓名

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否標記付款成功(approved→paid)。

範例
toko payment-requests mark-paid '<id>' --bank-reference 'example-bankReference'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payment-requests cancel

取消請款單(非 paid;僅建單人或 admin)

參數

<id>位置參數 · 必填
--reason <text>
旗標 · 選填

取消原因;留空預設為「使用者取消」(上限 200 字)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否取消成功(idempotent,已取消再呼叫仍為 true)。

範例
toko payment-requests cancel '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payment-requests mark-signed

記錄紙本簽核人

參數

<id>位置參數 · 必填
--signed-by <name>
旗標 · 必填

紙本簽核人姓名(必填)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否記錄紙本簽核人成功。

範例
toko payment-requests mark-signed '<id>' --signed-by 'example-signedBy'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payment-requests mark-printed

標記 PDF/紙本已產生(idempotent)

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否標記 PDF / 紙本已產生成功(idempotent)。

範例
toko payment-requests mark-printed '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payment-requests update

編輯本人或管理員的草稿請款單

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否更新成功。

範例
toko payment-requests update '<id>' --data '{"payeeType":"supplier","payeeName":"example-payeeName","description":"example-description"}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko payments

收款流水帳:查詢、統計

toko payments list

列出/搜尋收款流水

參數

--status <all|paid|pending|failed|refunded|needs_manual_review>
旗標 · 選填

依金流狀態篩選(paid 已收款 / pending 待付 / failed 失敗或逾期 / refunded 已退款 / needs_manual_review 需人工核對退款)

--method <m>
旗標 · 選填

依付款方式篩選(如信用卡、ATM 轉帳)

--q <text>
旗標 · 選填

關鍵字搜尋(訂單編號、客戶名稱等)

--date-from <d>
旗標 · 選填

收款日期區間起日(YYYY-MM-DD)

--date-to <d>
旗標 · 選填

收款日期區間迄日(YYYY-MM-DD)

--page <n>
旗標 · 選填

頁碼(從 1 起算)

--json
旗標 · 選填

回應欄位 · data

rows
object[]

本頁付款嘗試列。

reconciliationTransactions
object[]
id
string
amountTwd
number
accountName
string | null
status
"matched" | "pending" | "unassigned" | "unsupported"
id
string

付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。

orderId
string

所屬訂單 ID。

orderNumber
string

所屬訂單編號(人可讀)。

merchantTradeNo
string

provider_order_ref(= 我們產的 MerchantTradeNo)。

providerTradeNo
string | null

金流商回傳的交易序號(未成交或手動入帳為 null)。

provider
string

金流商代號(如 ecpay、test;手動入帳為 manual)。

paymentMethod
string

付款方式(如信用卡、ATM 虛擬帳號)。

paymentChannel
string

收款通路與付款方式。舊收款缺少付款方式時標示未知。

amountTwd
number

此筆嘗試的金額(TWD 整數)。

purpose
string

收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。

receivingAccountName
string | null

錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。

status
string

attempt 狀態:pending | submitted | succeeded | failed | expired。

refunded
boolean

此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。

needsManualReview
boolean

此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。

paidAt
string | null

實際入帳(現金結算)時間;未結算為 null。

bankCreditedOn
string | null

銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。

createdAt
string

此筆付款嘗試的建立時間。

customerName
string

付款客戶姓名。

customerEmail
string

付款客戶 email。

tripTitle
string

訂單對應的行程名稱。

total
number

符合篩選條件的總筆數(跨全部分頁)。

page
number

目前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

範例
toko payments list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "reconciliationTransactions": [
          {
            "id": "…",
            "amountTwd": 0,
            "accountName": "…",
            "status": "matched"
          }
        ],
        "id": "…",
        "orderId": "…",
        "orderNumber": "…",
        "merchantTradeNo": "…",
        "providerTradeNo": "…",
        "provider": "…",
        "paymentMethod": "…",
        "paymentChannel": "…",
        "amountTwd": 0,
        "purpose": "…",
        "receivingAccountName": "…",
        "status": "…",
        "refunded": true,
        "needsManualReview": true,
        "paidAt": "…",
        "bankCreditedOn": "…",
        "createdAt": "…",
        "customerName": "…",
        "customerEmail": "…",
        "tripTitle": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}
toko payments stats

收款 KPI 統計

參數

--json
旗標 · 選填

回應欄位 · data

pendingReconciliationCount
number
totalAmount
number

累計實收現金(payment_transactions in)。

paidCount
number

已成功收款的付款嘗試數。

paidEcpayCount
number

已成功收款裡走綠界(provider = ecpay)的嘗試數。

paidAtmCount
number

已成功收款裡走虛擬 ATM(method = atm)的嘗試數。

pendingCount
number

待付 / 處理中的付款嘗試數(pending、submitted)。

failedCount
number

失敗或逾期的付款嘗試數(failed、expired)。

refundedCount
number

有關聯退款 / 退單的付款嘗試數。

needsManualReviewCount
number

近期需要人工核對後退款的付款嘗試數。只算最近 90 天收到的異常回呼;更早的紀錄仍會 帶著 `PaymentRow.needsManualReview`,用 `status=needs_manual_review` 篩選查得到。

thisMonthAmount
number

本月累計實收現金(TWD 整數)。

範例
toko payments stats
回應
{
  "ok": true,
  "data": {
    "pendingReconciliationCount": 0,
    "totalAmount": 0,
    "paidCount": 0,
    "paidEcpayCount": 0,
    "paidAtmCount": 0,
    "pendingCount": 0,
    "failedCount": 0,
    "refundedCount": 0,
    "needsManualReviewCount": 0,
    "thisMonthAmount": 0
  }
}
toko payments export

匯出金流分類帳為 CSV/JSON(同 list 篩選;取全頁)

參數

--status <s>
旗標 · 選填

依金流狀態篩選(如 paid 已收款 / pending 待付 / failed 失敗 / refunded 已退款)

--method <m>
旗標 · 選填

依付款方式篩選(如信用卡、ATM 轉帳)

--date-from <d>
旗標 · 選填

收款日期區間起日(YYYY-MM-DD)

--date-to <d>
旗標 · 選填

收款日期區間迄日(YYYY-MM-DD)

--q <t>
旗標 · 選填

關鍵字搜尋(訂單編號、客戶名稱等)

--format <csv|json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

rows
object[]

符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。

reconciliationTransactions
object[]
id
string
amountTwd
number
accountName
string | null
status
"matched" | "pending" | "unassigned" | "unsupported"
id
string

付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。

orderId
string

所屬訂單 ID。

orderNumber
string

所屬訂單編號(人可讀)。

merchantTradeNo
string

provider_order_ref(= 我們產的 MerchantTradeNo)。

providerTradeNo
string | null

金流商回傳的交易序號(未成交或手動入帳為 null)。

provider
string

金流商代號(如 ecpay、test;手動入帳為 manual)。

paymentMethod
string

付款方式(如信用卡、ATM 虛擬帳號)。

paymentChannel
string

收款通路與付款方式。舊收款缺少付款方式時標示未知。

amountTwd
number

此筆嘗試的金額(TWD 整數)。

purpose
string

收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。

receivingAccountName
string | null

錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。

status
string

attempt 狀態:pending | submitted | succeeded | failed | expired。

refunded
boolean

此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。

needsManualReview
boolean

此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。

paidAt
string | null

實際入帳(現金結算)時間;未結算為 null。

bankCreditedOn
string | null

銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。

createdAt
string

此筆付款嘗試的建立時間。

customerName
string

付款客戶姓名。

customerEmail
string

付款客戶 email。

tripTitle
string

訂單對應的行程名稱。

total
number

符合篩選條件的總筆數。

truncated
boolean

是否因達安全上限而截斷(true 表未回傳完整結果,呼叫端應提示)。

範例
toko payments export
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "reconciliationTransactions": [
          {
            "id": "…",
            "amountTwd": 0,
            "accountName": "…",
            "status": "matched"
          }
        ],
        "id": "…",
        "orderId": "…",
        "orderNumber": "…",
        "merchantTradeNo": "…",
        "providerTradeNo": "…",
        "provider": "…",
        "paymentMethod": "…",
        "paymentChannel": "…",
        "amountTwd": 0,
        "purpose": "…",
        "receivingAccountName": "…",
        "status": "…",
        "refunded": true,
        "needsManualReview": true,
        "paidAt": "…",
        "bankCreditedOn": "…",
        "createdAt": "…",
        "customerName": "…",
        "customerEmail": "…",
        "tripTitle": "…"
      }
    ],
    "total": 0,
    "truncated": true
  }
}

toko reconciliation

收款帳戶對帳 + 帳戶結算(讀取 / 報表)

toko reconciliation accounts

逐收款帳戶現金進出對帳

參數

--date-from <YYYY-MM-DD>
旗標 · 選填

對帳期間起日(YYYY-MM-DD,含當日),以 Asia/Taipei 牆鐘日界計;省略則不設下界

--date-to <YYYY-MM-DD>
旗標 · 選填

對帳期間迄日(YYYY-MM-DD,含整日),以 Asia/Taipei 牆鐘日界計;省略則不設上界

--json
旗標 · 選填

回應欄位 · data[]

accountId
string | null

收款帳戶 id;null = 未歸戶桶。

code
string | null

帳戶代碼;未歸戶桶為 null。

displayName
string | null

帳戶顯示名;未歸戶桶為 null。

kind
ReceivingAccountKind | null

帳戶類型(bank / cash / gateway);未歸戶桶為 null。

inTwd
number

期間內 direction='in' 的金額合計。

outTwd
number

期間內 payment_transactions direction='out' 的金額合計(客戶退款 / gateway 出)。

payableOutTwd
number

期間內供應商出款合計(payables paid 的 net_amount_twd;非 order-scoped,獨立來源 §3.1)。 **不含掛出款批次的 payable**(payout_batch_line_id 非 NULL)——批次出帳事實是一筆 account_transfers(銀行一筆 net),個別 payable 再計入即雙計。

transferInTwd
number

期間內帳戶間移轉**轉入**合計(account_transfers to 端 amount_twd;spec §3.2 / §3.3 口徑)。 排除 refund_payout(markRefundPaid 同 tx 雙寫,現金列已計入 outTwd)與沖正列 / 被沖正列 (更正記錄,非銀行流水)。

transferOutTwd
number

期間內帳戶間移轉**轉出**合計(from 端 amount_twd + fee_twd 實際離帳額;同上排除規則)。

netTwd
number

淨額 = in + transferIn − out − payableOut − transferOut(純現金流向;對帳找銀行入帳用毛額)。

txCount
number

期間內這帳戶的活動筆數(payment_transactions + payables paid + 移轉兩側)。

範例
toko reconciliation accounts
回應
{
  "ok": true,
  "data": [
    {
      "accountId": "…",
      "code": "…",
      "displayName": "…",
      "kind": null,
      "inTwd": 0,
      "outTwd": 0,
      "payableOutTwd": 0,
      "transferInTwd": 0,
      "transferOutTwd": 0,
      "netTwd": 0,
      "txCount": 0
    }
  ]
}
toko reconciliation list-accounts

收款帳戶目錄

參數

--active-only
旗標 · 選填

是否只回傳啟用中的收款帳戶(true/false);省略則含停用

--json
旗標 · 選填

回應欄位 · data[]

id
string

收款帳戶 ID。

code
string

帳戶代碼(租戶內唯一穩定識別)。

displayName
string

帳戶顯示名。

kind
"bank" | "cash" | "gateway"

帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。

gatewayProvider
string | null

綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `accounts/gateway-providers.ts`。

bankName
string | null

銀行名稱;現金/閘道帳戶為 null。

accountNo
string | null

銀行帳號;現金/閘道帳戶為 null。

bankCode
string | null
bankBranch
string | null
accountHolder
string | null
canReceive
boolean

可收款(幾乎都 true)。

canRemit
boolean

可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。

canChargeback
boolean

可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。

canPaySupplier
boolean

付款渠道:出團準備的付款登記區可選它付供應商(#1375)。

isDeprecated
boolean

廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。

isSettlementMaster
boolean

主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。

payoutAccountId
string | null

撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。

currency
string

帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。

isActive
boolean

此帳戶是否啟用。

displayOrder
number

後台清單排序序位(小者在前)。

usedCount
number

被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。

currencyLocked
boolean

幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko reconciliation list-accounts
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "kind": "bank",
      "gatewayProvider": "…",
      "bankName": "…",
      "accountNo": "…",
      "bankCode": "…",
      "bankBranch": "…",
      "accountHolder": "…",
      "canReceive": true,
      "canRemit": true,
      "canChargeback": true,
      "canPaySupplier": true,
      "isDeprecated": true,
      "isSettlementMaster": true,
      "payoutAccountId": "…",
      "currency": "…",
      "isActive": true,
      "displayOrder": 0,
      "usedCount": 0,
      "currencyLocked": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko reconciliation settlement-overview

月結互抵派生總覽

參數

--period <YYYY-MM>
旗標 · 必填

要查詢月結互抵總覽的結算期(YYYY-MM)

--json
旗標 · 選填

回應欄位 · data

period
string

結算月份(YYYY-MM,Asia/Taipei)。

matrix
object

兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。

lines
object[]

各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補淨額(恆正 > 0)。

components
object[]

組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。

label
string

組成項標籤(如某費用類型 / 代墊來源)。

amountTwd
number

簽名金額(相對 debtor→creditor 視角)。

unclassified
object

未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。

byAccount
object[]

landing 帳戶 → 未分類本金合計。

accountId
string | null

收款帳戶 ID;未歸戶為 null。

principalTwd
number

該帳戶未分類收款本金合計(TWD 整數)。

totalTwd
number

未分類收款本金總額(TWD 整數)。

obligations
object[]

本期相關掛帳(period_settlement + adjustment,含結清進度)。

id
string

帳戶間掛帳 ID。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補目標總額(TWD 整數,恆正)。

settledAmountTwd
number

已結清金額(TWD 整數,0 ≤ settled ≤ amount)。

outstandingTwd
number

待結餘額(派生 = amount − settled,>= 0)。

reason
"adjustment" | "advance_repayment" | "period_settlement" | "refund_advance"

掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。

originPeriod
string

產生月份(YYYY-MM,Asia/Taipei)。

status
"outstanding" | "partially_settled" | "settled"

結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。

note
string | null

備註;無則為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

carriedForward
object

跨期掛帳結轉基數(上期未結 period_settlement 殘額,已種入 matrix 淨額;此處供顯示明細 + 小計)。

lines
object[]

上期未結 period_settlement 殘額逐筆明細(已種入本期互抵基數)。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

outstandingTwd
number

殘額 = amount_twd − settled_amount_twd(恆正 > 0)。

originPeriod
string

原始產生月份(YYYY-MM,供顯示「來源期」)。

totalTwd
number

結轉殘額小計(TWD 整數)。

範例
toko reconciliation settlement-overview --period '2026-10'
回應
{
  "ok": true,
  "data": {
    "period": "…",
    "matrix": {
      "lines": [
        {
          "debtorAccountId": "…",
          "creditorAccountId": "…",
          "amountTwd": 0,
          "components": [
            {
              "label": "…",
              "amountTwd": 0
            }
          ]
        }
      ],
      "unclassified": {
        "byAccount": [
          {
            "accountId": "…",
            "principalTwd": 0
          }
        ],
        "totalTwd": 0
      }
    },
    "obligations": [
      {
        "id": "…",
        "debtorAccountId": "…",
        "creditorAccountId": "…",
        "amountTwd": 0,
        "settledAmountTwd": 0,
        "outstandingTwd": 0,
        "reason": "adjustment",
        "originPeriod": "…",
        "status": "outstanding",
        "note": "…",
        "createdAt": "…",
        "updatedAt": "…"
      }
    ],
    "carriedForward": {
      "lines": [
        {
          "debtorAccountId": "…",
          "creditorAccountId": "…",
          "outstandingTwd": 0,
          "originPeriod": "…"
        }
      ],
      "totalTwd": 0
    }
  }
}
toko reconciliation transfers

帳戶間移轉統一分類帳

參數

--kind <k>
旗標 · 選填

移轉類型篩選(fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 外幣期初 / reversal 沖正 / payout_batch 出款批次匯出 / gateway_payout 金流商撥款);省略則含全部

--account <id>
旗標 · 選填

帳戶 ID 篩選,回傳該帳戶為出帳或進帳方的移轉;省略則不限帳戶

--date-from <d>
旗標 · 選填

移轉日期起日(YYYY-MM-DD,含當日);省略則不設下界

--date-to <d>
旗標 · 選填

移轉日期迄日(YYYY-MM-DD,含當日);省略則不設上界

--settlement-period <YYYY-MM>
旗標 · 選填

對應月結期間(YYYY-MM)篩選;省略則不限月結

--obligation <id>
旗標 · 選填

掛帳 ID 篩選,回傳沖減該筆掛帳的移轉;省略則不限掛帳

--json
旗標 · 選填

回應欄位 · data[]

id
string

帳戶間移轉 ID。

kind
"advance" | "backfill" | "fx_conversion" | "gateway_payout" | "opening" | "payout_batch" | "refund_payout" | "replenishment" | "reversal"

移轉類型:fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 期初 / reversal 沖正 / payout_batch 出款批次匯出(系統落帳)/ gateway_payout 金流商撥款。

fromAccountId
string | null

出帳帳戶 ID;期初等單邊移轉為 null。

toAccountId
string | null

進帳帳戶 ID;單邊移轉為 null。

amountTwd
number

移轉金額(TWD 整數)。

feeTwd
number

手續費(TWD 整數)。

currency
string | null

外幣幣別(ISO 4217;純台幣移轉為 null)。

foreignAmount
number | null

外幣金額(整數;非外幣移轉為 null)。

feeForeign
number | null

外幣手續費(整數;無則為 null)。

grossRate
string | null

換匯牌價(numeric → 字串原值保精度;顯示/溯源用)。

settlementPeriod
string | null

對應月結期間(YYYY-MM);未歸屬月結為 null。

obligationId
string | null

沖減的帳戶間掛帳 ID;未沖減掛帳為 null。

reversesTransferId
string | null

被本筆沖正的原移轉 ID(kind='reversal' 時非 null)。

occurredAt
string

移轉日期('YYYY-MM-DD',date 欄)。

note
string | null

備註;無則為 null。

createdByUserId
string

登錄人 user ID。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko reconciliation transfers
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "kind": "advance",
      "fromAccountId": "…",
      "toAccountId": "…",
      "amountTwd": 0,
      "feeTwd": 0,
      "currency": "…",
      "foreignAmount": 0,
      "feeForeign": 0,
      "grossRate": "…",
      "settlementPeriod": "…",
      "obligationId": "…",
      "reversesTransferId": "…",
      "occurredAt": "…",
      "note": "…",
      "createdByUserId": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko reconciliation gateway-payout-candidates

金流商帳戶上還沒被撥出的收款與刷退(登錄金流商撥款時挑選)

參數

--account <gatewayAcctId>
旗標 · 必填

金流商(gateway)帳戶 ID,回傳該帳戶還沒被撥出的收款與刷退

--json
旗標 · 選填

回應欄位 · data[]

paymentTransactionId
string

現金列 ID。

direction
"in" | "out"

in = 收款(加項)/ out = 刷退(撥款內扣的扣項)。

orderId
string | null

訂單 ID。

retainedFundId
string | null
orderNumber
string | null

訂單編號。

date
string

發生日('YYYY-MM-DD',Asia/Taipei 牆鐘)。

amountTwd
number

金額(TWD 整數,正數;刷退的正負看 direction)。

feeTwd
number

現金列記的金流手續費(TWD 整數;多為付款回呼宣告的估計值)。

providerTradeNo
string | null

金流訂單編號(金流商交易序號,或登記收款時填的編號;沒有為 null)。

providerRefundNo
string | null
範例
toko reconciliation gateway-payout-candidates --account 'example-account'
回應
{
  "ok": true,
  "data": [
    {
      "paymentTransactionId": "…",
      "direction": "in",
      "orderId": "…",
      "retainedFundId": "…",
      "orderNumber": "…",
      "date": "…",
      "amountTwd": 0,
      "feeTwd": 0,
      "providerTradeNo": "…",
      "providerRefundNo": "…"
    }
  ]
}
toko reconciliation obligations

未結掛帳追蹤

參數

--period <YYYY-MM>
旗標 · 選填

月結來源期間(YYYY-MM),篩選由該期月結互抵推導出的掛帳;省略則不限期間

--reason <r>
旗標 · 選填

掛帳原因代碼,篩選特定成因的掛帳;省略則不限原因

--status <s>
旗標 · 選填

掛帳狀態(如未結清 / 已結清),篩選特定結清狀態;省略則含全部

--json
旗標 · 選填

回應欄位 · data[]

id
string

帳戶間掛帳 ID。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補目標總額(TWD 整數,恆正)。

settledAmountTwd
number

已結清金額(TWD 整數,0 ≤ settled ≤ amount)。

outstandingTwd
number

待結餘額(派生 = amount − settled,>= 0)。

reason
"adjustment" | "advance_repayment" | "period_settlement" | "refund_advance"

掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。

originPeriod
string

產生月份(YYYY-MM,Asia/Taipei)。

status
"outstanding" | "partially_settled" | "settled"

結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。

note
string | null

備註;無則為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko reconciliation obligations
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "debtorAccountId": "…",
      "creditorAccountId": "…",
      "amountTwd": 0,
      "settledAmountTwd": 0,
      "outstandingTwd": 0,
      "reason": "adjustment",
      "originPeriod": "…",
      "status": "outstanding",
      "note": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko reconciliation refund-execs

退款執行清單(approved + paid)

參數

--status <approved|paid>
旗標 · 選填

退款狀態篩選:approved 待執行(已核准)、paid 已執行(已出款);省略則合併回傳兩者

--json
旗標 · 選填

回應欄位 · data

rows
object[]

退款執行列(合併 approved 待執行 + paid 已執行,或收斂為指定段)。

creationSource
"manual" | "held_cash" | null
id
string

退款單 ID。

refundNumber
string

退款單號(人可讀,每租戶流水號)。

orderId
string | null

所屬訂單 ID。

ownerId
string
retainedFundId
string | null
orderNumber
string | null

所屬訂單編號(人可讀);無則為 null。

status
"approved" | "cancelled" | "draft" | "failed" | "paid" | "processing" | "submitted"

退款工作流狀態:draft / submitted / approved / processing / paid / failed / cancelled。

refundKind
"overpayment_return" | "receivable_reduction"

退款種類:receivable_reduction 減應收退款(取消 / 降價 / 服務失敗)/ overpayment_return 溢收退還(不動應收,只退多收現金)。

affectsReceivable
boolean

是否減少應收(receivable_reduction 為 true、overpayment_return 為 false;溢收退還不列入 refund_state)。

amountTwd
number

退款金額(TWD 整數,正值)。

method
"bank_transfer" | "cash" | "manual" | "original_gateway"

退款方式:original_gateway 原路退刷 / bank_transfer 銀行匯款 / cash 現金 / manual 手動。

reason
string

退款原因說明。

createdAt
string

退款單建立時間。

paidAt
string | null

實際退款出款(現金結算)時間;未執行為 null。

createdByName
string | null

建單人姓名;無則為 null。

executionMethod
RefundExecutionMethod | null

退款執行方法:chargeback 原信用卡刷退 / remit 匯出;未指定為 null。

gatewayExecutionMode選填
"manual" | "api" | undefined
gatewayNeedsReview
boolean

近 90 天已完成帳務、且明確記錄自動退刷降級的退款,需人工核對;不代表可重試。

originAccountId
string | null

出款來源帳戶 ID(從哪個收款帳戶退出);未指定為 null。

adminFeeTwd
number

內扣手續費(TWD 整數;自退款金額中扣除的行政費)。

remitFeeTwd
number

匯款手續費(TWD 整數;銀行匯出的轉帳費)。

payeeAccountName
string | null

收款人戶名(匯款退款用);無則為 null。

payeeBankCode
string | null

收款銀行代碼(匯款退款用);無則為 null。

payeeBranchCode
string | null

收款分行代碼(匯款退款用,選填);無則為 null。

payeeAccountNumber
string | null

收款帳號(匯款退款用);無則為 null。

customerName
string | null

訂購人姓名;無則為 null。

orderCancellationFeeTwd
number | null

所屬訂單的退改費(TWD 整數,公司收下不退的錢);未收退改費為 null。不含已付、不退的 換梯手續費(customer-cancellation §8.9),那筆寫在退款單事由。

orderCancellationReason
string | null

所屬訂單的取消事由:lottery_lost 未中籤 / group_not_confirmed 未成團 / customer_request 客人取消 / admin 後台取消 / no_show 未報到 / other 其他;未取消為 null。

paidByName
string | null

標記已退款的人;未執行為 null。

payoutAccountId
string | null

實際出款帳戶 ID(已執行退款的出帳現金列歸戶);未執行或未歸戶為 null。

waitingDays
number | null

從登記到現在已等待的天數;已退款、已失敗、已取消的退款單為 null。

total
number

回傳的退款執行筆數。

範例
toko reconciliation refund-execs
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "creationSource": "manual",
        "id": "…",
        "refundNumber": "…",
        "orderId": "…",
        "ownerId": "…",
        "retainedFundId": "…",
        "orderNumber": "…",
        "status": "approved",
        "refundKind": "overpayment_return",
        "affectsReceivable": true,
        "amountTwd": 0,
        "method": "bank_transfer",
        "reason": "…",
        "createdAt": "…",
        "paidAt": "…",
        "createdByName": "…",
        "executionMethod": null,
        "gatewayExecutionMode": "manual",
        "gatewayNeedsReview": true,
        "originAccountId": "…",
        "adminFeeTwd": 0,
        "remitFeeTwd": 0,
        "payeeAccountName": "…",
        "payeeBankCode": "…",
        "payeeBranchCode": "…",
        "payeeAccountNumber": "…",
        "customerName": "…",
        "orderCancellationFeeTwd": 0,
        "orderCancellationReason": "…",
        "paidByName": "…",
        "payoutAccountId": "…",
        "waitingDays": 0
      }
    ],
    "total": 0
  }
}
toko reconciliation settlement-report

月結互抵矩陣報表(同 settlement-overview 資料源)

參數

--period <YYYY-MM>
旗標 · 必填

要查詢月結互抵總覽的結算期(YYYY-MM)

--json
旗標 · 選填

回應欄位 · data

period
string

結算月份(YYYY-MM,Asia/Taipei)。

matrix
object

兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。

lines
object[]

各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補淨額(恆正 > 0)。

components
object[]

組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。

label
string

組成項標籤(如某費用類型 / 代墊來源)。

amountTwd
number

簽名金額(相對 debtor→creditor 視角)。

unclassified
object

未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。

byAccount
object[]

landing 帳戶 → 未分類本金合計。

accountId
string | null

收款帳戶 ID;未歸戶為 null。

principalTwd
number

該帳戶未分類收款本金合計(TWD 整數)。

totalTwd
number

未分類收款本金總額(TWD 整數)。

obligations
object[]

本期相關掛帳(period_settlement + adjustment,含結清進度)。

id
string

帳戶間掛帳 ID。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補目標總額(TWD 整數,恆正)。

settledAmountTwd
number

已結清金額(TWD 整數,0 ≤ settled ≤ amount)。

outstandingTwd
number

待結餘額(派生 = amount − settled,>= 0)。

reason
"adjustment" | "advance_repayment" | "period_settlement" | "refund_advance"

掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。

originPeriod
string

產生月份(YYYY-MM,Asia/Taipei)。

status
"outstanding" | "partially_settled" | "settled"

結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。

note
string | null

備註;無則為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

carriedForward
object

跨期掛帳結轉基數(上期未結 period_settlement 殘額,已種入 matrix 淨額;此處供顯示明細 + 小計)。

lines
object[]

上期未結 period_settlement 殘額逐筆明細(已種入本期互抵基數)。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

outstandingTwd
number

殘額 = amount_twd − settled_amount_twd(恆正 > 0)。

originPeriod
string

原始產生月份(YYYY-MM,供顯示「來源期」)。

totalTwd
number

結轉殘額小計(TWD 整數)。

範例
toko reconciliation settlement-report --period '2026-10'
回應
{
  "ok": true,
  "data": {
    "period": "…",
    "matrix": {
      "lines": [
        {
          "debtorAccountId": "…",
          "creditorAccountId": "…",
          "amountTwd": 0,
          "components": [
            {
              "label": "…",
              "amountTwd": 0
            }
          ]
        }
      ],
      "unclassified": {
        "byAccount": [
          {
            "accountId": "…",
            "principalTwd": 0
          }
        ],
        "totalTwd": 0
      }
    },
    "obligations": [
      {
        "id": "…",
        "debtorAccountId": "…",
        "creditorAccountId": "…",
        "amountTwd": 0,
        "settledAmountTwd": 0,
        "outstandingTwd": 0,
        "reason": "adjustment",
        "originPeriod": "…",
        "status": "outstanding",
        "note": "…",
        "createdAt": "…",
        "updatedAt": "…"
      }
    ],
    "carriedForward": {
      "lines": [
        {
          "debtorAccountId": "…",
          "creditorAccountId": "…",
          "outstandingTwd": 0,
          "originPeriod": "…"
        }
      ],
      "totalTwd": 0
    }
  }
}
toko reconciliation compute-settlement

重跑當期月結互抵派生 + upsert 掛帳(冪等)

參數

--period <YYYY-MM>
旗標 · 必填

要計算月結互抵的結算期(YYYY-MM),可重跑且冪等(不回退已結額)

--json
旗標 · 選填

回應欄位 · data

period
string

結算月份(YYYY-MM,Asia/Taipei)。

matrix
object

兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。

lines
object[]

各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補淨額(恆正 > 0)。

components
object[]

組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。

label
string

組成項標籤(如某費用類型 / 代墊來源)。

amountTwd
number

簽名金額(相對 debtor→creditor 視角)。

unclassified
object

未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。

byAccount
object[]

landing 帳戶 → 未分類本金合計。

accountId
string | null

收款帳戶 ID;未歸戶為 null。

principalTwd
number

該帳戶未分類收款本金合計(TWD 整數)。

totalTwd
number

未分類收款本金總額(TWD 整數)。

upserts
object[]

本次 run 對每條互抵列 upsert 的結果(含冪等護欄調整)。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

derivedAmountTwd
number

本次派生的目標淨額。

appliedAmountTwd
number

實際落地的掛帳 amount_twd(受冪等護欄約束,不低於已 settled)。

obligationId
string

對應的帳戶間掛帳 ID(本次 upsert 的目標列)。

action
"created" | "floored_to_settled" | "updated"

本次動作:created 新建 / updated 更新 / floored_to_settled 派生低於已結被護欄下限鎖住。

adjustmentTwd
number

派生與基準(原 amount + 已動帳 adjustment 簽名和)的差額絕對值(> 0 表示有缺口)。

adjustmentObligationId
string | null

缺口對應的引擎 adjustment 掛帳 id(新開或重跑沿用 / 改額的同一條;action='floored_to_settled' 時非 null)。

deletedObligationIds
string[]

本次 run 刪除的失效派生掛帳 id(settled=0 且不在新派生的 period_settlement + 被替換 / 失效的未結引擎 adjustment)。

範例
toko reconciliation compute-settlement --period '2026-10'
回應
{
  "ok": true,
  "data": {
    "period": "…",
    "matrix": {
      "lines": [
        {
          "debtorAccountId": "…",
          "creditorAccountId": "…",
          "amountTwd": 0,
          "components": [
            {
              "label": "…",
              "amountTwd": 0
            }
          ]
        }
      ],
      "unclassified": {
        "byAccount": [
          {
            "accountId": "…",
            "principalTwd": 0
          }
        ],
        "totalTwd": 0
      }
    },
    "upserts": [
      {
        "debtorAccountId": "…",
        "creditorAccountId": "…",
        "derivedAmountTwd": 0,
        "appliedAmountTwd": 0,
        "obligationId": "…",
        "action": "created",
        "adjustmentTwd": 0,
        "adjustmentObligationId": "…"
      }
    ],
    "deletedObligationIds": [
      "…"
    ]
  }
}
toko reconciliation create-transfer

登錄帳戶間移轉(補款/代墊/回填/換匯/金流商撥款/沖正;可選沖減掛帳)

參數

--kind <fx_conversion|replenishment|advance|backfill|gateway_payout|reversal>
旗標 · 必填

移轉類型:fx_conversion 換匯、replenishment 補款、advance 代墊、backfill 回填、gateway_payout 金流商撥款、reversal 沖正(退款匯出 / 出款批次由退款 / 出款模組落帳,不由此登錄)

--amount <twd>
旗標 · 必填

移轉台幣淨額(整數,不可為負);沖減掛帳時須大於 0。金流商撥款填銀行實際入帳的撥款額

--occurred-at <YYYY-MM-DD>
旗標 · 必填

移轉發生日期(YYYY-MM-DD)

--from <acctId>
旗標 · 選填

出帳(轉出)帳戶 ID;與進帳帳戶至少填一個,null 表示無出帳方

--to <acctId>
旗標 · 選填

進帳(轉入)帳戶 ID;與出帳帳戶至少填一個,null 表示無進帳方

--fee <twd>
旗標 · 選填

此筆移轉產生的手續費(台幣整數,不可為負)。金流商撥款填金流商從撥款內扣的手續費

--settlement-period <YYYY-MM>
旗標 · 選填

對應月結期間(YYYY-MM),標記此移轉沖減哪一期互抵;換匯不掛單一月結,傳 null

--currency <XXX>
旗標 · 選填

換匯外幣幣別(ISO 4217 三碼);非換匯傳 null

--foreign-amount <minor>
旗標 · 選填

換匯外幣金額(整數最小單位,須大於 0);非換匯傳 null

--gross-rate <r>
旗標 · 選填

換匯牌價(正數,最多 6 位小數,以字串表達避免精度遺失);非換匯傳 null

--obligation <aob_id>
旗標 · 選填

選填沖減的掛帳 ID(aob_ 開頭);換匯不沖減掛帳須傳 null

--reverses-transfer <atr_id>
旗標 · 選填

沖正指向的原移轉 ID(atr_ 開頭);kind=reversal 必填,其餘傳 null

--payment-transaction-ids <ptxn_a,ptxn_b>
旗標 · 選填

金流商撥款包含的現金列 ID(ptxn_ 開頭):收款為加項、同帳戶的刷退為扣項;kind=gateway_payout 必填且至少一筆收款,須滿足「收款合計 − 刷退合計 − 手續費 = 撥款額」,其餘傳 null

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否登錄成功(移轉 + 沖減掛帳的原子交易皆完成)。

範例
toko reconciliation create-transfer --kind fx_conversion --amount '1' --occurred-at '2026-10-13'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko reconciliation statement

銀行對帳單匯入 + 配對(範本 / 匯入 / 自動配對 / 人工配對 / 略過 / 刪批)

參數

<importId>位置參數 · 必填
<lineId>位置參數 · 必填
--account <id>
旗標 · 選填

收款帳戶 ID,回傳該帳戶的對帳單批次 / 行 / 進度彙總

--out <path>
旗標 · 選填
--period-start <d>
旗標 · 選填

對帳單期間起日(含當日)

--period-end <d>
旗標 · 選填

對帳單期間迄日(含當日)

--file <path.xlsx>
旗標 · 選填

上傳檔名,副檔名須為 .xlsx 或 .csv

--commit
旗標 · 選填
--confirm
對 production target 寫入時必帶
--source-type <payment_transaction|payable|account_transfer>
旗標 · 選填

配對來源種類:payment_transaction / payable / account_transfer

--source-id <id>
旗標 · 選填

配對來源 ID(該帳戶內未被配對的 ERP 候選)

--reason <r>
旗標 · 選填

略過原因(必填;如「手續費」「利息」)

回應欄位 · data

imports
object[]

該帳戶的對帳單批次清單(新到舊)。

id
string

對帳單批次 ID。

periodStart
string

批次期間起日('YYYY-MM-DD',含當日)。

periodEnd
string

批次期間迄日('YYYY-MM-DD',含當日)。

filename
string

匯入的檔名。

createdAt
string

匯入時間。

lineCount
number

批內總行數。

autoCount
number

自動配對的行數。

manualCount
number

人工配對的行數。

unmatchedCount
number

尚未配對的行數。

ignoredCount
number

已略過(ignored)的行數。

excludedCount
number

已解除配對(excluded)的行數。

lines
object[]

該帳戶所有對帳單行(跨批次)。

id
string

對帳單行 ID。

importId
string

所屬對帳單批次 ID。

lineNo
number

檔案內行號(1 起算)。

txnDate
string

交易日期('YYYY-MM-DD')。

direction
"in" | "out"

現金流向:in 存入 / out 支出。

amountTwd
number

金額(TWD 整數)。

memo
string

摘要 / 備註文字。

status
string

配對狀態:unmatched 未配 / auto 自動 / manual 人工 / ignored 略過 / excluded 已解除。

matchedSourceType
string | null

已配對來源種類(payment_transaction / payable / account_transfer);未配為 null。

matchedSourceId
string | null

已配對來源 ID;未配為 null。

ignoredReason
string | null

略過原因;非 ignored 為 null。

progress
object

配對進度彙總。

total
number

總行數。

matched
number

已配對行數(auto + manual)。

unmatched
number

未配對行數。

ignored
number

已略過行數。

excluded
number

已解除配對行數。

範例
toko reconciliation statement view --account 'example-account'
回應
{
  "ok": true,
  "data": {
    "imports": [
      {
        "id": "…",
        "periodStart": "…",
        "periodEnd": "…",
        "filename": "…",
        "createdAt": "…",
        "lineCount": 0,
        "autoCount": 0,
        "manualCount": 0,
        "unmatchedCount": 0,
        "ignoredCount": 0,
        "excludedCount": 0
      }
    ],
    "lines": [
      {
        "id": "…",
        "importId": "…",
        "lineNo": 0,
        "txnDate": "…",
        "direction": "in",
        "amountTwd": 0,
        "memo": "…",
        "status": "…",
        "matchedSourceType": "…",
        "matchedSourceId": "…",
        "ignoredReason": "…"
      }
    ],
    "progress": {
      "total": 0,
      "matched": 0,
      "unmatched": 0,
      "ignored": 0,
      "excluded": 0
    }
  }
}

toko accrual-ledger

掛帳台帳:四區塊派生、梯次彙總(純讀)

toko accrual-ledger get

單一期間掛帳台帳四區塊

參數

--period <YYYY-MM>
旗標 · 必填

出團月(格式 YYYY-MM,Asia/Taipei 時區)

--json
旗標 · 選填

回應欄位 · data

period
string

結算期間(YYYY-MM,Asia/Taipei 出團月)。

departureSummary
object[]

梯次彙總(區塊 1):出團月落於 period 的各梯次收入 / 成本 / 毛利。

departureId
string

梯次 ID。

tripTitle
string

團名。

departureDate
string

出團日期(YYYY-MM-DD)。

pax
number

出團人數(該梯次確認人數)。

revenueTwd
number

總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。

cancellationFeeTwd
number

已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。

realCostTwd
number

真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。

grossProfitTwd
number

毛利毛估 = revenue − realCost(含房費)。

costLines
object[]

成本掛帳逐筆(區塊 2):該期梯次上所有 departure_costs 成本列。

id
string

成本列 ID。

tripTitle
string

團名。

departureDate
string

所屬梯次出團日期(YYYY-MM-DD)。

category
string

成本分類(如 交通 / 餐費 / 保險 / 嚮導)。

vendor
string | null

廠商:已建檔廠商名優先,否則用成本列上填寫的廠商名;null = 未填。

amountTwd
number

代墊額(真實成本,TWD 整數)。

invoiceAmountTwd
number

憑證額(外帳可申報金額,TWD 整數)。

isDeclarable
boolean

有無發票憑證。

reviewStatus
string

覆核狀態:掛了支出證明單則用其 status(pending/approved),否則由有無憑證派生。

payables
object[]

應付清單(區塊 3):該期歸屬的請款單(payables)。

payableNumber
string

請款單號(人類可讀)。

tripTitle
string

團名(未綁定梯次的手動請款顯示「未綁定梯次」)。

payeeName
string

受款對象(供應商 / 嚮導 / 派車人等)。

amountTwd
number

請款金額(整數 TWD)。

status
string

draft | submitted | approved | paid | cancelled | rejected。

receivables
object[]

應收清單(區塊 4):該期梯次上的 tour 訂單應收 / 實收 / 待收。

orderId
string

訂單 ID(後台訂單頁連結用)。

orderNumber
string

訂單編號。

tripTitle
string

團名(該訂單在期間內任一梯次的團名)。

departureDate
string

出團日(YYYY-MM-DD)。同一行程同月常有多個梯次(例:10/15、10/16、10/22 三梯), 只看團名分不出是哪一梯,追尾款時得靠這欄(issue 600)。 ⚠️ 與 `tripTitle` 同一列取出(兩欄必定同梯),但口徑同樣是「該訂單在期間內**任一** 梯次」:跨梯次訂單只顯示最早那一梯,而 `receivableTwd` 是整張單未攤提的應收。真正 逐梯辨識要把來源改成 per (order, departure) 並接上 `order-money/allocation.ts` 的攤提, 屬系統級 follow-up,不在本欄範圍。

primaryTravelerName
string | null

主要旅客姓名:有標記 `is_primary` 取該列,沒標記就取最早建立的旅客(與 departure-prep / agreements / traveler-validation 同一套取法——匯入的歷史單 可能整單都沒標主要旅客)。訂單完全沒有旅客列時為 null。 刻意不取下單會員名:一張訂單的下單者與旅客常常不是同一人(CONTEXT.md「旅客」)。

receivableTwd
number

應收金額(TWD 整數)。

receivedTwd
number

實收金額(收款減退款,TWD 整數)。

outstandingTwd
number

待收 = receivable − received。

範例
toko accrual-ledger get --period '2026-10'
回應
{
  "ok": true,
  "data": {
    "period": "…",
    "departureSummary": [
      {
        "departureId": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "pax": 0,
        "revenueTwd": 0,
        "cancellationFeeTwd": 0,
        "realCostTwd": 0,
        "grossProfitTwd": 0
      }
    ],
    "costLines": [
      {
        "id": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "category": "…",
        "vendor": "…",
        "amountTwd": 0,
        "invoiceAmountTwd": 0,
        "isDeclarable": true,
        "reviewStatus": "…"
      }
    ],
    "payables": [
      {
        "payableNumber": "…",
        "tripTitle": "…",
        "payeeName": "…",
        "amountTwd": 0,
        "status": "…"
      }
    ],
    "receivables": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "primaryTravelerName": "…",
        "receivableTwd": 0,
        "receivedTwd": 0,
        "outstandingTwd": 0
      }
    ]
  }
}
toko accrual-ledger departure-summary

梯次彙總區塊(收入/成本/毛利)

參數

--period <YYYY-MM>
旗標 · 必填

出團月(格式 YYYY-MM,Asia/Taipei 時區)

--json
旗標 · 選填

回應欄位 · data

period
string

結算期間(YYYY-MM,Asia/Taipei 出團月),回聲請求參數。

departureSummary
object[]

梯次彙總:出團月落於 period 的各梯次收入 / 真實成本 / 毛估毛利。

departureId
string

梯次 ID。

tripTitle
string

團名。

departureDate
string

出團日期(YYYY-MM-DD)。

pax
number

出團人數(該梯次確認人數)。

revenueTwd
number

總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。

cancellationFeeTwd
number

已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。

realCostTwd
number

真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。

grossProfitTwd
number

毛利毛估 = revenue − realCost(含房費)。

範例
toko accrual-ledger departure-summary --period '2026-10'
回應
{
  "ok": true,
  "data": {
    "period": "…",
    "departureSummary": [
      {
        "departureId": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "pax": 0,
        "revenueTwd": 0,
        "cancellationFeeTwd": 0,
        "realCostTwd": 0,
        "grossProfitTwd": 0
      }
    ]
  }
}

toko cost-templates

成本範本:查詢、明細

toko cost-templates list

列出成本範本(--active 只回啟用中精簡清單)

參數

--status <active|archived>
旗標 · 選填

依狀態篩選:active 啟用、archived 已封存

--active
旗標 · 選填

啟用時只回傳輕量的 { id, name } 綁定挑選清單(行程設定的成本範本下拉用)

--json
旗標 · 選填

回應欄位 · data[]

id
string

成本範本 id(ct_ 前綴)。

name
string

成本範本名稱。

範例
toko cost-templates list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…"
    }
  ]
}
toko cost-templates get

單一成本範本完整明細(含成本行)

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

lines
object[]

成本行明細(品項 × 單價 × 數量模型)。

id
string

成本行 ID。

templateId
string

所屬成本範本 ID。

category
string

成本分類(如 交通 / 餐費 / 保險)。

vendorName
string | null

供應商 / 廠商名(選填)。

description
string | null

摘要說明(選填)。

unitPriceTwd
number | null

TWD 行的單價;外幣行 null。

currency
string

幣別('TWD' = 台幣行)。

unitPriceForeign
number | null

外幣行的外幣單價;TWD 行 null。

internalRateSource
TemplateRateSource | null

外幣行的內帳匯率來源;TWD 行 null。

fxAccountId
string | null

internalRateSource='fx_account' 時的外幣帳戶 id。

quantityMode
"fixed" | "headcount"

數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。

quantityFixed
number | null

fixed 模式的固定數量;headcount 模式為 null。

headcountComponents
HeadcountComponent[] | null

headcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。

groupDivisor
number | null

headcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。

isDeclarable
boolean

是否預設有合法憑證(帶入成本列的 is_declarable 初值)。

sortOrder
number

顯示排序。

id
string

成本範本 ID。

name
string

範本名稱。

description
string | null

範本說明(選填)。

status
"active" | "archived"

狀態:active 啟用 / archived 已封存。

lineCount
number

成本行數(派生)。

boundTripCount
number

綁定行程數(派生)。

appliedDepartureCount
number

套用過本範本的梯次數(派生:departure_costs 經 template_line_id 追溯)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko cost-templates get '<id>'
回應
{
  "ok": true,
  "data": {
    "lines": [
      {
        "id": "…",
        "templateId": "…",
        "category": "…",
        "vendorName": "…",
        "description": "…",
        "unitPriceTwd": 0,
        "currency": "…",
        "unitPriceForeign": 0,
        "internalRateSource": null,
        "fxAccountId": "…",
        "quantityMode": "fixed",
        "quantityFixed": 0,
        "headcountComponents": null,
        "groupDivisor": 0,
        "isDeclarable": true,
        "sortOrder": 0
      }
    ],
    "id": "…",
    "name": "…",
    "description": "…",
    "status": "active",
    "lineCount": 0,
    "boundTripCount": 0,
    "appliedDepartureCount": 0,
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko cost-templates create

建立成本範本

參數

--name <名稱>
旗標 · 必填

成本範本名稱

--description <說明>
旗標 · 選填

成本範本說明

--json
旗標 · 選填

回應欄位 · data

id
string

新建成本範本 ID(ct_ 前綴)。

範例
toko cost-templates create --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko cost-templates update

更新成本範本(名稱/說明/狀態)

參數

<id>位置參數 · 必填
--name <名稱>
旗標 · 必填

成本範本名稱

--status <active|archived>
旗標 · 必填

範本狀態:active 啟用、archived 已封存

--description <說明>
旗標 · 選填

成本範本說明

--json
旗標 · 選填

回應欄位 · data

ok
boolean

是否更新成功。

範例
toko cost-templates update '<id>' --name 'example-name' --status active
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko cost-templates add-line

新增成本行(--line 為 JSON:{category,unitPriceTwd,quantityMode,...})

參數

<templateId>位置參數 · 必填
--line <json>
旗標 · 必填

成本明細列:含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式(fixed 固定/headcount 人數)與對應數量/人數組成、isDeclarable 是否可報帳等欄位

--json
旗標 · 選填

回應欄位 · data

rateNotice
string | null

新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 null。

id
string

新建成本明細行 ID。

範例
toko cost-templates add-line '<templateId>' --line '{"category":"Transport","quantityMode":"fixed","quantityFixed":1,"unitPriceTwd":100}'
回應
{
  "ok": true,
  "data": {
    "rateNotice": "…",
    "id": "…"
  }
}
toko cost-templates update-line

更新成本行(--line 為 JSON)

參數

<lineId>位置參數 · 必填
--line <json>
旗標 · 必填

成本明細列更新內容:含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式(fixed 固定/headcount 人數)與對應數量/人數組成、isDeclarable 是否可報帳等欄位

--json
旗標 · 選填

回應欄位 · data

ok
boolean

是否更新成功。

rateNotice
string | null

新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 null。

範例
toko cost-templates update-line '<lineId>' --line '{"category":"example-category","quantityMode":"fixed"}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "rateNotice": "…"
  }
}
toko cost-templates delete-line

刪除成本行

參數

<lineId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

ok
boolean

是否刪除成功。

範例
toko cost-templates delete-line '<lineId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko ledger

內外帳:梯次毛利、逐筆成本、支出證明單、待覆核申報

toko ledger list

列出各梯次內外帳摘要(毛利 / 可申報 / pending 證明單)

參數

--period <YYYY-MM>
旗標 · 選填

出團月(格式 YYYY-MM);只列出該月的梯次

--trip <id>
旗標 · 選填

行程 ID;只列出該行程的梯次

--window-days <N>
旗標 · 選填

回看天數;只列出近 N 天內的梯次

--json
旗標 · 選填

回應欄位 · data[]

tripTitle
string

梯次標題(trip title)。

tripSlug
string

行程 slug(URL 識別)。

departureDate
string

出團日期(YYYY-MM-DD)。

returnDate
string

回程日期(YYYY-MM-DD)。

groupCode
string | null

團號(group-code),未產生為 null。

pax
number

報名人數(非取消單 party_size 合計)。

departureStatus
string

梯次狀態。`'cancelled'` 的列在毛利視圖裡只帶已認列退改費(訂單應收與成本都是 0), 呈現面必須標出來,否則會被當成一個真的有出團的梯次(issue 601)。

departureId
string

梯次 ID。

revenueTwd
number

本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。

orderRevenueTwd
number

訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。

cancellationFeeTwd
number

已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。

realCostTwd
number

內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。

declarableCostTwd
number

外帳可申報成本(各成本列憑證額合計,TWD 整數)。

nonDeclarableCostTwd
number

不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。

costBilledTwd
number

已轉請款成本。

costUnbilledTwd
number

未轉請款成本;不含即付(當下已付、不轉請款)。

grossProfitTwd
number

**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。

feeEcpayTwd
number

預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。

feeFongshouTwd
number

預估豐收款手續費(**參考預估**,非權威)。

taxEstTwd
number

預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。

estimatedNetProfitTwd
number

**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。

marginPct
number | null

毛利率(grossProfit / revenue),revenue=0 時為 null。

pendingProofCount
number

待核(pending)支出證明單數。

feeRates
object

套用的費率(呈現用)。

ecpayFeeBps
number

預估綠界手續費率(basis points,270 = 2.70%)。

fongshouFeeBps
number

預估豐收款手續費率(basis points,50 = 0.50%)。

profitTaxBps
number

預估發票 / 營所稅率(basis points,500 = 5.00%)。

範例
toko ledger list
回應
{
  "ok": true,
  "data": [
    {
      "tripTitle": "…",
      "tripSlug": "…",
      "departureDate": "…",
      "returnDate": "…",
      "groupCode": "…",
      "pax": 0,
      "departureStatus": "…",
      "departureId": "…",
      "revenueTwd": 0,
      "orderRevenueTwd": 0,
      "cancellationFeeTwd": 0,
      "realCostTwd": 0,
      "declarableCostTwd": 0,
      "nonDeclarableCostTwd": 0,
      "costBilledTwd": 0,
      "costUnbilledTwd": 0,
      "grossProfitTwd": 0,
      "feeEcpayTwd": 0,
      "feeFongshouTwd": 0,
      "taxEstTwd": 0,
      "estimatedNetProfitTwd": 0,
      "marginPct": 0,
      "pendingProofCount": 0,
      "feeRates": {
        "ecpayFeeBps": 0,
        "fongshouFeeBps": 0,
        "profitTaxBps": 0
      }
    }
  ]
}
toko ledger get

單一梯次內外帳派生明細

參數

<departureId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

departureId
string

梯次 ID。

revenueTwd
number

本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。

orderRevenueTwd
number

訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。

cancellationFeeTwd
number

已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。

realCostTwd
number

內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。

declarableCostTwd
number

外帳可申報成本(各成本列憑證額合計,TWD 整數)。

nonDeclarableCostTwd
number

不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。

costBilledTwd
number

已轉請款成本。

costUnbilledTwd
number

未轉請款成本;不含即付(當下已付、不轉請款)。

grossProfitTwd
number

**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。

feeEcpayTwd
number

預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。

feeFongshouTwd
number

預估豐收款手續費(**參考預估**,非權威)。

taxEstTwd
number

預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。

estimatedNetProfitTwd
number

**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。

marginPct
number | null

毛利率(grossProfit / revenue),revenue=0 時為 null。

pendingProofCount
number

待核(pending)支出證明單數。

feeRates
object

套用的費率(呈現用)。

ecpayFeeBps
number

預估綠界手續費率(basis points,270 = 2.70%)。

fongshouFeeBps
number

預估豐收款手續費率(basis points,50 = 0.50%)。

profitTaxBps
number

預估發票 / 營所稅率(basis points,500 = 5.00%)。

範例
toko ledger get '<departureId>'
回應
{
  "ok": true,
  "data": {
    "departureId": "…",
    "revenueTwd": 0,
    "orderRevenueTwd": 0,
    "cancellationFeeTwd": 0,
    "realCostTwd": 0,
    "declarableCostTwd": 0,
    "nonDeclarableCostTwd": 0,
    "costBilledTwd": 0,
    "costUnbilledTwd": 0,
    "grossProfitTwd": 0,
    "feeEcpayTwd": 0,
    "feeFongshouTwd": 0,
    "taxEstTwd": 0,
    "estimatedNetProfitTwd": 0,
    "marginPct": 0,
    "pendingProofCount": 0,
    "feeRates": {
      "ecpayFeeBps": 0,
      "fongshouFeeBps": 0,
      "profitTaxBps": 0
    }
  }
}
toko ledger costs

列出某梯次逐筆成本登記

參數

<departureId>位置參數 · 必填
--created-by <userId>
旗標 · 選填

登記者使用者 ID;只列出該人登記的成本列

--json
旗標 · 選填

回應欄位 · data[]

id
string

成本列 ID。

departureId
string

所屬梯次 ID。

category
string

成本分類(如 交通 / 餐費 / 保險 / 嚮導)。

vendorName
string | null

供應商 / 廠商名(選填)。

description
string | null

摘要說明(選填)。

receiptImageUrl
string | null

憑證照片 URL(G3-2);未附照片 null。app-route 私有 URL,讀取經 route 權限閘。

amountTwd
number

代墊 / 實付額(內帳真實成本,整數 TWD)。

invoiceAmountTwd
number

外帳可申報額(internal-external-ledger §2.1)。

isDeclarable
boolean

是否取得合法憑證。

reviewStatus
string

覆核狀態 'pending' | 'approved'(L'):pending 不計入毛利 / 可申報(UI 須標示、停用轉請款)。

currency
string

成本幣別(ISO 4217);'TWD' = 台幣列。

foreignAmount
number | null

外幣金額(最小單位整數);TWD 列 null。

internalRateSource
string | null

內帳匯率來源;TWD 列 null。

fxAccountId
string | null

internalRateSource='fx_account' 時的外幣帳戶 id。

internalRate
string | null

內帳匯率快照(numeric 字串);TWD 列 null。

externalRate
string | null

外帳匯率快照(numeric 字串,台銀牌告);TWD 列 null。

feeCategory
string | null

費用類型 tag(account-settlement §3.4,成本側類別→領域帳戶映射;null = 未 tag)。

quantityMode
QuantityMode | null

計價方式 'fixed' / 'headcount';一次性總額列 null。

headcountComponents
HeadcountComponent[] | null

headcount 人頭組合;非 headcount 列 null。

groupDivisor
number | null

headcount 組距;非 headcount 列 null。

quantity
number | null

解析後(headcount)或自訂(fixed)的數量;一次性總額列 null。

unitPriceTwd
number | null

單價(台幣整數);一次性總額列 null。

expenseProofId
string | null

無發票支出掛的支出證明單 id(null = 有憑證)。

proofNumber
string | null

支出證明單單號(join expense_proofs,null = 無)。

proofStatus
string | null

支出證明單狀態 'pending' | 'approved'(null = 無)。

payableId
string | null

已轉請款時連結的請款單 ID(null = 未轉請款)。

payableNumber
string | null

連結請款單的人類可讀單號(null = 未轉請款)。

payableStatus
string | null

連結請款單的狀態(draft / submitted / approved / paid…;null = 未轉請款)。

paymentMethod
"paid_on_spot" | "request"

付款方式:'request' 走請款核簽;'paid_on_spot' 即付,算已付、不轉請款。

paidOn
string | null

即付的付款日('YYYY-MM-DD');請款列 null。

paidAccountId
string | null

即付的付款帳戶 ID;未指定或請款列 null。

spentOn
string | null

消費日期('YYYY-MM-DD',嚮導填的);後台登記的列 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko ledger costs '<departureId>'
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "departureId": "…",
      "category": "…",
      "vendorName": "…",
      "description": "…",
      "receiptImageUrl": "…",
      "amountTwd": 0,
      "invoiceAmountTwd": 0,
      "isDeclarable": true,
      "reviewStatus": "…",
      "currency": "…",
      "foreignAmount": 0,
      "internalRateSource": "…",
      "fxAccountId": "…",
      "internalRate": "…",
      "externalRate": "…",
      "feeCategory": "…",
      "quantityMode": null,
      "headcountComponents": null,
      "groupDivisor": 0,
      "quantity": 0,
      "unitPriceTwd": 0,
      "expenseProofId": "…",
      "proofNumber": "…",
      "proofStatus": "…",
      "payableId": "…",
      "payableNumber": "…",
      "payableStatus": "…",
      "paymentMethod": "paid_on_spot",
      "paidOn": "…",
      "paidAccountId": "…",
      "spentOn": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko ledger proofs

列出某梯次支出證明單

參數

<departureId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

支出證明單 ID。

proofNumber
string

人類可讀單號(EP-YYMMDD-NNN)。

departureId
string

所屬梯次 ID。

payeeName
string

受款對象(自然人 / 廠商)。

amountTwd
number

金額(整數 TWD,對應所掛成本列的 amount_twd)。

reasonNoReceipt
string

無法取得單據的原因(如「自然人」)。

summary
string | null

支出內容及摘要(選填)。

handlerUserId
string

經手人(建單者)user ID。

approverUserId
string | null

核准人 user ID(強制 ≠ 經手人);未核准為 null。

status
"approved" | "pending"

狀態:pending 待核准 / approved 已核准(核准後 append-only)。

approvedAt
string | null

核准時間;未核准為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko ledger proofs '<departureId>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "proofNumber": "…",
    "departureId": "…",
    "payeeName": "…",
    "amountTwd": 0,
    "reasonNoReceipt": "…",
    "summary": "…",
    "handlerUserId": "…",
    "approverUserId": "…",
    "status": "approved",
    "approvedAt": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko ledger declarations

列出跨梯次待覆核的嚮導申報成本

參數

--json
旗標 · 選填

回應欄位 · data[]

id
string

成本列 ID。

departureId
string

所屬梯次 ID。

tripTitle
string

團名。

departureDate
string

出團日期(YYYY-MM-DD)。

category
string

成本分類。

vendorName
string | null

供應商 / 廠商名(選填)。

amountTwd
number

代墊 / 實付額(內帳真實成本,整數 TWD)。

invoiceAmountTwd
number

憑證 / 發票額(外帳可申報,整數 TWD)。

isDeclarable
boolean

是否取得合法憑證。

createdByName
string | null

登記者(經手人)姓名。

spentOn
string | null

消費日期('YYYY-MM-DD',嚮導填的);後台登記的列 null。

createdAt
string

建立時間(嚮導送出時間)。

範例
toko ledger declarations
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "departureId": "…",
      "tripTitle": "…",
      "departureDate": "…",
      "category": "…",
      "vendorName": "…",
      "amountTwd": 0,
      "invoiceAmountTwd": 0,
      "isDeclarable": true,
      "createdByName": "…",
      "spentOn": "…",
      "createdAt": "…"
    }
  ]
}
toko ledger cancelled-departures

列出取消梯次待結轉(殘餘成本 / 是否已結轉特殊損益)

參數

--json
旗標 · 選填

回應欄位 · data[]

departureId
string

取消梯次 ID。

tripTitle
string

團名。

tripSlug
string

行程 slug(URL 識別)。

departureDate
string

原出團日期(YYYY-MM-DD)。

returnDate
string

原回程日期(YYYY-MM-DD)。

groupCode
string | null

團號(group-code),未產生為 null。

residualCostTwd
number

殘餘成本(TWD 整數):已核准的逐筆成本合計 + 房費底價成本合計。

approvedCostCount
number

已核准成本筆數。

pendingCostCount
number

待覆核成本筆數(UI 提示「還有待覆核成本」)。

roomCostTwd
number

房費殘餘成本(房費底價成本合計,整數 TWD)。

conversion
{ expenseId: string; amountTwd: number; period: string; description: string; } | null

結轉狀態:已結轉為特殊損益時的費用列資訊(expenseId / 金額 / 歸屬月 / 摘要);未結轉為 null。

expenseId
string
amountTwd
number
period
string
description
string
範例
toko ledger cancelled-departures
回應
{
  "ok": true,
  "data": [
    {
      "departureId": "…",
      "tripTitle": "…",
      "tripSlug": "…",
      "departureDate": "…",
      "returnDate": "…",
      "groupCode": "…",
      "residualCostTwd": 0,
      "approvedCostCount": 0,
      "pendingCostCount": 0,
      "roomCostTwd": 0,
      "conversion": "…"
    }
  ]
}
toko ledger cost-create

登記一筆成本(departure_cost.manage)

參數

<departureId>位置參數 · 必填
--category <類別>
旗標 · 必填

成本類別代碼(須為有效的成本分類)

--amount <twd>
旗標 · 必填

真實成本(台幣整數)。台幣路徑必填;外幣路徑忽略,改由外幣金額乘匯率換算

--vendor <n>
旗標 · 選填

廠商/供應商名稱

--description <t>
旗標 · 選填

成本摘要說明

--no-receipt
旗標 · 選填
--payee <n>
旗標 · 選填

受款人姓名;無發票時的支出證明單欄位

--reason <t>
旗標 · 選填

無發票原因;無發票時的支出證明單欄位

--invoice-amount <n>
旗標 · 選填

外帳可申報額覆寫(台幣整數,須大於等於 0、無上限)

--quantity-mode <fixed|headcount>
旗標 · 選填

計價方式;未給=一次性總額,fixed=單價×固定數量,headcount=單價×ceil(Σ人頭/組距)

--unit-price-twd <twd>
旗標 · 選填

單價(台幣整數);計價方式給值時必填

--headcount-components <passenger,leader,assistant,driver>
旗標 · 選填

依人頭計價的人頭組合(passenger/leader/assistant/driver,至少一項)

--group-divisor <n>
旗標 · 選填

依人頭計價的組距(≥ 1;空=直接加總)

--quantity-fixed <n>
旗標 · 選填

固定數量計價的數量(≥ 0)

--currency <C>
旗標 · 選填

幣別;TWD 或留空走台幣路徑,其他幣別走外幣路徑

--foreign-amount <n>
旗標 · 選填

外幣金額(最小單位整數,ISO 4217 minor units:JPY 以「円」、USD 以「cent」計);僅外幣路徑使用

--rate-source <fx_account|published|manual>
旗標 · 選填
--fx-account <id>
旗標 · 選填

外幣帳戶 ID;內帳匯率來源為 fx_account 時使用

--manual-rate <r>
旗標 · 選填

手填成交匯率(字串保精度);內帳匯率來源為 manual 時使用

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立成本列的 ID(dc_ 前綴)。

expenseProofId
string | null

隨附憑證的 ID(若本次一併登記),無則為 null。

範例
toko ledger cost-create '<departureId>' --category 'example-category' --amount '1'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "expenseProofId": "…"
  }
}
toko ledger cost-update

更新一筆成本(departure_cost.manage)

參數

<costId>位置參數 · 必填
--category <類別>
旗標 · 必填

成本類別代碼(須為有效的成本分類)

--amount <twd>
旗標 · 選填

真實成本(台幣整數)。台幣路徑必填;外幣路徑忽略,改由外幣金額乘匯率換算

--vendor <n>
旗標 · 選填

廠商/供應商名稱

--description <t>
旗標 · 選填

成本摘要說明

--no-receipt
旗標 · 選填
--payee <n>
旗標 · 選填

受款人姓名;無發票時的支出證明單欄位

--reason <t>
旗標 · 選填

無發票原因;無發票時的支出證明單欄位

--invoice-amount <n>
旗標 · 選填

外帳可申報額覆寫(台幣整數,須大於等於 0、無上限)

--quantity-mode <fixed|headcount>
旗標 · 選填

計價方式;未給=一次性總額,fixed=單價×固定數量,headcount=單價×ceil(Σ人頭/組距)

--unit-price-twd <twd>
旗標 · 選填

單價(台幣整數);計價方式給值時必填

--headcount-components <passenger,leader,assistant,driver>
旗標 · 選填

依人頭計價的人頭組合(passenger/leader/assistant/driver,至少一項)

--group-divisor <n>
旗標 · 選填

依人頭計價的組距(≥ 1;空=直接加總)

--quantity-fixed <n>
旗標 · 選填

固定數量計價的數量(≥ 0)

--currency <C>
旗標 · 選填

幣別;TWD 或留空走台幣路徑,其他幣別走外幣路徑

--foreign-amount <n>
旗標 · 選填

外幣金額(最小單位整數,ISO 4217 minor units:JPY 以「円」、USD 以「cent」計);僅外幣路徑使用

--rate-source <s>
旗標 · 選填
--fx-account <id>
旗標 · 選填

外幣帳戶 ID;內帳匯率來源為 fx_account 時使用

--manual-rate <r>
旗標 · 選填

手填成交匯率(字串保精度);內帳匯率來源為 manual 時使用

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:成本列已更新。

範例
toko ledger cost-update '<costId>' --category 'example-category'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko ledger cost-delete

刪除一筆未轉請款的成本(departure_cost.manage)

參數

<costId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:成本列已刪除。

範例
toko ledger cost-delete '<costId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko ledger approve-proof

核准支出證明單(ledger.approve;責任分離)

參數

<proofId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:憑證已核准。

範例
toko ledger approve-proof '<proofId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko ledger approve-declaration

覆核嚮導自報待覆核成本(ledger.approve;責任分離)

參數

<costId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:成本自主申報已核准。

範例
toko ledger approve-declaration '<costId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko ledger convert-to-payable

成本轉請款核簽(departure_cost.manage 且 payable.create)

參數

<departureId>位置參數 · 必填
--costs <id1,id2,...>
旗標 · 必填
--payee-name <n>
旗標 · 必填

受款對象名稱

--payee-type <supplier|guide|staff_commission|other>
旗標 · 選填

受款對象類型:supplier 供應商、guide 嚮導、staff_commission 員工佣金、other 其他

--bank-account <n>
旗標 · 選填
--bank-name <n>
旗標 · 選填
--bank-branch <n>
旗標 · 選填
--tax-id <n>
旗標 · 選填
--tax-amount <n>
旗標 · 選填

代扣稅額(台幣整數)

--submit
旗標 · 選填

是否建立後立即送出核簽(true 直接送審)

--confirm
對 production target 寫入時必帶

回應欄位 · data

payableId
string

新建立應付單的 ID(pay_ 前綴)。

payableNumber
string

應付單編號(租戶內流水序號,出款核簽用)。

範例
toko ledger convert-to-payable '<departureId>' --costs '<id1,id2,...>' --payee-name 'example-payeeName'
回應
{
  "ok": true,
  "data": {
    "payableId": "…",
    "payableNumber": "…"
  }
}
toko ledger convert-cancelled

結轉取消梯次殘餘成本為公司特殊損益(operating_expense.manage)

參數

--departure <id>
旗標 · 必填

梯次 ID

--category <expenseCategoryId>
旗標 · 必填

特殊損益費用科目 ID(kind=special)

--amount <twd>
旗標 · 必填

結轉金額(整數 TWD,預設殘餘成本)

--period <YYYY-MM>
旗標 · 必填

歸屬月(取消月,格式 YYYY-MM)

--description <"...">
旗標 · 必填

摘要

--note <t>
旗標 · 選填

備註(選填)

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立的殘餘成本營業費用列 ID(opx_ 前綴)。

residualCostTwd
number

結轉的殘餘成本金額(TWD 整數)。

範例
toko ledger convert-cancelled --departure 'example-departureId' --category 'example-categoryId' --amount '1' --period '2026-10' --description 'example-description'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "residualCostTwd": 0
  }
}
toko ledger revert-cancelled

撤銷取消梯次的結轉(operating_expense.manage)

參數

--departure <id>
旗標 · 必填

梯次 ID

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:已還原取消梯次的轉列,回到未轉列狀態。

範例
toko ledger revert-cancelled --departure 'example-departureId'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko payouts

出款批次:彙整 preview、出帳帳戶、批次轉帳檔

toko payouts aggregate

建批前彙整 preview(當月已核准未付 payable 依收款對象 group)

參數

--period <YYYY-MM>
旗標 · 必填

出款月份(YYYY-MM),彙整該月已核准未付的應付

--scope <guide|supplier|staff>
旗標 · 必填

收款對象範圍(guide 領隊嚮導 / supplier 供應商 / staff 員工)

--json
旗標 · 選填

回應欄位 · data[]

payeeType
"guide" | "staff" | "supplier"

收款對象類型:guide 領隊嚮導 / supplier 供應商 / staff 員工。

payeeRefId
string

收款對象識別 key:供應商為其 ID,領隊 / 員工為收款人姓名。

payeeName
string

收款對象名稱。

payeeAccountName
string | null

收款人戶名(supplier 取 suppliers / guide 取 guides;staff 暫無主檔 → null)。

payeeBankCode
string | null

收款銀行代號(同上來源;無主檔為 null)。

payeeAccountNumber
string | null

收款帳號(同上來源;無主檔為 null,遮罩回傳)。

grossTwd
number

當月已核准未付的請款單淨額合計(TWD 整數)。

items
object[]

彙整明細(日期 + 團名 + 金額,唯讀派生,不另存)。

payableId
string

請款單 ID。

payableNumber
string

請款單人類可讀單號。

date
string | null

梯次出發日('YYYY-MM-DD');無連梯次時 null。

tripLabel
string | null

團名;無連梯次時 null。

amountTwd
number

該請款單的應付淨額(TWD 整數)。

範例
toko payouts aggregate --period '2026-10' --scope guide
回應
{
  "ok": true,
  "data": [
    {
      "payeeType": "guide",
      "payeeRefId": "…",
      "payeeName": "…",
      "payeeAccountName": "…",
      "payeeBankCode": "…",
      "payeeAccountNumber": "…",
      "grossTwd": 0,
      "items": [
        {
          "payableId": "…",
          "payableNumber": "…",
          "date": "…",
          "tripLabel": "…",
          "amountTwd": 0
        }
      ]
    }
  ]
}
toko payouts remit-accounts

出帳帳戶選項(收款帳戶目錄)

參數

--json
旗標 · 選填

回應欄位 · data[]

id
string

收款帳戶 ID。

code
string

帳戶代碼(租戶內唯一穩定識別)。

displayName
string

帳戶顯示名。

kind
"bank" | "cash" | "gateway"

帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。

gatewayProvider
string | null

綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `accounts/gateway-providers.ts`。

bankName
string | null

銀行名稱;現金/閘道帳戶為 null。

accountNo
string | null

銀行帳號;現金/閘道帳戶為 null。

bankCode
string | null
bankBranch
string | null
accountHolder
string | null
canReceive
boolean

可收款(幾乎都 true)。

canRemit
boolean

可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。

canChargeback
boolean

可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。

canPaySupplier
boolean

付款渠道:出團準備的付款登記區可選它付供應商(#1375)。

isDeprecated
boolean

廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。

isSettlementMaster
boolean

主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。

payoutAccountId
string | null

撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。

currency
string

帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。

isActive
boolean

此帳戶是否啟用。

displayOrder
number

後台清單排序序位(小者在前)。

usedCount
number

被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。

currencyLocked
boolean

幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko payouts remit-accounts
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "kind": "bank",
      "gatewayProvider": "…",
      "bankName": "…",
      "accountNo": "…",
      "bankCode": "…",
      "bankBranch": "…",
      "accountHolder": "…",
      "canReceive": true,
      "canRemit": true,
      "canChargeback": true,
      "canPaySupplier": true,
      "isDeprecated": true,
      "isSettlementMaster": true,
      "payoutAccountId": "…",
      "currency": "…",
      "isActive": true,
      "displayOrder": 0,
      "usedCount": 0,
      "currencyLocked": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko payouts transfer-file

出款批次標準四欄批次轉帳檔

參數

<pob_id>位置參數 · 必填
--format <csv|json>
旗標 · 選填

輸出格式:json 完整匯出(預設)或 csv 僅回傳轉帳檔字串

--json
旗標 · 選填
範例
toko payouts transfer-file '<pob_id>'
回應
{
  "ok": true,
  "data": "…"
}
toko payouts create-batch

建立出款批次草稿(gross + 通用扣款項 → draft,不 mark paid)

參數

--period <YYYY-MM>
旗標 · 必填

出款月份(YYYY-MM)

--scope <guide|supplier|staff>
旗標 · 必填
--account <acct_id>
旗標 · 選填
--lines <json|@file>
旗標 · 必填

納入批次的出款列(至少一列)

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立出款批次的 ID(pob_ 前綴)。

範例
toko payouts create-batch --period '2026-10' --scope guide --lines json
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko payouts confirm-batch

確認出款批次(draft → confirmed:mark paid + 記出帳)

參數

<pob_id>位置參數 · 必填
--bank-ref <ref>
旗標 · 選填

網銀交易序號 / 轉帳憑證號(可選)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:出款批次已確認送出。

範例
toko payouts confirm-batch '<pob_id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko payouts issue-confirm-token

為供應商批次列簽發廠商自助確認 token(idempotent,回 token)

參數

<pobl_id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

token
string

廠商自助確認 token(拼成對外確認頁網址;未過期重複簽發回原 token)。

expiresAt
string

token 失效時點(簽發起 14 天;重簽發會展延)。

範例
toko payouts issue-confirm-token '<pobl_id>'
回應
{
  "ok": true,
  "data": {
    "token": "…",
    "expiresAt": "…"
  }
}

toko pnl

公司損益:營業費用台帳、費用科目、月損益表

toko pnl expenses

列出公司營業費用(list)

參數

--period <YYYY-MM>
旗標 · 選填

歸屬月(格式 YYYY-MM);只列出該月的費用

--kind <opex|tax|platform_fee|special>
旗標 · 選填

費用大類:opex 營業費用、tax 稅、platform_fee 平台手續費、special 特殊損益

--category <id>
旗標 · 選填

費用類別 ID;只列出該類別的費用

--json
旗標 · 選填

回應欄位 · data[]

id
string

費用列 ID。

categoryId
string

費用科目 ID。

categoryCode
string | null

費用科目代碼(如 rent / salary_admin)。

categoryDisplayName
string | null

費用科目顯示名。

categoryKind
string | null

費用科目大類(opex / tax / platform_fee / special)。

period
string

歸屬月(YYYY-MM,損益表據此彙整;可與支付日不同月)。

incurredOn
string | null

發生 / 支付日期(YYYY-MM-DD);金流商內扣 / 攤提無單一發生日者為 null。

amountTwd
number

金額(整數 TWD,恆正;損 / 益由 direction 表達)。

direction
"expense" | "income"

損益方向:'expense' 費用(預設)| 'income' 特殊收入(僅 kind='special' 科目)。

description
string

摘要(廠商 / 品名,如 台中房租 / 委外廣告投放)。

paidFromAccountId
string | null

出帳帳戶 ID;金流商內扣者為 null。

paidFromAccountName
string | null

出帳帳戶顯示名。

frontedByUserId
string | null

代墊者 user ID;非空代表由此人代墊待回補(走請款回補代墊者)。

frontedByName
string | null

代墊者姓名。

payableId
string | null

若走出款核簽,連結的請款單 ID;否則 null。

payableNumber
string | null

連結請款單的人類可讀單號。

recurring
boolean

月固定標記(人工登記時備註「月固定」;自動生成走範本表,非此欄)。

status
"confirmed" | "draft"

'draft'(月固定範本自動生成、待確認,不入損益)| 'confirmed'(計入損益)。

origin
"departure_conversion" | "manual" | "recurring"

'manual'(手動登記)| 'recurring'(月固定範本自動生成)| 'departure_conversion'(取消梯次結轉,§3.4)。

sourceTemplateId
string | null

生成來源範本(origin='recurring');手動登記為 null。

note
string | null

備註。

createdByUserId
string

經手人 user ID(建立此費用列者)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko pnl expenses list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "categoryId": "…",
      "categoryCode": "…",
      "categoryDisplayName": "…",
      "categoryKind": "…",
      "period": "…",
      "incurredOn": "…",
      "amountTwd": 0,
      "direction": "expense",
      "description": "…",
      "paidFromAccountId": "…",
      "paidFromAccountName": "…",
      "frontedByUserId": "…",
      "frontedByName": "…",
      "payableId": "…",
      "payableNumber": "…",
      "recurring": true,
      "status": "confirmed",
      "origin": "departure_conversion",
      "sourceTemplateId": "…",
      "note": "…",
      "createdByUserId": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko pnl expense-categories

列出費用科目目錄(list)

參數

--active-only
旗標 · 選填

是否只回傳啟用中的費用類別;預設含停用列

--json
旗標 · 選填

回應欄位 · data[]

id
string

費用類別 ID。

code
string

科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。

displayName
string

顯示名(如 房租 / 行政薪資 / 營業稅)。

kind
"opex" | "platform_fee" | "special" | "tax"

費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。

isActive
boolean

是否啟用(停用不刪,既有費用列仍引用得到)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko pnl expense-categories list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "kind": "opex",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko pnl expense-create

登錄一筆公司營業費用(與梯次無關;歸屬月供月損益彙整)

參數

--category <id>
旗標 · 必填

費用類別 ID(對應公司費用類別目錄)

--period <YYYY-MM>
旗標 · 必填

歸屬月(格式 YYYY-MM),供月損益表彙整

--description <t>
旗標 · 必填

費用摘要

--amount <twd>
旗標 · 必填

費用金額(台幣非負整數;損 / 益由 direction 表達,金額恆正)

--paid-from <acctId>
旗標 · 選填

支付來源帳戶 ID

--fronted-by <userId>
旗標 · 選填

代墊人使用者 ID(由員工先行墊付時填寫)

--incurred-on <YYYY-MM-DD>
旗標 · 選填

費用發生日期(格式 YYYY-MM-DD)

--note <t>
旗標 · 選填

備註

--recurring
旗標 · 選填

是否為週期性費用

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:營業費用列已新增。

id
string

新建立營業費用列的 ID(opx_ 前綴)。

範例
toko pnl expense-create --category 'example-categoryId' --period '2026-10' --description 'example-description' --amount '1'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko pnl expense-update

更正一筆公司營業費用(整列覆寫;payable 連結須帶回)

參數

<id>位置參數 · 必填
--category <id>
旗標 · 必填

費用類別 ID(對應公司費用類別目錄)

--period <YYYY-MM>
旗標 · 必填

歸屬月(格式 YYYY-MM),供月損益表彙整

--description <t>
旗標 · 必填

費用摘要

--amount <twd>
旗標 · 必填

費用金額(台幣非負整數;損 / 益由 direction 表達,金額恆正)

--paid-from <acctId>
旗標 · 選填

支付來源帳戶 ID

--fronted-by <userId>
旗標 · 選填

代墊人使用者 ID(由員工先行墊付時填寫)

--incurred-on <d>
旗標 · 選填

費用發生日期(格式 YYYY-MM-DD)

--note <t>
旗標 · 選填

備註

--payable-id <id>
旗標 · 選填

關聯的請款核簽 ID;整列覆寫時須原樣帶回,省略則清為 null

--recurring
旗標 · 選填

是否為週期性費用

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:營業費用列已更新。

範例
toko pnl expense-update '<id>' --category 'example-categoryId' --period '2026-10' --description 'example-description' --amount '1'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko pnl statement

公司月損益表(各區毛利→公司淨利)

參數

--period <YYYY-MM>
旗標 · 必填

損益表結算月(格式 YYYY-MM)

--json
旗標 · 選填

回應欄位 · data

period
string

結算期間(YYYY-MM)。

regions
object[]

各區毛利明細(出團月落 period 的梯次按區 roll-up)。

region
string

派生 region key(穩定,由 trip 屬性派生)。

label
string

顯示標籤(destination 原文 / 衍生)。

revenueTwd
number

本區收入(出團月落 period 的梯次合計 = 訂單收入 + 已認列退改費,TWD 整數)。

cancellationFeeTwd
number

本區已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 拆出來呈現,會計才對得出「這區的收入有多少不是出團賺的」。

directCostTwd
number

本區真實直接成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。

marginTwd
number

本區毛利 = revenue − directCost。

departures
number

本區梯次數(出團月落 period)。

grossMarginTwd
number

各區毛利加總(整數 TWD)。

revenueTotalTwd
number

各區營收加總(整數 TWD)。

adminFeeIncomeTwd
number

行政手續費收入(退款收取的行政手續費,只計未出團 / 取消單,TWD 整數)。

otherIncomeTwd
number

其他收入合計 = adminFeeIncome(整數 TWD)。GS「額外收入總計」改由 special income 列 承載(specialIncomeTwd,於特殊損益帶號區認列),**不在此重複加總**(防雙計)。

expensesByKind
object[]

公司營業費用按 kind roll-up(opex / tax / platform_fee,只計已確認)。

kind
string

'opex' / 'tax' / 'platform_fee'。

amountTwd
number

該 kind 本期費用合計(整數 TWD)。

count
number

該 kind 本期費用筆數。

operatingExpenseTotalTwd
number

公司營業費用合計 = Σ opex / tax / platform_fee(整數 TWD)。

special
object[]

特殊損益逐筆(kind='special',一次性、獨立列、損 / 益雙向,只計已確認)。

id
string

費用列 ID。

categoryId
string

費用科目 ID(特殊損益科目)。

categoryDisplayName
string | null

費用科目顯示名。

description
string

摘要(如 取消神山床位沒收訂金 / 保險理賠)。

amountTwd
number

金額(整數 TWD ≥ 0,DB CHECK operating_expenses_amount_nonneg)。恆正;損 / 益由 `direction` 表達(0055 特殊損益雙向)。

direction
"expense" | "income"

'expense' 損(扣減淨利)| 'income' 益(增益淨利;GS「額外收入」的載體)。

specialExpenseTwd
number

特殊損合計(direction='expense',整數 TWD ≥ 0)。

specialIncomeTwd
number

特殊益合計(direction='income',整數 TWD ≥ 0)= GS「額外收入總計」的載體。

specialTotalTwd
number

特殊損益淨額(**帶號**)= specialExpense − specialIncome(整數 TWD;淨益時為負)。 淨利計算從淨利扣減此值——income 為正貢獻(損 1000 + 益 300 → specialTotal 700 → 淨利 −700)。

netProfitTwd
number

公司淨利 = grossMargin + otherIncome − operatingExpenseTotal − specialTotal(帶號)。

netMarginPct
number | null

淨利率(netProfit / revenueTotal),revenue=0 時 null。

範例
toko pnl statement --period '2026-10'
回應
{
  "ok": true,
  "data": {
    "period": "…",
    "regions": [
      {
        "region": "…",
        "label": "…",
        "revenueTwd": 0,
        "cancellationFeeTwd": 0,
        "directCostTwd": 0,
        "marginTwd": 0,
        "departures": 0
      }
    ],
    "grossMarginTwd": 0,
    "revenueTotalTwd": 0,
    "adminFeeIncomeTwd": 0,
    "otherIncomeTwd": 0,
    "expensesByKind": [
      {
        "kind": "…",
        "amountTwd": 0,
        "count": 0
      }
    ],
    "operatingExpenseTotalTwd": 0,
    "special": [
      {
        "id": "…",
        "categoryId": "…",
        "categoryDisplayName": "…",
        "description": "…",
        "amountTwd": 0,
        "direction": "expense"
      }
    ],
    "specialExpenseTwd": 0,
    "specialIncomeTwd": 0,
    "specialTotalTwd": 0,
    "netProfitTwd": 0,
    "netMarginPct": 0
  }
}

toko reports

財務報表:月結摘要(實收現金口徑,tour-scoped)

toko reports monthly

月結財務摘要(KPI + 行程排行 + 金流商分布)

參數

--year <YYYY>
旗標 · 必填

報表年份(西元四位數),月界以台北時區計

--month <1-12>
旗標 · 必填

報表月份,1 至 12

--json
旗標 · 選填

回應欄位 · data

year
number

報表年份(西元四位數)。

month
number

報表月份(1-12,月界以 Asia/Taipei 計)。

totalOrders
number

本月建立的 tour 訂單數(依 created_at 計)。

paidOrders
number

本月有實收現金的 tour 訂單數(月內有 inbound 交易)。

cancelledOrders
number

本月取消的 tour 訂單數(依 `orders.cancelled_at` 計,Asia/Taipei 月界)。 取消時刻不明的單(`cancelled_at IS NULL`)任何月份都不計 —— 見 repo 內註解。

cancelledOrdersUnknownDate
number

取消時刻不明的 tour 訂單數(`cancelled_at IS NULL`)。**不分月份** —— 它們 不屬於任何一個月,所以每個月的報表都回報同一個值。> 0 時畫面要講出來: 否則這批單在每個月的報表裡都不出現,逐月讀完也看不出它們存在 —— 而它們確實 被取消了。(不要拿它跟訂單清單的取消總數對:報表側是 tour line 口徑、清單側是 `o.kind`,兩者本來就不相等,見 #20。)

totalRevenue
number

本月實際收到的現金。

refundedAmount
number

本月退還客人的現金,含退款與信用卡爭議退款(chargeback)。

netCash
number

本月淨現金:實收減退還現金,再扣手續費。

newCustomers
number

本月新註冊會員數(排除 staff 角色)。

byTrip
object[]

依行程銷售排行(前 10 名,按本月實收現金的攤提份額)。跨出團/跨行程訂單 的現金按 order-money/allocation 份額分(#12),Σ revenue = totalRevenue 守恆。

tripId
string

行程 ID。

tripTitle
string

團名。

orderCount
number

該行程本月有實收現金份額的訂單數。

revenue
number

collected_cash by trip:本月實收現金攤提份額(tour-scoped)。

byProvider
object[]

依金流商分組的本月實收現金。

provider
string

金流商代碼(如 ecpay / test)。

paymentChannel
string

該組實際包含的收款通路,以「、」分隔。金額仍依金流商分組。

orderCount
number

該金流商本月有實收現金的訂單數。

amount
number

collected_cash by provider:本月實收現金(tour-scoped)。

dailyRevenue
object[]

collected_cash by day:本月逐日實收現金(tour-scoped,Asia/Taipei 日界), 整月零填滿(無入帳的日子 amount=0)。Σ amount === totalRevenue,與 KPI 對帳。

day
string

日期(YYYY-MM-DD,Asia/Taipei 日界)。

amount
number

當日實收現金(tour-scoped,整數 TWD)。

範例
toko reports monthly --year '2000' --month '1'
回應
{
  "ok": true,
  "data": {
    "year": 0,
    "month": 0,
    "totalOrders": 0,
    "paidOrders": 0,
    "cancelledOrders": 0,
    "cancelledOrdersUnknownDate": 0,
    "totalRevenue": 0,
    "refundedAmount": 0,
    "netCash": 0,
    "newCustomers": 0,
    "byTrip": [
      {
        "tripId": "…",
        "tripTitle": "…",
        "orderCount": 0,
        "revenue": 0
      }
    ],
    "byProvider": [
      {
        "provider": "…",
        "paymentChannel": "…",
        "orderCount": 0,
        "amount": 0
      }
    ],
    "dailyRevenue": [
      {
        "day": "…",
        "amount": 0
      }
    ]
  }
}

toko suppliers

廠商目錄:查詢、明細

toko suppliers list

列出/搜尋廠商目錄

參數

--status <active|inactive|all>
旗標 · 選填

依狀態篩選(active 啟用 / inactive 停用 / all 全部,預設 active)

--q <text>
旗標 · 選填

關鍵字搜尋(廠商名稱或類別)

--json
旗標 · 選填

回應欄位 · data[]

id
string

廠商 ID。

name
string

廠商名稱。

categoryHint
string | null

慣用類別提示(租戶自定,非硬枚舉)。

payeeAccountName
string | null

收款人戶名(批次轉帳檔欄 (1))。

payeeBankCode
string | null

收款銀行代號(批次轉帳檔欄 (3))。

payeeAccountNumber
string | null

收款帳號(批次轉帳檔欄 (2),遮罩回傳)。

status
"active" | "inactive"

狀態:active 啟用 / inactive 停用(停用不刪)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko suppliers list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "categoryHint": "…",
      "payeeAccountName": "…",
      "payeeBankCode": "…",
      "payeeAccountNumber": "…",
      "status": "active",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko suppliers get

單一廠商明細(含遮罩收款資料)

參數

<sup_id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

廠商 ID。

name
string

廠商名稱。

categoryHint
string | null

慣用類別提示(租戶自定,非硬枚舉)。

payeeAccountName
string | null

收款人戶名(批次轉帳檔欄 (1))。

payeeBankCode
string | null

收款銀行代號(批次轉帳檔欄 (3))。

payeeAccountNumber
string | null

收款帳號(批次轉帳檔欄 (2),遮罩回傳)。

status
"active" | "inactive"

狀態:active 啟用 / inactive 停用(停用不刪)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko suppliers get '<sup_id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "categoryHint": "…",
    "payeeAccountName": "…",
    "payeeBankCode": "…",
    "payeeAccountNumber": "…",
    "status": "active",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
toko suppliers create

新增廠商(出款對象主檔;進階會計模組)

參數

--name <n>
旗標 · 必填

廠商名稱(出款對象顯示名)

--category <t>
旗標 · 選填

類別提示(如住宿、交通、餐飲),供分類與搜尋

--payee-name <n>
旗標 · 選填
--bank-code <004>
旗標 · 選填
--account-number <n>
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:廠商已新增。

id
string

新建立廠商的 ID(sup_ 前綴)。

範例
toko suppliers create --name 'example-name'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
toko suppliers update

編輯廠商(partial:省略=保留;帳號 write-only,留空不變更)

參數

<sup_id>位置參數 · 必填
--name <n>
旗標 · 選填

廠商名稱(出款對象顯示名)

--category <t>
旗標 · 選填

類別提示(如住宿、交通、餐飲),供分類與搜尋

--payee-name <n>
旗標 · 選填
--bank-code <004>
旗標 · 選填
--account-number <n>
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

固定為 true:廠商資料已更新。

範例
toko suppliers update '<sup_id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko audit

稽核日誌:查詢、統計(唯讀)

toko audit list

列出/篩選稽核紀錄

參數

--action <prefix>
旗標 · 選填

動作代碼篩選,例如 order.update(比對稽核事件的動作)

--actor <userId>
旗標 · 選填

操作者篩選,比對執行該動作的使用者 ID

--entity <targetType>
旗標 · 選填

目標實體篩選,比對被操作對象的類型或 ID

--from <YYYY-MM-DD>
旗標 · 選填

起始時間(ISO 8601),僅回傳此時間之後的事件

--to <YYYY-MM-DD>
旗標 · 選填

結束時間(ISO 8601),僅回傳此時間之前的事件

--before <cursor>
旗標 · 選填

往更舊翻頁的游標:直接帶前一批最後一列的 cursor 欄位(勿用 createdAt 重組)

--after <cursor>
旗標 · 選填

往更新翻頁的游標:帶前一批第一列的 cursor 欄位。與 before 併用時以 before 為準

--limit <n>
旗標 · 選填

回傳筆數上限,最多 1000 筆

--json
旗標 · 選填

回應欄位 · data[]

id
string

稽核事件 ID。

actorUserId
string | null

操作者的使用者 ID;系統事件(webhook/排程等非人為列)為 null。

actorEmail
string | null

操作者 Email;系統事件或帳號已刪時為 null。

actorName
string | null

操作者顯示名;系統事件或帳號已刪時為 null。

action
string

動作代碼,例如 order.create、traveler.decrypt。

targetType
string

被操作對象的類型,例如 order、member。

targetId
string

被操作對象的 ID。

metadata
unknown

該事件的附帶內容(欄位隨動作而異的自由結構 JSON)。

ipAddress
string | null

發起請求的來源 IP;無法取得時為 null。

createdAt
string

事件發生時間。**只用來顯示** —— 它到毫秒為止(JSON 序列化也是),翻頁請用 `cursor`。

cursor
string

這一列的 keyset 游標(`<ISO 微秒時間>|<id>`)。要往這一列的前後翻頁就直接把它 餵回 `before` / `after`,**不要拿 `createdAt` 重組**:那是 JS `Date`,只到毫秒, 而 `audit_log.created_at` 是微秒。JSON 序列化之後只剩 3 位小數,同一毫秒內更舊 的列會被整批跳過(`/api/v1` 與 CLI 走的正是這條路)。

範例
toko audit list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "actorUserId": "…",
      "actorEmail": "…",
      "actorName": "…",
      "action": "…",
      "targetType": "…",
      "targetId": "…",
      "metadata": "…",
      "ipAddress": "…",
      "createdAt": "…",
      "cursor": "…"
    }
  ]
}
toko audit stats

稽核 KPI 統計

參數

--actor <userId>
旗標 · 選填

操作者使用者 ID,指定時將統計數據限縮至該操作者

--json
旗標 · 選填

回應欄位 · data

eventsThisMonth
number

本月(Asia/Taipei)稽核事件總數。

eventsToday
number

今日(Asia/Taipei)稽核事件總數。

writesThisMonth
number

本月寫入類事件數(排除 *.read 讀取事件)。

distinctActorsThisMonth
number

本月有動作紀錄的不重複操作者人數。

範例
toko audit stats
回應
{
  "ok": true,
  "data": {
    "eventsThisMonth": 0,
    "eventsToday": 0,
    "writesThisMonth": 0,
    "distinctActorsThisMonth": 0
  }
}

toko leaderboard

業績排行:每位業務成交應收業績、待派發 KPI(admin-only)

toko leaderboard list

全公司業務業績排行

參數

--period <month|quarter|year|all>
旗標 · 選填

業績統計區間:當月、當季、當年或全部,預設 month

--json
旗標 · 選填

回應欄位 · data[]

userId
string

業務的使用者 ID。

name
string

業務顯示姓名。

email
string

業務登入 Email。

role
string

業務角色代碼(admin/sales/op/accountant)。

orderCount
number

承作訂單總數(歸屬此業務、含各狀態的旅遊團訂單)。

paidCount
number

成交訂單數(未取消,且已付清或已完成)。

cancelledCount
number

已取消訂單數。

revenue
number

業績額(TWD 整數):歸屬於該業務、未取消訂單的應收合計。

commissionTwd
number

估算佣金 = round(revenue × sales_commission_bps / 10000)(tenant_settings 費率)。

bonusTwd
number

月度第一名加碼 = round(revenue × monthly_top_bonus_bps / 10000),僅當期 rank 1 且 revenue > 0;其餘為 0。與 isMonthlyTop 同步。

isMonthlyTop
boolean

當期 rank 1(revenue > 0)=月度第一,享 bonus。

avgOrderTwd
number

客單均價 = round(revenue / orderCount);0 單為 0。

範例
toko leaderboard list
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "name": "…",
      "email": "…",
      "role": "…",
      "orderCount": 0,
      "paidCount": 0,
      "cancelledCount": 0,
      "revenue": 0,
      "commissionTwd": 0,
      "bonusTwd": 0,
      "isMonthlyTop": true,
      "avgOrderTwd": 0
    }
  ]
}
toko leaderboard review-stats

待派發訂單 KPI

參數

--json
旗標 · 選填

回應欄位 · data

pendingCount
number

待派發(pending_review)訂單筆數。

pendingTotalTwd
number

待派發訂單的應收金額合計(新台幣)。

longestWaitHours
number

目前待派發訂單中,最長已等待的時數。

thisMonthAssigned
number

本月(Asia/Taipei)已完成派發的訂單數。

範例
toko leaderboard review-stats
回應
{
  "ok": true,
  "data": {
    "pendingCount": 0,
    "pendingTotalTwd": 0,
    "longestWaitHours": 0,
    "thisMonthAssigned": 0
  }
}

toko message-templates

罐頭訊息範本:查詢、明細

toko message-templates list

列出訊息範本(可依通道過濾)

參數

--channel <line|email>
旗標 · 選填

依發送管道篩選範本(line 或 email)

--json
旗標 · 選填

回應欄位 · data[]

id
string

範本 ID。

key
string | null

穩定識別碼(NULL = 未指定)。

stage
string

SOP 階段(受理 → 出團完成)。

channel
"email" | "line"

發送管道:line 或 email。

title
string

範本標題。

bodySingle
string

單人版內文(含 {{...}} 合併變數)。

bodyMulti
string | null

多人版變體;NULL = 只有單人版。

isActive
boolean

是否為該階段目前啟用的範本。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

updatedBy
string | null

最後更新者姓名;未知或帳號已刪除時為 null。

範例
toko message-templates list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "key": "…",
      "stage": "…",
      "channel": "email",
      "title": "…",
      "bodySingle": "…",
      "bodyMulti": "…",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…",
      "updatedBy": "…"
    }
  ]
}
toko message-templates get

單一訊息範本完整明細

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

範本 ID。

key
string | null

穩定識別碼(NULL = 未指定)。

stage
string

SOP 階段(受理 → 出團完成)。

channel
"email" | "line"

發送管道:line 或 email。

title
string

範本標題。

bodySingle
string

單人版內文(含 {{...}} 合併變數)。

bodyMulti
string | null

多人版變體;NULL = 只有單人版。

isActive
boolean

是否為該階段目前啟用的範本。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

updatedBy
string | null

最後更新者姓名;未知或帳號已刪除時為 null。

範例
toko message-templates get '<id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "key": "…",
    "stage": "…",
    "channel": "email",
    "title": "…",
    "bodySingle": "…",
    "bodyMulti": "…",
    "isActive": true,
    "createdAt": "…",
    "updatedAt": "…",
    "updatedBy": "…"
  }
}
toko message-templates create

新增訊息範本

參數

--stage <stage>
旗標 · 必填

訊息對應的 SOP 階段(合法值 = 租戶階段目錄中的階段名)

--channel <line|email>
旗標 · 必填

發送管道(line 或 email)

--title <t>
旗標 · 必填

範本標題(供後台辨識)

--body-single <b>
旗標 · 必填

單人版訊息內文

--key <K>
旗標 · 選填

範本識別碼,2–64 碼大寫英數 / _ / -(用於程式化引用,選填,自動轉大寫)

--body-multi <b>
旗標 · 選填

多人版訊息內文(留空表示沿用單人版;選填)

--inactive
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立的訊息範本 ID。

範例
toko message-templates create --stage 'example-stage' --channel line --title 'example-title' --body-single 'example-bodySingle'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko message-templates update

更新訊息範本(全量覆寫)

參數

<id>位置參數 · 必填
--stage <stage>
旗標 · 必填

訊息對應的 SOP 階段(合法值 = 租戶階段目錄中的階段名)

--channel <line|email>
旗標 · 必填

發送管道(line 或 email)

--title <t>
旗標 · 必填

範本標題(供後台辨識)

--body-single <b>
旗標 · 必填

單人版訊息內文

--key <K>
旗標 · 選填

範本識別碼,2–64 碼大寫英數 / _ / -(用於程式化引用,選填,自動轉大寫)

--body-multi <b>
旗標 · 選填

多人版訊息內文(留空表示沿用單人版;選填)

--inactive
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功更新訊息範本。

範例
toko message-templates update '<id>' --stage 'example-stage' --channel line --title 'example-title' --body-single 'example-bodySingle'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko message-templates set-active

啟用 / 停用訊息範本

參數

<id>位置參數 · 必填
--active
旗標 · 選填
--inactive
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功切換訊息範本的啟用狀態。

範例
toko message-templates set-active '<id>' --active
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko message-templates delete

刪除訊息範本(硬刪,清除草稿)

參數

<id>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功刪除訊息範本。

範例
toko message-templates delete '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko message-templates stages-update

更新 message-template-stages/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko message-templates stages-update '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko message-templates stages-delete

刪除 message-template-stages/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
removed
object
name
string
sortOrder
number
isActive
boolean
範例
toko message-templates stages-delete '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "removed": {
      "name": "…",
      "sortOrder": 0,
      "isActive": true
    }
  }
}
toko message-templates stages-list

查詢 message-template-stages

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string

階段 ID('mts_<ulid>')。

name
string

階段顯示名(FK 錨點;改名 ON UPDATE CASCADE 連動範本列)。

sortOrder
number
isActive
boolean

停用 = 不供新範本選用(既有綁此階段的範本不受影響)。

templateCount
number

綁此階段的範本數(>0 時不可刪,只可停用)。

範例
toko message-templates stages-list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "sortOrder": 0,
      "isActive": true,
      "templateCount": 0
    }
  ]
}
toko message-templates stages-create

執行 message-template-stages

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
id
string
範例
toko message-templates stages-create --data '{"name":"example-name"}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}

toko roles

RBAC 角色:列表、明細、權限目錄

toko roles list

列出所有角色(內建 + 自訂)

參數

--system
旗標 · 選填

是否只列內建角色:true 僅內建、false 僅自訂,省略則全部

--custom
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string

角色 ID(內建角色為其代碼)。

name
string

角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。

label
string

角色顯示名稱。

isSystem
boolean

是否為系統內建角色(內建角色不可改名或刪除)。

permissionCount
number

該角色目前擁有的 (resource, action) 數量(內建角色含後台調整)。

customized
boolean

內建角色的權限與程式預設不同時為 true;自訂角色恆為 false。

memberCount
number

持有此角色的使用者人數。

對應端點GET /api/v1/roles
範例
toko roles list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "label": "…",
      "isSystem": true,
      "permissionCount": 0,
      "customized": true,
      "memberCount": 0
    }
  ]
}
toko roles get

單一角色 + 完整權限矩陣

參數

<roleId>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

id
string

角色 ID(內建角色為其代碼)。

name
string

角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。

label
string

角色顯示名稱。

isSystem
boolean

是否為系統內建角色(內建角色不可改名或刪除)。

editable
boolean

權限可否調整:自訂角色與業務、線控、會計可以;管理員、會員、嚮導不行。

orderScope
"all" | "own"

訂單資料範圍:'own' 只看名下訂單、'all' 全租戶(含旅客證件解密)。

permissions
object[]

此角色授予的完整 (resource, action) 權限清單(內建角色含後台調整)。

resource
string

權限資源代碼,例如 order、member。

action
string

權限動作代碼,例如 read、update。

defaultPermissions
Permission[] | null

內建角色的程式預設權限;自訂角色為 null。

baseRole
string | null

承接的內建角色代碼(sales、op 或 accountant):從內建角色複製的自訂角色才有;其餘為 null。

範例
toko roles get '<roleId>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "label": "…",
    "isSystem": true,
    "editable": true,
    "orderScope": "all",
    "permissions": [
      {
        "resource": "…",
        "action": "…"
      }
    ],
    "defaultPermissions": null,
    "baseRole": "…"
  }
}
toko roles catalog

列出權限目錄(每個 resource 的可授權 action)

參數

--json
旗標 · 選填

回應欄位 · data[]

resource
string

權限資源代碼,例如 order、member。

label
string

中文名。

actions
object[]
action
string

動作代碼,例如 read、set-role。

label
string

中文說明;指派權限的人看的是這個。

risk選填
string | undefined

有值表示高風險,內容是授出去會發生什麼事。

adminOnly選填
string | undefined

有值表示預設只給管理員,內容是給其他角色前要知道的事。

範例
toko roles catalog
回應
{
  "ok": true,
  "data": [
    {
      "resource": "…",
      "label": "…",
      "actions": [
        {
          "action": "…",
          "label": "…",
          "risk": "…",
          "adminOnly": "…"
        }
      ]
    }
  ]
}
toko roles create

新增自訂角色(name + label + 權限 + 訂單資料範圍)

參數

--name <code>
旗標 · 必填

角色代碼,小寫英數與底線、2–32 字且須以字母開頭,建立後不可改

--label <顯示名>
旗標 · 必填

角色顯示名稱,呈現於後台角色清單

--permissions <r.a,r.a>
旗標 · 選填

此角色授予的權限清單,每筆為一組資源與動作

--order-scope <own|all>
旗標 · 選填

訂單資料範圍:own 只看自己名下訂單(預設)、all 全租戶(含旅客證件解密)

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立的角色 ID。

對應端點POST /api/v1/roles
範例
toko roles create --name 'example-name' --label 'example-label'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko roles copy

複製既有角色成新的自訂角色(帶入來源當下的權限與訂單資料範圍)

參數

<sourceRoleId>位置參數 · 必填
--name <code>
旗標 · 必填

新角色代碼,小寫英數與底線、2–32 字且須以字母開頭,建立後不可改

--label <顯示名>
旗標 · 必填

新角色顯示名稱,呈現於後台角色清單

--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立的角色 ID。

name
string

新角色代碼。

label
string

新角色顯示名稱。

orderScope
"all" | "own"

訂單資料範圍,照抄來源角色:own 只看自己名下訂單、all 全租戶。

baseRole
string | null

承接的內建角色代碼(sales、op 或 accountant);來源沒有承接任何內建角色時為 null。

permissions
string[]

帶入的權限,`resource.action` 字串,依字典序。

範例
toko roles copy '<sourceRoleId>' --name 'example-name' --label 'example-label'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "label": "…",
    "orderScope": "all",
    "baseRole": "…",
    "permissions": [
      "…"
    ]
  }
}
toko roles update

更新角色顯示名與權限(整組覆寫;內建業務、線控、會計只能改權限)

參數

<roleId>位置參數 · 必填
--label <顯示名>
旗標 · 必填

角色顯示名稱,呈現於後台角色清單。內建角色不能改名,要帶目前的顯示名

--permissions <r.a,r.a>
旗標 · 選填

完整取代後的權限清單,會整批覆寫此角色現有權限。內建角色帶 defaultPermissions 即回到預設;內建角色省略則不變,自訂角色省略則清空

--order-scope <own|all>
旗標 · 選填

訂單資料範圍:own 只看自己名下訂單、all 全租戶(含旅客證件解密);省略則不變。內建角色不能改

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功更新角色。

範例
toko roles update '<roleId>' --label 'example-label'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko roles delete

刪除自訂角色(仍有成員使用時拒絕)

參數

<roleId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功刪除角色。

範例
toko roles delete '<roleId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko settings

租戶設定:公司檔 / 收款帳戶 / 費用類別 / 模組 / 寄件網域 / 整合憑證

toko settings payment-provider

查詢租戶預設金流商、平台能力與憑證遮罩

參數

--json
旗標 · 選填

回應欄位 · data

selected
"ecpay" | "manual" | "newebpay" | "paynow" | "payuni" | "sinopac" | "test"
switchingAllowed
boolean
testAllowed
boolean
providers
{ credential: { merchantId: string; mask: string | null; } | null; versions: { id: string; merchantAccount: string; environment: string; mask: string | null; createdAt: string; current: boolean; }[]; ... 11 more ...; requiresFeePolicy: false; } | { ...; } | { ...; } | { ...; } | { ...; }[]
範例
toko settings payment-provider
回應
{
  "ok": true,
  "data": {
    "selected": "ecpay",
    "switchingAllowed": true,
    "testAllowed": true,
    "providers": [
      "…"
    ]
  }
}
toko settings set-payment-provider

切換新付款、設定或輪替憑證及解除綁定

參數

--operation <switch|configure|change_merchant|rotate_key|unlink|fee_policy>
旗標 · 必填
--provider <manual|test|ecpay|payuni|newebpay|paynow|sinopac>
旗標 · 必填
--merchant-id <id>
旗標 · 選填

Required for credential configuration, merchant changes, and key rotation.

--environment <sandbox|production>
旗標 · 選填

Required for credential operations.

--hash-key <t>
旗標 · 選填

Required with HashIV for ECPay and PAYUNi. This secret is never returned.

--hash-iv <t>
旗標 · 選填

Required with HashKey for credential operations. This secret is never returned.

--transaction-password <t>
旗標 · 選填

Required for PayNow credential operations. This secret is never returned.

--hash-a1 <t>
旗標 · 選填

Required for SinoPac credential operations. This secret is never returned.

--hash-a2 <t>
旗標 · 選填

Required for SinoPac credential operations. This secret is never returned.

--hash-b1 <t>
旗標 · 選填

Required for SinoPac credential operations. This secret is never returned.

--hash-b2 <t>
旗標 · 選填

Required for SinoPac credential operations. This secret is never returned.

--x-key <t>
旗標 · 選填

Required for SinoPac credential operations. This secret is never returned.

--fee-bps <n>
旗標 · 選填
--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

ok
boolean
範例
toko settings set-payment-provider --operation switch --provider manual
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings workflow-controls

查詢新付款與新契約的暫停設定

參數

--json
旗標 · 選填

回應欄位 · data

newPaymentsPaused
boolean
newAgreementsPaused
boolean
範例
toko settings workflow-controls
回應
{
  "ok": true,
  "data": {
    "newPaymentsPaused": true,
    "newAgreementsPaused": true
  }
}
toko settings set-workflow-controls

設定新付款與新契約的暫停開關,保留既有交易

參數

--new-payments-paused <true|false>
旗標 · 必填

Pause new payment forms

--new-agreements-paused <true|false>
旗標 · 必填

Pause new agreements

--confirm
對 production target 寫入時必帶
--json
旗標 · 選填

回應欄位 · data

newPaymentsPaused
boolean
newAgreementsPaused
boolean
範例
toko settings set-workflow-controls --new-payments-paused true --new-agreements-paused true
回應
{
  "ok": true,
  "data": {
    "newPaymentsPaused": true,
    "newAgreementsPaused": true
  }
}
toko settings get

租戶設定單例(公司檔 / 指派模式 / SEO;寄件網域見 settings sending-domain)

參數

--json
旗標 · 選填

回應欄位 · data

id
string

設定列 ID(單例,恆為 'singleton')。

companyName
string

公司全名,顯示於發票、合約與對外信件抬頭。**必填**(#87,DB NOT NULL + 非空白 CHECK)。

companyPhone
string | null

公司聯絡電話,顯示於對外文件;null = 未設定。

companyEmail
string | null

公司對外聯絡信箱,自建前台的站台資訊輸出它;null = 未設定。

taxId
string | null

公司統一編號(8 位數字),用於開立發票;null = 未設定。

companyAddress
string | null

公司登記地址,顯示於對外文件;null = 未設定。

logoUrl
string | null

公司 Logo 圖片網址,用於後台與對外頁面品牌呈現;null = 未設定。

homeSeoTitle
string | null

首頁標題(含品牌段)整句覆寫,平台前台與自建前台共用;null = 用品牌名與標語組成。

siteTagline
string | null

公開站標語(SEO/首頁);null = 未設定。

seoDefaultDescription
string | null

公開站預設 SEO meta description;null = 未設定。

ogImageUrl
string | null

社群分享預設 Open Graph 圖片網址;null = 未設定。

emailReplyTo
string | null

系統寄信時的回覆收件信箱;null = 未設定。

lineOfficialUrl
string | null

官方 LINE 加好友連結(issue 748);null = 未設定。

facebookUrl
string | null

Facebook 粉專網址;null = 未設定。

instagramUrl
string | null

Instagram 網址;null = 未設定。

youtubeUrl
string | null

YouTube 頻道網址;null = 未設定。

assignmentMode
string

S5: 'auto_round_robin' | 'auto_customer_choice' | 'manual_review'

defaultAssigneeUserId
string | null

S5: fallback assignee when round-robin finds no active sales, etc.

allowSalesClaim
boolean

order-assignment §6:業務自派搶單開關(per-tenant opt-in,預設 false)。

passportExpiryWarningDays
number

護照效期提醒天數(document-expiry §4.1;NOT NULL DEFAULT 180)。

guideCertExpiryWarningDays
number

嚮導證照到期提醒天數(#563;NOT NULL DEFAULT 60)。回程日 + 此天數 > 到期日即警示。

guideDispatchNearGap
number

派嚮導清單的「快成團」門檻人數(#1377;NOT NULL DEFAULT 2)。

groupCodePattern
string | null

團號 token 樣板(如 '{YY}{region}{airline?}{MMDD}{seq}')。NULL = 內建預設。

groupCodeSeqStyle
string

序號樣式:'alpha' | 'alpha_no_io' | 'numeric'(NOT NULL DEFAULT 'alpha')。

groupCodeSeqWidth
number

numeric 序號補零寬度(NOT NULL DEFAULT 2;alpha 樣式忽略)。

ecpayFeeBps
number

預估綠界手續費率(270 = 2.70%)。NOT NULL DEFAULT 270。

fongshouFeeBps
number

預估豐收款手續費率(50 = 0.50%)。NOT NULL DEFAULT 50。

profitTaxBps
number

預估發票 / 營所稅率(500 = 5.00%)。NOT NULL DEFAULT 500。

salesCommissionBps
number

業務抽成率(1000 = 10.00%)。NOT NULL DEFAULT 1000。

monthlyTopBonusBps
number

月度第一名加碼率(500 = 5.00%)。NOT NULL DEFAULT 500。

senderLocalPart
string | null

寄件人 local-part,未填視為 'info'。

storefrontTemplate
string

前台店面模板 key(storefront-templates §3)。可能對不上 registry(打錯、模板 改名/下架)—— 前台渲染一律經 resolveStorefrontTemplate() fallback `minimal`。

customStorefrontUrl
string | null
websiteMode
"headless" | "platform"
activeCustomStorefrontUrl
string | null
customStorefrontTripPath
string | null
ga4MeasurementId
string | null

轉換追蹤 ID(specs/conversion-tracking.md)。NULL = 不載入該追蹤碼。

metaPixelId
string | null
googleAdsId
string | null
customerCancelUnpaidEnabled
boolean

未付款單可否由客人自行線上取消。

customerCancelPaidEnabled
boolean

已付款(含只付訂金)單可否由客人自行線上取消。

customerCancelPaidMinDaysBefore
number

已付款單的出發日門檻:距出發 < 此天數即不可線上取消。

customerRescheduleMinDaysBefore
number | null

自助換梯門檻(customer-cancellation §8.1):null = 不開放,N = 來源與目標距出發 ≥ N 天。

customerRescheduleSurplus
"keep_overpaid" | "refund_draft"

自助換梯後新梯較便宜時的差額處理(§8.5)。

cancellationFeeTiers
object[]

租戶預設退改費階梯(已正規化、降序)。`[]` = 不收退改費。

daysBefore
number

距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。

feePercent選填
number | undefined

扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。

feeFixedTwd選填
number | undefined

定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。

refundRemitFeeTwd
number

退款轉帳費(customer-cancellation §3.4,按單一次)。走匯出的退款才收,刷退恆 0。

refundApprovalPolicy
object

退款核准權限(#1405)。見 `refunds/approval-policy`。

approverRoles
string[] | null

可核准退款的角色名單。null = 不另外限縮,持有 `refund.approve` 的角色都可核准。 不是 null 時一律含管理員。

accountantCanCreate
boolean

內建會計角色可開退款單並送審(`refund.create`)。

selfApprovalEnabled
boolean

建單人可以核准自己的退款單。關 = 維持現狀的責任分離:只擋建單人 (`CREATOR_CANNOT_APPROVE`),送審人不受限。

customerCancelReminder
string | null

客人自助取消提醒文字(customer-cancellation §5.1);null = 不顯示。

lotteryFilingFeeTiers
object[]

送件行政費的次數階梯(customer-cancellation §3.6,**每人**,已正規化、升序)。 `[]` = 不收。計次範圍是該訂單所屬的備案鏈。

fromCount
number

累計未中籤 ≥ 此次數時適用本列(最小 1)。

totalTwd
number

到 `fromCount` 次為止的**累計總額**(整數 TWD,每位旅客各自計)。

tourAgreementEnabled
boolean

契約流程總開關(預設關)。

tourAgreementTravelForm
"group" | "individual"

舊 API 的單一旅遊型態;只供相容使用。

tourAgreementDomesticTravelForm
"group" | "individual"
tourAgreementOverseasTravelForm
"group" | "individual"
companyRepresentative
string | null

乙方負責人;null = 未設定 → 契約 fail-closed。

travelAgencyRegistrationNo
string | null

旅行業註冊編號;null = 未設定 → 契約 fail-closed。

courtJurisdiction
string | null

合意管轄法院;null = 未設定 → 契約 fail-closed。

tourAgreementChangeDaysDefault
number

可變更第三人期限:免抽籤梯次預設(NOT NULL DEFAULT 35)。

tourAgreementChangeBufferDays
number

可變更第三人期限:抽籤日前的緩衝天數(NOT NULL DEFAULT 5)。

tourAgreementLotteryDeadlineTypeKey選填
string | null | undefined
tourAgreementReviewHardBlock
boolean

審閱期硬擋 24 小時(預設關,只記錄提供 / 簽署時間)。

tourAgreementGuardianSigning
boolean

未成年由法定代理人代簽(預設開)。

tourAgreementSoftBlock
boolean

出團軟擋:未簽列入出團前待辦(預設關;系統永不硬擋)。

escortLeadLabel
string

隨團人員職稱:`leader` 的顯示文字(issue 587;NOT NULL DEFAULT '主要隨團人員')。

escortAssistantLabel
string

隨團人員職稱:`assistant` 的顯示文字(NOT NULL DEFAULT '協同')。

updatedAt
string

設定最後更新時間。

範例
toko settings get
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "companyName": "…",
    "companyPhone": "…",
    "companyEmail": "…",
    "taxId": "…",
    "companyAddress": "…",
    "logoUrl": "…",
    "homeSeoTitle": "…",
    "siteTagline": "…",
    "seoDefaultDescription": "…",
    "ogImageUrl": "…",
    "emailReplyTo": "…",
    "lineOfficialUrl": "…",
    "facebookUrl": "…",
    "instagramUrl": "…",
    "youtubeUrl": "…",
    "assignmentMode": "…",
    "defaultAssigneeUserId": "…",
    "allowSalesClaim": true,
    "passportExpiryWarningDays": 0,
    "guideCertExpiryWarningDays": 0,
    "guideDispatchNearGap": 0,
    "groupCodePattern": "…",
    "groupCodeSeqStyle": "…",
    "groupCodeSeqWidth": 0,
    "ecpayFeeBps": 0,
    "fongshouFeeBps": 0,
    "profitTaxBps": 0,
    "salesCommissionBps": 0,
    "monthlyTopBonusBps": 0,
    "senderLocalPart": "…",
    "storefrontTemplate": "…",
    "customStorefrontUrl": "…",
    "websiteMode": "headless",
    "activeCustomStorefrontUrl": "…",
    "customStorefrontTripPath": "…",
    "ga4MeasurementId": "…",
    "metaPixelId": "…",
    "googleAdsId": "…",
    "customerCancelUnpaidEnabled": true,
    "customerCancelPaidEnabled": true,
    "customerCancelPaidMinDaysBefore": 0,
    "customerRescheduleMinDaysBefore": 0,
    "customerRescheduleSurplus": "keep_overpaid",
    "cancellationFeeTiers": [
      {
        "daysBefore": 0,
        "feePercent": 0
      }
    ],
    "refundRemitFeeTwd": 0,
    "refundApprovalPolicy": {
      "approverRoles": "…",
      "accountantCanCreate": true,
      "selfApprovalEnabled": true
    },
    "customerCancelReminder": "…",
    "lotteryFilingFeeTiers": [
      {
        "fromCount": 0,
        "totalTwd": 0
      }
    ],
    "tourAgreementEnabled": true,
    "tourAgreementTravelForm": "group",
    "tourAgreementDomesticTravelForm": "group",
    "tourAgreementOverseasTravelForm": "group",
    "companyRepresentative": "…",
    "travelAgencyRegistrationNo": "…",
    "courtJurisdiction": "…",
    "tourAgreementChangeDaysDefault": 0,
    "tourAgreementChangeBufferDays": 0,
    "tourAgreementLotteryDeadlineTypeKey": "…",
    "tourAgreementReviewHardBlock": true,
    "tourAgreementGuardianSigning": true,
    "tourAgreementSoftBlock": true,
    "escortLeadLabel": "…",
    "escortAssistantLabel": "…",
    "updatedAt": "…"
  }
}
toko settings accounts

收款帳戶目錄

參數

--active-only
旗標 · 選填

是否只回傳啟用中的收款帳戶(true/false);省略則含停用

--json
旗標 · 選填

回應欄位 · data[]

id
string

收款帳戶 ID。

code
string

帳戶代碼(租戶內唯一穩定識別)。

displayName
string

帳戶顯示名。

kind
"bank" | "cash" | "gateway"

帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。

gatewayProvider
string | null

綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `accounts/gateway-providers.ts`。

bankName
string | null

銀行名稱;現金/閘道帳戶為 null。

accountNo
string | null

銀行帳號;現金/閘道帳戶為 null。

bankCode
string | null
bankBranch
string | null
accountHolder
string | null
canReceive
boolean

可收款(幾乎都 true)。

canRemit
boolean

可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。

canChargeback
boolean

可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。

canPaySupplier
boolean

付款渠道:出團準備的付款登記區可選它付供應商(#1375)。

isDeprecated
boolean

廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。

isSettlementMaster
boolean

主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。

payoutAccountId
string | null

撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。

currency
string

帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。

isActive
boolean

此帳戶是否啟用。

displayOrder
number

後台清單排序序位(小者在前)。

usedCount
number

被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。

currencyLocked
boolean

幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko settings accounts list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "kind": "bank",
      "gatewayProvider": "…",
      "bankName": "…",
      "accountNo": "…",
      "bankCode": "…",
      "bankBranch": "…",
      "accountHolder": "…",
      "canReceive": true,
      "canRemit": true,
      "canChargeback": true,
      "canPaySupplier": true,
      "isDeprecated": true,
      "isSettlementMaster": true,
      "payoutAccountId": "…",
      "currency": "…",
      "isActive": true,
      "displayOrder": 0,
      "usedCount": 0,
      "currencyLocked": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko settings fee-routes

費用類別 → 收款帳戶路由表

參數

--json
旗標 · 選填

回應欄位 · data[]

id
string

路由設定 ID。

feeCategory
string

費用類型代碼(租戶自定唯一鍵,如 tour_fee/lodging/equipment)。

displayName
string

費用類型顯示名。

finalAccountId
string

此費用類型最終結算進的收款帳戶 ID。

finalAccountName
string | null

最終收款帳戶名稱;無對應帳戶時為 null。

finalAccountCode
string | null

final 帳戶代號。

isActive
boolean

此路由是否啟用。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko settings fee-routes list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "feeCategory": "…",
      "displayName": "…",
      "finalAccountId": "…",
      "finalAccountName": "…",
      "finalAccountCode": "…",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko settings expense-categories

公司營業費用類別目錄

參數

--active-only
旗標 · 選填

是否只回傳啟用中的費用類別(true/false);省略則含停用

--json
旗標 · 選填

回應欄位 · data[]

id
string

費用類別 ID。

code
string

科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。

displayName
string

顯示名(如 房租 / 行政薪資 / 營業稅)。

kind
"opex" | "platform_fee" | "special" | "tax"

費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。

isActive
boolean

是否啟用(停用不刪,既有費用列仍引用得到)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

範例
toko settings expense-categories list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "kind": "opex",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko settings modules

租戶啟用的方案模組(唯讀;供應由平台 CLI 管)

參數

--json
旗標 · 選填

回應欄位 · data

tour
boolean
climbing
boolean
lodging
boolean
accounting
boolean
lottery
boolean
api_access
boolean
headless_storefront
boolean
custom_domain
boolean
affiliated_sales
boolean
範例
toko settings modules list
回應
{
  "ok": true,
  "data": {
    "tour": true,
    "climbing": true,
    "lodging": true,
    "accounting": true,
    "lottery": true,
    "api_access": true,
    "headless_storefront": true,
    "custom_domain": true,
    "affiliated_sales": true
  }
}
toko settings assignable-staff

可被指派訂單的員工名單

參數

--json
旗標 · 選填

回應欄位 · data[]

userId
string

員工的使用者 ID(作為指派對象)。

name
string

員工顯示姓名。

email
string

員工登入 Email。

role
string

員工角色代碼(sales/admin 等可指派角色)。

thisMonthAssigned
number

本月(Asia/Taipei)已指派給此員工的訂單數(供輪派負載參考)。

範例
toko settings assignable-staff list
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "name": "…",
      "email": "…",
      "role": "…",
      "thisMonthAssigned": 0
    }
  ]
}
toko settings sending-domain

寄件網域狀態(含 DNS record;網域未設定時 records 為空)

參數

--json
旗標 · 選填

回應欄位 · data

sendingDomain
string | null

自有寄件網域;未設定時為 null。

resendDomainId
string | null

寄件服務商(Resend)的網域識別碼;未設定時為 null。

sendingDomainStatus
string | null

網域驗證狀態(如 pending/verified);未設定時為 null。

senderLocalPart
string | null

寄件人信箱的帳號部分(@ 前段);未填視為 info。

records
object[]

待設定的 DNS 記錄清單(SPF/DKIM 等);Resend 不可達或未設定時為空陣列。

record
string

DNS 記錄用途分類(如 DKIM/SPF 等,來自 Resend)。

name
string

記錄主機名(需在網域 DNS 新增的 host)。

type
string

記錄類型(如 TXT/MX/CNAME)。

value
string

記錄值(需填入 DNS 的內容)。

ttl選填
string | undefined

存活時間(TTL);未指定時省略。

status選填
string | undefined

此筆記錄的驗證狀態(如 pending/verified);未指定時省略。

priority選填
number | undefined

MX 記錄優先權;非 MX 記錄省略。

範例
toko settings sending-domain status
回應
{
  "ok": true,
  "data": {
    "sendingDomain": "…",
    "resendDomainId": "…",
    "sendingDomainStatus": "…",
    "senderLocalPart": "…",
    "records": [
      {
        "record": "…",
        "name": "…",
        "type": "…",
        "value": "…",
        "ttl": "…",
        "status": "…",
        "priority": 0
      }
    ]
  }
}
toko settings credentials

整合憑證綁定狀態(特店 ID + HashKey 遮罩;密文永不回傳)

參數

--json
旗標 · 選填

回應欄位 · data[]

provider
string

整合代號(`ecpay` / `travelinvoice`… / 轉換追蹤的 `ga4`、`meta`)。列不存在=該家未綁定。

merchantId
string

金鑰綁定的帳號 ID(明文,顯示 / 診斷用):金流是特店 ID,`ga4` 是 Measurement ID,`meta` 是 Pixel ID。

secretsMask
string | null

金鑰的遮罩碼(`****` + 末 4):金流是 HashKey,`ga4`/`meta` 是後端補送的金鑰。金鑰本身永不回傳。

範例
toko settings credentials status
回應
{
  "ok": true,
  "data": [
    {
      "provider": "…",
      "merchantId": "…",
      "secretsMask": "…"
    }
  ]
}
toko settings update

更新公司檔 / 寄件身分(只送有帶的欄;空字串=清空)

參數

--company-name <n>
旗標 · 選填

公司全名,顯示於發票、合約與對外信件抬頭。必填欄,不可清除(省略=不修改)

--tax-id <8碼>
旗標 · 選填

公司統一編號(8 位數字),用於開立發票;傳 null 或空字串清除

--company-phone <p>
旗標 · 選填

公司聯絡電話,顯示於對外文件;傳 null 或空字串清除

--company-address <a>
旗標 · 選填

公司登記地址,顯示於對外文件;傳 null 或空字串清除

--logo-url <u>
旗標 · 選填

公司 Logo 圖片網址(http/https 或本站圖庫資產路徑),用於後台與對外頁面品牌呈現;傳 null 或空字串清除

--email-reply-to <e>
旗標 · 選填

系統寄信時的回覆收件信箱,客戶回信會寄到此處;傳 null 或空字串清除

--sender-local-part <s>
旗標 · 選填

寄件人信箱的帳號部分(@ 前段),與寄件網域組成完整寄件地址;傳 null 或空字串清除

--passport-expiry-warning-days <n>
旗標 · 選填

護照到期前提早幾天提醒(1 至 3650 天),用於行前護照效期預警

--escort-lead-label <t>
旗標 · 選填

主要隨團人員(leader)在畫面與信件上的職稱,例:領隊、嚮導(1 至 20 字,不可清空)

--escort-assistant-label <t>
旗標 · 選填

協同(assistant)在畫面與信件上的職稱,例:導遊、協作嚮導(1 至 20 字,不可清空)

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功更新租戶設定。

範例
toko settings update
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings seo

更新 SEO 預設(首頁標題 / tagline / description / og 圖;空字串=清空)

參數

--home-title <t>
旗標 · 選填
--tagline <t>
旗標 · 選填
--description <d>
旗標 · 選填
--og-image-url <u>
旗標 · 選填

社群分享預設縮圖(Open Graph image)網址(http/https 或本站圖庫資產路徑);空字串清除

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功更新公開站 SEO 設定。

範例
toko settings seo update
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings ledger-fees

更新內外帳試算費率(bps 0..10000;空=不變)

參數

--ecpay-bps <n>
旗標 · 選填
--fongshou-bps <n>
旗標 · 選填
--profit-tax-bps <n>
旗標 · 選填

淨利稅率,單位 basis points(0..10000,10000=100%),用於內外帳參考預估淨利;留空不變更

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功更新內外帳參考預估淨利費率。

範例
toko settings ledger-fees update
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings assignment

設定訂單指派模式 + 預設指派人

參數

--mode <auto_round_robin|auto_customer_choice|auto_by_destination|manual_review|none>
旗標 · 必填
--default-assignee <userId>
旗標 · 選填

預設承辦人員的使用者 ID,自動指派找不到對象時的兜底承辦人;空字串表示不設預設

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功更新訂單指派模式設定。

範例
toko settings assignment set --mode auto_round_robin
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings ecpay

ECPay 憑證(set 三欄一起寫 / clear 解除綁定;write-only)

參數

--merchant-id <id>
旗標 · 選填

綠界 ECPay 特店編號(MerchantID),用於金流請款與簽章

--hash-key <k>
旗標 · 選填

綠界 ECPay HashKey,CheckMacValue 簽章用密鑰;寫入後即 KMS 加密儲存且永不回傳

--hash-iv <iv>
旗標 · 選填

綠界 ECPay HashIV,CheckMacValue 簽章用初始向量;寫入後即 KMS 加密儲存且永不回傳

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功清除 ECPay 憑證。

範例
toko settings ecpay set --merchant-id 'example-merchantId' --hash-key 'example-hashKey' --hash-iv 'example-hashIv'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings sending-domain-manage

寄件網域:啟用 / 驗證 / 停用

參數

<enable|verify|disable>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功啟用自有寄件網域。

domain
string

啟用的寄件網域(由綁定的站台網域派生)。

範例
toko settings sending-domain-manage enable
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "domain": "…"
  }
}
toko settings accounts-write

收款帳戶寫入:create / update

參數

<id>位置參數 · 必填
--code <c>
旗標 · 選填

收款帳戶代號,建立後不可變更,作為帳戶的穩定識別

--name <n>
旗標 · 選填
--kind <bank|cash|gateway>
旗標 · 選填

帳戶種類:bank 銀行帳戶、cash 現金、gateway 金流閘道

--gateway-provider
旗標 · 選填

綁定的金流商代號(如 ecpay),限 gateway 帳戶;該金流商的收款會自動歸入此帳戶。空字串或省略 = 不綁定

--payout-account
旗標 · 選填

撥款帳戶 ID,限 gateway 帳戶:金流商把收款撥進的台幣銀行帳戶(須啟用中)。設定後月結把此帳戶的收款落地改算成撥款帳戶。空字串或省略 = 不設

--currency
旗標 · 選填

帳戶幣別,ISO 4217 三碼(如 TWD / JPY / IDR);空字串預設 TWD,非 TWD 即為外幣池

--bank-name
旗標 · 選填

銀行名稱(bank 類別適用);空字串清除

--account-no
旗標 · 選填

銀行帳號(bank 類別適用);空字串清除

--display-order
旗標 · 選填

排序權重(0..9999),數字越小越前面;預設 0

--active
旗標 · 選填
--can-receive
旗標 · 選填

是否可作為收款(進帳)帳戶

--can-remit
旗標 · 選填

是否可作為出款(匯出)帳戶

--can-pay-supplier
旗標 · 選填

是否可作為出團準備付款登記的付款渠道(例:小編機)

--deprecated
旗標 · 選填
--settlement-master
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立的收款帳戶 ID。

範例
toko settings accounts-write create --code 'example-code' --name '1' --kind bank
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko settings fee-routes-write

費用類型路由:upsert / set-active

參數

<id>位置參數 · 必填
--category <code>
旗標 · 選填
--name <n>
旗標 · 選填
--final-account <id>
旗標 · 選填

此費用類型最終結算進的收款帳戶 ID

--active <true|false>
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string

新建立或更新的費用類型路由 ID。

範例
toko settings fee-routes-write upsert --category '<code>' --name '1' --final-account 'example-finalAccountId'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko settings expense-categories-write

費用類別:create / update / set-active

參數

<id>位置參數 · 必填
--code <c>
旗標 · 選填

費用類別代碼(小寫英數與底線),建立後不可變更,作為類別的穩定識別

--name <n>
旗標 · 選填
--kind <opex|tax|platform_fee|special>
旗標 · 選填

費用類別種類:opex 營業費用、tax 稅務、platform_fee 平台手續費、special 特殊,影響損益表歸類

--confirm
對 production target 寫入時必帶
--active <true|false>
旗標 · 選填

回應欄位 · data

id
string

新建立的費用類別 ID。

範例
toko settings expense-categories-write create --code 'undefined_example' --name '1' --kind opex
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko settings cancellation-policy

更新 settings/cancellation-policy

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings cancellation-policy --data '{"unpaidEnabled":true,"paidEnabled":true,"paidMinDaysBefore":1,"refundRemitFeeTwd":1,"feeTiers":[{"daysBefore":0,"feePercent":100}],"lotteryFilingFeeTiers":[{"fromCount":1,"totalTwd":1}]}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings destination-rules-delete

刪除 settings/destination-rules/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings destination-rules-delete '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings departure-owner-rotation-get

查詢 settings/departure-owner-rotation

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

domestic
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

overseas
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

範例
toko settings departure-owner-rotation-get
回應
{
  "ok": true,
  "data": {
    "domestic": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    },
    "overseas": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    }
  }
}
toko settings departure-owner-rotation-update

更新 settings/departure-owner-rotation

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

domestic
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

overseas
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

範例
toko settings departure-owner-rotation-update --data '{"region":"domestic","userIds":["example-userIds"]}'
回應
{
  "ok": true,
  "data": {
    "domestic": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    },
    "overseas": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    }
  }
}
toko settings destination-rules-list

查詢 settings/destination-rules

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
regionCode
string
regionName
string | null

地區中文名稱。

assigneeUserId
string | null

受派業務 userId;null = assignee 離職/刪帳號後被 SET NULL(規則退化為未命中)。

assigneeName
string | null

受派業務姓名;未指派或帳號已刪除時為 null。

assigneeRole
string | null
createdAt
string
updatedAt
string
範例
toko settings destination-rules-list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "regionCode": "…",
      "regionName": "…",
      "assigneeUserId": "…",
      "assigneeName": "…",
      "assigneeRole": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko settings destination-rules-update

更新 settings/destination-rules

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string
範例
toko settings destination-rules-update --data '{"regionCode":"example-regionCode","assigneeUserId":"example-assigneeUserId"}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko settings fee-item-presets-delete

執行 settings/fee-item-presets/[id]/delete

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings fee-item-presets-delete '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings fee-item-presets-update

更新 settings/fee-item-presets/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings fee-item-presets-update '<id>' --data '{"text":"example-text","included":true}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings fee-item-presets-list

查詢 settings/fee-item-presets

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
text
string

項目文字(租戶內唯一)。

included
boolean

預設歸「含」(true)或「不含」(false)。

displayOrder
number
createdAt
string
updatedAt
string
範例
toko settings fee-item-presets-list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "text": "…",
      "included": true,
      "displayOrder": 0,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko settings fee-item-presets-create

執行 settings/fee-item-presets

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string
範例
toko settings fee-item-presets-create --data '{"text":"example-text","included":true}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko settings group-code-pattern

更新 settings/group-code-pattern

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings group-code-pattern --data '{"pattern":"{region}{YY}{MMDD}-{seq}","seqStyle":"alpha","seqWidth":2}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings guide-portal-policy

Set guide login mode and roster access days

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings guide-portal-policy --data '{"loginMode":"password_totp","dossierWindowDays":1}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings pnl-regions-active

執行 settings/pnl-regions/[id]/active

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings pnl-regions-active '<id>' --data '{"isActive":true}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings pnl-regions-update

更新 settings/pnl-regions/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings pnl-regions-update '<id>' --data '{"displayName":"example-displayName"}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings pnl-regions-list

查詢 settings/pnl-regions

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
code
string
displayName
string
displayOrder
number
isActive
boolean
createdAt
string
updatedAt
string
範例
toko settings pnl-regions-list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "displayOrder": 0,
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko settings pnl-regions-create

執行 settings/pnl-regions

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string
範例
toko settings pnl-regions-create --data '{"code":"example-code","displayName":"example-displayName"}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko settings recurring-expenses-active

執行 settings/recurring-expenses/[id]/active

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings recurring-expenses-active '<id>' --data '{"isActive":true}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings recurring-expenses-update

更新 settings/recurring-expenses/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings recurring-expenses-update '<id>' --data '{"categoryId":"example-categoryId","amountTwd":1,"description":"example-description"}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings recurring-expenses-list

查詢 settings/recurring-expenses

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data[]

id
string
categoryId
string
categoryCode
string | null
categoryDisplayName
string | null
categoryKind
string | null
amountTwd
number
description
string
paidFromAccountId
string | null
paidFromAccountName
string | null
isActive
boolean
createdByUserId
string
createdAt
string
updatedAt
string
範例
toko settings recurring-expenses-list
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "categoryId": "…",
      "categoryCode": "…",
      "categoryDisplayName": "…",
      "categoryKind": "…",
      "amountTwd": 0,
      "description": "…",
      "paidFromAccountId": "…",
      "paidFromAccountName": "…",
      "isActive": true,
      "createdByUserId": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
toko settings recurring-expenses-create

執行 settings/recurring-expenses

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string
範例
toko settings recurring-expenses-create --data '{"categoryId":"example-categoryId","amountTwd":1,"description":"example-description"}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}
toko settings storefront-update

更新網站內容或準備網址;websiteMode 明確啟用或切回平台

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings storefront-update
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko settings storefront-list

查詢 settings/storefront

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

banners
object[]
imageUrl
string
alt
string
linkUrl
string | null
name
string | null
faqs
object[]
question
string
answer
string
categories
object[]
name
string
tag
string
imageUrl
string | null
websiteMode
"headless" | "platform"
activeCustomStorefrontUrl
string | null
template
string
customStorefrontUrl
string | null
customStorefrontTripPath
string | null
slots
object
aboutContentMdx
string | null
範例
toko settings storefront-list
回應
{
  "ok": true,
  "data": {
    "banners": [
      {
        "imageUrl": "…",
        "alt": "…",
        "linkUrl": "…",
        "name": "…"
      }
    ],
    "faqs": [
      {
        "question": "…",
        "answer": "…"
      }
    ],
    "categories": [
      {
        "name": "…",
        "tag": "…",
        "imageUrl": "…"
      }
    ],
    "websiteMode": "headless",
    "activeCustomStorefrontUrl": "…",
    "template": "…",
    "customStorefrontUrl": "…",
    "customStorefrontTripPath": "…",
    "slots": "…",
    "aboutContentMdx": "…"
  }
}
toko settings tour-agreement

更新 settings/tour-agreement

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko settings tour-agreement --data '{"enabled":true,"companyRepresentative":"example-companyRepresentative","travelAgencyRegistrationNo":"example-travelAgencyRegistrationNo","courtJurisdiction":"example-courtJurisdiction","changeDaysDefault":1,"changeBufferDays":1,"reviewHardBlock":true,"guardianSigning":true,"softBlock":true,"domesticTravelForm":"group","overseasTravelForm":"group"}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko staff

員工:查詢租戶內部員工名單

toko staff list

列出租戶所有員工

參數

--json
旗標 · 選填

回應欄位 · data[]

userId
string

員工的使用者 ID。

email
string

員工登入 Email(帳號識別)。

name
string

員工顯示姓名。

role
string

員工角色代碼(admin/sales/op/accountant)。

createdAt
string

帳號建立時間。

banned
boolean

Account frozen via ban (離職 / 停權). False after a temporary ban ends, also before the next sign-in clears it.

twoFactorEnabled
boolean

是否已完成 TOTP 兩步驟驗證註冊。

emailVerified
boolean

Email 是否已驗證。**不是**啟用判準:員工邀請流程不寄信(一次性密碼當場交付), 所以受邀者走完整條流程這個旗標也不會變 true。啟用看 `activated`。

lastLoginAt
string | null

最後一次登入時間;`null` = 從來沒有人登入過這個帳號。代理登入不計。

activated
boolean

派生的「已啟用」狀態:至少成功登入過一次,代表發出去的一次性密碼有人在用。

對應端點GET /api/v1/staff
範例
toko staff list
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "email": "…",
      "name": "…",
      "role": "…",
      "createdAt": "…",
      "banned": true,
      "twoFactorEnabled": true,
      "emailVerified": true,
      "lastLoginAt": "…",
      "activated": true
    }
  ]
}
toko staff invite

建立新員工帳號(指定角色);回一次性暫時密碼

參數

--email <e>
旗標 · 必填

受邀員工的登入 Email,作為帳號識別

--name <n>
旗標 · 必填

員工顯示姓名

--role <admin|sales|op|accountant>
旗標 · 必填

指派的員工角色(內建 admin/sales/op/accountant,或本租戶自訂角色),決定權限範圍

--confirm
對 production target 寫入時必帶

回應欄位 · data

userId
string

新建立員工的使用者 ID。

tempPassword
string

一次性明文暫時密碼,僅此次回傳(請立即轉交並要求員工首次登入改密)。

email
string

新員工的登入 Email。

role
string

指派的員工角色(admin/sales/op/accountant)。

範例
toko staff invite --email 'customer@example.com' --name 'example-name' --role admin
回應
{
  "ok": true,
  "data": {
    "userId": "…",
    "tempPassword": "…",
    "email": "…",
    "role": "…"
  }
}
toko staff set-role

變更員工角色(admin|sales|op|accountant)

參數

<userId>位置參數 · 必填
--role <admin|sales|op|accountant>
旗標 · 必填

變更後的員工角色(內建 admin/sales/op/accountant,或本租戶自訂角色),決定權限範圍

--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功變更員工角色。

範例
toko staff set-role '<userId>' --role admin
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko staff remove

移除員工(降為 customer,保留 user 紀錄)

參數

<userId>位置參數 · 必填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean

是否成功移除員工身分(降為一般顧客)。

範例
toko staff remove '<userId>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
toko staff ban

執行 staff/[userId]/ban

參數

<userId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko staff ban '<userId>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
toko staff unban

執行 staff/[userId]/unban

參數

<userId>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
true
範例
toko staff unban '<userId>'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}

toko email-history

寄信紀錄:查詢、明細與安全重試

toko email-history list

查詢寄信紀錄(預設最近七個台北日期)

參數

--start-date <YYYY-MM-DD>
旗標 · 選填
--end-date <YYYY-MM-DD>
旗標 · 選填
--status <queued|sending|sent|failed>
旗標 · 選填
--category <auth|order|payment|guide|contract|message|system>
旗標 · 選填
--recipient <email>
旗標 · 選填
--departure <id>
旗標 · 選填
--order <id>
旗標 · 選填
--guide <id>
旗標 · 選填
--as-of <timestamp>
旗標 · 選填
--page <n>
旗標 · 選填
--page-size <n>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

items
object[]
id
string
toEmail
string
subject
string
templateKey
string
category
"auth" | "contract" | "guide" | "message" | "order" | "payment" | "system"
status
string
error
string | null
attempts
number
orderId
string | null
departureId
string | null
guideId
string | null
createdAt
string
sentAt
string | null
canRetry
boolean
retryRecipient
string | null
retryUnavailableReason
"unsupported" | "auth_requires_new_request" | "not_failed" | "intent_changed" | null
total
number
page
number
pageSize
number
asOf
string
範例
toko email-history list
回應
{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "…",
        "toEmail": "…",
        "subject": "…",
        "templateKey": "…",
        "category": "auth",
        "status": "…",
        "error": "…",
        "attempts": 0,
        "orderId": "…",
        "departureId": "…",
        "guideId": "…",
        "createdAt": "…",
        "sentAt": "…",
        "canRetry": true,
        "retryRecipient": "…",
        "retryUnavailableReason": "unsupported"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0,
    "asOf": "…"
  }
}
toko email-history get

讀取寄信紀錄與安全內容

參數

<id>位置參數 · 必填
--json
旗標 · 選填

回應欄位 · data

html
string | null
text
string | null
contentState
"available" | "masked" | "unavailable"
id
string
toEmail
string
subject
string
templateKey
string
category
"auth" | "contract" | "guide" | "message" | "order" | "payment" | "system"
status
string
error
string | null
attempts
number
orderId
string | null
departureId
string | null
guideId
string | null
createdAt
string
sentAt
string | null
canRetry
boolean
retryRecipient
string | null
retryUnavailableReason
"unsupported" | "auth_requires_new_request" | "not_failed" | "intent_changed" | null
範例
toko email-history get '<id>'
回應
{
  "ok": true,
  "data": {
    "html": "…",
    "text": "…",
    "contentState": "available",
    "id": "…",
    "toEmail": "…",
    "subject": "…",
    "templateKey": "…",
    "category": "auth",
    "status": "…",
    "error": "…",
    "attempts": 0,
    "orderId": "…",
    "departureId": "…",
    "guideId": "…",
    "createdAt": "…",
    "sentAt": "…",
    "canRetry": true,
    "retryRecipient": "…",
    "retryUnavailableReason": "unsupported"
  }
}
toko email-history retry

安全重試可重試的失敗寄信

參數

<id>位置參數 · 必填
--recipient <email>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

retried
boolean
範例
toko email-history retry '<id>'
回應
{
  "ok": true,
  "data": {
    "retried": true
  }
}

toko feedback

預覽公開問題回報或功能需求,確認後開啟 GitHub 草稿

toko feedback bug

準備 bug 回報;GitHub 範本自動加上 bug label

參數

--no-browser
旗標 · 選填
--json
旗標 · 選填
範例
toko feedback bug
toko feedback feature

準備功能需求;GitHub 範本自動加上 enhancement label

參數

--no-browser
旗標 · 選填
--json
旗標 · 選填
範例
toko feedback feature

toko lottery-filings

lottery-filings

toko lottery-filings adjustments

執行 lottery-filings/adjustments

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

personId
string
chains
object[]

依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。

headOrderId
string

鏈首訂單(分組鍵)。

headOrderNumber
string
filingCount
number

送件紀錄筆數(這條鏈上)。

adjustmentTotal
number

調整差額加總(這條鏈上,可負)。

count
number

目前送件次數加上調整差額,下限為 0。

nextSeq
number

下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。

filings
object[]
id
string
orderId
string
orderNumber
string
travelerName
string | null

送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。

createdAt
string
adjustments
object[]
id
string
orderId
string

這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。

orderNumber
string
delta
number
reason
string
actorName
string

下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。

createdAt
string
範例
toko lottery-filings adjustments --data '{"personId":"example-personId","orderId":"example-orderId","delta":1,"reason":"example-reason"}'
回應
{
  "ok": true,
  "data": {
    "personId": "…",
    "chains": [
      {
        "headOrderId": "…",
        "headOrderNumber": "…",
        "filingCount": 0,
        "adjustmentTotal": 0,
        "count": 0,
        "nextSeq": 0,
        "filings": [
          {
            "id": "…",
            "orderId": "…",
            "orderNumber": "…",
            "travelerName": "…",
            "createdAt": "…"
          }
        ],
        "adjustments": [
          {
            "id": "…",
            "orderId": "…",
            "orderNumber": "…",
            "delta": 0,
            "reason": "…",
            "actorName": "…",
            "createdAt": "…"
          }
        ]
      }
    ]
  }
}
toko lottery-filings count

查詢 lottery-filings/count

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填

回應欄位 · data

personId
string
chains
object[]

依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。

headOrderId
string

鏈首訂單(分組鍵)。

headOrderNumber
string
filingCount
number

送件紀錄筆數(這條鏈上)。

adjustmentTotal
number

調整差額加總(這條鏈上,可負)。

count
number

目前送件次數加上調整差額,下限為 0。

nextSeq
number

下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。

filings
object[]
id
string
orderId
string
orderNumber
string
travelerName
string | null

送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。

createdAt
string
adjustments
object[]
id
string
orderId
string

這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。

orderNumber
string
delta
number
reason
string
actorName
string

下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。

createdAt
string
範例
toko lottery-filings count --data '{"personId":"example-personId","orderId":"example-orderId"}'
回應
{
  "ok": true,
  "data": {
    "personId": "…",
    "chains": [
      {
        "headOrderId": "…",
        "headOrderNumber": "…",
        "filingCount": 0,
        "adjustmentTotal": 0,
        "count": 0,
        "nextSeq": 0,
        "filings": [
          {
            "id": "…",
            "orderId": "…",
            "orderNumber": "…",
            "travelerName": "…",
            "createdAt": "…"
          }
        ],
        "adjustments": [
          {
            "id": "…",
            "orderId": "…",
            "orderNumber": "…",
            "delta": 0,
            "reason": "…",
            "actorName": "…",
            "createdAt": "…"
          }
        ]
      }
    ]
  }
}
toko lottery-filings lookup

執行 lottery-filings/lookup

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
範例
toko lottery-filings lookup --data '{"docType":"id_number","docNumber":"example-docNumber"}'
回應
{
  "ok": true,
  "data": "…"
}

toko operating-expenses

operating-expenses

toko operating-expenses confirm

執行 operating-expenses/[id]/confirm

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
範例
toko operating-expenses confirm '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toko order-conversations

訂單對話:待回覆清單(唯讀)

toko order-conversations awaiting-reply

列出待回覆的訂單對話(由舊到新,不含留言內容)

參數

--older-than-hours <n>
旗標 · 必填

最後一則訂購人留言距今至少幾小時(含),整數 1–720,必填

--page <n>
旗標 · 選填

頁碼,從 1 起算,預設第 1 頁

--page-size <n>
旗標 · 選填

每頁筆數,上限 200

--json
旗標 · 選填

回應欄位 · data

rows
object[]
orderId
string
orderNumber
string
customerName
string
lastCustomerMessageAt
string
total
number
page
number
pageSize
number
範例
toko order-conversations awaiting-reply --older-than-hours '1'
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "customerName": "…",
        "lastCustomerMessageAt": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}

toko skill

內建 agent skill:租戶操作、員工 API 與自建前台

toko skill show

讀取目前 CLI 版本的 skill 指引

參數

--topic <overview|tenant|staff-api|storefront>
旗標 · 選填
--json
旗標 · 選填
範例
toko skill show
toko skill install

建立或更新專案的 skill 入口,保留自訂內容

參數

--project <directory>
旗標 · 選填
--json
旗標 · 選填
範例
toko skill install

toko travelinvoice

travelinvoice

toko travelinvoice allowance

執行 travelinvoice/[id]/allowance

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
result
object
allowanceId
string
allowanceNo
string | null
範例
toko travelinvoice allowance '<id>' --data '{"amountTwd":1,"reason":"example-reason"}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "allowanceId": "…",
      "allowanceNo": "…"
    }
  }
}
toko travelinvoice invalidate

執行 travelinvoice/[id]/invalidate

參數

<id>位置參數 · 必填
--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
result
object
invalidationId
string
範例
toko travelinvoice invalidate '<id>' --data '{"reason":"example-re"}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "invalidationId": "…"
    }
  }
}
toko travelinvoice get

查詢 travelinvoice/[id]

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

id
string
orderId
string
orderNumber
string | null
merchantOrderNo
string
provider
string
category
"B2B" | "B2C"
buyerName
string
buyerUbn
string | null
totalAmtTwd
number
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
declaredStatus
"declared" | "undeclared"
invoiceNumber
string | null
invoiceTransNo
string | null

平台開立流水號;pending 列有值代表平台已受理預約開立。

displayUrl
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
lastError
string | null
lastSyncedAt
string | null
createdAt
string
範例
toko travelinvoice get '<id>'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "orderId": "…",
    "orderNumber": "…",
    "merchantOrderNo": "…",
    "provider": "…",
    "category": "B2B",
    "buyerName": "…",
    "buyerUbn": "…",
    "totalAmtTwd": 0,
    "status": "allowance",
    "declaredStatus": "declared",
    "invoiceNumber": "…",
    "invoiceTransNo": "…",
    "displayUrl": "…",
    "tourName": "…",
    "tourNo": "…",
    "tourDate": "…",
    "lastError": "…",
    "lastSyncedAt": "…",
    "createdAt": "…"
  }
}
toko travelinvoice sync

執行 travelinvoice/[id]/sync

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
result
object
declaredStatus
TaxReceiptDeclaredStatus | null
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"

查回後的本地收據狀態(預約收據回補後可能轉 issued / cancelled)。

範例
toko travelinvoice sync '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "declaredStatus": null,
      "status": "allowance"
    }
  }
}
toko travelinvoice abandon

執行 travelinvoice/[id]/abandon

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
result
object
id
string
status
"cancelled"
範例
toko travelinvoice abandon '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "id": "…",
      "status": "cancelled"
    }
  }
}
toko travelinvoice cancel-scheduled

執行 travelinvoice/[id]/cancel-scheduled

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
result
object
id
string
status
"cancelled"
範例
toko travelinvoice cancel-scheduled '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "id": "…",
      "status": "cancelled"
    }
  }
}
toko travelinvoice touch-issue

執行 travelinvoice/[id]/touch-issue

參數

<id>位置參數 · 必填
--data <json>
旗標 · 選填
--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

ok
boolean
result
object
id
string
merchantOrderNo
string
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
invoiceNumber
string | null
lastError
string | null

落缺件(pending + last_error)時填,供 UI 顯示缺件原因。

範例
toko travelinvoice touch-issue '<id>'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "id": "…",
      "merchantOrderNo": "…",
      "status": "allowance",
      "invoiceNumber": "…",
      "lastError": "…"
    }
  }
}
toko travelinvoice create

執行 travelinvoice

參數

--data <json>
旗標 · 必填

JSON object with the fields from the linked API request.

--json
旗標 · 選填
--confirm
對 production target 寫入時必帶

回應欄位 · data

id
string
merchantOrderNo
string
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
invoiceNumber
string | null
lastError
string | null

落缺件(pending + last_error)時填,供 UI 顯示缺件原因。

範例
toko travelinvoice create --data '{"orderId":"example-orderId","buyer":{"category":"B2B","name":"example-name","email":"customer@example.com"}}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "merchantOrderNo": "…",
    "status": "allowance",
    "invoiceNumber": "…",
    "lastError": "…"
  }
}
toko travelinvoice list

查詢 travelinvoice

參數

--data <json>
旗標 · 選填
--json
旗標 · 選填

回應欄位 · data

rows
object[]
id
string
orderId
string
orderNumber
string | null
merchantOrderNo
string
provider
string
category
"B2B" | "B2C"
buyerName
string
buyerUbn
string | null
totalAmtTwd
number
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
declaredStatus
"declared" | "undeclared"
invoiceNumber
string | null
invoiceTransNo
string | null

平台開立流水號;pending 列有值代表平台已受理預約開立。

displayUrl
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
lastError
string | null
lastSyncedAt
string | null
createdAt
string
total
number
page
number
pageSize
number
範例
toko travelinvoice list
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "…",
        "orderId": "…",
        "orderNumber": "…",
        "merchantOrderNo": "…",
        "provider": "…",
        "category": "B2B",
        "buyerName": "…",
        "buyerUbn": "…",
        "totalAmtTwd": 0,
        "status": "allowance",
        "declaredStatus": "declared",
        "invoiceNumber": "…",
        "invoiceTransNo": "…",
        "displayUrl": "…",
        "tourName": "…",
        "tourNo": "…",
        "tourDate": "…",
        "lastError": "…",
        "lastSyncedAt": "…",
        "createdAt": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}

toko version

檢查 CLI 新版與執行方式,不需要登入

toko version check

查詢 npm 發佈通道;只檢查,不安裝

參數

--channel <channel>
旗標 · 選填
--json
旗標 · 選填
範例
toko version check

Command Palette

Search for a command to run...