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 }。
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@1AI agent skill
CLI 內建租戶操作、員工 API 與自建前台指引。專案入口讀取目前 CLI 的內容,更新 CLI 就會更新指引。
複製初始化 prompt,讓 agent 安裝 CLI 並建立入口,見 AI agent 初始化與內建 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 參考),回應欄位即該端點的回應。
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 一樣只看得到自己經手的訂單。
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 --confirmorders refund-paid 只送出系統刷退。原付款超過金流商 API 退款期限、 接近待核對門檻,或退款單採人工模式時,server 會拒絕送出。CLI 不提供人工退刷登錄或執行模式變更,請至後台訂單頁操作。請先閱讀退款期限與人工退刷說明,再依各筆原收款選擇流程。
toko discount-codes
折扣碼:列表、明細、預覽試算、兌換報表
toko discount-codes list列出所有折扣碼
參數
--json回應欄位 · data[]
id折扣碼 id(disc_ 前綴)。
code折扣碼字串(客戶結帳輸入用,租戶內唯一)。
label折扣碼顯示名稱(後台辨識用)。
discountType折扣型別:fixed 定額折抵 / percentage 比例折抵。
discountValue折扣值:fixed 為 TWD 整數,percentage 為百分比數字。
discountBasis計算方式:per_order 整張訂單折一次 / per_travelers 每 N 位旅客折一次 / per_amount 每滿 N 元折一次。
discountStepN:每幾位旅客 / 每滿幾元(TWD);per_order 時為 null。
profitShareType分潤型別:fixed 定額 / percentage 比例;null = 無分潤。
profitShareValue分潤值:fixed 為 TWD 整數,percentage 為百分比;null = 無分潤。
profitSharePayee分潤受款對象(如合作夥伴名稱);null = 無。
isActive是否啟用(停用後不可再兌換)。
validFrom生效起始時間;null = 無下限。
validUntil生效截止時間;null = 無上限。
maxRedemptions總兌換次數上限;null = 不限。
redemptionCount已兌換次數(不含已取消訂單)。
minOrderTwd最低訂單金額門檻(TWD 整數);null = 無門檻。
minTravelerCount最低旅客人數門檻;null = 無門檻。
appliesToAll是否適用所有行程(true = 全站,false = 僅限 tripIds 名單)。
maxRedemptionsPerCustomer每位客戶兌換次數上限;null = 不限。
allowedPriceChannels限用的價格通路清單(如 direct / agency);null = 不限。
allowedCustomerTypes限用的客戶類型清單;null = 不限。
stackable保留的旗標,結帳不讀:一張訂單只能套一個折扣碼。
notes內部備註;null = 無。
createdAt建立時間。
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折扣碼 id(disc_ 前綴)。
code折扣碼字串(客戶結帳輸入用,租戶內唯一)。
label折扣碼顯示名稱(後台辨識用)。
discountType折扣型別:fixed 定額折抵 / percentage 比例折抵。
discountValue折扣值:fixed 為 TWD 整數,percentage 為百分比數字。
discountBasis計算方式:per_order 整張訂單折一次 / per_travelers 每 N 位旅客折一次 / per_amount 每滿 N 元折一次。
discountStepN:每幾位旅客 / 每滿幾元(TWD);per_order 時為 null。
profitShareType分潤型別:fixed 定額 / percentage 比例;null = 無分潤。
profitShareValue分潤值:fixed 為 TWD 整數,percentage 為百分比;null = 無分潤。
profitSharePayee分潤受款對象(如合作夥伴名稱);null = 無。
isActive是否啟用(停用後不可再兌換)。
validFrom生效起始時間;null = 無下限。
validUntil生效截止時間;null = 無上限。
maxRedemptions總兌換次數上限;null = 不限。
redemptionCount已兌換次數(不含已取消訂單)。
minOrderTwd最低訂單金額門檻(TWD 整數);null = 無門檻。
minTravelerCount最低旅客人數門檻;null = 無門檻。
appliesToAll是否適用所有行程(true = 全站,false = 僅限 tripIds 名單)。
maxRedemptionsPerCustomer每位客戶兌換次數上限;null = 不限。
allowedPriceChannels限用的價格通路清單(如 direct / agency);null = 不限。
allowedCustomerTypes限用的客戶類型清單;null = 不限。
stackable保留的旗標,結帳不讀:一張訂單只能套一個折扣碼。
notes內部備註;null = 無。
createdAt建立時間。
tripIds限定適用的行程 id 清單(appliesToAll=false 時生效)。
redemptions逐筆兌換紀錄。
orderId兌換該折扣碼的訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
codeSnapshot兌換當下的折扣碼字串快照。
originalTotalTwd套用折扣前的原始應收總額(TWD 整數);跨行程換梯後為目標團費。
discountTwd現行折抵金額(TWD 整數);跨行程換梯退出優惠後為 0。
profitShareTwd現行分潤金額(TWD 整數);跨行程換梯退出優惠後為 0。
orderStatus訂單當前狀態。
createdAt兌換(下單)時間。
totalDiscountTwd累計折抵金額合計(TWD 整數)。
totalProfitShareTwd累計分潤金額合計(TWD 整數)。
totalPaidTwd兌換訂單累計已收金額合計(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,用於每客戶使用次數限制判定
--jsontoko discount-codes preview --code 'example-code' --kind tour --total '1'{
"ok": true,
"data": null
}toko discount-codes redemptions折扣碼兌換 / 分潤報表
參數
<id>位置參數 · 必填--json回應欄位 · data
id折扣碼 id(disc_ 前綴)。
code折扣碼字串。
label折扣碼顯示名稱。
redemptionCount已兌換次數(不含已取消訂單)。
totalDiscountTwd累計折抵金額合計(TWD 整數)。
totalProfitShareTwd累計分潤金額合計(TWD 整數)。
totalPaidTwd兌換訂單累計已收金額合計(TWD 整數)。
redemptions逐筆兌換紀錄。
orderId兌換該折扣碼的訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
codeSnapshot兌換當下的折扣碼字串快照。
originalTotalTwd套用折扣前的原始應收總額(TWD 整數);跨行程換梯後為目標團費。
discountTwd現行折抵金額(TWD 整數);跨行程換梯退出優惠後為 0。
profitShareTwd現行分潤金額(TWD 整數);跨行程換梯退出優惠後為 0。
orderStatus訂單當前狀態。
createdAt兌換(下單)時間。
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回應欄位 · data
id新建立折扣碼的 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回應欄位 · data
ok操作成功旗標,恆為 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回應欄位 · data
ok操作成功旗標,恆為 true。
toko discount-codes set-active '<id>' --active true{
"ok": true,
"data": {
"ok": true
}
}toko group-codes
團號:碼表(地區/航空)與團號反查
toko group-codes regions地區碼對照表
參數
--active-only傳 true 或 1 時只列出啟用中的地區碼
--json回應欄位 · data[]
code地區代碼(團號組成,通常大寫縮寫,如 YS)。
name地區名稱(如「玉山」)。
isActive是否啟用(停用後不可再指派給新梯次)。
displayOrder顯示排序(由小到大)。
usedCount被多少梯次引用 —— 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航空公司代碼(團號組成,通常大寫縮寫,如 EG)。
name航空公司名稱。
isActive是否啟用(停用後不可再指派給新梯次)。
displayOrder顯示排序(由小到大)。
usedCount被多少梯次引用。
toko group-codes airlines list{
"ok": true,
"data": [
{
"code": "…",
"name": "…",
"isActive": true,
"displayOrder": 0,
"usedCount": 0
}
]
}toko group-codes lookup精確團號反查單一梯次
參數
<groupCode>位置參數 · 必填--json回應欄位 · data
id梯次 id(dep_ 前綴)。
tripId所屬行程 id(trip_ 前綴)。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日(ISO 'YYYY-MM-DD')。
groupCode完整團號。
regionCode地區代碼;null = 未設。
airlineCode航空公司代碼;null = 國內團或未設。
toko group-codes lookup '<groupCode>'{
"ok": true,
"data": {
"id": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureDate": "…",
"groupCode": "…",
"regionCode": "…",
"airlineCode": "…"
}
}toko group-codes search前綴團號反查多梯次
參數
<prefix>位置參數 · 必填--json回應欄位 · data[]
id梯次 id(dep_ 前綴)。
tripId所屬行程 id(trip_ 前綴)。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日(ISO 'YYYY-MM-DD')。
groupCode完整團號。
regionCode地區代碼;null = 未設。
airlineCode航空公司代碼;null = 國內團或未設。
toko group-codes search '<prefix>'{
"ok": true,
"data": [
{
"id": "…",
"tripId": "…",
"tripTitle": "…",
"tripSlug": "…",
"departureDate": "…",
"groupCode": "…",
"regionCode": "…",
"airlineCode": "…"
}
]
}toko group-codes region-create新增地區碼
參數
<code>位置參數 · 必填--name <名>碼的顯示名稱(如地區或航空公司全名)
--order <n>--inactive回應欄位 · data
ok操作成功旗標,恆為 true。
code新增或更新的地區代碼。
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操作成功旗標,恆為 true。
code新增或更新的地區代碼。
toko group-codes region-update '<code>' --name 'example-name'{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}toko group-codes region-delete刪除沒有梯次引用的地區碼(有引用的只能停用)
參數
<code>位置參數 · 必填回應欄位 · data
ok操作成功旗標,恆為 true。
code刪除的地區碼。
toko group-codes region-delete '<code>'{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}toko group-codes airline-create新增航空碼
參數
<code>位置參數 · 必填--name <名>碼的顯示名稱(如地區或航空公司全名)
--order <n>--inactive回應欄位 · data
ok操作成功旗標,恆為 true。
code新增或更新的航空公司代碼。
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操作成功旗標,恆為 true。
code新增或更新的航空公司代碼。
toko group-codes airline-update '<code>' --name 'example-name'{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}toko group-codes airline-delete刪除沒有梯次引用的航空碼(有引用的只能停用)
參數
<code>位置參數 · 必填回應欄位 · data
ok操作成功旗標,恆為 true。
code刪除的航空碼。
toko group-codes airline-delete '<code>'{
"ok": true,
"data": {
"ok": true,
"code": "…"
}
}toko holidays
國定假日 / 補班表:查詢、年度統計
toko holidays list列出假日 / 補班(可依年度篩選)
參數
--year <2026>篩選的西元年份(1000..9999);省略則回傳所有年份
--json回應欄位 · data
rows假日列(依日期排序)。
date日期(ISO 'YYYY-MM-DD')。
name名稱(如「國慶日」「補班」)。
isWorkday是否為補班日(true = 該日照常上班,false = 放假)。
toko holidays list{
"ok": true,
"data": {
"rows": [
{
"date": "…",
"name": "…",
"isWorkday": true
}
]
}
}toko holidays stats某年度假日 / 補班計數
參數
--year <2026>要統計的西元年份(1000..9999,必填)
--json回應欄位 · data
holidayCount該年度放假日數。
makeupCount該年度補班日數。
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回應欄位 · data
ok操作成功旗標,恆為 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回應欄位 · data
ok操作成功旗標,恆為 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回應欄位 · data
importedtoko 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當頁圖片列。
id圖片資源 id(timg_ 前綴)。
tripId所屬行程 id(trip_ 前綴);null = 未歸屬。
tripTitle所屬行程標題;null = 未歸屬。
tripSlug所屬行程網址 slug;null = 未歸屬。
url圖片公開 URL。
caption圖說文字;null = 無。
displayOrder在行程相簿中的排序(由小到大)。
createdAt上傳建立時間。
total符合條件的總筆數(跨頁)。
page目前頁碼(1 起算)。
pageSize每頁筆數。
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行程 id(trip_ 前綴)。
title行程標題。
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回應欄位 · data
id新建立圖片的 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回應欄位 · data
id新建立圖片的 id(timg_ 前綴)。
url圖片網址,可直接填進輪播或封面欄位。
toko images upload '<file>'{
"ok": true,
"data": {
"id": "…",
"url": "…"
}
}toko images delete刪除行程圖片
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok操作成功旗標,恆為 true。
toko images delete '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko lodging
旅宿:物件、房型、可用量、訂房、統計
toko lodging properties列出旅宿物件
參數
--json回應欄位 · data[]
id住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
slug網址 slug(公開站路徑,租戶內唯一)。
name住宿館名稱。
kind類型:hotel 旅館 / camp 營地。
isOverseas是否為海外住宿。
location地點描述;null = 未設。
description簡介文字;null = 未設。
contentMdx內文(MDX 原始碼);null = 未設。
facilities設施清單(JSON);null = 未設。
coverImageUrl封面圖 URL;null = 未設。
usageHint用途:direct 散客直訂 / package 梯次配套 / both 兩者皆可 / internal 不販售(內部據點)。
checkInTime入住時間文字(如「15:00」);null = 未設。
checkOutTime退房時間文字(如「11:00」);null = 未設。
checkInInfo入住須知;null = 未設。
houseRules館內規範;null = 未設。
cancellationPolicy取消政策;null = 未設。
addressRegion地址:縣市/區域;null = 未設。
addressLocality地址:鄉鎮/地區;null = 未設。
streetAddress街道地址;null = 未設。
postalCode郵遞區號;null = 未設。
latitude緯度;null = 未設。
longitude經度;null = 未設。
phone聯絡電話;null = 未設。
petsAllowed是否允許攜帶寵物;null = 未設。
smokingAllowed是否允許吸菸;null = 未設。
pretripArrivalFrom出發前夜可入住時段的起 'HH:MM';null = 不限。與 `pretripArrivalUntil` 同空同有。
pretripArrivalUntil出發前夜可入住時段的迄 'HH:MM';null = 不限。
status狀態:active 啟用 / inactive 停用。
seoTitleSEO 標題覆寫;null = 沿用內容欄。
seoDescriptionSEO 描述;null = 未設。
ogImageUrlOpen Graph 分享圖 URL;null = 未設。
createdAt建立時間。
updatedAt最後更新時間。
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住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
slug網址 slug(公開站路徑,租戶內唯一)。
name住宿館名稱。
kind類型:hotel 旅館 / camp 營地。
isOverseas是否為海外住宿。
location地點描述;null = 未設。
description簡介文字;null = 未設。
contentMdx內文(MDX 原始碼);null = 未設。
facilities設施清單(JSON);null = 未設。
coverImageUrl封面圖 URL;null = 未設。
usageHint用途:direct 散客直訂 / package 梯次配套 / both 兩者皆可 / internal 不販售(內部據點)。
checkInTime入住時間文字(如「15:00」);null = 未設。
checkOutTime退房時間文字(如「11:00」);null = 未設。
checkInInfo入住須知;null = 未設。
houseRules館內規範;null = 未設。
cancellationPolicy取消政策;null = 未設。
addressRegion地址:縣市/區域;null = 未設。
addressLocality地址:鄉鎮/地區;null = 未設。
streetAddress街道地址;null = 未設。
postalCode郵遞區號;null = 未設。
latitude緯度;null = 未設。
longitude經度;null = 未設。
phone聯絡電話;null = 未設。
petsAllowed是否允許攜帶寵物;null = 未設。
smokingAllowed是否允許吸菸;null = 未設。
pretripArrivalFrom出發前夜可入住時段的起 'HH:MM';null = 不限。與 `pretripArrivalUntil` 同空同有。
pretripArrivalUntil出發前夜可入住時段的迄 'HH:MM';null = 不限。
status狀態:active 啟用 / inactive 停用。
seoTitleSEO 標題覆寫;null = 沿用內容欄。
seoDescriptionSEO 描述;null = 未設。
ogImageUrlOpen Graph 分享圖 URL;null = 未設。
createdAt建立時間。
updatedAt最後更新時間。
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房型 id(rt_ 前綴)。
lengthReturns the length of a String object.
propertyId所屬住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
name房型名稱。
inventoryUnit庫存單位:room 以房計 / bed 以床位計。
unitsTotal總庫存量(房間數或床位數)。
capacityPerUnit每單位可住人數。
lowAvailabilityThreshold低水位提示門檻;null = 不提示。
basePriceTwd底價(TWD 整數,每晚每單位;可被逐晚覆寫)。
description房型描述;null = 未設。
facilities設施清單(JSON);null = 未設。
bedConfig床型配置(JSON);null = 未設。
floorSizeSqm房間坪數(平方公尺);null = 未設。
status狀態:active 啟用 / inactive 停用。
createdAt建立時間。
updatedAt最後更新時間。
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房型 id(rt_ 前綴)。
lengthReturns the length of a String object.
propertyId所屬住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
name房型名稱。
inventoryUnit庫存單位:room 以房計 / bed 以床位計。
unitsTotal總庫存量(房間數或床位數)。
capacityPerUnit每單位可住人數。
lowAvailabilityThreshold低水位提示門檻;null = 不提示。
basePriceTwd底價(TWD 整數,每晚每單位;可被逐晚覆寫)。
description房型描述;null = 未設。
facilities設施清單(JSON);null = 未設。
bedConfig床型配置(JSON);null = 未設。
floorSizeSqm房間坪數(平方公尺);null = 未設。
status狀態:active 啟用 / inactive 停用。
createdAt建立時間。
updatedAt最後更新時間。
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整段住宿期間可訂房間數(各晚剩餘取最小;任一晚關閉則為 0)。
nights住宿晚數。
totalPriceTwd整段期間房價合計(TWD 整數,逐晚牌價加總)。
perNight逐晚可售明細。
night該晚日期(ISO 'YYYY-MM-DD')。
capacity該晚可售容量(房間數;有覆寫則用覆寫值,否則房型總數)。
booked該晚已訂數。
remaining該晚剩餘可訂數(capacity − booked,不小於 0)。
priceTwd該晚房價(TWD 整數;有逐晚覆寫則用覆寫值,否則房型底價)。
status該晚販售狀態: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該晚日期(ISO 'YYYY-MM-DD')。
directBooked該晚散客直訂的已訂數。
packageBooked該晚梯次配套佔用的已訂數。
pretripBooked該晚出發前夜住宿(非販售佔用)的已訂數。
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圖片資源 id(pimg_ / rtimg_ 前綴)。
url圖片公開 URL。
caption圖說文字;null = 無。
displayOrder相簿中的排序(由小到大)。
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訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
status顯示狀態(派生自三軸,沿用舊欄名供 UI badge / canCancel 相容)。
bookingState訂位軸狀態(如 confirmed / cancelled)。
paymentState付款軸狀態(如 unpaid / partial / paid)。
refundState退款軸狀態。
totalTwd應收總額(TWD 整數,訂單各應收明細加總)。
createdAt訂單建立時間。
bookerName訂購人姓名。
bookerEmail訂購人 email。
propertyId住宿館 id(prop_ 前綴)。
propertyName住宿館名稱。
roomTypeId房型 id(rt_ 前綴)。
roomTypeName房型名稱。
checkIn入住日(ISO 'YYYY-MM-DD')。
checkOut退房日(ISO 'YYYY-MM-DD')。
units訂購房間數。
guestCount入住總人數。
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訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
status顯示狀態(派生自三軸,沿用舊欄名供 UI badge / canCancel 相容)。
bookingState訂位軸狀態(如 confirmed / cancelled)。
paymentState付款軸狀態(如 unpaid / partial / paid)。
refundState退款軸狀態。
totalTwd應收總額(TWD 整數,訂單各應收明細加總)。
createdAt訂單建立時間。
bookerName訂購人姓名。
bookerEmail訂購人 email。
propertyId住宿館 id(prop_ 前綴)。
propertyName住宿館名稱。
roomTypeId房型 id(rt_ 前綴)。
roomTypeName房型名稱。
checkIn入住日(ISO 'YYYY-MM-DD')。
checkOut退房日(ISO 'YYYY-MM-DD')。
units訂購房間數。
guestCount入住總人數。
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今晚入住房間數(Asia/Taipei)。
tonightCheckInGuests今晚入住總人數(Asia/Taipei)。
weekOccupancyPct未來 7 晚住房率(已訂 / 可售,0–100)。
next7AvailableUnits未來 7 晚仍可售的房晚數。
pendingPaymentCount待收款訂單筆數。
pendingPaymentTwd待收款金額合計(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--json回應欄位 · data
id新建立住宿館的 id(prop_ 前綴)。
slug實際寫入的網址 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--json回應欄位 · data
ok操作成功旗標,恆為 true。
toko lodging property-update '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko lodging property-archive封存旅宿物件(status→inactive)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok操作成功旗標,恆為 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--json回應欄位 · data
id新建立房型的 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--json回應欄位 · data
ok操作成功旗標,恆為 true。
toko lodging room-type-update '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko lodging room-type-archive封存房型(status→inactive)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok操作成功旗標,恆為 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回應欄位 · data
ok操作成功旗標,恆為 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回應欄位 · data
ok操作成功旗標,恆為 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--json回應欄位 · data
orderId新建立住宿訂單的 id(ord_ 前綴)。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;建單與入帳本身已完成。
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--json回應欄位 · data
id新建立住宿館圖片的 id(pimg_ 前綴)。
toko lodging image-add --property '<id>' --url 'example-url'{
"ok": true,
"data": {
"id": "…"
}
}toko lodging image-delete刪除物件或房型圖片
參數
<imageId>位置參數 · 必填--property--room-type--confirm回應欄位 · data
ok操作成功旗標,恆為 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選填全公司共用的後台釘選時間。
id行程 id(trip_ 前綴)。
slug行程網址 slug。
title行程標題。
destination目的地名稱。
durationDays天數。
guideStartDay選填guideEndDay選填priceFromTwd「NT$ X 起」起價(TWD 整數)。
status上架狀態:draft 草稿 / published 已上架 / archived 封存。
isHidden不對外顯示(#1435)。
isLinkOnly僅限連結:不進任何列表,行程頁不給搜尋引擎收錄,拿到網址可報名。與 `isHidden` 互斥。
foreignTravelersOnly限外籍旅客(issue 1519)。
updatedAt最後更新時間。
isClimbing是否登山團(行程層模組旗標)。
isOverseas是否海外團(行程層模組旗標)。
hasPreTripNight是否有行前集合夜(trips.md §3)。
activeDepartureCountCount of departures with status='selling'.
nextDepartureDateEarliest selling departure_date, ISO date string, or null.
representativeGroupCode代表團號(group-code §8.2):最新一筆有團號的梯次;無則 null(UI 顯示 —)。
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行程 id(trip_ 前綴)。
lengthReturns the length of a String object.
slug行程網址 slug(公開站路徑)。
title行程標題。
shortName選填內部簡稱(issue 1414);null = 未填。只有後台讀取帶,前台投影不帶。
summary一句話摘要;null = 未設。
contentMdx行程內文(MDX 原始碼);null = 未設。
lotteryNoticeMdx選填destination目的地名稱。
durationDays天數。
balanceDueDaysBeforeDeparture選填尾款於出發前幾天;null = 未設(出發當天)。前台顯示尾款期限用(trip-pricing §3.1)。
guideStartDay選填guideEndDay選填priceFromTwd「NT$ X 起」起價(TWD 整數)。
coverImageUrl封面圖 URL;null = 未設。
status上架狀態:draft 草稿 / published 已上架 / archived 封存。
isHidden不對外顯示(#1435):官網看不到、網址 404,後台照常可用。
isLinkOnly僅限連結(issue 1351):不進任何列表,行程頁 noindex、不出 JSON-LD,拿到網址可報名。
createdAt建立時間。
updatedAt最後更新時間。
isClimbing是否登山團(行程層模組旗標)。
isOverseas是否海外團(行程層模組旗標)。
equipmentRentalEnabled可租借裝備(equipment-inventory §3.1):與登山團旗標疊加,梯次不得覆寫。
hasPreTripNight是否有行前集合夜(trips.md §3)。集合日恆為 `departure_date − 1`,不落欄。
meetingDay第幾天集合(issue 1474):1 = 出發日。有行前集合夜時恆為 1。
minGroupSize最低成團人數(旅遊契約第 10 條揭露用);null = 不設門檻。
pretripStayRoomTypeId出發前夜住宿據點的床位池(ADR 0022 / 0029);null = 不住公司據點。出團不得覆寫。
pretripStayExternalArranged出發前夜住宿由公司安排外部住宿(民宿等);效力同旅客自理,僅顯示語意(#431)。
gradeScore難度評鑑分數(climbing-screening §3.1);null = 未評級。
difficultyLeveltagsrequiresAlpineExperience是否要求具備高山經驗(報名審核用)。
isHighAltitude行程本身屬高海拔(#2018):結團寫入的登山紀錄依此認列高山經驗。
screeningExempt入門免審:不做分數審核,高山經驗硬閘照判。
gradeLabel難度標籤(如「B+」);null = 未設。
waitlistEnabled候補開關(席滿後仍收候補,lottery-integration §3.5)。
defaultAllocationMode預設分配模式(lottery-integration §2.1):新增梯次時 copy-on-create,梯次可覆寫。
lotteryLeadDays選填抽籤日在出發日前幾天(issue 1095);null = 未設。梯次可覆寫;admin-only。
lotteryDrawTime選填抽籤時刻預設(`HH:MM`,issue 1656);null = 未設。梯次可覆寫;admin-only。
lotteryDrawDayOffset選填抽籤時刻落在哪一天(issue 2041):0 = 抽籤日當天,-1 = 前一天。梯次可覆寫;admin-only。
agreementChangeBufferDays選填抽籤梯次緩衝天數的行程覆寫(issue 1178);null = 沿用公司設定;admin-only。
agreementTravelForm選填本行程契約的旅遊型態(issue 1178);null = 沿用公司設定;admin-only。
agreementExempt選填此行程不需旅遊契約(issue 1524)。
foreignTravelersOnly限外籍旅客(issue 1519):本國旅客不能報名。行程頁對客揭露,所以公開投影也帶。
travelersPerGuide選填每幾位旅客配一位隨團人員(issue 1117);null = 不自動算;admin-only。
defaultGuideCount選填預設需要幾位嚮導(#1377);建梯次沒指定時帶入,0 = 不需嚮導;null = 沒設;admin-only。
defaultCapacity新增梯次的預設席次(trips.md §2.1);null = 沒設,表單用固定預設。
meetingTime集合時間的行程層預設(HH:mm,台北牆鐘;departure-prep §2.4.1);null = 未設。梯次未填時繼承。
meetingPlace集合地點的行程層預設;null = 未設。梯次未填時繼承。
pretripBriefingUrl選填行前說明網址(issue 1618);null = 未填。所有梯次共用;admin-only。
paymentReceivedBody選填收款後通知內文(issue 1743);null = 未填,用範本內文。所有梯次共用;admin-only。
salesCloseDaysBefore停止售票預設:出發前 N 天 00:00(trips.md §2.2);null = 行程層不設。
feeInclusions團費包含/不包含(前台費用區唯一來源);null = 未設。
notices注意事項(前台行程頁顯示);空陣列 = 未設。
suggestedFlights建議航班(前台航班卡片);null = 未設。
updatedticketplansnameprimarymodemeetDaymeetTimemeetPlaceflightsdirflightfromtodepDaydeparrDayarrairportsroutedurationarriveDayBeforeextraAirlinesextraAirportscancellationFeeTiers逐行程退改費階梯覆寫(customer-cancellation §3);**null = 未覆寫**(用租戶預設), `[]` = 本行程不收退改費。兩者語意不同,不可折疊。
manualCancellationRefundseoTitleSEO 標題覆寫;null = 沿用 title。
seoDescriptionSEO 描述;null = 未設。
ogImageUrlOpen Graph 分享圖 URL;null = 未設。
images行程相簿圖片(依 displayOrder 排序)。
id圖片資源 id(timg_ 前綴)。
url圖片公開 URL。
caption圖說文字;null = 無。
displayOrder在行程相簿中的排序(由小到大)。
departuresActive (selling, future) departures only on the public side; all on admin.
id梯次 id(dep_ 前綴)。
tripId所屬行程 id(trip_ 前綴)。
departureDate出發日(ISO 'YYYY-MM-DD')。
returnDate回程日(ISO 'YYYY-MM-DD')。
priceTwd售價(TWD 整數,未稅牌價)。
capacity名額上限(人數)。
bookedCount已成團佔用名額(人數)。
status梯次狀態:selling 販售中 / closed 關閉 / cancelled 取消 / completed 已結團。
notes內部備註;null = 無。
allocationMode抽籤分配模式(lottery-integration §2.1):fcfs=先到先得 / lottery=抽籤制。
label選填梯次標籤 / 副標(例:「包」「包1」);null = 無;admin-only,公開站不映射。
isPrivate選填不對外販售(前台不顯示、不可自助報名;後台可建單);admin-only,公開站不映射。
agencyPriceTwd選填同業價(TWD 整數);admin-only,公開站不映射。
depositMode選填訂金規則模式:none 免訂金 / fixed 定額 / percent 比例;admin-only。
depositAmountTwd選填訂金定額(TWD 整數,depositMode=fixed 時適用);admin-only。
depositPercent選填訂金比例(百分比,depositMode=percent 時適用);admin-only。
groupCode選填團號(group-code §3.3);admin-only,公開站不映射。
regionCode選填地區代碼(團號組成);admin-only。
airlineCode選填航空公司代碼(團號組成);admin-only。
promoActive選填梯次促銷是否啟用(trip-pricing);admin-only。
promoPriceTwd選填促銷覆寫售價(TWD 整數);admin-only。
promoAgencyPriceTwd選填促銷覆寫同業價(TWD 整數);admin-only。
salesCloseAt選填逐梯停止售票時間(trips.md §2.2);null = 繼承行程層;admin-only。
effectiveSalesCloseAt選填有效停止售票時間:逐梯值,否則行程層「出發前 N 天 00:00」派生;兩者皆無為 null。 排程到點把 selling → closed 就是看這個值;admin-only。
salesAutoClosedAt選填排程自動關閉的時間;null = 人工關或未關。與 status='closed' 合看;admin-only。
salesClosePassed選填有效停止售票時間是否已到(DB 的 NOW() 判,與排程同一個時鐘);admin-only。
salesOpenAt選填開賣時間(trips.md §2.2a);null = 沒有排程;admin-only。
salesOpenFailedReason選填到點開賣被擋下的原因;null = 沒有失敗;admin-only。
meetingTime選填第 4 條集合時間(牆鐘字串);admin-only。
meetingPlace選填第 4 條集合地點;admin-only。
agreementChangeDays選填可變更第三人期限天數的逐梯覆寫;null = 退回租戶預設(團體契約的抽籤梯次必填);admin-only。
entryDateOffsetDays選填實際入園日相對出發日的偏移天數(departure-prep §2.6.1);admin-only。
lotteryLeadDays選填抽籤前幾天的逐梯覆寫(issue 1095);null = 繼承行程層;admin-only。
lotteryDrawTime選填抽籤時刻的逐梯覆寫(`HH:MM`,issue 1656);null = 繼承行程層;admin-only。
lotteryDrawDayOffset選填抽籤時刻落在哪一天的逐梯覆寫(issue 2041):0 = 抽籤日當天,-1 = 前一天;null = 繼承行程層; admin-only。
lotteryChangeDays選填抽籤梯次的自動可變更第三人期限(出發前幾天,issue 1178):抽籤前幾天+緩衝天數,或公司抽籤 日期來源推回的天數;算不出來是 null。不看逐梯手填值與分配模式;admin-only。
lotteryDrawDate選填抽籤日(`YYYY-MM-DD`,`lotteryDrawDateSql`,issue 1656);沒有抽籤日為 null。不看分配模式;admin-only。
effectiveLotteryDrawTime選填生效的抽籤時刻(`HH:MM`,`lotteryDrawTimeSql`:時程表時段開始 → 梯次覆寫 → 行程預設); 未設為 null,前台在抽籤日 00:00 截止;admin-only。
lotteryDrawAtDate選填生效抽籤時刻所在的日期(`YYYY-MM-DD`,`lotteryDrawAtDateSql`,issue 2041):抽籤日加日偏移。 時程表時段優先或沒有抽籤時刻時等於 `lotteryDrawDate`;admin-only。
lotteryApplicationClosed選填抽籤梯次已截止申請(前台不收單,issue 1656);admin-only。
requiredGuideCount選填需要的隨團人員數(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新建立梯次的 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回應欄位 · data
id新建立行程的 id(trip_ 前綴)。
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回應欄位 · data
ok操作成功旗標,恆為 true。
toko trips update '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko trips lottery-notice-templates抽籤須知範本:查詢、建立、取代與刪除
參數
<id>位置參數 · 必填--name <name>範本名稱,可依抽籤天數或路線命名
--content-mdx <mdx>須知 MDX 內容,可使用 Notice 醒目提醒區塊
回應欄位 · data[]
idlengthReturns the length of a String object.
namecontentMdxcreatedAtupdatedAttoko 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回應欄位 · data
idlengthReturns the length of a String object.
namecontentMdxcreatedAtupdatedAttoko 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回應欄位 · data
ok操作成功旗標,恆為 true。
toko trips set-cost-template '<tripId>'{
"ok": true,
"data": {
"ok": true
}
}toko trips cost-templates列出可綁定的 active 成本範本
參數
--json回應欄位 · data[]
id成本範本 id(ct_ 前綴)。
name成本範本名稱。
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--json回應欄位 · data
filename已匯入的檔名。
result匯入結果(建檔筆數與逐列結果)。
importBatchId本次匯入批次 id(imp_ 前綴),供稽核追溯。
createdTripCount新建行程數。
createdDepartureCount新建梯次數。
skippedCount略過列數(重複/無需匯入)。
errorCount失敗列數。
results逐列匯入結果。
rowNumber試算表列號(含表頭列,資料第一列為 2)。
status該列匯入結果:new_trip / append_departure / skip / error。
messageerror / skip 的人話原因(繁中);成功列為空。
tripId選填建出的 trip id(new_trip 成功時)。
departureId選填建出的 departure id(new_trip / append_departure 成功時)。
groupCode選填產生的團號(有地區碼時;航空碼選填)。
incompleteTrips本批**新建**行程中,關鍵設定仍為空者(#461)。漏填的三組全是靜默失效(難度分留空 → 審核器不作用;階梯未覆寫 → 套租戶預設那組;訂金不收),結果頁列出並附編輯連結。 只列有缺的行程;補梯次的既有行程不列(匯入不動它的設定)。
tripIdslugtitlemissing仍為空的關鍵設定(至少一項)。
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匯出的行程列(套用相同 filter,無分頁)。
adminPinnedAt選填全公司共用的後台釘選時間。
id行程 id(trip_ 前綴)。
slug行程網址 slug。
title行程標題。
destination目的地名稱。
durationDays天數。
guideStartDay選填guideEndDay選填priceFromTwd「NT$ X 起」起價(TWD 整數)。
status上架狀態:draft 草稿 / published 已上架 / archived 封存。
isHidden不對外顯示(#1435)。
isLinkOnly僅限連結:不進任何列表,行程頁不給搜尋引擎收錄,拿到網址可報名。與 `isHidden` 互斥。
foreignTravelersOnly限外籍旅客(issue 1519)。
updatedAt最後更新時間。
isClimbing是否登山團(行程層模組旗標)。
isOverseas是否海外團(行程層模組旗標)。
hasPreTripNight是否有行前集合夜(trips.md §3)。
activeDepartureCountCount of departures with status='selling'.
nextDepartureDateEarliest selling departure_date, ISO date string, or null.
representativeGroupCode代表團號(group-code §8.2):最新一筆有團號的梯次;無則 null(UI 顯示 —)。
total匯出總筆數。
truncated是否因上限被截斷(此端點回全列,恆為 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回應欄位 · data
defaultstransportkeydescriptionvehicleInfofareNotecateringkeysuppliermealPlanheadcountNoteinsurance逐 kind 一列:保險公司與排定辦理日的「出發前 N 個工作天」(issue 1373)。兩欄至少一欄有值; 缺 kind = 該類不預建。保單號永遠逐梯填。`workdaysBefore` 省略 = 不帶排定日。
kindinsurerworkdaysBefore選填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
transportkeydescriptionvehicleInfofareNotecateringkeysuppliermealPlanheadcountNoteinsurance逐 kind 一列:保險公司與排定辦理日的「出發前 N 個工作天」(issue 1373)。兩欄至少一欄有值; 缺 kind = 該類不預建。保單號永遠逐梯填。`workdaysBefore` 省略 = 不帶排定日。
kindinsurerworkdaysBefore選填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回應欄位 · data
foundtoko 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回應欄位 · data
foundtoko 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回應欄位 · data
idtoko 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回應欄位 · data
foundtoko 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回應欄位 · data
idtoko 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[]
idtripIdkindlabeldescriptionrequireddisplayOrderisActiveoptionsidlabelequipmentItemId綁定的裝備主檔品項(issue 240;只有 multi / quantity 題可綁);null = 純文字選項。
displayOrderisActivetoko 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`leadDays` 為 null:首列與租戶預設同門檻,直接重套成租戶預設。
tripIdtitleleadDaysskipped略過的行程(無效列、不收退改費、判斷不出前置天數、租戶預設產不出階梯)。
tripIdtitlereasonunchangedCount已經一致或未覆寫,不需要改的行程數。
tenantTiers判斷時用的租戶預設。確認寫入時原樣送回,交易內比對它有沒有被改過。
daysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
onSaleCount`changes` 裡已開賣的行程數:有後台可建單(販售中)、且尚未出發的梯次。
orderCount`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回應欄位 · data
changes`leadDays` 為 null:首列與租戶預設同門檻,直接重套成租戶預設。
tripIdtitleleadDaysskipped略過的行程(無效列、不收退改費、判斷不出前置天數、租戶預設產不出階梯)。
tripIdtitlereasonunchangedCount已經一致或未覆寫,不需要改的行程數。
tenantTiers判斷時用的租戶預設。確認寫入時原樣送回,交易內比對它有沒有被改過。
daysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
onSaleCount`changes` 裡已開賣的行程數:有後台可建單(販售中)、且尚未出發的梯次。
orderCount`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同業 id(前綴 `agc_`)。
name同業公司名 / 個人團主名稱。
taxId統一編號(個人團主可留空)。
contactName主要聯絡人姓名(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
address公司地址(未填 → null)。
paymentTerm帳期 / 結算方式(自由文字,例:'月結 30 天')。
paymentDueRuleownerUserId負責業務 user id(NULL = 未指派)。
ownerName負責業務顯示名;未指派為 null。
status同業狀態:active 啟用中 / archived 已封存。
note內部備註(未填 → null)。
orderCount累計訂單數(COUNT orders WHERE agency_id = id)。
createdAt建立時間。
updatedAt最後更新時間。
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同業 id(前綴 `agc_`)。
name同業公司名 / 個人團主名稱。
taxId統一編號(個人團主可留空)。
contactName主要聯絡人姓名(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
address公司地址(未填 → null)。
paymentTerm帳期 / 結算方式(自由文字,例:'月結 30 天')。
paymentDueRuleownerUserId負責業務 user id(NULL = 未指派)。
ownerName負責業務顯示名;未指派為 null。
status同業狀態:active 啟用中 / archived 已封存。
note內部備註(未填 → null)。
orderCount累計訂單數(COUNT orders WHERE agency_id = id)。
createdAt建立時間。
updatedAt最後更新時間。
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員工使用者 id(可作為負責業務指派的 ownerUserId)。
name員工顯示名。
role角色代碼(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同業匯出資料列(依 owner 篩選後的全表快照,供試算表匯出)。
id同業 id(前綴 `agc_`)。
name同業公司名 / 個人團主名稱。
taxId統一編號(個人團主可留空)。
contactName主要聯絡人姓名(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
address公司地址(未填 → null)。
paymentTerm帳期 / 結算方式(自由文字,例:'月結 30 天')。
paymentDueRuleownerUserId負責業務 user id(NULL = 未指派)。
ownerName負責業務顯示名;未指派為 null。
status同業狀態:active 啟用中 / archived 已封存。
note內部備註(未填 → null)。
orderCount累計訂單數(COUNT orders WHERE agency_id = id)。
createdAt建立時間。
updatedAt最後更新時間。
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回應欄位 · data
id新建立同業的 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回應欄位 · data
ok固定為 true:同業資料已更新。
toko agencies update '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko agencies archive下架同業(鏡射 setAgencyStatus archived;agency.manage)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true:同業啟用/停用狀態已更新。
toko agencies archive '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko agencies restore上架同業(鏡射 setAgencyStatus active;agency.manage)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true:同業啟用/停用狀態已更新。
toko agencies restore '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko consent
同意書範本:查詢、明細
toko consent list列出同意書範本(各版本)
參數
--kind <pdpa|tour_agreement|cancellation_policy|refund_policy>同意書類別代碼,指定時僅列出該類別的範本版本
--json回應欄位 · data[]
id同意書範本 id(前綴 `ct_`)。同一 kind 每個版本各有一個 id。
kind同意書類型:系統種類 pdpa(個資)/ tour_agreement(旅遊契約)/ cancellation_policy / refund_policy,或自訂種類的 `consent_kinds.id`(`cnsk_…`)。
agreementType旅遊契約的種類(觀光署四種之一)。非旅遊契約恆 null;`tour_agreement` 為 null = #585 之前建的未分類舊範本,選範本時選不到。
version版本號,同一 kind(旅遊契約則是同一 kind + 種類)從 1 遞增;append-only,編輯即新增下一版。
contentMdx範本內容(MDX 原始碼),可含 {{...}} merge 變數。
effectiveFrom此版本生效起始時間。
createdAt此版本建立時間。
signatureCount引用此版本的已簽署份數(COUNT consent_signatures)。
retiredsigningFieldsbalancePaymentMethodrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
emergencyContactRelationrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article30Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article32Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
guardianrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
electronicSigningConsentrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
toko consent list{
"ok": true,
"data": [
{
"id": "…",
"kind": "…",
"agreementType": "domestic_individual",
"version": 0,
"contentMdx": "…",
"effectiveFrom": "…",
"createdAt": "…",
"signatureCount": 0,
"retired": true,
"signingFields": {
"balancePaymentMethod": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"emergencyContactRelation": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"article30Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"article32Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"guardian": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"electronicSigningConsent": {
"required": true,
"options": [
"agree"
],
"hidden": true
}
}
}
]
}toko consent get單一同意書範本明細
參數
<id>位置參數 · 必填--json回應欄位 · data
id同意書範本 id(前綴 `ct_`)。同一 kind 每個版本各有一個 id。
kind同意書類型:系統種類 pdpa(個資)/ tour_agreement(旅遊契約)/ cancellation_policy / refund_policy,或自訂種類的 `consent_kinds.id`(`cnsk_…`)。
agreementType旅遊契約的種類(觀光署四種之一)。非旅遊契約恆 null;`tour_agreement` 為 null = #585 之前建的未分類舊範本,選範本時選不到。
version版本號,同一 kind(旅遊契約則是同一 kind + 種類)從 1 遞增;append-only,編輯即新增下一版。
contentMdx範本內容(MDX 原始碼),可含 {{...}} merge 變數。
effectiveFrom此版本生效起始時間。
createdAt此版本建立時間。
signatureCount引用此版本的已簽署份數(COUNT consent_signatures)。
retiredsigningFieldsbalancePaymentMethodrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
emergencyContactRelationrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article30Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article32Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
guardianrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
electronicSigningConsentrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
toko consent get '<id>'{
"ok": true,
"data": {
"id": "…",
"kind": "…",
"agreementType": "domestic_individual",
"version": 0,
"contentMdx": "…",
"effectiveFrom": "…",
"createdAt": "…",
"signatureCount": 0,
"retired": true,
"signingFields": {
"balancePaymentMethod": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"emergencyContactRelation": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"article30Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"article32Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"guardian": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"electronicSigningConsent": {
"required": true,
"options": [
"agree"
],
"hidden": true
}
}
}
}toko consent create新增同意書範本版本(append-only,版號自動遞增)
參數
--kind <pdpa|tour_agreement|cancellation_policy|refund_policy>同意書類別代碼:系統種類(pdpa / tour_agreement / cancellation_policy / refund_policy)或租戶自訂種類的 id(cnsk_ 開頭)
--agreement-type <domestic_individual|domestic_group|overseas_individual|overseas_group>旅遊契約種類(國內/國外 × 個別/團體),kind 為 tour_agreement 時必填
--content-mdx <text|@file>同意書內文(MDX 格式),即此版本的條款全文
--confirm回應欄位 · data
id新建立同意書範本的 ID。
version範本版本號(每次發布遞增,簽署時綁定當下版本)。
toko consent create --kind pdpa --content-mdx text{
"ok": true,
"data": {
"id": "…",
"version": 0
}
}toko consent kinds-update更新 consent-kinds/[id]
參數
<id>位置參數 · 必填--data <json>JSON object with the fields from the linked API request.
--json--confirm回應欄位 · data
okidtoko consent kinds-update '<id>' --data '{"label":"example-label","signTiming":"checkout","signerScope":"order","allTrips":true,"tripIds":["example-tripIds"],"isActive":true}'{
"ok": true,
"data": {
"ok": "…",
"id": "…"
}
}toko consent kinds-delete刪除 consent-kinds/[id](只能刪還沒有範本版本的種類)
參數
<id>位置參數 · 必填--json--confirm回應欄位 · data
okidtoko consent kinds-delete '<id>'{
"ok": true,
"data": {
"ok": "…",
"id": "…"
}
}toko consent kinds-list查詢 consent-kinds
參數
--data <json>--json回應欄位 · data[]
id`cnsk_<ulid>`;同時是這個種類的範本列 `consent_templates.kind`。
labelsortOrderisActivesignTimingsignerScopeallTripstrue = 所有行程適用;false = 只適用 `tripIds`。
tripIdstemplateCount此種類已建的範本版本數。
toko consent kinds-list{
"ok": true,
"data": [
{
"id": "…",
"label": "…",
"sortOrder": 0,
"isActive": true,
"signTiming": "after_confirm",
"signerScope": "order",
"allTrips": true,
"tripIds": [
"…"
],
"templateCount": 0
}
]
}toko consent kinds-create執行 consent-kinds
參數
--data <json>JSON object with the fields from the linked API request.
--json--confirm回應欄位 · data
okidtoko consent kinds-create --data '{"label":"example-label","signTiming":"checkout","signerScope":"order","allTrips":true,"tripIds":["example-tripIds"]}'{
"ok": true,
"data": {
"ok": "…",
"id": "…"
}
}toko members
會員(客戶):查詢、明細、統計
toko members list列出/搜尋會員
參數
--q <text>關鍵字,模糊比對會員姓名、Email 或電話
--county <縣市>縣市篩選,僅回傳通訊地址在該縣市的會員
--year <yyyy>加入年份(西元四位數),僅回傳該年註冊的會員
--page <n>分頁頁碼,從 1 起算,預設第 1 頁
--page-size <n>每頁筆數,上限 200,預設由後端決定
--json回應欄位 · data
rows當前頁的會員列。
userId會員(顧客)的 user id。
email會員 Email(登入帳號)。
name會員姓名。
createdAt會員註冊時間。
phone聯絡電話(未填 → null)。
address通訊地址(未填 → null)。
birthDate生日 YYYY-MM-DD(未填 → null)。
orderCount累計訂單數(含所有狀態與 kind)。
paidOrderCount成交訂單數(未取消,且已付清或已完成)。
totalSpent累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。
lastOrderAt最後一筆訂單建立時間(無訂單 → null)。
pdpaSignedAt最新版 PDPA 同意書簽署時間(未簽 → null)。
anonymizedAtPDPA 匿名化時間;非空 = 已匿名化。
createdByUserId後台代建者 user id(member-admin-create);null = 客戶自助註冊。
createdByName代建者姓名(join `user`);自助註冊 → null。
total符合篩選的會員總數。
page當前頁碼(從 1 起算)。
pageSize每頁筆數。
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會員基本資料 + 訂單彙整。
userId會員(顧客)的 user id。
email會員 Email(登入帳號)。
name會員姓名。
createdAt會員註冊時間。
phone聯絡電話(未填 → null)。
address通訊地址(未填 → null)。
birthDate生日 YYYY-MM-DD(未填 → null)。
orderCount累計訂單數(含所有狀態與 kind)。
paidOrderCount成交訂單數(未取消,且已付清或已完成)。
totalSpent累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。
lastOrderAt最後一筆訂單建立時間(無訂單 → null)。
pdpaSignedAt最新版 PDPA 同意書簽署時間(未簽 → null)。
anonymizedAtPDPA 匿名化時間;非空 = 已匿名化。
createdByUserId後台代建者 user id(member-admin-create);null = 客戶自助註冊。
createdByName代建者姓名(join `user`);自助註冊 → null。
orders近期訂單列表(上限 50 筆,含 lodging)。
id訂單 id。
orderNumber人類可讀訂單編號。
status金流模型 v2:deriveOrderDisplayStatus(booking/payment/refund) 派生的單一顯示狀態。
total該會員所有訂單的應收總額(TWD 整數)。
createdAt訂單建立時間。
tripTitle行程 / 產品標題。
consents已簽署的同意書紀錄(上限 50 筆)。
id簽署紀錄 id。
kind同意書類型:系統種類(pdpa / tour_agreement / cancellation_policy / refund_policy) 或租戶自訂種類的 id(`cnsk_…`)。
kindLabel自訂種類的名稱;系統種類為 null。
travelerName代簽時被代簽旅客的姓名(逐旅客的自訂同意書);本人簽署為 null。
version簽署當下的範本版本號。
signedAt簽署時間。
ipAddress簽署時來源 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會員(顧客)總數(排除員工帳號)。
newThisMonth本月新增會員數(自助 + 代建)。
newThisMonthStaffCreated本月新增中由後台代建的數量(member-admin-create §4)。
staffCreated累計由後台代建的會員數(`member_profiles.created_by_user_id IS NOT NULL`)。
withOrders有下過訂單的會員數。
averageOrders平均訂單數(只計有訂單者,避免零訂單稀釋)。
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證件即將到期(或已過期)需提醒的會員 user id 清單。
toko members expiry-flags --ids 'example-ids'{
"ok": true,
"data": {
"userIds": [
"…"
]
}
}toko members anonymizePDPA 匿名化會員(不可逆:抹除 PII + 封鎖登入 + 撤銷憑證)
參數
<userId>位置參數 · 必填--reason <t>匿名化原因,記入稽核紀錄備查
--confirm回應欄位 · data
ok固定為 true:會員個資已匿名化(PDPA 刪除權)。
toko members anonymize '<userId>'{
"ok": true,
"data": {
"ok": true
}
}toko members create建立會員並寄啟用信
參數
--email <value>會員登入 Email,也是啟用信的收件地址
--name <value>會員姓名
--phone <value>聯絡電話(選填)
--json--confirm回應欄位 · data
userId新建會員的使用者 ID。
email正規化(小寫)後的登入 Email。
name會員姓名。
activationSent啟用信是否已送出請求;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,完整比對、不分大小寫
--jsontoko members lookup --email 'customer@example.com'{
"ok": true,
"data": "…"
}toko members search搜尋建單會員候選
參數
--q <value>關鍵字,模糊比對會員姓名或 Email
--json回應欄位 · data[]
userIdnameemailphonelineIdlineDisplayNameorderCounttoko members search --q 'example-q'{
"ok": true,
"data": [
{
"userId": "…",
"name": "…",
"email": "…",
"phone": "…",
"lineId": "…",
"lineDisplayName": "…",
"orderCount": 0
}
]
}toko members line-user-id-set把官方 LINE 機器人蒐集的 LINE userId 綁到會員
參數
<id>位置參數 · 必填--line-user-id <value>LINE userId:U 開頭加 32 碼小寫十六進位
--json--confirm回應欄位 · data
oktoko 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回應欄位 · data
oktoko 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 碼小寫十六進位
--jsontoko 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當前頁的訂單列(每筆商品明細一列)。
accountingDisplay accounting amounts. The cash ledger remains unchanged.
orderReceivableTwdcancellationFeePendingcancellationFeeTwdrefundFeesTwdCompleted administrative fees. Excludes bank fees.
percentageFeeTwdfixedAdminFeeTwdchangeFeeTwdunclassifiedFeeTwdUnclassified historical fees remain separate.
refundRemainingTwdcancelledCash已取消訂單的對帳現金(issue 1974):保留款轉移與現金收退分開算。 未取消的訂單為 null。
collectedTwd已收現金:客人實際付進本單的錢,不含保留款轉入。
heldCashTransferredTwd轉成保留款的淨額:保留款轉出減轉入。這筆錢還在保留款,或已折抵到別張訂單。 負數表示本單是用保留款折抵的(轉入多於轉出)。
customerRefundedTwd已退給客人的現金:退款、刷退與沖正,不含保留款轉出與匯款手續費。
cancellationFeeDueTwd客人還欠的退改費。應收不含這筆。0 = 沒有欠款。
kindid訂單 id(前綴 `ord_`)。
orderNumber人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。
bookingState預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。
paymentState付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。
refundState退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。
grossReceivableTwd應收(TWD 整數,派生自應收分類帳)。
collectedTwd收到現金(TWD 整數,派生),含保留款轉入。已取消訂單對帳讀 `accounting.cancelledCash.collectedTwd`,那個數字不含保留款轉入(issue 1974)。
customerCashAppliedTwd客戶現金淨套用(收款減已退現金,TWD 整數,派生)。
refundableCashTwd可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。
outstandingTwd未收(應收減客戶現金淨套用,TWD 整數,派生)。
partySize參團人數(tour 訂單)。
createdAt訂單建立時間。
notes訂單備註(未填 → null)。
userId下單客戶的 user id(同庫 user 表)。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名(is_primary,未登記 → null)。
primaryTravelerPhone主要旅客電話(未登記 → null)。
tripId行程 id(tour 訂單經梯次反查;lodging 為空字串)。
tripTitle行程 / 產品標題。
tripShortName行程內部簡稱(issue 1414);未填或訂房訂單為 null。
tripSlug行程 slug。
departureId梯次 id(tour 訂單;lodging 為空字串)。
departureDate出發日 YYYY-MM-DD(lodging 為入住日)。
returnDate回程日 YYYY-MM-DD(lodging 為退房日)。
assignedToUserId派發給哪位業務的 user id(未派發 → null)。
assigneeName承辦業務顯示名(未派發 / 查無 → null)。
assignmentStatus派發狀態:unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間(未派發 → null)。
assignedByUserId執行派發者的 user id(未派發 → null)。
createdByUserIdS5: 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是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。
roomingStatus分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。
failoverFromOrderId備案訂單所對應的原訂單 ID。
isOverdue是否有已到期、尚未收齊的收款計畫。
receiptAllocationNeedsReorder收據分配要重排(issue 1942):公司收據加總超過應收。訂單列表 `?receipt=needs_reorder` 與工作台待辦同一個口徑。
total符合篩選的訂單總數(DISTINCT 訂單,非列數)。
page當前頁碼(從 1 起算)。
pageSize每頁筆數。
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
participationVersiondepartureChangesidparticipationVersionactorNamereasoncreatedAtsnapshotdocumentsagreementEnabledversioningReadyagreementCountagreementPendingagreementHistoryconsentslabelversionpendingretainedduepassportExpiryWarningsfingerprintcrossTrip選填sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdepartureprice_twdagency_price_twddeposit_modedeposit_amount_twddeposit_percentpromo_activepromo_price_twdpromo_agency_price_twdtripdirect_price_twdagency_price_twdprice_from_twddeposit_modedeposit_amount_twddeposit_percentdeposit_basisschema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。
unitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
basisstepN:每幾位旅客 / 每滿幾元。
unitTwd每次折多少(碼的折扣值)。
units折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource 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.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valueselfService選填repricingThe target fare at its current price. Same shape as a cross-trip quote, without answers.
sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdeparturetripunitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource 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.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valuefeetierdaysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
amountTwddescriptioncharge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。
surplusremitFeeTwdlottery選填sourceModetargetModestateBeforestateAfter`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.
placement選填failover選填Set when the backup failover made the change. A general target confirms the seat (`won`).
skippedBackup choices that the failover skipped before this one.
rankdepartureIdreasonnotFormed選填notFormedDepartureId選填hitRankRank of the backup choice that this step tries.
remainingDepartureIdsBackup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.
applicationKeyBeforeapplicationId選填Set on confirmation: the new application uses the departure change ID.
legacyChain選填effectiveCreditTwd選填policyTotalTwd選填refundDrafts選填participationVersionequipmentblockedrentalsrentalIdrentalCodedepartureIdrentStartDaterentEndDatereturnStatereconStatedeliveredAtdepositClearedAtrentTotalTwd租借單的租金與押金合計。只是租借單的事實,換梯不搬這些錢。
depositTotalTwdreplacesRentalIdreadyblockerlinesitemIdnamequantitycommittedQuantitypaymentWindowStartedAt選填sourceFingerprintrosterFingerprintsourceidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percenttargetidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percentarrangements選填roomFeeBeforeTwdroomFeeAfterTwdotherRoomOrderCountotherRoomFeeDeltaTwdotherRefundDraftTwdreleasedRoomCountreleasedPretripStayCounttaskstravelerIdkindlabelfingerprinttotalTwdunitPriceTwddiscountTwdchargeLinesidtypeamount_twddescriptiondepositTwdbalanceTwdbalanceDueAtreceiptsblockedreceiptsidmerchantOrderNostatusinvoiceNumberinvoiceTransNosubmittedoperationPendinglastErrortourNametourNotourDatetotalAmtTwdupdatedAtresolutiontargettourNametourNotourDatetotalAmtTwdcollectedTwdreturnedTwdpaidRefundFeesTwdcustomerCashAppliedTwdoutstandingTwdrefundHeadroomgrossReceivableTwd當前應收。
refundableCashTwd可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。
assessedCancellationFeeTwd此實收單保留的退改費;舊資料沿用人工核算基準。
openRefundGrossTwd同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。
openRefundCount同單其他未執行退款的張數。
openReceivableReductionTwd同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。
carriedToLiveBackupsTwd已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。
assessmentPending人工核算單、退改費尚未核算。
baseTwd額度基準 = 可退現金 − 上面三項扣減,下限 0。
surplusDisposition選填retainedFundId選填overpaymentRefundTwddepositOutstandingTwdnextPaymentPurposenextPaymentTwdmoneyFingerprintrefundDraftId選填legacyChaincollectedTwdreturnedTwdpaidRefundFeesTwdeffectiveCreditTwdrefundableTwdopenRefundCountnodesorderIdorderNumbercollectedTwdreturnedTwdopenRefundCountarrangementsCurrent arrangement tasks after a departure change. Null means this order has no departure change.
departureIdtaskstravelerIdkindlabelreceiptAllocation收據分配表:一列對一張收據。公司收據列(`isOrderer: false`,有統編)依序在前,最後一列固定是 訂購人個人收據(`isOrderer: true`,沒有統編,金額=應收減公司收據加總,最低 0;0 表示不開)。 `needsReorder: true` 表示收據分配要重排:公司收據加總超過應收,`excessTwd` 是超過的金額。 `personalEmail` 是訂購人個人收據另填的寄送 Email,null 表示用訂購人帳號的 Email。
rows公司收據列依序,最後一列固定是訂購人個人收據。
isOrderertrue = 訂購人個人收據(沒有統編、金額由系統算)。
buyerNamebuyerUbn統編。訂購人個人收據為 null。
emailamountTwdreceivableTwd推導時用的應收。
companyTotalTwdneedsReorder收據分配要重排:公司收據加總超過應收。應收變少時先從個人收據列扣,扣到 0 還超過 就是這個狀態。
excessTwd公司收據加總超過應收的差額。沒有超過時為 0。
personalEmailactions訂單可行動作。每個動作是 `{ ok: true }`(部分動作另帶欄位,例:`cancel.path`、 `createRefund.headroom`)或 `{ ok: false, reason }`。`reason` 沿用對應寫入端點的 原因碼;`forbidden` 表示呼叫者沒有該動作的權限。
cancel`cancelOrder` / `cancelLodgingBooking` / `cancelFailoverChildOrder` / `cancelLotteryLostOrder`(依 `path`)。`lottery_lost` 的權限是 lottery.manage 加抽籤模組。
transferDepartureGeneral departure change with completed payment records. The selected target is checked during preview and confirmation.
adjust掛帳 / 折讓 / 沖正(`applyManualAdjustment` / `reverseChargeLine`)。
editTravelers旅客新增 / 編輯 / 移除(`addTraveler` / `updateTraveler` / `removeTraveler`)。名單凍結中 回 `EDIT_WINDOW_CLOSED` 加 `rosterFreezeUnlockable: true`(見 `TravelerEditAvailability`)。
editRooming分房需求登記(`updateRoomingPreference`)。
markPaid手動登記收款(`markOrderManuallyPaid`)。`settled`:寫入端回冪等成功、不入帳。
collectCancellationFee選填Record actual cancellation fee collections without reopening the booking.
balancePayment補尾款連結 / 繳款單(`prepareBalancePayment`,可收分期的 `balance_link` 收款入口)。
balanceSlip寄尾款繳款單(`sendBalanceSlipInTx`,可收分期的 `balance_slip` 收款入口)。訂金制同 `balancePayment`,全額單收全額列的餘額(issue 1522)。
payLink自填金額付款連結(`issueOrderPayLink`,可收分期的 `pay_link` 收款入口,issue 1487)。已付訂金時同 `balancePayment`; 訂金未付時掛目前這一期,`remainingTwd` 是這一期的餘額。
createRefund建立退款。只看權限;金額上限與「為何是 0」在 `headroom`(`describeNoHeadroom`), 與建立 / 送審 / 標記已付三道 guard 讀同一份可退額度。
splitTraveler拆出旅客(`splitTraveler`)。`otherDepartures`:能不能拆到別梯;整單不能換梯時只能同梯另開單。 名單凍結時拆到別梯要帶 `acknowledgeRosterFreeze: true`(見 `editTravelers.rosterFreezeUnlockable`)。旅客、款項與目標梯次的資格在寫入端鎖內重驗。
withdrawTraveler旅客退出(`withdrawTraveler`,issue 2056):非主要旅客退出,系統減席、減應收、收取消費、 退款或保留。`rosterFreeze`:出發前 6 天內,要帶 `acknowledgeRosterFreeze: true`。 不能做時 `reason` 是原單的守門(款項、附加費用、抽籤未中籤等),按鈕旁照原因說明。
heldCashTransfer用保留款折抵,本單是轉入目標(`transferHeldCash`)。來源單在寫入端鎖內重驗。
reduceReceivable直接減少應收:折讓、沖正原始應收、跨行程換梯的負數調整(`assertDirectAdjustmentAllowed`)。 「折讓必須經核准」開啟時,沒有核准權的人回 `APPROVAL_REQUIRED`。
requestDiscount手動少收申請(`requestManualDiscount`)。
decideDiscount核准或拒絕手動少收申請(`decideManualDiscount`)。核准權與 `canApproveAllowance` 同一條。
requestFeeWaiver申請減免退改費(`requestCancellationFeeWaiver`,#1621)。權限同建立退款單。
decideFeeWaiver核准或拒絕退改費減免。核准權同少收申請(`canApproveAllowance`+order.adjust)。
revokeReceipt撤銷或申請撤銷人工收款(`revokeManualReceipt` / `requestManualReceiptRevocation`)。只看權限, 不看這張單有沒有人工收款登記;逐筆的撤銷條件在寫入端。
submitRefund退款草稿送審(`submitRefund`)。退款單本身的狀態閘在寫入端。
cancelRefund退款草稿作廢(`cancelRefund`)。
approveRefund核准退款(`approveRefund`)。
rejectRefund駁回退款(`rejectRefund`)。
markRefundPaid標記退款已付與綠界刷退(`markRefundPaid`)。
assign派發:待審派發單走首次派發(`assignOrder`,order.assign),其他單走重派 (`reassignOrder`,order.reassign)。
updateOrder訂單層的其他更新(order.update):解除實名占用、代登登山紀錄、護照、同意書、 重寄信件、跨行程換梯報價。
reviewScreening審核登山資格(screening.review)。
manageAgreement管理旅遊契約(tour_agreement.manage)。
viewAgreementEvidence檢視旅遊契約簽署證據(tour_agreement.evidence)。
revealPii顯示證號全碼、檢視護照影本(order.reveal_pii)。
readConversation讀訂單對話(order_conversation.read)。
editReceiptAllocation修改收據分配表(`saveOrderReceiptAllocation`,issue 1942)。小編(order.update)與會計 (invoice.issue)都能改,訂單狀態不限制。
accountingDisplay accounting amounts. The cash ledger remains unchanged.
orderReceivableTwdcancellationFeePendingcancellationFeeTwdrefundFeesTwdCompleted administrative fees. Excludes bank fees.
percentageFeeTwdfixedAdminFeeTwdchangeFeeTwdunclassifiedFeeTwdUnclassified historical fees remain separate.
refundRemainingTwdcancelledCash已取消訂單的對帳現金(issue 1974):保留款轉移與現金收退分開算。 未取消的訂單為 null。
collectedTwd已收現金:客人實際付進本單的錢,不含保留款轉入。
heldCashTransferredTwd轉成保留款的淨額:保留款轉出減轉入。這筆錢還在保留款,或已折抵到別張訂單。 負數表示本單是用保留款折抵的(轉入多於轉出)。
customerRefundedTwd已退給客人的現金:退款、刷退與沖正,不含保留款轉出與匯款手續費。
cancellationFeeDueTwd客人還欠的退改費。應收不含這筆。0 = 沒有欠款。
kind訂單種類(kind-agnostic 外殼)。'tour' 用既有 tour 區塊(梯次/分房/登山審核); 'lodging' 隱藏 tour-only 區、改顯示住宿 header(見 `lodging`)。共用的金流/旅客/ 派發/同意書區塊兩者皆 order-scoped 通用。
id訂單 id(前綴 `ord_`)。
orderNumber人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。
bookingState預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。
paymentState付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。
refundState退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。
grossReceivableTwd應收(TWD 整數,派生自應收分類帳)。
collectedTwd收到現金(TWD 整數,派生),含保留款轉入。已取消訂單對帳讀 `accounting.cancelledCash.collectedTwd`,那個數字不含保留款轉入(issue 1974)。
customerCashAppliedTwd客戶現金淨套用(收款減已退現金,TWD 整數,派生)。
refundableCashTwd可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。
outstandingTwd未收(應收減客戶現金淨套用,TWD 整數,派生)。
partySize參團人數(tour 訂單)。
createdAt訂單建立時間。
notes訂單備註(未填 → null)。
userId下單客戶的 user id(同庫 user 表)。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名(is_primary,未登記 → null)。
primaryTravelerPhone主要旅客電話(未登記 → null)。
tripId行程 id(tour 訂單經梯次反查;lodging 為空字串)。
tripTitle行程 / 產品標題。
tripShortName行程內部簡稱(issue 1414);未填或訂房訂單為 null。
tripSlug行程 slug。
departureId梯次 id(tour 訂單;lodging 為空字串)。
departureDate出發日 YYYY-MM-DD(lodging 為入住日)。
returnDate回程日 YYYY-MM-DD(lodging 為退房日)。
assignedToUserId派發給哪位業務的 user id(未派發 → null)。
assigneeName承辦業務顯示名(未派發 / 查無 → null)。
assignmentStatus派發狀態:unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間(未派發 → null)。
assignedByUserId執行派發者的 user id(未派發 → null)。
createdByUserIdS5: 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是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。
roomingStatus分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。
failoverFromOrderId備案訂單所對應的原訂單 ID。
isOverdue是否有已到期、尚未收齊的收款計畫。
receiptAllocationNeedsReorder收據分配要重排(issue 1942):公司收據加總超過應收。訂單列表 `?receipt=needs_reorder` 與工作台待辦同一個口徑。
cancellationFeeTwd取消時公司留下的錢:退改費加上已付、不退的換梯手續費(customer-cancellation §8.9)。 NULL = 尚未核算,0 = 已核算且扣 0;兩者不可互換。
cancellationChangeFeeTwd`cancellationFeeTwd` 裡屬於已付換梯手續費、不退的部分(customer-cancellation §8.9)。 退改費 = `cancellationFeeTwd` − 這筆。null = 沒有。
administrativeFeeItems已核准的退改費減免合計(#1621)。`cancellationFeeTwd` 已是減免後的數字。0 = 沒有減免。
amountTwdincomeDatereasoncancellationFeeTierdaysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
cancellationIncomeDatepaidRefundRemitFeesTwdcancellationFeeWaivedTwdstaffNote承辦備註(issue 1659,`orders.staff_note`)。只給後台;null = 沒有備註。
cancellationRefundPendingcancellationMoney取消單現金與未執行退款摘要。
openRefundCount未執行退款單張數。
openRefundAmountTwd未執行退款單的實際退款金額合計。
openRefundAdminFeesTwd未執行退款單的**行政手續費**合計(`refunds.admin_fee_twd`)。與匯款手續費分成兩欄,顯示面 才叫得出名字 —— 合併成一個「手續費」會把這筆行政費講成匯款費。
openRefundRemitFeesTwd未執行退款單的**匯款手續費**合計(`refunds.remit_fee_twd`;spec 稱轉帳費,§3.4)。
retainedCashTwd可退現金扣退改費;無未執行退款單且退改費已核算時,與保留款帳同口徑。
uncoveredCashTwd未執行退款單沒蓋到的可退現金(issue 2055)。未取消的訂單與沒有未執行退款單時是 0。 大於 0 時要補開退款,工作台「多付待處理」也計入。
heldCashAppliedTo本單的錢折抵到的其他訂單(issue 1974):直接轉到別張訂單,或經本單建立的保留款折抵。 折抵回本單的不列。未取消的訂單為空陣列。
orderIdorderNumberamountTwdheldCashRefundedTwd從本單保留款退給客人的金額。
heldCashRefundFeesTwd從本單保留款退款時,已認列的行政手續費與匯款手續費。
tripIsOverseas行程是否出國(`trips.is_overseas`;lodging 為 false)。旅客編輯器據此顯示英文姓名 / 國籍欄(#459)。
tripCancellationFeeTiers行程自己的退改階梯(`trips.cancellation_fee_tiers` 解析後);null = 未覆寫,沿用租戶預設。 實際生效的階梯由呼叫端用 `resolveFeeTiers` 合成,與取消時同一個優先順序。
agencyPaymentDueDate客戶分類:同業單(`orders.agency_id`)帶同業名稱;直客單為 null。
agencyidnamecontactName同業主檔的聯絡窗口(#1782)。訂單頁顯示「聯絡窗口」,訂購人不變。
phoneconsentConfirmed「同業已代為取得旅客同意」的勾選(#1479)。沒有勾選時為 null。
atbyNamepdpaManualSignedPDPA 同意書有人工標記已簽(舊系統或紙本,#1913)。進度條據此不寫「已簽署」。
departureLabel梯次標籤 / 副標(issue 509 ①;lodging 為 null)。訂單頁的「梯次」欄接在日期後顯示。
lodginglodging 住宿 header(房型/住期/房數/人數);tour 為 null。
propertyNamepropertySlugroomTypeNamecheckIn入住日 YYYY-MM-DD。
checkOut退房日 YYYY-MM-DD(不含當晚)。
unitsguestCounttravelers旅客名單(含 PII 遮罩欄;主要旅客排前)。
id旅客 id(前綴 `trv_`)。
fullName旅客姓名。
idNumberMask遮罩碼(jsonb→mask,零解密);NULL = 未填。全碼走 reveal action(Task 7)。
passportNoMask護照號碼遮罩碼(零解密);NULL = 未填。全碼走 order-scoped reveal。
birthDate生日 YYYY-MM-DD(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
lineIdLINE ID(未填 → null)。明文。
lineDisplayNameenglishName英文姓名(#459,海外團;未填 → null)。明文,已 normalize 大寫。
nationality國籍(#459,海外團;未填 → null)。明文。
passportExpiryDate護照效期(#609,海外團;未填 → null)`YYYY-MM-DD`。明文 date 欄。
emergencyContactName緊急聯絡人姓名(未填 → null)。
emergencyContactPhone緊急聯絡人電話(未填 → null)。
isPrimary是否為主要旅客(訂單聯絡人)。
gender性別(分房硬約束 + 顯示):'male'|'female'|'other'|null。明文。
roomPreference分房房型偏好(下單登記)。
roommatePref指定房友 / 特殊需求自由文字。
diet飲食需求(葷素)明文;null = 未填。非 PII,不走 reveal。
medicalNotes醫療 / 過敏 / 病史備註明文;null = 未填。非 PII,不走 reveal。
address通訊地址(未填 → null)。
roomLabel團控已排房號的房間 label(null = 待團控分房)。
chargeLines應收分類帳(itemized)。
id應收明細列 id。
type應收類型:base(原始價)/ room_upgrade(房升補款)/ adjustment / failover_deposit_credit 等。
amountTwd金額(TWD 整數,signed;credit / 沖銷為負)。
description明細說明文字。
sourceType來源:system(系統派生)/ manual(人工登錄)等。
reversesChargeLineId若為沖銷列,指向被沖銷的應收明細列 id(否則 null)。
createdByUserId開立這筆費用列的使用者 id;系統派生或匯入列為 null。
createdAt建立時間。
transactions現金分類帳。
id現金交易列 id。
direction金流方向:in(收款)/ out(退款、扣款、沖銷)。
type交易類型:payment / refund / chargeback / reversal。
amountTwd交易金額(TWD 整數,正值)。
feeTwd金流商手續費(TWD 整數)。
netTwd淨額 = amount − fee(TWD 整數)。
provider金流商:manual / ecpay / test 等。
paymentChannel收款通路與付款方式。缺少線上付款方式時明確標示未知。
providerTradeNo金流商交易序號(manual 入帳可能為 null)。
merchantTradeNoThe merchant order reference of this transaction's payment attempt.
moneyReceiptIdPublic receipt ID for a proven money-core binding. Unbound historical rows retain null.
refundId若屬退款,指向 refunds 列 id(否則 null)。
bankReference銀行參考號:手動收款是客人的匯款後五碼,退款是匯款憑證號(未填為 null)。
remittanceId同源匯款關聯鍵:這列來自一筆拆到多張訂單的匯款時非 null,同一筆匯款的各列共用同一個值。
registrationId登記收款的批次鍵(#1411):撤銷人工收款時,原收款與反向紀錄共用同一個值。
bankCreditedOn入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填,其他為 null。
overTheCounter臨櫃存款(沒有末五碼)。
receivingAccountName收款帳戶顯示名稱(未歸戶為 null)。
transferCounterpartOrderId保留款轉移(`type='transfer'`,issue 1407)的對方訂單:轉出列指向目標單,轉入列指向 來源單。其他列為 null。
transferCounterpartOrderNumber對方訂單編號(同上)。
transferActorName執行這次保留款轉移的員工名稱(取自稽核紀錄;其他列為 null)。
occurredAt交易發生時間。
schedules收款計畫(current + historical)。
id收款計畫列 id。
purpose用途:full(全額)/ deposit(訂金)/ balance(尾款)/ adjustment(補款)。
targetAmountTwd應收目標金額(TWD 整數)。
status計畫狀態:open(未收齊)/ satisfied(已收齊)。
appliedTwd已套用到此列的現金(H3 唯一基準 `appliedCashForSchedule`;含 replaces 鏈)。
dueAt到期日(null = 未設)。
sequence排序序號(deposit → balance → adjustment)。
intents付款意圖(+ 最新 attempt)。
idpurposeamountTwdstatusscheduleIdinvalidationReasonReason for closing this checkout. departure_change permits a verified late payment.
invalidatedAmountTwdOriginal checkout amount in TWD when the intent became invalid.
attemptProviderattemptMethodattemptStatusbankCodevirtualAccountpayExpireAtrefunds退款工作流。
idrefundNumberstatusrefundKindamountTwdmethodreasoncreatedAtpaidAtexecutionMethod執行方式:chargeback 刷退 / remit 匯出;未定為 null(customer-cancellation §3.4)。
gatewayExecutionMode選填remitFeeTwd轉帳費(按單一次;remit 才有值)。承辦核放時可調降。
splitGroupId拆單組(#1406):同一筆退款拆成刷退+匯款時,各張共用。null = 沒有拆單。
gatewayLocked原路退刷 claim 已佔但無成功紀錄 = DoAction 結果不明,退款單被鎖住(mark-paid 一律 回 GATEWAY_IN_FLIGHT_OR_UNKNOWN)。判準取 clearRefundGatewayClaim 的 NOT_LOCKED 守衛 (別在 UI 端重刻)再加狀態閘:已 paid / cancelled 的殘留 claim 不該露出解鎖入口。
gatewayNeedsReview近 90 天已完成帳務且明確記錄自動退刷降級,供對帳辨識;不提供重試入口。
payee收款人四欄(匯款單才有值)。付款前承辦可改(issue 1698)。含完整帳號:`/api/v1` 對沒有 `refund.create` 權限的呼叫者回 null,和後台訂單頁的顯示條件相同。
accountNamebankCodebranchCodeaccountNumberconsentskindkindLabel自訂種類的名稱(#586);系統種類為 null,由畫面依 `kind` 查標籤。
versionsignedAtsignerName送出的帳號。逐旅客的自訂同意書是代簽人(訂購人)。
travelerName被代簽旅客的姓名;訂單層簽署為 null。旅客列移除後也是 null(紀錄本身仍在)。
travelerId被代簽旅客的 id(無 FK,旅客移除後仍保留作證據)。
ipAddressauditLogidactionactorUserIdactorUserNamemetadataipAddresscreatedAtorderDiscountcodeSnapshotoriginalTotalTwddiscountTwdprofitShareTwdprofitSharePayeeSnapshottoko 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 護照號碼。
value解密後的證件明碼;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回應欄位 · data
orderId新建立訂單的 ID(ord_ 前綴)。
orderNumber訂單編號(租戶內流水序號,對外顯示用)。
waitlistedtrue = 梯次額滿,依 waitlistIfSoldOut 建成候補單:不佔名額、遞補前不能付款。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
warnings建單成功、但有資料沒存時的提醒;沒有時為空陣列。
codeclimbing_records_skipped:旅客未填證件,代填的登山經歷沒有儲存。
message給人看的提醒文字。
travelers沒存的旅客:index 是 travelers 的位置(從 0 起算),skippedCount 是沒存的筆數。
index旅客在輸入 travelers 的位置,從 0 起算。
fullName旅客姓名(輸入值去掉前後空白)。
skippedCount這位旅客沒存的登山經歷筆數。
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回應欄位 · data
idempotenttrue = 此請求已入帳或訂單已結清,本次未重複入帳。
collectedTwd本次入帳金額;冪等重送為 0。
customerCashAppliedTwd入帳後已收現金淨額。
outstandingTwd入帳後待收餘額。
paymentState入帳後付款狀態。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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回應欄位 · data
ok固定為 true:訂單已取消(座位釋出、booking_state 轉 cancelled)。
refundsorderIdorderNumberrefundIdrefundNumberamountTwdremitFeeTwd選填retentionDeferredtrue = 回訪來源尚未同步,每日排程會補做;取消本身已完成。
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回應欄位 · data
ok固定為 true:訂單金額調整已套用。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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回應欄位 · data
ok固定為 true:訂單已沖銷(沖回應收與已認列項)。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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回應欄位 · data
id退款單 id(前綴 `rfnd_`)。
refundNumber人類可讀退款單號。
status退款工作流狀態: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回應欄位 · data
ok固定為 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回應欄位 · data
ok固定為 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回應欄位 · data
ok固定為 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回應欄位 · data
ok指令已處理;pending 或 unknown 不代表已退款。
gatewaypending:已受理;unknown:結果不明;succeeded:已確認個別退款;not_applicable:非刷退或既有已付紀錄。
skipReason新執行不降級記帳;此相容欄位為 null。
providerRefundNo已確認的個別退款編號;未完成時為 null。
retentionDeferredtrue = 回訪來源尚未同步,每日排程會補做;退款帳務本身已完成。
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回應欄位 · data
ok固定為 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回應欄位 · data
ok固定為 true:訂單已指派承辦。
idempotenttrue = 原提交已完成,或受派者相同,本次沒有再次派發。
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回應欄位 · data
ok固定為 true:訂單已改派承辦。
idempotenttrue = 原提交已完成,或受派者相同,本次沒有再次派發。
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回應欄位 · data
ok固定為 true:批次指派已執行。
assignedCount成功指派的訂單筆數。
skippedCount略過的訂單筆數(如已指派或不在可指派範圍)。
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回應欄位 · data
ok固定為 true:名單複核結果已登錄。
followUpState處置後追蹤狀態;退費或核可為 null。
emailSent通知已加入寄送佇列;false 包含未選範本或寄送失敗。
toko orders review-screening '<id>' --decision approve{
"ok": true,
"data": {
"ok": true,
"followUpState": "…",
"emailSent": true
}
}toko orders resolve-screening-follow-up客人回覆並完成處置後,結束本單資格審核追蹤
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok固定 true:本單的待回覆審核追蹤已完成。
toko orders resolve-screening-follow-up '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko orders balance-link產生/重用尾款付款連結(回待補金額;owner-scope)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true:尾款付款連結已產生。
amountTwd本次尾款金額(TWD 整數)。
scheduleId對應的收款計畫 ID。
toko orders balance-link '<id>'{
"ok": true,
"data": {
"ok": true,
"amountTwd": 0,
"scheduleId": "…"
}
}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回應欄位 · data
ok固定為 true:旅客已新增至訂單。
travelerId新建立旅客的 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回應欄位 · data
ok固定為 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回應欄位 · data
ok固定為 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回應欄位 · data
ok固定為 true:旅客分房設定已更新。
toko orders rooming-pref '<orderId>' '<travelerId>'{
"ok": true,
"data": {
"ok": true
}
}toko orders stats訂單 KPI 統計
參數
--json回應欄位 · data
pendingPayment待付款訂單數(未取消 / 未完成 / 未退款且 payment_state=unpaid)。
depositPaid已付訂金訂單數(payment_state=deposit_paid)。
paid已收齊訂單數(payment_state in paid/overpaid)。
cancelled已取消訂單數(booking_state=cancelled)。
refunded有退款的訂單數(refund_state in refunded/partially_refunded)。
completed已完成訂單數(booking_state=completed)。
thisMonthPaidTwd本月實收現金(payment_transactions direction=in 加總,TWD 整數)。
thisMonthNewOrders本月新建訂單數。
thisMonthCancelled本月取消訂單數(依 `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符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。
accountingDisplay accounting amounts. The cash ledger remains unchanged.
orderReceivableTwdcancellationFeePendingcancellationFeeTwdrefundFeesTwdCompleted administrative fees. Excludes bank fees.
percentageFeeTwdfixedAdminFeeTwdchangeFeeTwdunclassifiedFeeTwdUnclassified historical fees remain separate.
refundRemainingTwdcancelledCash已取消訂單的對帳現金(issue 1974):保留款轉移與現金收退分開算。 未取消的訂單為 null。
collectedTwd已收現金:客人實際付進本單的錢,不含保留款轉入。
heldCashTransferredTwd轉成保留款的淨額:保留款轉出減轉入。這筆錢還在保留款,或已折抵到別張訂單。 負數表示本單是用保留款折抵的(轉入多於轉出)。
customerRefundedTwd已退給客人的現金:退款、刷退與沖正,不含保留款轉出與匯款手續費。
cancellationFeeDueTwd客人還欠的退改費。應收不含這筆。0 = 沒有欠款。
kindid訂單 id(前綴 `ord_`)。
orderNumber人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。
bookingState預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。
paymentState付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。
refundState退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。
grossReceivableTwd應收(TWD 整數,派生自應收分類帳)。
collectedTwd收到現金(TWD 整數,派生),含保留款轉入。已取消訂單對帳讀 `accounting.cancelledCash.collectedTwd`,那個數字不含保留款轉入(issue 1974)。
customerCashAppliedTwd客戶現金淨套用(收款減已退現金,TWD 整數,派生)。
refundableCashTwd可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。
outstandingTwd未收(應收減客戶現金淨套用,TWD 整數,派生)。
partySize參團人數(tour 訂單)。
createdAt訂單建立時間。
notes訂單備註(未填 → null)。
userId下單客戶的 user id(同庫 user 表)。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名(is_primary,未登記 → null)。
primaryTravelerPhone主要旅客電話(未登記 → null)。
tripId行程 id(tour 訂單經梯次反查;lodging 為空字串)。
tripTitle行程 / 產品標題。
tripShortName行程內部簡稱(issue 1414);未填或訂房訂單為 null。
tripSlug行程 slug。
departureId梯次 id(tour 訂單;lodging 為空字串)。
departureDate出發日 YYYY-MM-DD(lodging 為入住日)。
returnDate回程日 YYYY-MM-DD(lodging 為退房日)。
assignedToUserId派發給哪位業務的 user id(未派發 → null)。
assigneeName承辦業務顯示名(未派發 / 查無 → null)。
assignmentStatus派發狀態:unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間(未派發 → null)。
assignedByUserId執行派發者的 user id(未派發 → null)。
createdByUserIdS5: 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是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。
roomingStatus分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。
failoverFromOrderId備案訂單所對應的原訂單 ID。
isOverdue是否有已到期、尚未收齊的收款計畫。
receiptAllocationNeedsReorder收據分配要重排(issue 1942):公司收據加總超過應收。訂單列表 `?receipt=needs_reorder` 與工作台待辦同一個口徑。
total符合篩選條件的總筆數。
truncated是否因達安全上限而截斷(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回應欄位 · data
ok固定為 true:訂單已由當前承辦認領。
toko orders claim '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko orders message-preview預覽訂單罐頭訊息
參數
<id>位置參數 · 必填--template <value>訊息範本 ID(line 或 email 通道皆可)
--json回應欄位 · data
channel範本通道:line 或 email。
subject代入本訂單變數後的標題(email 為信件主旨)。
body代入本訂單變數後的內文。
missingVars範本引用但本訂單沒有值的變數名;成品裡仍是 `{{變數}}` 原樣,貼出前要手動處理。
toko orders message-preview '<id>'{
"ok": true,
"data": {
"channel": "…",
"subject": "…",
"body": "…",
"missingVars": [
"…"
]
}
}toko orders discount-preview依建單定價試算折扣
參數
--data <json>--jsontoko orders discount-preview{
"ok": true,
"data": "…"
}toko orders quote試算 K 單金額(含訂金與尾款)
參數
--data <json>--json回應欄位 · data
quote金額試算:單價、小計、折扣、總計、實際付款方案與訂金 / 尾款。
unitPriceTwdpartySizesubtotalTwd折前小計 = 單價 × 人數。
discountTwdtotalTwd折後總計,也就是訂單應收。
paymentPlan實際採用的付款方案:訂金方案拆不出尾款時改成全額。
depositDueTwdbalanceDueTwddiscount優惠碼結果: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收款帳戶 ID(標記已退款時當出款帳戶帶入)。
code帳戶代碼(租戶自訂短碼)。
displayName顯示名稱(下拉選項用)。
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回應欄位 · data
oktoko 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回應欄位 · data
deliverytoko 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回應欄位 · data
oknewAgreementIdtoko 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回應欄位 · data
oktoko orders agreements-revoke '<id>' '<agreementId>'{
"ok": true,
"data": {
"ok": true
}
}toko orders agreements-sign-link執行 orders/[id]/agreements/[agreementId]/sign-link
參數
<id>位置參數 · 必填<agreementId>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
okurlexpiresAttoko orders agreements-sign-link '<id>' '<agreementId>'{
"ok": true,
"data": {
"ok": "…",
"url": "…",
"expiresAt": "…"
}
}toko orders agreements-generate執行 orders/[id]/agreements/generate
參數
<id>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
skipped整單層級略過原因;null = 有處理逐旅客。
issuedrevokedfailurestravelerIdtravelerNamereasonvarsmissingTemplateTypes這張單上「行程類型對得到種類、但該種類沒有範本」的契約種類(#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[]
idorderIddepartureIddepartureDate梯次出發日(ISO date);一張單多梯時用來標示這份契約屬哪一梯。
participationVersion選填isCurrent選填travelerIdtravelerNamestatustemplateVersioncontractDateprovidedAttokenExpiresAtsignedAtsignerNamesignerIparticle32AgreedsigningPayloadevidenceSha256contentSha256hasPdfdeliveredAtdeliveryAddressrevokedAtrevokeReasonsupersededAt已由新版取代的時間、理由與承辦補充(#2054);非 superseded 列為 null。
supersedeReasonsupersedeNotesupersededById取代這一份的新契約 id(superseded 列才有)。
supersedesId這一份取代的舊契約 id(重新簽署產生的新列才有)。
lastSyncedAtsync 最後檢視時間(排程漂移訊號的基準)。
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回應欄位 · data
okchosentoko 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回應欄位 · data
okheadOrderId鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。
refunds實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。
orderIdorderNumberrefundIdrefundError需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。
refundTotals本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。
amountTwdadminFeeTwdremitFeeTwdfilingFee逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。
totalTwd逐旅客費率的加總。
lines逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。
seqfeeTwd這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。
travelerName送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 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回應欄位 · data
oknotifiedheadOrderId鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。
refunds實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。
orderIdorderNumberrefundIdrefundError需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。
refundTotals本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。
amountTwdadminFeeTwdremitFeeTwdfilingFee逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。
totalTwd逐旅客費率的加總。
lines逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。
seqfeeTwd這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。
travelerName送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 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回應欄位 · data
retentionDeferredtrue = 回訪來源或期間尚未同步,每日排程會補做;安置本身已完成。
okorderIddepartureChangeIdtoko 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回應欄位 · data
oktoko 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回應欄位 · data
okemailSentTrue when this call adds a queue entry. Delivery is still pending.
outcomeThe 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回應欄位 · data
oktoko 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回應欄位 · data
okorderIdpreview選填Present after a preview. Send its previewToken on the confirmation.
previewTokensourceOrderIdtravelerIdtravelerNamesourceDepartureIdtargetDepartureIdsameDepartureunitPriceTwdmoneysourceReceivableBeforeTwdsourceReceivableAfterTwdnewReceivableTwdsuggestedTransferTwd系統建議值:依應收比例分配原單的有效已付款(§3.5)。
maxTransferTwdtransferTwdtransferOverriddensourceOverpaymentTwd拆出後原單多收、要開溢收退款草稿的金額。
keptOnSourceTwd留在原單、不分攤的折扣、人工調整與房型升等合計(§6 M2)。
discountTwdadjustmentTwdroomUpgradeTwdnewOrderSchedulesfirstPurposedepositTwdbalanceTwddepositOutstandingTwdnextPurposenextTwdnewOrderBalanceDueAtclears這位旅客目前在分房、同行組裡;拆出後清空。
roomcompanionGroupnewOrderId選填newOrderNumber選填splitId選填transferTwd選填refundDraftId選填Overpayment refund draft on the source order. null = no overpayment.
idempotent選填true = a retry of a completed request.
departureChange選填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回應欄位 · data
okorderIdpreview選填Present after a preview. Send its previewToken on the confirmation.
previewTokenorderIdtravelerIdtravelerNamedepartureIdshareTwd這位旅客的團費份額(成交單價;搬入舊單用每人單價)。
daysUntilDeparturetierdaysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
feeBasis命中級距連基準的人話(`成交總額的 80%`/`每人 NT$ 200`)。
tierFeeTwd階梯照章算出的取消費。
feeTwd取消費:照章金額,上限是這位旅客分到的已付款。減免前的金額。
waiverTwd減免金額。
waiverDirecttrue=減免當下生效;false=減免進少收待核,先照取消費全額退出。
netFeeTwd實收取消費:直接生效的減免已扣掉。
paidShareTwd這位旅客分到的已付款(依應收比例)。
transferTwd轉到退出新單的錢:實收取消費加上可退金額。
refundableTwd可退金額(尚未扣退款單的轉帳費)。
receivableBeforeTwdreceivableAfterTwdoutstandingAfterTwd退出後原單還要收的錢。
sourceOverpaidAfterTwd退出後原單仍多收的錢。原單本來多收超過這位旅客的已付款時才大於 0;確認時在原單開溢收 退款草稿,與拆出相同(§3.5)。
rosterFrozen出發前 6 天內(名單凍結)。
lottery抽籤單:提醒入園證與保險名單要另外處理。
holdAvailable這張單能不能把可退金額轉成保留款。
clearsroomcompanionGroupwithdrawalId選填Withdrawal record ID.
withdrawalOrderId選填Cancelled order that holds the cancellation fee and the refund. Not in daily order lists.
feeTwd選填Cancellation fee that the company keeps.
refundableTwd選填Refundable amount before the remittance fee.
disposition選填Where the refundable amount went. null = nothing to refund.
refundIds選填Refund drafts on the withdrawal order.
retainedFundId選填Retained fund for the orderer, when disposition is keep.
waiver選填Fee waiver request. applied=false = waits for underpayment approval.
requestIdamountTwdappliedidempotent選填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回應欄位 · data
okorderIddepartureChangeId選填preview選填Includes current document requirements, retained consents, and passport expiry warnings.
canRetainSurplus選填arrangementsroomFeeBeforeTwdroomFeeAfterTwdotherRoomOrderCountotherRoomFeeDeltaTwdotherRefundDraftTwdreleasedRoomCountreleasedPretripStayCounttaskstravelerIdkindlabelfingerprintpreviewTokenpaymentWindowHoursexpiresAtdocumentsagreementEnabledversioningReadyagreementCountagreementPendingagreementHistoryconsentslabelversionpendingretainedduepassportExpiryWarningsfingerprintcrossTrip選填sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdepartureprice_twdagency_price_twddeposit_modedeposit_amount_twddeposit_percentpromo_activepromo_price_twdpromo_agency_price_twdtripdirect_price_twdagency_price_twdprice_from_twddeposit_modedeposit_amount_twddeposit_percentdeposit_basisschema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。
unitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
basisstepN:每幾位旅客 / 每滿幾元。
unitTwd每次折多少(碼的折扣值)。
units折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource 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.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valueselfService選填repricingThe target fare at its current price. Same shape as a cross-trip quote, without answers.
sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdepartureprice_twdagency_price_twddeposit_modedeposit_amount_twddeposit_percentpromo_activepromo_price_twdpromo_agency_price_twdtripdirect_price_twdagency_price_twdprice_from_twddeposit_modedeposit_amount_twddeposit_percentdeposit_basisschema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。
unitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
basisstepN:每幾位旅客 / 每滿幾元。
unitTwd每次折多少(碼的折扣值)。
units折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource 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.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valuefeetierdaysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
amountTwddescriptioncharge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。
surplusremitFeeTwdlottery選填sourceModetargetModestateBeforestateAfter`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.
placement選填failover選填Set when the backup failover made the change. A general target confirms the seat (`won`).
skippedBackup choices that the failover skipped before this one.
rankdepartureIdreasonnotFormed選填notFormedDepartureId選填hitRankRank of the backup choice that this step tries.
remainingDepartureIdsBackup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.
applicationKeyBeforeapplicationId選填Set on confirmation: the new application uses the departure change ID.
legacyChain選填effectiveCreditTwd選填policyTotalTwd選填refundDrafts選填participationVersionequipmentblockedrentalsrentalIdrentalCodedepartureIdrentStartDaterentEndDatereturnStatereconStatedeliveredAtdepositClearedAtrentTotalTwd租借單的租金與押金合計。只是租借單的事實,換梯不搬這些錢。
depositTotalTwdreplacesRentalIdreadyblockerlinesitemIdnamequantitycommittedQuantitypaymentWindowStartedAt選填sourceFingerprintrosterFingerprintsourceidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percenttargetidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percenttotalTwdunitPriceTwddiscountTwdchargeLinesidtypeamount_twddescriptiondepositTwdbalanceTwdbalanceDueAtreceiptsblockedreceiptsidmerchantOrderNostatusinvoiceNumberinvoiceTransNosubmittedoperationPendinglastErrortourNametourNotourDatetotalAmtTwdupdatedAtresolutiontargettourNametourNotourDatetotalAmtTwdcollectedTwdreturnedTwdpaidRefundFeesTwdcustomerCashAppliedTwdoutstandingTwdrefundHeadroomgrossReceivableTwd當前應收。
refundableCashTwd可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。
assessedCancellationFeeTwd此實收單保留的退改費;舊資料沿用人工核算基準。
openRefundGrossTwd同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。
openRefundCount同單其他未執行退款的張數。
openReceivableReductionTwd同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。
carriedToLiveBackupsTwd已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。
assessmentPending人工核算單、退改費尚未核算。
baseTwd額度基準 = 可退現金 − 上面三項扣減,下限 0。
surplusDisposition選填retainedFundId選填overpaymentRefundTwddepositOutstandingTwdnextPaymentPurposenextPaymentTwdmoneyFingerprintrefundDraftId選填retentionDeferred選填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[]
departureIdlabeltoko 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
quoteorderIdparticipationVersionsourceVersionquoteFingerprintquotedAtexpiresAtconfirmationAvailableTrue when this order can continue to the departure change preview.
sourcedepartureIdtripIdtitledatetargetdepartureIdtripIdtitledatepriceChannelpriceSourcepartySizeoriginalFareTwdtargetFareTwdoriginalDiscountTwdtargetDiscountTwdoriginalProfitShareTwdtargetProfitShareTwddiscountcodestatusreasonexistingLinesidtypedescriptionamountTwdcategoryadjustmentkindamountTwdreasonoriginalReceivableTwdtargetReceivableTwddifferenceTwdcollectedTwdreturnedCashTwdpaidRefundFeesTwdeffectivePaidTwdoutstandingTwdrefundableTwdoverpaymentRefundTwddepositTargetTwddepositOutstandingTwdbalanceOutstandingTwddepositDueAtbalanceDueAtNull when the target is a lottery departure: the due date is set at the win.
tasksblockerstoko 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回應欄位 · data
oktoko 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[]
idlabelgradeScoresystemGradeScorehasAlpineExperienceclimbedOndurationValue完成時間(自填,選填);未填兩欄皆 null。
durationUnitcreatedAttoko 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回應欄位 · data
okrecordIdtoko 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
orderIdorderNumbercustomerNametripTitleoutstandingTwdbookingStatepaymentStatetoko 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回應欄位 · data
retentionDeferredokidempotentremittanceIdordersorderIdorderNumbercollectedTwdcustomerCashAppliedTwdoutstandingTwdpaymentStatetoko 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梯次 id。
tripId所屬行程 id。
tripTitle行程名稱。
tripShortName行程內部簡稱(issue 1414);未填為 null。
hasPreTripNight行程有行前集合夜:出發日前一晚集合(trips.md §3)。
tripSlug行程公開頁網址代稱(slug)。
groupCode團號(可空)。
label梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);null = 無。
isPrivate不對外販售(issue 509 ①):前台藏、後台照建。
customerCancelPausedAt暫停客人自助取消的時間 ISO 字串(issue 1808);null = 未暫停。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(YYYY-MM-DD)。
capacity團位容量(總名額)。
bookedCount已佔位人數。
status梯次狀態(如 open 開放/closed 關閉)。
salesOpenAt排定的開賣時間 ISO 字串;null = 沒排程(trips.md §2.2a,issue 1643)。
salesOpenFailedReason自動開賣被擋下的原因;null = 沒失敗。
confirmedAt成團時間 ISO 字串;null = 尚未成團(group-confirmation §2,與 status 正交)。
minGroupSize行程層最低成團人數門檻;null = 未設門檻(不提示達標)。
allocationMode佔位模式:fcfs 先到先得/lottery 抽籤。
leaderNames已排主要隨團人員姓名(confirmed + tentative 皆列;空 = 未指派)。
assistantNames已排協作 / 助教姓名(空 = 未指派協作)。
nameBoundGuideNamesNames on assignments that require a reason for replacement or removal.
confirmedLeaderCount已確認(status='confirmed')的主要隨團人員人數;0 = 沒有確認的主要隨團人員(tentative 不算)。
confirmedGuideCount已確認(status='confirmed')的主要+協同人數合計(issue 1117 的「已派」)。
permitSwappedCount已確認指派中勾了「已換領」的人數(issue 1731)。
requiredGuideCount需要的隨團人員數;null = 未填(issue 1117)。
notes梯次備註(集合上下車點、代收註記…;null = 無)。
opNames承辦小編姓名;空陣列不代表本梯不需承辦。
opNotRequiredReason選填明確標記本梯不需承辦的原因;null = 未標記。
priceTwd定價(TWD)。
agencyPriceTwd同業/旅行社報價(TWD;未設為 null)。
promoActive是否有進行中的促銷價。
promoPriceTwd促銷價(TWD;無促銷為 null)。
promoAgencyPriceTwd同業促銷價(TWD;無促銷為 null)。
daysUntilDeparture距出發天數(負值表示已出發)。
salesClosePassed選填有效停止售票時間已過(同 `updateDepartureStatus` 的守衛)。true 時改回售票中一定被拒, 梯次總覽的「恢復售票」改成停用並寫原因(issue 1654)。省略視同 false。
travelerCount旅客總人數(未取消訂單的 party_size 加總)。
paidCount已付款人數(party_size 加總;不含取消)。
pendingCount未結清人數(未付/部分付/已付訂金;不含取消)= unpaidCount + balanceDueCount。
unpaidCount完全未付人數(payment_state = unpaid;不含取消)。
balanceDueCount待收尾款人數(已付部分或訂金、還沒付清:partially_paid / deposit_paid;不含取消)。
cancelledCount已取消人數(僅供參考,不計入總數)。
confirmedOrderCount已確認、還沒完成的訂單數(`booking_state = confirmed`,筆數不是人數)。結團把它們改成已完成。 狀態已完成的梯次這個值大於 0,代表梯次沒經過結團就變成已完成,要再結團一次。
ordersWithoutConsent尚未簽署同意書(PDPA)的訂單數。
codedRevenueTwd有折扣訂單的應收營收合計(TWD;排除取消/退款)。
discountTotalTwd折扣金額合計(TWD)。
profitShareTotalTwd利潤分潤金額合計(TWD)。
lottery梯次層抽籤結果:`result` 為 none(未送件)/pending(待抽籤)/waitlisted(備取中)/ won(已中籤)/lost(未中籤),`waitlistedCount` 為同梯還在備取的張數。先到先得梯次為 null。
resultwaitlistedCountlotteryWaitlistEnabled行程開了「抽籤結果含備取」(issue 1691):抽籤梯次才出現「備取」標記鍵。
stage生命週期階段。
metThreshold已達最低成團人數;門檻未設時為 false。
rooming分房進度;null = 這一梯不用分房(通鋪團或沒有房)。
roomCountassignedCounttotalTravelerstoko 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
todayhorizonrangerowssoftDatehardDatesourcedayMode梯次期限列存的 day_mode(產生或人工寫入當下解析出的有效規則)。距離單位:`workday` 算工作天, 其他模式(含 `month_same_day`)算日曆天。
hardDistancesoftDistanceurgencylotteryDraw期限日取自抽籤時程表時的時段與原抽籤日(lottery-schedule spec §3.5)。
slotStartslotEndfirstDrawDatelabeldepartureIdtripIdtripTitletripShortName行程內部簡稱(issue 1414);未填為 null。
groupCodedepartureDateopNames承辦小編姓名(依姓名排序);空陣列 = 未指派。
typeKeyanomalies`anomalies: false` 時恆為空陣列。
labeldepartureIdtripIdtripTitletripShortName行程內部簡稱(issue 1414);未填為 null。
groupCodedepartureDateopNames承辦小編姓名(依姓名排序);空陣列 = 未指派。
typeKeycountsoverduecriticalstartupcomingmissingHolidayYears未逾期的工作天事項「今天 → 硬 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**整單**會計應收(TWD,不是每人分攤)。同一張單的每一列都帶同一個數字。 未取消=訂單應收。已取消=`cancellationFeeTwd`+`refundFeesTwd`:取消時訂單應收 歸零,公司留下的是這兩筆錢。匯款費屬於已退,不含在應收內。 null=退改費尚未核算(見 `cancellationFeePending`)。
cancellationFeePendingtrue=已取消、退改費尚未核算、手上還有可退現金:整單應收還定不下來。
cancellationFeeTwd已取消單留下的退改費(整單)。未取消=null;尚未核算=null。
refundFeesTwdCompleted administrative fees. Excludes bank fees. 已取消單已執行退款的行政手續費(不含匯款手續費)(整單)。未取消=null。
percentageFeeTwdfixedAdminFeeTwdchangeFeeTwdunclassifiedFeeTwdUnclassified historical fees remain separate.
refundRemainingTwdtravelerId旅客 id。外部系統用它對人,不靠姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
travelerName旅客姓名。
phone聯絡電話。
email聯絡 Email。
isPrimary是否為該訂單的主要聯絡人(訂購人)。
gender性別(明文 enum-like):'male'|'female'|'other'|null(未填)。
birthDate生日 ISO `YYYY-MM-DD`;null = 未填。
diet飲食需求(葷素)明文;null = 未填。
medicalNotes醫療 / 過敏 / 病史備註明文;null = 未填。
specialNeeds「飲食 · 特殊需求」欄的合併顯示字串(diet + medical_notes,以 ` · ` 併接)。 結構化欄落地後改吃 diet / medical_notes(不再湊 roommate_pref —— 分房需求回歸分房面板)。 兩者皆空 → null。
staffNote該訂單的承辦備註(issue 1659,`orders.staff_note`)。同一張單的每位旅客列帶同一份; null = 沒有備註。與 `specialNeeds` 分開,不併進飲食 / 過敏字串。
emergencyContactName緊急聯絡人姓名;null = 未填。
emergencyContactPhone緊急聯絡人電話;null = 未填。
consentPending該訂單是否仍缺最新版 PDPA 同意書(per-order,同訂單所有旅客共享此旗標)。 true = 未簽 / 只簽過舊版;與 dashboard KPI、催簽 badge 同一述詞。
orderStatusSingle display status (派生自三軸,與 deriveOrderDisplayStatus 同 precedence)。
amount每人分攤的應收(整單應收 ÷ 人數,四捨五入,TWD)。加總可能差幾元;對帳用 `orderReceivableTwd`。
companionGroupId本梯次的同行組 id(departure-prep §2.11);null = 不屬任何組。
companionGroupCode同行組代號(A、B…);null = 不屬任何組。
companionGroupColor同行組顏色序號(0 起);null = 不屬任何組。
climbingExperience登山經歷(新到舊)。登山模組未啟用時恆為空陣列。
label行程 / 山岳名稱(自填為自由文字;order 來源 = 行程名稱快照)。
climbedOn約略完成日 `YYYY-MM-DD`;null = 未填。
source來源: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梯次 id。
guides隨團人員指派(leader 在前),含指派狀態。
id指派紀錄 id。
guideId被指派的嚮導 id。
guideName被指派的嚮導姓名。
role指派角色:leader 主要隨團人員/assistant 協同。
status指派狀態:tentative 預塞暫定/confirmed 正式確認。
guideStartDateguideEndDateeffectiveStartDateeffectiveEndDateisNameBoundpermitSwappedAt勾「已換領」的時間(ISO);null = 未勾(issue 1731)。
permitSwappedByName勾「已換領」的人的名稱;帳號已刪或未勾時為 null。
transport派車紀錄。
iddescriptiondriverNamedriverIddriverPhonelicensePlatevehicleTypevehicleInfofareNotestatuscatering餐食紀錄。
idsuppliermealPlanheadcountNotestatuspretripStay出發前夜住宿:宣告 + 全部登記(含已釋回列,看 releaseReason)。人數與性別彙總由 呼叫端從登記列算。訂房模組未啟用或行程沒指定據點時為 null。
declarationid實體列 id;**尚未實體化時為 null**(ADR 0022)。分頁的顯示條件是行程設定,不是這一列, 所以「有分頁但還沒有列」是正常狀態,第一筆登記或第一次發名單連結才會把它建出來。
departureIddepartureDatepropertyIdpropertyNameroomTypeIdroomTypeNametripRoomTypeId行程當下指定的床位池;null = 行程已改回旅客自理。**與 `roomTypeId` 不同時,這個出團 走的是實體化當下那一份**(ADR 0022 的 Consequence:畫面要說得出這件事)。
stayNight住宿夜 = 出發日前一晚(由 departure_date 現算,非讀 `check_in` 欄)。
rosterLinkExpiresAt只讓後台判斷是否已有有效連結;token 本體不進 server render。
rosterLinkActivedepartureConfirmed成團(`departures.confirmed_at` 有值)。旅客自助登記連結只在成團後可產生(issue 463)。
registrationsidtravelerIdrolefullName活動登記現讀 travelers;旅客退團刪除後顯示不含 PII 的佔位文字。
genderphoneorderNumberorderCancelled訂單是否已取消;T8 後對應登記應同時帶 releaseReason。
arrivalTimenightcleaningFeeCollectedAtcleaningFeeCollectedByNamereleaseReasonreleasedAtrentals本梯裝備租借單(含明細)。登山未對此梯生效時為空陣列。
orderOnDepartureWhether the order currently includes this rental departure.
deliveredAt選填awaitingDelivery還沒實際交付(issue 1917):沒有交付時間,或交付時間只是舊資料回填(= 建單時間)且起日 在今天之後的預留單。後台依這個欄位顯示交付動作,不只看 `deliveredAt` 有沒有值。
depositClearedAt選填id租借單 id(equipmentRental_ 前綴)。
rentalCode人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。
orderId掛載的訂單 id。
orderNumber訂單編號;無對應訂單時為 null。
departureId綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。
departureLabel梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。
renterName租借人姓名(可空)。
rentStartDate租期起日(YYYY-MM-DD;可空)。
rentEndDate租期迄日(YYYY-MM-DD;可空)。
returnedAt歸還驗收時間(尚未歸還為 null)。
returnState歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。
inspectedAt驗收時間(尚未驗收為 null)。
damageCostTwd破損/遺失賠償金額(TWD;無為 null)。
reconState對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。
cancelledAt取消時間(未取消為 null)。
cancelReason取消原因(未取消為 null)。
notes備註(可空)。
createdAt建單時間。
updatedAt最後更新時間。
lines租借明細(借出的品項清單)。
id租借明細 id(equipmentRentalLine_ 前綴)。
equipmentItemId借出的裝備主檔品項 id。
itemName裝備品項目前的名稱。
quantity借出數量。
rentPriceTwdSnapshot成交單位總價快照(每日單價 × 計價日數;TWD)。
depositTwdSnapshot成交每件押金快照(TWD,不乘天數)。
returnedQuantity已歸還數量(尚未歸還為 null)。
rentTotalTwd成交租金合計(Σ rent snapshot × qty)。
depositTotalTwd成交押金合計(Σ deposit snapshot × qty)。
rentCollectedAt租金已收時間(未收為 null)。
rentCollectedByName勾記租金已收的經手人姓名(遷移標記的單為 null)。
rentCollectedVia租金在哪裡收:onsite 現場收;order_payment 遷移前隨訂單付款收進公司戶頭。
depositCollectedAt押金已收時間(未收為 null)。
depositCollectedByName勾記押金已收的經手人姓名。
depositSettledAt押金結清(退還或沒收)時間(未結清為 null)。
depositSettledByName登記押金結清的經手人姓名。
depositRefundedTwd退還客人的押金(TWD;未結清為 null)。
depositForfeitedTwd沒收的押金(TWD;未結清為 null)。
documents證件追蹤(只回既有列)。登山未對此梯生效時為空陣列。
iddocType證件種類 key(`departure_document_types.key`)。
applyStatusfileReadyuploadedToCloudfileUriappliedAtapprovedAtnotenotApplicableAt標「本團不需要」的時間;null = 沒標。
notApplicableByUserIdnotApplicableReason不需要的原因;有標記才有值。
checklist團層級出團待辦(出團前在前,含已勾或有狀態文字但事後停用的項目),每項帶狀態文字。
id勾稽列 id;null = 目錄有此項但本梯次還沒有勾稽列。
itemKeylabelphase目錄階段。UI 依此分「出團前」「出團後」兩區;完成分母只計 'pre'。
isActive目錄啟用狀態。false 只可能出現在「已勾但事後停用」的列(見 listChecklist)。
required這一梯要做:項目啟用中,而且行程沒設定或有勾選(issue 1369)。false 的列只因為本梯已勾、 寫過字或標過不適用才列出,不計入進度。
checkedAtcheckedByUserIdcheckedByName勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。
note狀態文字(issue 1245);null = 沒有字。與勾選彼此獨立。
noteUpdatedAt最後寫字的時間;沒有字時為 null。
noteUpdatedByUserId最後寫字的人;沒有字或帳號刪除後為 null。
noteUpdatedByName最後寫字的人的顯示名(同 `checkedByName`,帳號刪除後為 null)。
notApplicableAt標「本團不適用」的時間;null = 沒標(issue 1369)。
notApplicableByName標記者的顯示名;帳號刪除後為 null。
notApplicableReason不適用的原因;有標記才有值。
travelerChecks旅客層級出團待辦:欄(items)+ 已勾的格(checks)+ 有狀態文字的格(notes),都以 travelerId 對人。勾選與狀態文字彼此獨立,所以分兩份稀疏清單。
itemsitemKeylabelisActivefalse 只可能出現在「已勾或寫過字但事後停用」的項目。
checkstravelerIditemKeycheckedAtcheckedByUserIdcheckedByName勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。
notestravelerIditemKeynotenoteUpdatedAtnoteUpdatedByUserIdnoteUpdatedByName最後寫字的人的顯示名(帳號刪除後為 null)。
insurance投保(旅責險 / 登山險兩軸,依 kind 分)。
idkindinsurerpolicyNostatusscheduledDate排定日 'YYYY-MM-DD'(可以開始辦的日,不是死線);null = 未排定。
insuredCount投保人數;null = 未填。
noteupdatedAt列的版本:最後寫入時間,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訂單 id。
orderNumber訂單編號。
errorCount該訂單的 error(必補缺漏)項目數。
warningCount該訂單的 warning(建議補齊)項目數。
incompleteTravelerCount至少有一項 error 或 warning 的旅客數(資料待補人數)。
errorTravelerCount含 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訂單 id。
orderNumber訂單編號。
customerName訂購人姓名。
partySize佔位人數。
lotteryState抽籤狀態:applied 已應募/won 中籤/lost 未中籤。null = 落在受管制抽籤梯次但沒標 應募的單(後台 K 單、事後改成抽籤的梯次)——只因抽籤實名制占用而被列出(§3.7)。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。 只有 `lotteryState='applied'` 時可能為 true。
applicationKeyCurrent application (`lotteryApplicationKey`). A decision sends it back to reject an old page.
undoDecisionId選填Latest reversible decision. The write entry checks later work under the order lock.
backupChoiceCount客人自選的有序備案筆數(order_backup_choices;0 = 無備案)。
collectedTwd已收現金(payment_transactions direction='in');抽籤未中安置時的訂金結轉基準。
failoverFromOrderId落腳譜系:本單若是由某主單 force-place / cascade 落腳而成立的備案單,指向原主單 id。 null = 本單即主單(非備案落腳單)。供線控從備案列回溯主單。
awaitingPlacementtrue when lottery_state='lost' and still active (not cancelled). Means backup cascade exhausted — awaiting manual placement or explicit cancel.
identityHoldPending是否仍占用抽籤實名資格。為 true 時可顯示「解除實名占用」動作。
identityHoldReleased抽籤實名占用是否已由線控手動解除。
failover最近一次未中籤自動轉備案:`placed` 落腳、`reapplied` 重新應募、`stopped` 停止並待人工安置。 `blocker` 為停止原因,null=清單走完。`skipped` 列被跳過的順位與原因。null=未曾自動轉備案。
outcomeplaced = a general backup took the order; reapplied = a new application; stopped = awaits placement.
blockerWhy the failover stopped. null = every backup choice was tried. Only for `stopped`.
skippedBackup choices that the failover skipped, in rank order.
rankdepartureIdreasontoko 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梯次表頭(id/起訖日/行程名/容量等)。
id梯次 id(dep_ 前綴)。
departureDate出發日(ISO 'YYYY-MM-DD')。
returnDate回程日(ISO 'YYYY-MM-DD')。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
capacity名額上限(人數)。
bookedCount已成團佔用名額(人數)。
rooms此梯次的所有房間(含入住旅客)。
id房間 id。
roomLabel房號/房間標籤。
roomType房型(如 single 單人/double 雙人/dorm 通舖)。
bedCount床位數。
bedConfig床位配置說明(可空)。
accommodationName住宿名稱(梯次配套派生房才有;可空)。
accommodationDate住宿日期(YYYY-MM-DD;可空)。
baseCostTwd房間底價成本(TWD)。
upgradeFeeTwd房型升等補款(TWD)。
notes備註(可空)。
departureLodgingIdnull = 手動建立的房;non-null = 梯次配套自動派生房的來源 ID。
assignedTravelers已入住此房的旅客。
id旅客 id。
fullName旅客姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
isPrimary是否為該訂單的主要聯絡人(訂購人)。
gender性別(分房 gender 衝突偵測用):'male'|'female'|'other'|null。
roomPreference下單登記的房型偏好(chip 上顯示配房意向 badge)。
roommatePref指定房友 id / 特殊需求自由文字。
companionGroup本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。
groupIdcode代號(A、B…,第 27 組起 AA)。
colorIndex顏色序號(0 起,循環)。UI 用它挑色票。
unassignedTravelers尚未分房的旅客清單。
assignedElsewhere選填True when the traveler has a room in another departure.
id旅客 id。
fullName旅客姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
isPrimary是否為該訂單的主要聯絡人(訂購人)。
gender性別:'male'|'female'|'other'|null。
birthDate選填出生日期(YYYY-MM-DD;可空)。
roomPreference下單登記的房型偏好(auto-pair 起點提示)。
roommatePref指定房友 id / 特殊需求自由文字。
companionGroup本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。
groupIdcode代號(A、B…,第 27 組起 AA)。
colorIndex顏色序號(0 起,循環)。UI 用它挑色票。
stats分房統計彙總(總人數/已分房數/房間數/升等補款合計)。
totalTravelers此梯次旅客總人數。
assignedCount已分配房間的旅客數。
roomCount房間數。
totalUpgradeFee升等補款合計(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>位置參數 · 必填--jsontoko control room-stats '<depId>'{
"ok": true,
"data": {}
}toko control finance梯次財務摘要(唯讀)
參數
<depId>位置參數 · 必填--json回應欄位 · data
header梯次表頭(團號/行程名/出發日等基本資訊)。
id梯次 id(dep_ 前綴)。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日(ISO 'YYYY-MM-DD')。
returnDate回程日(ISO 'YYYY-MM-DD')。
finance應收/已收金額彙整(TWD)。
receivableTwd梯次應收:tour 訂單的攤提份額(order-money/allocation;排除已取消單)。 **含代收暫收款**(裝備押金等)—— 客人確實欠這筆錢,收款計畫與待收都照它走。 要「本團收入」請用 revenueTwd,不要拿這個當收入(issue #578)。
custodialTwd應收之中的代收暫收款份額(裝備押金等;要退還,不是收入)。
revenueTwd本團收入 = 應收 − 代收暫收款。毛利、損益、月報表一律用這個。
collectedTwd實收:tour 訂單 payment_transactions(direction='in') 的攤提份額。
cashReturnedTwd客戶現金退回(refund/chargeback/reversal)的攤提份額。
netCollectedTwd已收淨額 = 實收 − 退回。
outstandingTwd待收 = 應收 − (實收 − 退回),floor 0。
costTwd成本:departure_costs 真實額(房費另計,見成本登記簿)。
costBilledTwd已轉請款成本。
costUnbilledTwd未轉請款成本;不含即付(當下已付、不轉請款)。
anomalyOrderCount異常單數:overpaid / partially_refunded / refund pending 的 tour 訂單。
cost成本彙整(各類直接成本合計,TWD)。
totalTwd內帳真實成本合計(TWD 整數,各成本列金額加總)。
billedTwd已轉請款的成本合計(TWD 整數)。
paidOnSpotTwd即付的成本合計(TWD 整數):當下已付,不轉請款。
unbilledTwd尚未轉請款的成本合計(TWD 整數);不含即付列。
declarableTwd外帳可申報金額合計(TWD 整數,各列憑證金額加總)。
nonDeclarableTwd無憑證的不可申報成本合計(TWD 整數,逐列取 金額−憑證 的正值,不可跨列抵減)。
count成本列筆數。
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
departureIdpaymentsiddepartureIdgroupCode團號;未產生為 null。
tripTitledepartureDate出發日(YYYY-MM-DD)。
paidOn付款日期(YYYY-MM-DD)。
handlerUserIdhandlerName經手人姓名。
receivingAccountId付款渠道(收款帳戶 ID)。
channelName付款帳戶名稱(例:小編機)。
payee付給誰/項目。
note說明;未填為 null。
amountTwd金額(TWD 整數);退費為負數。
createdAt登記時間(ISO 8601,UTC)。
updatedAt最後修改時間(ISO 8601,UTC)。
totalTwdtoko 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
fromtopaymentsiddepartureIdgroupCode團號;未產生為 null。
tripTitledepartureDate出發日(YYYY-MM-DD)。
paidOn付款日期(YYYY-MM-DD)。
handlerUserIdhandlerName經手人姓名。
receivingAccountId付款渠道(收款帳戶 ID)。
channelName付款帳戶名稱(例:小編機)。
payee付給誰/項目。
note說明;未填為 null。
amountTwd金額(TWD 整數);退費為負數。
createdAt登記時間(ISO 8601,UTC)。
updatedAt最後修改時間(ISO 8601,UTC)。
totalTwdtoko 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梯次成本列 ID。
category成本分類(如 交通 / 餐費 / 保險)。
vendorName供應商 / 廠商名(可空)。
description摘要說明(可空)。
amountTwd內帳成本金額(TWD;數量 × 單價派生)。
invoiceAmountTwd報帳/發票金額(TWD;is_declarable=true 時同步 amount,否則 0)。
isDeclarable是否有合法憑證可報帳(開發票)。
quantityMode數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。
headcountComponentsheadcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。
groupDivisorheadcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。
quantity實際套用的數量(依 quantityMode 派生)。
unitPriceTwd內帳單價(TWD;外幣列可為 null)。
currency幣別('TWD' = 台幣列)。
unitPriceForeign外幣單價;TWD 列 null。
foreignAmount外幣金額快照 = unit_price_foreign × quantity;TWD 列 null。
internalRate內帳匯率快照(numeric 字串);TWD 列 null。
externalRate外帳匯率快照(numeric 字串);TWD 列 null。
isManualOverride是否為線控手動改寫(true 時重算會跳過此列,不覆蓋手改值)。
payableId已轉請款 → 鎖定(不可手改 / 重算)。
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**整單**會計應收(TWD,不是每人分攤)。同一張單的每一列都帶同一個數字。 未取消=訂單應收。已取消=`cancellationFeeTwd`+`refundFeesTwd`:取消時訂單應收 歸零,公司留下的是這兩筆錢。匯款費屬於已退,不含在應收內。 null=退改費尚未核算(見 `cancellationFeePending`)。
cancellationFeePendingtrue=已取消、退改費尚未核算、手上還有可退現金:整單應收還定不下來。
cancellationFeeTwd已取消單留下的退改費(整單)。未取消=null;尚未核算=null。
refundFeesTwdCompleted administrative fees. Excludes bank fees. 已取消單已執行退款的行政手續費(不含匯款手續費)(整單)。未取消=null。
percentageFeeTwdfixedAdminFeeTwdchangeFeeTwdunclassifiedFeeTwdUnclassified historical fees remain separate.
refundRemainingTwdtravelerId旅客 id。外部系統用它對人,不靠姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
travelerName旅客姓名。
phone聯絡電話。
email聯絡 Email。
isPrimary是否為該訂單的主要聯絡人(訂購人)。
gender性別(明文 enum-like):'male'|'female'|'other'|null(未填)。
birthDate生日 ISO `YYYY-MM-DD`;null = 未填。
diet飲食需求(葷素)明文;null = 未填。
medicalNotes醫療 / 過敏 / 病史備註明文;null = 未填。
specialNeeds「飲食 · 特殊需求」欄的合併顯示字串(diet + medical_notes,以 ` · ` 併接)。 結構化欄落地後改吃 diet / medical_notes(不再湊 roommate_pref —— 分房需求回歸分房面板)。 兩者皆空 → null。
staffNote該訂單的承辦備註(issue 1659,`orders.staff_note`)。同一張單的每位旅客列帶同一份; null = 沒有備註。與 `specialNeeds` 分開,不併進飲食 / 過敏字串。
emergencyContactName緊急聯絡人姓名;null = 未填。
emergencyContactPhone緊急聯絡人電話;null = 未填。
consentPending該訂單是否仍缺最新版 PDPA 同意書(per-order,同訂單所有旅客共享此旗標)。 true = 未簽 / 只簽過舊版;與 dashboard KPI、催簽 badge 同一述詞。
orderStatusSingle display status (派生自三軸,與 deriveOrderDisplayStatus 同 precedence)。
amount每人分攤的應收(整單應收 ÷ 人數,四捨五入,TWD)。加總可能差幾元;對帳用 `orderReceivableTwd`。
companionGroupId本梯次的同行組 id(departure-prep §2.11);null = 不屬任何組。
companionGroupCode同行組代號(A、B…);null = 不屬任何組。
companionGroupColor同行組顏色序號(0 起);null = 不屬任何組。
climbingExperience登山經歷(新到舊)。登山模組未啟用時恆為空陣列。
label行程 / 山岳名稱(自填為自由文字;order 來源 = 行程名稱快照)。
climbedOn約略完成日 `YYYY-MM-DD`;null = 未填。
source來源: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旅客 id。外部系統用它對人,不靠姓名。
fullName旅客姓名。
gender性別(中文標籤:男/女/其他)。
roomLabel房號/房間標籤(未排房為「未分房」)。
bedInfo床位資訊(房型中文標籤 + 床位)。
roommates同房其他旅客姓名(依房號分組派生)。
specialRequest特殊需求(房友偏好等自由文字)。
contactSummary聯絡摘要(電話已遮罩,只露末 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回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的梯次成本列 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回應欄位 · data
ok更新成功旗標,恆為 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回應欄位 · data
ok刪除成功旗標,恆為 true。
toko control cost-rm '<depId>' --cost 'example-costId'{
"ok": true,
"data": {
"ok": true
}
}toko control template-apply套用行程綁定範本到本梯次(冪等)
參數
<depId>位置參數 · 必填--confirm回應欄位 · data
ok套用成功旗標,恆為 true。
inserted本次新補插入的範本成本行數(冪等,已存在的不重複插)。
skippedForeign因匯率未備妥而跳過的外幣行數。補齊匯率後再套用,會自動補上這些行。
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回應欄位 · data
ok手改金額成功旗標,恆為 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回應欄位 · data
ok清除手改鎖並重算成功旗標,恆為 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回應欄位 · data
ok轉請款成功旗標,恆為 true。
payableId新建立的出款單(payable)id。
payableNumber出款單編號。
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回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的房間 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回應欄位 · data
ok更新成功旗標,恆為 true。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
toko control room-update '<depId>' --room '<roomId>'{
"ok": true,
"data": {
"ok": true,
"retentionDeferred": true
}
}toko control room-rm刪除房間
參數
<depId>位置參數 · 必填--room <roomId>房間 ID
--confirm回應欄位 · data
ok刪除成功旗標,恆為 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回應欄位 · data
ok指派入房成功旗標,恆為 true。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
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回應欄位 · data
ok移出房間成功旗標,恆為 true。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
toko control room-unassign --traveler 'example-travelerId'{
"ok": true,
"data": {
"ok": true,
"retentionDeferred": true
}
}toko control room-auto-pair-previewauto-pair 建議分組預覽(純讀取;供 apply 取 travelerIds)
參數
<depId>位置參數 · 必填--json回應欄位 · data
suggestionauto-pair 引擎產出的分房建議(未寫入,供線控確認)。
groups建議的分房組合(每組一間房,含旅客與需確認註記)。
kindtravelerIdsneedsConfirmation選填需線控人工確認(跨性別指定房友 / gender='other')。
note選填給線控看的提示(特殊需求原文、超過床數、單人房卻又指名房友…)。
unmatched無法安全自動配對、待人工處理的旅客。
travelerIdreasonnamestravelerId → 顯示名(建議分組渲染用)。
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回應欄位 · data
ok套用成功旗標,恆為 true。
roomId建議分組寫入後所在的房間 id。
travelerIds被排入該房的旅客 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回應欄位 · data
ok固定為 true:抽籤結果已登錄。
outcome抽籤結果:won 中籤 / lost 未中籤。
balanceNotice中籤後的尾款通知(lost 為 null):sent 已寄出、already_sent 之前寄過、 not_eligible 沒有待收尾款、no_template 租戶沒有啟用中的收尾款範本、 no_recipient 沒有收件人(同業單或訂購人沒有 email)、failed 寄送失敗。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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回應欄位 · data
ok更新成功旗標,恆為 true。
departureId被更新的梯次 id。
mode更新後的佔位模式: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回應欄位 · data
ok設定成功旗標,恆為 true。
id出團待辦勾稽紀錄 id。
toko control prep-checklist '<depId>' --item 'example-itemKey' --checked true{
"ok": true,
"data": {
"ok": true,
"id": "…"
}
}toko control prep-documentupsert 證件追蹤狀態
參數
<depId>位置參數 · 必填--type <docType>--apply-status <todo|applying|approved>申辦狀態:todo(待辦)/ applying(申請中)/ approved(已核准)
--file-ready <true|false>文件檔案是否已備妥
--note <t>備註;給 null 清空
--confirm回應欄位 · data
okupsert 成功旗標,恆為 true。
id證件追蹤紀錄 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回應欄位 · data
ok設定成功旗標,恆為 true。
departureId被設定期限的梯次 id。
deadlines本次套用的硬 deadline 異動(key → 日期;null = 已清除)。寫入的列來源為 manual。
softDates本次套用的軟日期異動(key → 日期;null = 已清空)。
toko control prep-deadlines '<depId>'{
"ok": true,
"data": {
"ok": true,
"departureId": "…",
"deadlines": "…",
"softDates": "…"
}
}toko control prep-equipment-needupsert 裝備需求數
參數
<depId>位置參數 · 必填--item <equipmentItemId>--qty <n>--note <t>需求備註;給 null 清空
--confirm回應欄位 · data
okupsert 成功旗標,恆為 true。
id裝備需求紀錄 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回應欄位 · data
ok刪除成功旗標,恆為 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回應欄位 · data
ok指派成功旗標,恆為 true。
id指派紀錄 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回應欄位 · data
ok開單成功旗標,恆為 true。
rentalId新開立的裝備租借單 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回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的投保紀錄 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回應欄位 · data
ok更新成功旗標,恆為 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回應欄位 · data
ok刪除成功旗標,恆為 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回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的派車紀錄 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回應欄位 · data
ok更新成功旗標,恆為 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回應欄位 · data
ok刪除成功旗標,恆為 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回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的餐食紀錄 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回應欄位 · data
ok更新成功旗標,恆為 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回應欄位 · data
ok刪除成功旗標,恆為 true。
toko control prep-catering-rm '<depId>' --id 'example-id'{
"ok": true,
"data": {
"ok": true
}
}toko control survey取得梯次有效問卷
參數
<id>位置參數 · 必填--json回應欄位 · data[]
idkindlabeldescriptionrequiredoptionsidlabeldisabled本梯次停用(新答案不可選;既有答案保留並標示)。
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回應欄位 · data
departureId被重算的梯次 id。
rows各事項的公式結果;written=false 表示該列是人工覆寫、本次未動。
keylabelsoftDatedeadlineDatewrittenfalse = 該列是人工覆寫、本次未動(includeManual=false)。
missingHolidayYearsskipped規則無法套用而略過的事項(key / label / 原因)。
keylabelmessagemissingHolidayYears假日表未維護、但工作天回推觸及的年度;非空即「假日資料不完整」。
removed被清掉的事項 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回應欄位 · data
okdepartureIduserIdtoko 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回應欄位 · data
backupSucceededOrders moved to a backup in this batch.
heldOrders placed in the holding area in this batch.
skippedOrders left unchanged, with a reason for staff.
orderIdorderNumberreasonorderResultsEach order result for the batch audit.
orderIdorderNumberoutcomereason選填cancelled本次完成未成團處理的訂單數。
alreadyCancelled已完成未成團處理、本次不重複處理的訂單數(重跑時的正常值)。
emailed本次寄出(信進了佇列)的通知數。
emailSkippedAlreadySent已寄過通知、本次略過的訂單數。
emailSkippedNoTemplate取消成立但沒寄成,因為租戶沒有啟用中的「未成團通知」範本。**不留 claim** —— 設好範本後重按同一顆按鈕會補寄。
emailSkippedNoRecipient取消成立但沒寄成,因為訂購人沒有 email。**與缺範本分開數**:缺範本的後續動作是 去設範本再按一次,這種按幾次都沒用,要改走電話或其他管道。混成一個數字等於叫 承辦對這張單做一件永遠不會生效的事。
unprocessedDepartureIneligible因**梯次**中途失格(被標記成團 / 已結團)而未處理的訂單數 —— 含發現當下那張與 其後全部未跑到的單。>0 = 這批提早中止。刻意**不併進其他數字**:那些的後續動作是 去看那張單,這種是去看梯次。
crossDepartureSkipped**跨梯訂單**:同時掛在本梯與別梯的單,一律不碰(見批次說明)。清單而不是計數 —— 這些單要承辦逐張人工處理,沒有訂單號等於沒有回報。
orderIdorderNumberfailed**取消**沒成立的訂單數(其餘訂單不受影響)。**只數 `phase='cancel'`** —— 取消已經 commit、只是通知寄不出去的單不算,那張單真的取消了,把它報成失敗等於對線控謊稱 「這張還沒取消」,而他會去做一件已經做完的事。
failures失敗清單(辨識到訂單號)。`phase` 分「取消沒成立」與「取消成立但通知炸了」—— 後續動作完全不同。**不帶例外訊息**:DB 例外會帶表名 / 約束名 / 衝突鍵的值(可能 含 email),那些留 server log,不經 server action 回瀏覽器。
orderIdorderNumberphaseselectedNotEligible**只有選單版會有值**:選了、但不在本梯名單上的單(不掛在本梯、已出團、或已被其他 事由取消)—— 一張都沒動。清單而不是計數,理由同 `crossDepartureSkipped`。整梯版恆為空。
orderIdorderNumbertoko 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回應欄位 · data
oktoko 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回應欄位 · data
oktoko control confirmation-create '<depId>' --data '{"confirmed":true}'{
"ok": true,
"data": {
"ok": true
}
}toko control delete執行 departures/[depId]/delete
參數
<depId>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
oktoko 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回應欄位 · data
changedtoko 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回應欄位 · data
changedreasontoko 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回應欄位 · data
transportcateringinsurancetoko 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
assignmentsiduserIduserNamecandidatesidnametoko 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回應欄位 · data
okidcreatedtrue = 這次真的新增;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回應欄位 · data
oktoko 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回應欄位 · data
oktoko 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回應欄位 · data
oktoko control prep-pretrip-stays-cleaning-fee '<depId>' '<registrationId>' --data '{"collected":true}'{
"ok": true,
"data": {
"ok": true
}
}toko control prep-pretrip-stays-roster-link執行 departures/[depId]/prep/pretrip-stays/roster-link
參數
<depId>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
tokenexpiresAturltoko control prep-pretrip-stays-roster-link '<depId>'{
"ok": true,
"data": {
"token": "…",
"expiresAt": "…",
"url": "…"
}
}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回應欄位 · data
okregistrationIdtoko control prep-pretrip-stays-create '<depId>' --data '{"travelerId":"example-travelerId"}'{
"ok": true,
"data": {
"ok": "…",
"registrationId": "…"
}
}toko control prep-pretrip-stays-self-links執行 departures/[depId]/prep/pretrip-stays/self-links
參數
<depId>位置參數 · 必填--data <json>JSON object with the fields from the linked API request.
--json--confirm回應欄位 · data
linksorderIdorderNumberurlexpiresAtrotatedtoko control prep-pretrip-stays-self-links '<depId>' --data '{"mode":"ensure"}'{
"ok": true,
"data": {
"links": [
{
"orderId": "…",
"orderNumber": "…",
"url": "…",
"expiresAt": "…",
"rotated": true
}
]
}
}toko control send-balance-slips執行 departures/[depId]/send-balance-slips
參數
<depId>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
sent真的寄出(信進了佇列)的訂單數。
excludedAgencyOrders同業單不寄信、不建連結,請經同業收款。
skipped逐單略過數 = `skippedAlreadySent` + `skippedNoTemplate` + `skippedNoRecipient` + `skippedNotEligible`。 **不含**因梯次失格而中止未跑到的單(那些在 `unsentDepartureIneligible`)。
skippedAlreadySent略過細分:已寄過(claim 命中)。重跑仍會略過,正常。
skippedNoTemplate略過細分:連結已建但租戶沒有啟用中的「收尾款」範本而沒寄成。這種略過**不留 claim** —— 補設範本後重跑同一批次會補寄。
skippedNoRecipient略過細分:連結已建但沒有收件人而沒寄成。訂購人沒有 email。補設範本不會補寄,承辦要另行聯繫。
skippedNotEligible略過細分:撈出來之後才發現不符資格(尾款已結清 / 期間被取消)。
unsentDepartureIneligible因**梯次**中途失格(被取消 / 被退回成團)而未寄的訂單數 —— 含發現當下那張與其後 全部未跑到的單。>0 = 這批提早中止。刻意**不併進 `skipped`**:那三種略過的後續動作 是去看那張單,這種是去看梯次。
failed例外中斷的訂單數(其餘訂單不受影響)。
failures失敗清單(辨識到訂單號)。`reason` 只給分類字串 —— DB 例外訊息會帶表名 / 約束名 / 衝突鍵的值(可能含 email),那些留 server log,不經 server action 回瀏覽器。
orderIdorderNumberreasonnoCandidates本梯沒有任何符合條件的單時,各張單為什麼不符(#1456);有符合的單時 null。 結果全是 0 時,承辦要看得出是「沒有符合的單」,不是「按了沒反應」。
total本梯的訂單數(含已取消)。
cancelledwaitlisted候補中(還沒有席位)。
lotteryNotWon抽籤梯次未中籤。
unpaidpartiallyPaid已付款但未付足訂金。
paid已付清(含溢收)。
othertoko 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 send-consent-reminders執行 departures/[depId]/send-consent-reminders
參數
<depId>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
sentskippedNoPending沒有待簽的自訂同意書(已簽齊或不適用)。
skippedNoRecipient訂購人帳號沒有 email,系統寄不出去。
failedfailuresorderNumbertoko control send-consent-reminders '<depId>'{
"ok": true,
"data": {
"sent": 0,
"skippedNoPending": 0,
"skippedNoRecipient": 0,
"failed": 0,
"failures": [
{
"orderNumber": "…"
}
]
}
}toko control submission-export執行 departures/[depId]/submission-export
參數
<depId>位置參數 · 必填--data <json>JSON object with the fields from the linked API request.
--json--confirm回應欄位 · data
kindvexportedAt匯出時間(ISO 8601,UTC)。承辦貼上後用來核對不是上一梯的資料。
tripcodenamedeparturegroupCode團號;還沒產生時為 null。
entryDate入園日 = 出發日 + 入園日偏移。
startDate出發日 YYYY-MM-DD。
endDate回程日 YYYY-MM-DD。
groupsnotravelersnamegenderbirthDateidNumberphoneemailaddressemergencyNameemergencyPhonevalidationorderNumberpassportNonationalitynationalityNamepassportFile護照影本的下載網址(passport-ocr §0.5)。沒有影本時為 null。網址 30 分鐘到期, 兌換時另要登入身分與 `departure.submission_export`。
urlcontentTypeexpiresAt網址到期時間(ISO 8601,UTC)。
staff加帶的隨團人員,不屬於任何一組(issue 1416)。沒勾任何人為空陣列。
kindguideIdroleleader 主要/assistant 協同。
statustentative 預塞/confirmed 正式。
englishName英文姓名(與護照一致);未填為空字串。
namephoneemailaddressgenderbirthDateidNumberemergencyNameemergencyPhonevalidationpassportNonationalitynationalityNamecounts送件人數:客人(各組合計)+隨團。
travelersstafftotalsourcetooltoko 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回應欄位 · data
guideIdstoko 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
departuredepartureIdgroupCode團號;還沒產生時為 null。
tripCode行程的中性代碼(slug)。
tripTitlestartDate出發日 YYYY-MM-DD。
endDate回程日 YYYY-MM-DD。
entryDate入園日 = 出發日 + 入園日偏移。
entryDateOffsetDaysordersorderIdorderNumberleadName主要聯絡人(訂單第一位旅客)姓名,讓承辦認得是哪一張單。
travelerCounttravelers這張單的全部旅客,順序同匯出。`companionGroup` 是旅客在本梯次的同行組(§2.11), 給承辦當「誰跟誰一夥」的提示,跨訂單也對得上(issue 1171)。
namecompanionGroupgroupIdcode代號(A、B…,第 27 組起 AA)。
colorIndex顏色序號(0 起,循環)。UI 用它挑色票。
lastGroup上一次匯出時這張單的組別(已重編)。`null` = 沒有可沿用的紀錄:沒匯出過、這張單 當時不在梯次上、或人數變了。
groupissues有驗證問題的旅客;沒有問題的旅客不列。
travelerNamemessagesstaff這一梯的全部已派隨團人員,`included` = 已勾加帶進送籤名單(issue 1416)。
assignmentId指派紀錄 id。
guideIdnickname暱稱(後台顯示名)。
legalName正式姓名;未填為 null(送籤檢查會列「姓名未填」)。
roleleader 主要/assistant 協同。
statustentative 預塞/confirmed 正式。
included已勾「加帶進送籤名單」。
issues送籤檢查問題(資料待補);沒有問題為空陣列。
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回應欄位 · data
oktoko control survey-options-update '<depId>' '<optionId>' --data '{"disabled":true}'{
"ok": true,
"data": {
"ok": "…"
}
}toko control backup-candidates查詢同一行程的備案梯次及定價
參數
<depId>位置參數 · 必填--json回應欄位 · data
mainstatus選填idtripIddepartureDatereturnDatepriceTwd牌價 `departures.price_twd`(備案同價的基準)。
agencyPriceTwd同業通路有效單價(見 `effectiveAgencyUnitPrice`)。
capacitybookedCountallocationModelabel梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。
isPrivate不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。
candidatesstatus選填idtripIddepartureDatereturnDatepriceTwd牌價 `departures.price_twd`(備案同價的基準)。
agencyPriceTwd同業通路有效單價(見 `effectiveAgencyUnitPrice`)。
capacitybookedCountallocationModelabel梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。
isPrivate不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。
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回應欄位 · data
ok開單成功旗標,恆為 true。
rentalId新開立的裝備租借單 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申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 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回應欄位 · data
application建立後的申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
applied每個有帶的欄位是否套用。
created是否建了新單;冪等重送時沿用第一次的值。
replayed這次是同一個 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申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
files證件檔清單。檔案本身只能從後台下載。
id證件檔 ID(pmf_ 前綴)。
kind檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。
contentType檔案類型:application/pdf、image/png 或 image/jpeg。
sizeBytes檔案大小(位元組)。
sha256檔案的 sha256(hex)。
originalName原始檔名。
uploadedAt上傳時間。
uploadedByUserId上傳者的使用者 ID。
source來源:staff(後台)或 api(送籤台)。
events歷程,新的在前。身分證只有遮罩值。
id歷程 ID(pme_ 前綴)。
kind歷程種類,例:created、status_changed、status_ignored、renumbered。
source來源:staff(後台)或 api(送籤台)。
actorUserId寫入者的使用者 ID。
actorName寫入者的姓名。
apiKeyId送籤台寫入時的 API 金鑰 ID。
apiKeyName寫入的 API 金鑰名稱;金鑰已刪為 null。
changes改了什麼:{ 欄位: { from, to } }。身分證只有遮罩值。 領隊是嚮導或旅客時,歷程只存來源 id;讀取時補上來源目前的姓名與遮罩。 補的欄是 `name`、`idNumber`;建單歷程是 `leaderName`、`leaderIdNumber`。 去識別化的旅客顯示去識別化後的名字。
reason原因(強制覆蓋、作廢)。
createdAt寫入時間。
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回應欄位 · data
application更新後的申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
applied每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。
createdPATCH 恆為 false。
replayed這次是同一個 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申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 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回應欄位 · data
application更新或新建後的申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
applied每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。
created這次是否建了新單。
replayed這次是同一個 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回應欄位 · data
file證件檔資訊。
id證件檔 ID(pmf_ 前綴)。
kind檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。
contentType檔案類型:application/pdf、image/png 或 image/jpeg。
sizeBytes檔案大小(位元組)。
sha256檔案的 sha256(hex)。
originalName原始檔名。
uploadedAt上傳時間。
uploadedByUserId上傳者的使用者 ID。
source來源:staff(後台)或 api(送籤台)。
createdfalse = 這張單已有同一個檔案,沒有再存一份。
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回應欄位 · data
field本次顯示的欄位。
value身分證全碼;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還沒完成的請求,依截止時間排序。
id取消請求 ID(pcr_ 前綴)。
applicationId申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
kindcancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。
trigger觸發點:order_cancelled / departure_changed / traveler_removed。
orderId觸發的訂單 ID。
orderNumber觸發的訂單編號。
travelers離開的旅客:只有 id、姓名與身分證遮罩。
idnameidNumberMaskstatuspending(待處理)/ claimed(送籤台已取走)/ done(已完成)。
attempts送籤台回報失敗的次數。
claimedAt送籤台取走的時間。
resultNote最近一次回報的說明。
dueAt最晚要完成的時間:入園日前一天的台北時間 12:00。
createdAt建立時間。
completedAt完成時間。
application申請單摘要,送籤台到站方找單用。
office申請處。
officeLabel申請處名稱(office = other 時有值)。
applicationNo申請編號。
groupLabel組別。
entryDate入園日(YYYY-MM-DD)。
status申請單目前的狀態。
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回應欄位 · data
requests這次取走的請求,已標成 claimed。
id取消請求 ID(pcr_ 前綴)。
applicationId申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
kindcancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。
trigger觸發點:order_cancelled / departure_changed / traveler_removed。
orderId觸發的訂單 ID。
orderNumber觸發的訂單編號。
travelers離開的旅客:只有 id、姓名與身分證遮罩。
idnameidNumberMaskstatuspending(待處理)/ claimed(送籤台已取走)/ done(已完成)。
attempts送籤台回報失敗的次數。
claimedAt送籤台取走的時間。
resultNote最近一次回報的說明。
dueAt最晚要完成的時間:入園日前一天的台北時間 12:00。
createdAt建立時間。
completedAt完成時間。
application申請單摘要,送籤台到站方找單用。
office申請處。
officeLabel申請處名稱(office = other 時有值)。
applicationNo申請編號。
groupLabel組別。
entryDate入園日(YYYY-MM-DD)。
status申請單目前的狀態。
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回應欄位 · data
request回報後的請求。
id取消請求 ID(pcr_ 前綴)。
applicationId申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
kindcancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。
trigger觸發點:order_cancelled / departure_changed / traveler_removed。
orderId觸發的訂單 ID。
orderNumber觸發的訂單編號。
travelers離開的旅客:只有 id、姓名與身分證遮罩。
idnameidNumberMaskstatuspending(待處理)/ claimed(送籤台已取走)/ done(已完成)。
attempts送籤台回報失敗的次數。
claimedAt送籤台取走的時間。
resultNote最近一次回報的說明。
dueAt最晚要完成的時間:入園日前一天的台北時間 12:00。
createdAt建立時間。
completedAt完成時間。
application申請單摘要,送籤台到站方找單用。
office申請處。
officeLabel申請處名稱(office = other 時有值)。
applicationNo申請編號。
groupLabel組別。
entryDate入園日(YYYY-MM-DD)。
status申請單目前的狀態。
replayed這次是同一個 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裝備主檔品項 id(equipmentItem_ 前綴)。
name品名。
category分類(如帳篷/睡袋/爐具;未分類為 null)。
spec規格描述(尺寸/型號等;可空)。
rentPriceTwd每日租金單價(TWD)。
depositTwd每件押金(TWD)。
totalCount庫存總件數。
outCount目前在外件數:已交付未歸還(不含尚未開始的預留)加上歸還時的短少件。由租借明細導出。
maintenanceCount維修中件數(不可借出)。
inStockCount目前在倉可借件數 = 總數 − 維修 − 目前在外(不小於 0)。
availableCount指定租期可借件數 = 總數 − 維修 − 期間內任一天的最高占用(不小於 0)。沒有指定租期時 看今天。占用含尚未交付的預留、逾期未還與短少件。
isActive是否啟用(可租借)。
createdAt建檔時間。
updatedAt最後更新時間。
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[]
moneyMarksrent租金標記;null=沒有要收的租金(已取消且沒收過,或租金為 0)。 `state`:due 未收、done 已收、refund_due 單已取消但租金已收(要退)。
deposit押金標記;null=押金為 0,或已取消且沒收過押金。 `state`:due 未收、held 已收待退、done 已結清(帶退還額與沒收額)。
orderOnDepartureWhether the order currently includes this rental departure.
deliveredAt選填awaitingDelivery還沒實際交付(issue 1917):沒有交付時間,或交付時間只是舊資料回填(= 建單時間)且起日 在今天之後的預留單。後台依這個欄位顯示交付動作,不只看 `deliveredAt` 有沒有值。
depositClearedAt選填id租借單 id(equipmentRental_ 前綴)。
rentalCode人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。
orderId掛載的訂單 id。
orderNumber訂單編號;無對應訂單時為 null。
departureId綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。
departureLabel梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。
renterName租借人姓名(可空)。
rentStartDate租期起日(YYYY-MM-DD;可空)。
rentEndDate租期迄日(YYYY-MM-DD;可空)。
returnedAt歸還驗收時間(尚未歸還為 null)。
returnState歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。
inspectedAt驗收時間(尚未驗收為 null)。
damageCostTwd破損/遺失賠償金額(TWD;無為 null)。
reconState對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。
cancelledAt取消時間(未取消為 null)。
cancelReason取消原因(未取消為 null)。
notes備註(可空)。
createdAt建單時間。
updatedAt最後更新時間。
lines租借明細(借出的品項清單)。
id租借明細 id(equipmentRentalLine_ 前綴)。
equipmentItemId借出的裝備主檔品項 id。
itemName裝備品項目前的名稱。
quantity借出數量。
rentPriceTwdSnapshot成交單位總價快照(每日單價 × 計價日數;TWD)。
depositTwdSnapshot成交每件押金快照(TWD,不乘天數)。
returnedQuantity已歸還數量(尚未歸還為 null)。
rentTotalTwd成交租金合計(Σ rent snapshot × qty)。
depositTotalTwd成交押金合計(Σ deposit snapshot × qty)。
rentCollectedAt租金已收時間(未收為 null)。
rentCollectedByName勾記租金已收的經手人姓名(遷移標記的單為 null)。
rentCollectedVia租金在哪裡收:onsite 現場收;order_payment 遷移前隨訂單付款收進公司戶頭。
depositCollectedAt押金已收時間(未收為 null)。
depositCollectedByName勾記押金已收的經手人姓名。
depositSettledAt押金結清(退還或沒收)時間(未結清為 null)。
depositSettledByName登記押金結清的經手人姓名。
depositRefundedTwd退還客人的押金(TWD;未結清為 null)。
depositForfeitedTwd沒收的押金(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嚮導 id。
name嚮導姓名。
rosterRole名冊職能:leader 主要隨團人員/assistant 協同/both 皆可。
specialties可帶路線 / 專長;未設為空陣列。
status嚮導狀態:active 啟用/inactive 停用。
internalNote內部備註(只給後台看,派團時參考);null = 沒填,或檢視者沒有 `guide.read`。
maxDaysPerMonth單一曆月實際帶團天數上限(跨月梯次按實際日期拆分計入各月);NULL = 不限。
monthDays視窗涵蓋月份內 confirmed 指派實際落在月內的帶團天數合計。
monthTrips視窗涵蓋月份內有帶團日的 confirmed 梯次數(每梯只算一次)。
hasTentative視窗涵蓋月份內是否含 tentative(預塞)指派。
availability派生載量狀態:任一涵蓋月達上限即 full。
monthLoads視窗涵蓋的每個曆月的載量(依時間排序)。
month曆月 `YYYY-MM`。
days該月 confirmed 指派實際落在月內的帶團天數。
trips該月有帶團日的 confirmed 梯次數(跨月梯次在兩個月各算一次)。
hasTentative該月是否有 tentative(預塞)指派佔用日期。
availability該月的派生載量狀態。
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梯次 id。
tripId所屬行程 id。
tripTitle行程名稱。
tripShortName行程內部簡稱(issue 1414);未填為 null。
label梯次標籤 / 副標(issue 509 ①);null = 無。排班下拉靠它分辨同日兩梯。
groupCode團號(group-code spec §3.3);null = 尚未產生。排班 UI 用它指認梯次。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(YYYY-MM-DD)。
days帶團天數(含頭尾)。
capacity團位容量(總名額)。
bookedCount已成團報名人數。
status梯次狀態(如 open 開放/full 已滿/cancelled 已取消)。
assignments該梯次所有指派(leader 在前)。
id指派紀錄 id。
guideId被指派的嚮導 id。
guideName被指派的嚮導姓名。
role指派角色:leader 主要隨團人員/assistant 協同。
status指派狀態:tentative 預塞暫定/confirmed 正式確認。
guideStartDateguideEndDateeffectiveStartDateeffectiveEndDateisNameBoundpermitSwappedAt勾「已換領」的時間(ISO);null = 未勾(issue 1731)。
permitSwappedByName勾「已換領」的人的名稱;帳號已刪或未勾時為 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發生衝突的嚮導 id。
guideName發生衝突的嚮導姓名。
a衝突梯次之一(含梯次 id/行程名/起訖日)。
departureId梯次 id。
tripTitle行程名稱。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(YYYY-MM-DD)。
b與 a 日期重疊的另一梯次(含梯次 id/行程名/起訖日)。
departureId梯次 id。
tripTitle行程名稱。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(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>預計帶團結束日期;與開始日期成對
--jsontoko 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回應欄位 · data
id新建立(或重派後)的指派紀錄 id。
toko guide-roster assign --departure 'example-departureId' --guide '<id>' --role leader --status tentative{
"ok": true,
"data": {
"id": "…"
}
}toko guide-roster confirm正式確認某筆指派
參數
<assignmentId>位置參數 · 必填--confirm回應欄位 · data
ok確認成功旗標,恆為 true。
toko guide-roster confirm '<assignmentId>'{
"ok": true,
"data": {
"ok": true
}
}toko guide-roster remove移除某筆指派
參數
<assignmentId>位置參數 · 必填--name-bound-change-reason <text>移除綁名指派的原因(查詢參數)
--confirm回應欄位 · data
ok移除成功旗標,恆為 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回應欄位 · data
id新任 leader 的指派紀錄 id。
removedGuideIds被移除的舊 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)
--jsontoko guides list{
"ok": true,
"data": "…"
}toko guides get單一嚮導明細(依 id 或 --slug)
參數
<id>位置參數 · 必填--slug <slug>依嚮導公開頁網址代稱(slug)精確查單筆(選填)
--json回應欄位 · data
id嚮導 id(guide_ 前綴)。
name嚮導姓名。
slug公開頁網址代稱(slug;小寫英數與連字號)。
bio簡介/經歷(可空)。
avatarUrl大頭照圖片網址(可空)。
specialties專長領域清單。
careerStartYear入行年份(西元年;可空)。
yearsExperience帶團年資(年數;由入行年份與台北今年推算,唯讀;可空)。
contactPhone聯絡電話(可空)。
contactEmail聯絡 Email(可空)。
status嚮導狀態:active 啟用/inactive 停用。
categoryId嚮導分類 id(gcat_ 前綴;名稱與順序見 guide-categories)。null = 未分類。
internalNote內部備註(只給後台看,前台不顯示;可空)。
createdAt建檔時間。
updatedAt最後更新時間。
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回應欄位 · data
id新建立的嚮導 id。
slug嚮導公開頁網址代稱(未帶則系統自動產生)。
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回應欄位 · data
ok更新成功旗標,恆為 true。
toko guides update '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko guides archive封存嚮導(status→inactive;重啟用請用 guides update --status active)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok封存成功旗標,恆為 true。
toko guides archive '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko guides invite-account開通嚮導 portal 登入帳號(寄啟用信到嚮導資料的聯絡 Email)
參數
<id>位置參數 · 必填--name <n>嚮導帳號的顯示姓名
--confirm--json回應欄位 · data
email已開通登入帳號的 Email(= 嚮導資料的聯絡 Email)。
activationSent是否已寄出啟用信。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正式姓名。
gender性別 male / female / other;未填為 null。
emergencyContactNameemergencyContactPhoneenglishName英文姓名(與護照一致)。
idNumberMask身分證遮罩(例:*******789);null = 未填。
passportNoMask護照號碼遮罩;null = 未填。
birthDate生日(YYYY-MM-DD)。
nationality國籍;空值 = 本國。
address通訊地址。
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回應欄位 · data
changedFields這次實際寫入的欄位。
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 護照號碼。
value解密後的證件全碼;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--json回應欄位 · data
filename已匯入的檔名。
result匯入結果(新建 / 更新 / 失敗筆數與逐列結果)。
created新建筆數。
updated更新筆數。
failed失敗筆數(含 dry-run 就是 error 的列)。
rows逐列結果。
rowNumber試算表列號。
statuscreated 已建立 / updated 已更新 / error 失敗未寫入。
guideId寫入的嚮導 id(成功列;部分寫入的失敗列也帶,指出哪位嚮導已被改過)。
name暱稱。
message失敗原因(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回應欄位 · data
oktoko guides certificate-types-update '<id>'{
"ok": true,
"data": {
"ok": "…"
}
}toko guides certificate-types-delete刪除 guide-certificate-types/[id]
參數
<id>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
okremovednametoko guides certificate-types-delete '<id>'{
"ok": true,
"data": {
"ok": "…",
"removed": {
"name": "…"
}
}
}toko guides certificate-types-list查詢 guide-certificate-types
參數
--data <json>--json回應欄位 · data[]
idnamesortOrderisActive停用 = 不供新證照選用(既有證照不受影響)。
certificateCount引用此類別的證照數(>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回應欄位 · data
okidtoko 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回應欄位 · data
oktoko guides categories-update '<id>'{
"ok": true,
"data": {
"ok": "…"
}
}toko guides categories-delete刪除 guide-categories/[id]
參數
<id>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
okremovednametoko guides categories-delete '<id>'{
"ok": true,
"data": {
"ok": "…",
"removed": {
"name": "…"
}
}
}toko guides categories-list查詢 guide-categories
參數
--data <json>--json回應欄位 · data[]
idnamesortOrderisActive停用 = 不供新選用(既有嚮導照舊顯示這個分類)。
guideCount引用此分類的嚮導數(>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回應欄位 · data
okidtoko 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回應欄位 · data
okidtoko 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回應欄位 · data
oktoko guides certificate-delete '<id>' '<certificateId>'{
"ok": true,
"data": {
"ok": true
}
}toko guides certificates-list查詢 guides/[id]/certificates
參數
<id>位置參數 · 必填--data <json>--json回應欄位 · data[]
idtypeIdtypeNamecertNumber證號(明文)。只給 guide_pii.read 看,其餘讀者由呼叫端清成 null。
issuedOnexpiresOnNULL = 終身有效。
attachmentUrl私有掃描件 URL(/api/assets 以 guide_pii.read 閘讀取)。
hasPii有沒有證號或掃描件。不看 `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回應欄位 · data
okidtoko 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本頁的手記文章列表。
id手記文章 id(journalPost_ 前綴)。
slug文章公開頁網址代稱(slug)。
title文章標題。
excerpt摘要(列表/SEO 用;可空)。
coverImageUrl封面圖網址(可空)。
contentMdx內文原始 MDX 內容。
authorGuideId作者嚮導 id(未指定作者時 null)。
lengthReturns the length of a String object.
seoTitleSEO 標題(覆寫 <title>;可空)。
seoDescriptionSEO 描述(meta description;可空)。
ogImageUrlOpen Graph 分享圖網址(可空)。
status文章狀態:draft 草稿/published 已發佈/archived 已封存。
publishedAt首次發佈時間(尚未發佈為 null)。
createdAt建檔時間。
updatedAt最後更新時間。
total符合條件的文章總數(跨頁)。
page目前頁碼(從 1 起)。
pageSize每頁筆數。
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手記文章 id(journalPost_ 前綴)。
slug文章公開頁網址代稱(slug)。
title文章標題。
excerpt摘要(列表/SEO 用;可空)。
coverImageUrl封面圖網址(可空)。
contentMdx內文原始 MDX 內容。
authorGuideId作者嚮導 id(未指定作者時 null)。
lengthReturns the length of a String object.
seoTitleSEO 標題(覆寫 <title>;可空)。
seoDescriptionSEO 描述(meta description;可空)。
ogImageUrlOpen Graph 分享圖網址(可空)。
status文章狀態:draft 草稿/published 已發佈/archived 已封存。
publishedAt首次發佈時間(尚未發佈為 null)。
createdAt建檔時間。
updatedAt最後更新時間。
toko journal get '<id>'{
"ok": true,
"data": {
"id": "…",
"slug": "…",
"title": "…",
"excerpt": "…",
"coverImageUrl": "…",
"contentMdx": "…",
"authorGuideId": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"status": "archived",
"publishedAt": "…",
"createdAt": "…",
"updatedAt": "…"
}
}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新建立的手記文章 id。
slug文章公開頁網址代稱(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更新成功旗標,恆為 true。
toko journal update '<id>' --title 'example-title' --content-mdx 'example-contentMdx'{
"ok": true,
"data": {
"ok": true
}
}toko journal archive封存手記
參數
<id>位置參數 · 必填--json回應欄位 · data
ok封存成功旗標,恆為 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匯率牌價列 ID。
rateDate掛牌日期('YYYY-MM-DD',Asia/Taipei)。
currencyISO 4217('JPY' / 'IDR' / 'USD'…)。
cashBuy各報價 canonical「1 外幣 = ? 台幣」(numeric → 字串原值保精度;NULL = 該幣別無此報價)。
cashSell現金賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。
spotBuy即期買入匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。
spotSell即期賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。
source牌價來源:bot 台銀自動抓取 / manual 租戶手動覆蓋。
createdAt建立時間。
updatedAt最後更新時間。
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換算的外幣幣別(ISO 4217 三碼)。
date換算基準日期(YYYY-MM-DD)。
quote使用的報價類型(cash_buy / cash_sell / spot_buy / spot_sell)。
rate解析出的匯率「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回應欄位 · data
ok是否覆蓋寫入成功。
id寫入 / 更新的 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本頁請款單列。
id請款單 ID。
requestNumber請款單號(人可讀,每租戶流水號)。
status核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。
payeeType收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。
payeeName收款對象名稱。
amountTwd請款總額(TWD 整數;= 細項小計合計,代扣稅前)。
netAmountTwd實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。
taxAmountTwd代扣稅額(TWD 整數)。
departureId關聯梯次 ID;未歸屬特定出團為 null。
departureLabel關聯梯次顯示標籤(行程名稱+出發日);無則為 null。
description請款單摘要說明。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單人 user ID。
createdByName建單人姓名;查無為 null。
paidAt標記付款完成時間;未付為 null。
submittedAt送審時間;未送審為 null。
approvedAt核准時間;未核准為 null。
paperSignedBy紙本簽核人;未簽為 null。
total符合篩選條件的總筆數(跨全部分頁)。
page目前頁碼(從 1 起算)。
pageSize每頁筆數。
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收款銀行帳號。
payeeBankName收款銀行名稱。
payeeBankBranch收款銀行分行。
payeeTaxId收款對象統一編號 / 稅籍編號。
submittedByUserId送審人 user ID;未送審為 null。
submissionEventIdAudit event for the current submission.
submittedByName送審人姓名;無則為 null。
approvedByUserId核准人 user ID;未核准為 null。
approvedByName核准人姓名;無則為 null。
paidByUserId標記付款人 user ID;未付為 null。
paidByName標記付款人姓名;無則為 null。
rejectedAt退件時間;未退件為 null。
rejectedByName退件人姓名;無則為 null。
rejectionReason退件原因;無則為 null。
cancelledAt取消時間;未取消為 null。
cancelledByName取消人姓名;無則為 null。
cancellationReason取消原因;無則為 null。
pdfGeneratedAt請款單 PDF 產生時間;未產生為 null。
paperPrintedAt紙本列印時間;未列印為 null。
bankReference銀行匯款交易參考號(付款後回填);無則為 null。
sourceType來源類別(`departure_cost` 梯次成本 / `profit_share` 折扣碼分潤 / `migration` 匯入); 手動建單為 null。**非 null = 細項與來源列連動,不可編輯**(見 `updatePaymentRequest`)。
items請款細項清單。
id請款細項 ID。
category細項類別(如住宿、交通、餐食)。
description細項說明。
quantity數量。
unitPriceTwd單價(TWD 整數;負值表折讓)。
totalTwd細項小計(TWD 整數;= 數量 × 單價)。
notes細項備註;無則為 null。
sortOrder顯示排序(由小到大)。
audit稽核軌跡(狀態機每次轉移一筆,時間新到舊或建立序)。
id稽核記錄 ID。
action動作代號(如 payable.create、payable.submit、payable.approve)。
createdAt動作發生時間。
actorUserId操作者 user ID;系統動作為 null。
actorName操作者姓名;無則為 null。
metadata動作附帶的結構化資料(欄位隨 action 而定)。
ipAddress操作來源 IP;無則為 null。
id請款單 ID。
requestNumber請款單號(人可讀,每租戶流水號)。
status核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。
payeeType收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。
payeeName收款對象名稱。
amountTwd請款總額(TWD 整數;= 細項小計合計,代扣稅前)。
netAmountTwd實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。
taxAmountTwd代扣稅額(TWD 整數)。
departureId關聯梯次 ID;未歸屬特定出團為 null。
departureLabel關聯梯次顯示標籤(行程名稱+出發日);無則為 null。
description請款單摘要說明。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單人 user ID。
createdByName建單人姓名;查無為 null。
paidAt標記付款完成時間;未付為 null。
submittedAt送審時間;未送審為 null。
approvedAt核准時間;未核准為 null。
paperSignedBy紙本簽核人;未簽為 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草稿狀態的請款單數。
submittedCount已送審待核准的請款單數。
approvedCount已核准待付款的請款單數。
paidCount已付款的請款單數。
thisMonthPaidCount本月已付款的請款單數。
thisMonthAmount本月已付款的實付淨額合計(TWD 整數;台北月起算)。
totalApprovedAmount已核准未付的實付淨額合計(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建議的請款細項類別(如住宿)。
description建議的細項說明(住宿廠商 × 房型 × 晚數)。
quantity建議數量(間數 × 晚數)。
unitPriceTwd建議單價(TWD 整數;每間每晚成本)。
totalTwd建議小計(TWD 整數;= 數量 × 單價)。
suggestedPayee建議的收款對象(住宿供應商名稱);查無為 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回應欄位 · data
id新建立請款單的 id。
requestNumber新建立請款單的單號(人可讀)。
status建立後狀態(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回應欄位 · data
ok原核准操作已完成;重試不代表目前狀態。
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回應欄位 · data
ok原送審操作已完成;重試不代表目前狀態。
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回應欄位 · data
ok原退回操作已完成;重試不代表目前狀態。
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回應欄位 · data
ok是否標記付款成功(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回應欄位 · data
ok是否取消成功(idempotent,已取消再呼叫仍為 true)。
toko payment-requests cancel '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko payment-requests mark-signed記錄紙本簽核人
參數
<id>位置參數 · 必填--signed-by <name>紙本簽核人姓名(必填)
--confirm回應欄位 · data
ok是否記錄紙本簽核人成功。
toko payment-requests mark-signed '<id>' --signed-by 'example-signedBy'{
"ok": true,
"data": {
"ok": true
}
}toko payment-requests mark-printed標記 PDF/紙本已產生(idempotent)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok是否標記 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回應欄位 · data
ok是否更新成功。
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本頁付款嘗試列。
reconciliationTransactionsidamountTwdaccountNamestatusid付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。
orderId所屬訂單 ID。
orderNumber所屬訂單編號(人可讀)。
merchantTradeNoprovider_order_ref(= 我們產的 MerchantTradeNo)。
providerTradeNo金流商回傳的交易序號(未成交或手動入帳為 null)。
provider金流商代號(如 ecpay、test;手動入帳為 manual)。
paymentMethod付款方式(如信用卡、ATM 虛擬帳號)。
paymentChannel收款通路與付款方式。舊收款缺少付款方式時標示未知。
amountTwd此筆嘗試的金額(TWD 整數)。
purpose收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。
receivingAccountName錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。
statusattempt 狀態:pending | submitted | succeeded | failed | expired。
refunded此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。
needsManualReview此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。
paidAt實際入帳(現金結算)時間;未結算為 null。
bankCreditedOn銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。
createdAt此筆付款嘗試的建立時間。
customerName付款客戶姓名。
customerEmail付款客戶 email。
tripTitle訂單對應的行程名稱。
total符合篩選條件的總筆數(跨全部分頁)。
page目前頁碼(從 1 起算)。
pageSize每頁筆數。
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
pendingReconciliationCounttotalAmount累計實收現金(payment_transactions in)。
paidCount已成功收款的付款嘗試數。
paidEcpayCount已成功收款裡走綠界(provider = ecpay)的嘗試數。
paidAtmCount已成功收款裡走虛擬 ATM(method = atm)的嘗試數。
pendingCount待付 / 處理中的付款嘗試數(pending、submitted)。
failedCount失敗或逾期的付款嘗試數(failed、expired)。
refundedCount有關聯退款 / 退單的付款嘗試數。
needsManualReviewCount近期需要人工核對後退款的付款嘗試數。只算最近 90 天收到的異常回呼;更早的紀錄仍會 帶著 `PaymentRow.needsManualReview`,用 `status=needs_manual_review` 篩選查得到。
thisMonthAmount本月累計實收現金(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符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。
reconciliationTransactionsidamountTwdaccountNamestatusid付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。
orderId所屬訂單 ID。
orderNumber所屬訂單編號(人可讀)。
merchantTradeNoprovider_order_ref(= 我們產的 MerchantTradeNo)。
providerTradeNo金流商回傳的交易序號(未成交或手動入帳為 null)。
provider金流商代號(如 ecpay、test;手動入帳為 manual)。
paymentMethod付款方式(如信用卡、ATM 虛擬帳號)。
paymentChannel收款通路與付款方式。舊收款缺少付款方式時標示未知。
amountTwd此筆嘗試的金額(TWD 整數)。
purpose收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。
receivingAccountName錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。
statusattempt 狀態:pending | submitted | succeeded | failed | expired。
refunded此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。
needsManualReview此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。
paidAt實際入帳(現金結算)時間;未結算為 null。
bankCreditedOn銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。
createdAt此筆付款嘗試的建立時間。
customerName付款客戶姓名。
customerEmail付款客戶 email。
tripTitle訂單對應的行程名稱。
total符合篩選條件的總筆數。
truncated是否因達安全上限而截斷(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收款帳戶 id;null = 未歸戶桶。
code帳戶代碼;未歸戶桶為 null。
displayName帳戶顯示名;未歸戶桶為 null。
kind帳戶類型(bank / cash / gateway);未歸戶桶為 null。
inTwd期間內 direction='in' 的金額合計。
outTwd期間內 payment_transactions direction='out' 的金額合計(客戶退款 / gateway 出)。
payableOutTwd期間內供應商出款合計(payables paid 的 net_amount_twd;非 order-scoped,獨立來源 §3.1)。 **不含掛出款批次的 payable**(payout_batch_line_id 非 NULL)——批次出帳事實是一筆 account_transfers(銀行一筆 net),個別 payable 再計入即雙計。
transferInTwd期間內帳戶間移轉**轉入**合計(account_transfers to 端 amount_twd;spec §3.2 / §3.3 口徑)。 排除 refund_payout(markRefundPaid 同 tx 雙寫,現金列已計入 outTwd)與沖正列 / 被沖正列 (更正記錄,非銀行流水)。
transferOutTwd期間內帳戶間移轉**轉出**合計(from 端 amount_twd + fee_twd 實際離帳額;同上排除規則)。
netTwd淨額 = in + transferIn − out − payableOut − transferOut(純現金流向;對帳找銀行入帳用毛額)。
txCount期間內這帳戶的活動筆數(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收款帳戶 ID。
code帳戶代碼(租戶內唯一穩定識別)。
displayName帳戶顯示名。
kind帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。
gatewayProvider綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `accounts/gateway-providers.ts`。
bankName銀行名稱;現金/閘道帳戶為 null。
accountNo銀行帳號;現金/閘道帳戶為 null。
bankCodebankBranchaccountHoldercanReceive可收款(幾乎都 true)。
canRemit可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。
canChargeback可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。
canPaySupplier付款渠道:出團準備的付款登記區可選它付供應商(#1375)。
isDeprecated廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。
isSettlementMaster主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。
payoutAccountId撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。
currency帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位(小者在前)。
usedCount被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。
currencyLocked幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。
createdAt建立時間。
updatedAt最後更新時間。
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結算月份(YYYY-MM,Asia/Taipei)。
matrix兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。
lines各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補淨額(恆正 > 0)。
components組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。
label組成項標籤(如某費用類型 / 代墊來源)。
amountTwd簽名金額(相對 debtor→creditor 視角)。
unclassified未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。
byAccountlanding 帳戶 → 未分類本金合計。
accountId收款帳戶 ID;未歸戶為 null。
principalTwd該帳戶未分類收款本金合計(TWD 整數)。
totalTwd未分類收款本金總額(TWD 整數)。
obligations本期相關掛帳(period_settlement + adjustment,含結清進度)。
id帳戶間掛帳 ID。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補目標總額(TWD 整數,恆正)。
settledAmountTwd已結清金額(TWD 整數,0 ≤ settled ≤ amount)。
outstandingTwd待結餘額(派生 = amount − settled,>= 0)。
reason掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份(YYYY-MM,Asia/Taipei)。
status結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註;無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
carriedForward跨期掛帳結轉基數(上期未結 period_settlement 殘額,已種入 matrix 淨額;此處供顯示明細 + 小計)。
lines上期未結 period_settlement 殘額逐筆明細(已種入本期互抵基數)。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
outstandingTwd殘額 = amount_twd − settled_amount_twd(恆正 > 0)。
originPeriod原始產生月份(YYYY-MM,供顯示「來源期」)。
totalTwd結轉殘額小計(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帳戶間移轉 ID。
kind移轉類型:fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 期初 / reversal 沖正 / payout_batch 出款批次匯出(系統落帳)/ gateway_payout 金流商撥款。
fromAccountId出帳帳戶 ID;期初等單邊移轉為 null。
toAccountId進帳帳戶 ID;單邊移轉為 null。
amountTwd移轉金額(TWD 整數)。
feeTwd手續費(TWD 整數)。
currency外幣幣別(ISO 4217;純台幣移轉為 null)。
foreignAmount外幣金額(整數;非外幣移轉為 null)。
feeForeign外幣手續費(整數;無則為 null)。
grossRate換匯牌價(numeric → 字串原值保精度;顯示/溯源用)。
settlementPeriod對應月結期間(YYYY-MM);未歸屬月結為 null。
obligationId沖減的帳戶間掛帳 ID;未沖減掛帳為 null。
reversesTransferId被本筆沖正的原移轉 ID(kind='reversal' 時非 null)。
occurredAt移轉日期('YYYY-MM-DD',date 欄)。
note備註;無則為 null。
createdByUserId登錄人 user ID。
createdAt建立時間。
updatedAt最後更新時間。
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現金列 ID。
directionin = 收款(加項)/ out = 刷退(撥款內扣的扣項)。
orderId訂單 ID。
retainedFundIdorderNumber訂單編號。
date發生日('YYYY-MM-DD',Asia/Taipei 牆鐘)。
amountTwd金額(TWD 整數,正數;刷退的正負看 direction)。
feeTwd現金列記的金流手續費(TWD 整數;多為付款回呼宣告的估計值)。
providerTradeNo金流訂單編號(金流商交易序號,或登記收款時填的編號;沒有為 null)。
providerRefundNotoko 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帳戶間掛帳 ID。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補目標總額(TWD 整數,恆正)。
settledAmountTwd已結清金額(TWD 整數,0 ≤ settled ≤ amount)。
outstandingTwd待結餘額(派生 = amount − settled,>= 0)。
reason掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份(YYYY-MM,Asia/Taipei)。
status結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註;無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
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退款執行列(合併 approved 待執行 + paid 已執行,或收斂為指定段)。
creationSourceid退款單 ID。
refundNumber退款單號(人可讀,每租戶流水號)。
orderId所屬訂單 ID。
ownerIdretainedFundIdorderNumber所屬訂單編號(人可讀);無則為 null。
status退款工作流狀態:draft / submitted / approved / processing / paid / failed / cancelled。
refundKind退款種類:receivable_reduction 減應收退款(取消 / 降價 / 服務失敗)/ overpayment_return 溢收退還(不動應收,只退多收現金)。
affectsReceivable是否減少應收(receivable_reduction 為 true、overpayment_return 為 false;溢收退還不列入 refund_state)。
amountTwd退款金額(TWD 整數,正值)。
method退款方式:original_gateway 原路退刷 / bank_transfer 銀行匯款 / cash 現金 / manual 手動。
reason退款原因說明。
createdAt退款單建立時間。
paidAt實際退款出款(現金結算)時間;未執行為 null。
createdByName建單人姓名;無則為 null。
executionMethod退款執行方法:chargeback 原信用卡刷退 / remit 匯出;未指定為 null。
gatewayExecutionMode選填gatewayNeedsReview近 90 天已完成帳務、且明確記錄自動退刷降級的退款,需人工核對;不代表可重試。
originAccountId出款來源帳戶 ID(從哪個收款帳戶退出);未指定為 null。
adminFeeTwd內扣手續費(TWD 整數;自退款金額中扣除的行政費)。
remitFeeTwd匯款手續費(TWD 整數;銀行匯出的轉帳費)。
payeeAccountName收款人戶名(匯款退款用);無則為 null。
payeeBankCode收款銀行代碼(匯款退款用);無則為 null。
payeeBranchCode收款分行代碼(匯款退款用,選填);無則為 null。
payeeAccountNumber收款帳號(匯款退款用);無則為 null。
customerName訂購人姓名;無則為 null。
orderCancellationFeeTwd所屬訂單的退改費(TWD 整數,公司收下不退的錢);未收退改費為 null。不含已付、不退的 換梯手續費(customer-cancellation §8.9),那筆寫在退款單事由。
orderCancellationReason所屬訂單的取消事由:lottery_lost 未中籤 / group_not_confirmed 未成團 / customer_request 客人取消 / admin 後台取消 / no_show 未報到 / other 其他;未取消為 null。
paidByName標記已退款的人;未執行為 null。
payoutAccountId實際出款帳戶 ID(已執行退款的出帳現金列歸戶);未執行或未歸戶為 null。
waitingDays從登記到現在已等待的天數;已退款、已失敗、已取消的退款單為 null。
total回傳的退款執行筆數。
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結算月份(YYYY-MM,Asia/Taipei)。
matrix兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。
lines各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補淨額(恆正 > 0)。
components組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。
label組成項標籤(如某費用類型 / 代墊來源)。
amountTwd簽名金額(相對 debtor→creditor 視角)。
unclassified未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。
byAccountlanding 帳戶 → 未分類本金合計。
accountId收款帳戶 ID;未歸戶為 null。
principalTwd該帳戶未分類收款本金合計(TWD 整數)。
totalTwd未分類收款本金總額(TWD 整數)。
obligations本期相關掛帳(period_settlement + adjustment,含結清進度)。
id帳戶間掛帳 ID。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補目標總額(TWD 整數,恆正)。
settledAmountTwd已結清金額(TWD 整數,0 ≤ settled ≤ amount)。
outstandingTwd待結餘額(派生 = amount − settled,>= 0)。
reason掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份(YYYY-MM,Asia/Taipei)。
status結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註;無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
carriedForward跨期掛帳結轉基數(上期未結 period_settlement 殘額,已種入 matrix 淨額;此處供顯示明細 + 小計)。
lines上期未結 period_settlement 殘額逐筆明細(已種入本期互抵基數)。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
outstandingTwd殘額 = amount_twd − settled_amount_twd(恆正 > 0)。
originPeriod原始產生月份(YYYY-MM,供顯示「來源期」)。
totalTwd結轉殘額小計(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結算月份(YYYY-MM,Asia/Taipei)。
matrix兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。
lines各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補淨額(恆正 > 0)。
components組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。
label組成項標籤(如某費用類型 / 代墊來源)。
amountTwd簽名金額(相對 debtor→creditor 視角)。
unclassified未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。
byAccountlanding 帳戶 → 未分類本金合計。
accountId收款帳戶 ID;未歸戶為 null。
principalTwd該帳戶未分類收款本金合計(TWD 整數)。
totalTwd未分類收款本金總額(TWD 整數)。
upserts本次 run 對每條互抵列 upsert 的結果(含冪等護欄調整)。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
derivedAmountTwd本次派生的目標淨額。
appliedAmountTwd實際落地的掛帳 amount_twd(受冪等護欄約束,不低於已 settled)。
obligationId對應的帳戶間掛帳 ID(本次 upsert 的目標列)。
action本次動作:created 新建 / updated 更新 / floored_to_settled 派生低於已結被護欄下限鎖住。
adjustmentTwd派生與基準(原 amount + 已動帳 adjustment 簽名和)的差額絕對值(> 0 表示有缺口)。
adjustmentObligationId缺口對應的引擎 adjustment 掛帳 id(新開或重跑沿用 / 改額的同一條;action='floored_to_settled' 時非 null)。
deletedObligationIds本次 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回應欄位 · data
ok是否登錄成功(移轉 + 沖減掛帳的原子交易皆完成)。
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--source-type <payment_transaction|payable|account_transfer>配對來源種類:payment_transaction / payable / account_transfer
--source-id <id>配對來源 ID(該帳戶內未被配對的 ERP 候選)
--reason <r>略過原因(必填;如「手續費」「利息」)
回應欄位 · data
imports該帳戶的對帳單批次清單(新到舊)。
id對帳單批次 ID。
periodStart批次期間起日('YYYY-MM-DD',含當日)。
periodEnd批次期間迄日('YYYY-MM-DD',含當日)。
filename匯入的檔名。
createdAt匯入時間。
lineCount批內總行數。
autoCount自動配對的行數。
manualCount人工配對的行數。
unmatchedCount尚未配對的行數。
ignoredCount已略過(ignored)的行數。
excludedCount已解除配對(excluded)的行數。
lines該帳戶所有對帳單行(跨批次)。
id對帳單行 ID。
importId所屬對帳單批次 ID。
lineNo檔案內行號(1 起算)。
txnDate交易日期('YYYY-MM-DD')。
direction現金流向:in 存入 / out 支出。
amountTwd金額(TWD 整數)。
memo摘要 / 備註文字。
status配對狀態:unmatched 未配 / auto 自動 / manual 人工 / ignored 略過 / excluded 已解除。
matchedSourceType已配對來源種類(payment_transaction / payable / account_transfer);未配為 null。
matchedSourceId已配對來源 ID;未配為 null。
ignoredReason略過原因;非 ignored 為 null。
progress配對進度彙總。
total總行數。
matched已配對行數(auto + manual)。
unmatched未配對行數。
ignored已略過行數。
excluded已解除配對行數。
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結算期間(YYYY-MM,Asia/Taipei 出團月)。
departureSummary梯次彙總(區塊 1):出團月落於 period 的各梯次收入 / 成本 / 毛利。
departureId梯次 ID。
tripTitle團名。
departureDate出團日期(YYYY-MM-DD)。
pax出團人數(該梯次確認人數)。
revenueTwd總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。
cancellationFeeTwd已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。
realCostTwd真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。
grossProfitTwd毛利毛估 = revenue − realCost(含房費)。
costLines成本掛帳逐筆(區塊 2):該期梯次上所有 departure_costs 成本列。
id成本列 ID。
tripTitle團名。
departureDate所屬梯次出團日期(YYYY-MM-DD)。
category成本分類(如 交通 / 餐費 / 保險 / 嚮導)。
vendor廠商:已建檔廠商名優先,否則用成本列上填寫的廠商名;null = 未填。
amountTwd代墊額(真實成本,TWD 整數)。
invoiceAmountTwd憑證額(外帳可申報金額,TWD 整數)。
isDeclarable有無發票憑證。
reviewStatus覆核狀態:掛了支出證明單則用其 status(pending/approved),否則由有無憑證派生。
payables應付清單(區塊 3):該期歸屬的請款單(payables)。
payableNumber請款單號(人類可讀)。
tripTitle團名(未綁定梯次的手動請款顯示「未綁定梯次」)。
payeeName受款對象(供應商 / 嚮導 / 派車人等)。
amountTwd請款金額(整數 TWD)。
statusdraft | submitted | approved | paid | cancelled | rejected。
receivables應收清單(區塊 4):該期梯次上的 tour 訂單應收 / 實收 / 待收。
orderId訂單 ID(後台訂單頁連結用)。
orderNumber訂單編號。
tripTitle團名(該訂單在期間內任一梯次的團名)。
departureDate出團日(YYYY-MM-DD)。同一行程同月常有多個梯次(例:10/15、10/16、10/22 三梯), 只看團名分不出是哪一梯,追尾款時得靠這欄(issue 600)。 ⚠️ 與 `tripTitle` 同一列取出(兩欄必定同梯),但口徑同樣是「該訂單在期間內**任一** 梯次」:跨梯次訂單只顯示最早那一梯,而 `receivableTwd` 是整張單未攤提的應收。真正 逐梯辨識要把來源改成 per (order, departure) 並接上 `order-money/allocation.ts` 的攤提, 屬系統級 follow-up,不在本欄範圍。
primaryTravelerName主要旅客姓名:有標記 `is_primary` 取該列,沒標記就取最早建立的旅客(與 departure-prep / agreements / traveler-validation 同一套取法——匯入的歷史單 可能整單都沒標主要旅客)。訂單完全沒有旅客列時為 null。 刻意不取下單會員名:一張訂單的下單者與旅客常常不是同一人(CONTEXT.md「旅客」)。
receivableTwd應收金額(TWD 整數)。
receivedTwd實收金額(收款減退款,TWD 整數)。
outstandingTwd待收 = 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結算期間(YYYY-MM,Asia/Taipei 出團月),回聲請求參數。
departureSummary梯次彙總:出團月落於 period 的各梯次收入 / 真實成本 / 毛估毛利。
departureId梯次 ID。
tripTitle團名。
departureDate出團日期(YYYY-MM-DD)。
pax出團人數(該梯次確認人數)。
revenueTwd總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。
cancellationFeeTwd已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。
realCostTwd真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。
grossProfitTwd毛利毛估 = 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成本範本 id(ct_ 前綴)。
name成本範本名稱。
toko cost-templates list{
"ok": true,
"data": [
{
"id": "…",
"name": "…"
}
]
}toko cost-templates get單一成本範本完整明細(含成本行)
參數
<id>位置參數 · 必填--json回應欄位 · data
lines成本行明細(品項 × 單價 × 數量模型)。
id成本行 ID。
templateId所屬成本範本 ID。
category成本分類(如 交通 / 餐費 / 保險)。
vendorName供應商 / 廠商名(選填)。
description摘要說明(選填)。
unitPriceTwdTWD 行的單價;外幣行 null。
currency幣別('TWD' = 台幣行)。
unitPriceForeign外幣行的外幣單價;TWD 行 null。
internalRateSource外幣行的內帳匯率來源;TWD 行 null。
fxAccountIdinternalRateSource='fx_account' 時的外幣帳戶 id。
quantityMode數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。
quantityFixedfixed 模式的固定數量;headcount 模式為 null。
headcountComponentsheadcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。
groupDivisorheadcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。
isDeclarable是否預設有合法憑證(帶入成本列的 is_declarable 初值)。
sortOrder顯示排序。
id成本範本 ID。
name範本名稱。
description範本說明(選填)。
status狀態:active 啟用 / archived 已封存。
lineCount成本行數(派生)。
boundTripCount綁定行程數(派生)。
appliedDepartureCount套用過本範本的梯次數(派生:departure_costs 經 template_line_id 追溯)。
createdAt建立時間。
updatedAt最後更新時間。
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新建成本範本 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是否更新成功。
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新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 null。
id新建成本明細行 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是否更新成功。
rateNotice新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 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是否刪除成功。
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梯次標題(trip title)。
tripSlug行程 slug(URL 識別)。
departureDate出團日期(YYYY-MM-DD)。
returnDate回程日期(YYYY-MM-DD)。
groupCode團號(group-code),未產生為 null。
pax報名人數(非取消單 party_size 合計)。
departureStatus梯次狀態。`'cancelled'` 的列在毛利視圖裡只帶已認列退改費(訂單應收與成本都是 0), 呈現面必須標出來,否則會被當成一個真的有出團的梯次(issue 601)。
departureId梯次 ID。
revenueTwd本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。
orderRevenueTwd訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。
cancellationFeeTwd已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。
realCostTwd內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。
declarableCostTwd外帳可申報成本(各成本列憑證額合計,TWD 整數)。
nonDeclarableCostTwd不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。
costBilledTwd已轉請款成本。
costUnbilledTwd未轉請款成本;不含即付(當下已付、不轉請款)。
grossProfitTwd**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。
feeEcpayTwd預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。
feeFongshouTwd預估豐收款手續費(**參考預估**,非權威)。
taxEstTwd預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。
estimatedNetProfitTwd**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。
marginPct毛利率(grossProfit / revenue),revenue=0 時為 null。
pendingProofCount待核(pending)支出證明單數。
feeRates套用的費率(呈現用)。
ecpayFeeBps預估綠界手續費率(basis points,270 = 2.70%)。
fongshouFeeBps預估豐收款手續費率(basis points,50 = 0.50%)。
profitTaxBps預估發票 / 營所稅率(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梯次 ID。
revenueTwd本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。
orderRevenueTwd訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。
cancellationFeeTwd已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。
realCostTwd內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。
declarableCostTwd外帳可申報成本(各成本列憑證額合計,TWD 整數)。
nonDeclarableCostTwd不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。
costBilledTwd已轉請款成本。
costUnbilledTwd未轉請款成本;不含即付(當下已付、不轉請款)。
grossProfitTwd**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。
feeEcpayTwd預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。
feeFongshouTwd預估豐收款手續費(**參考預估**,非權威)。
taxEstTwd預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。
estimatedNetProfitTwd**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。
marginPct毛利率(grossProfit / revenue),revenue=0 時為 null。
pendingProofCount待核(pending)支出證明單數。
feeRates套用的費率(呈現用)。
ecpayFeeBps預估綠界手續費率(basis points,270 = 2.70%)。
fongshouFeeBps預估豐收款手續費率(basis points,50 = 0.50%)。
profitTaxBps預估發票 / 營所稅率(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成本列 ID。
departureId所屬梯次 ID。
category成本分類(如 交通 / 餐費 / 保險 / 嚮導)。
vendorName供應商 / 廠商名(選填)。
description摘要說明(選填)。
receiptImageUrl憑證照片 URL(G3-2);未附照片 null。app-route 私有 URL,讀取經 route 權限閘。
amountTwd代墊 / 實付額(內帳真實成本,整數 TWD)。
invoiceAmountTwd外帳可申報額(internal-external-ledger §2.1)。
isDeclarable是否取得合法憑證。
reviewStatus覆核狀態 'pending' | 'approved'(L'):pending 不計入毛利 / 可申報(UI 須標示、停用轉請款)。
currency成本幣別(ISO 4217);'TWD' = 台幣列。
foreignAmount外幣金額(最小單位整數);TWD 列 null。
internalRateSource內帳匯率來源;TWD 列 null。
fxAccountIdinternalRateSource='fx_account' 時的外幣帳戶 id。
internalRate內帳匯率快照(numeric 字串);TWD 列 null。
externalRate外帳匯率快照(numeric 字串,台銀牌告);TWD 列 null。
feeCategory費用類型 tag(account-settlement §3.4,成本側類別→領域帳戶映射;null = 未 tag)。
quantityMode計價方式 'fixed' / 'headcount';一次性總額列 null。
headcountComponentsheadcount 人頭組合;非 headcount 列 null。
groupDivisorheadcount 組距;非 headcount 列 null。
quantity解析後(headcount)或自訂(fixed)的數量;一次性總額列 null。
unitPriceTwd單價(台幣整數);一次性總額列 null。
expenseProofId無發票支出掛的支出證明單 id(null = 有憑證)。
proofNumber支出證明單單號(join expense_proofs,null = 無)。
proofStatus支出證明單狀態 'pending' | 'approved'(null = 無)。
payableId已轉請款時連結的請款單 ID(null = 未轉請款)。
payableNumber連結請款單的人類可讀單號(null = 未轉請款)。
payableStatus連結請款單的狀態(draft / submitted / approved / paid…;null = 未轉請款)。
paymentMethod付款方式:'request' 走請款核簽;'paid_on_spot' 即付,算已付、不轉請款。
paidOn即付的付款日('YYYY-MM-DD');請款列 null。
paidAccountId即付的付款帳戶 ID;未指定或請款列 null。
spentOn消費日期('YYYY-MM-DD',嚮導填的);後台登記的列 null。
createdAt建立時間。
updatedAt最後更新時間。
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支出證明單 ID。
proofNumber人類可讀單號(EP-YYMMDD-NNN)。
departureId所屬梯次 ID。
payeeName受款對象(自然人 / 廠商)。
amountTwd金額(整數 TWD,對應所掛成本列的 amount_twd)。
reasonNoReceipt無法取得單據的原因(如「自然人」)。
summary支出內容及摘要(選填)。
handlerUserId經手人(建單者)user ID。
approverUserId核准人 user ID(強制 ≠ 經手人);未核准為 null。
status狀態:pending 待核准 / approved 已核准(核准後 append-only)。
approvedAt核准時間;未核准為 null。
createdAt建立時間。
updatedAt最後更新時間。
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成本列 ID。
departureId所屬梯次 ID。
tripTitle團名。
departureDate出團日期(YYYY-MM-DD)。
category成本分類。
vendorName供應商 / 廠商名(選填)。
amountTwd代墊 / 實付額(內帳真實成本,整數 TWD)。
invoiceAmountTwd憑證 / 發票額(外帳可申報,整數 TWD)。
isDeclarable是否取得合法憑證。
createdByName登記者(經手人)姓名。
spentOn消費日期('YYYY-MM-DD',嚮導填的);後台登記的列 null。
createdAt建立時間(嚮導送出時間)。
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取消梯次 ID。
tripTitle團名。
tripSlug行程 slug(URL 識別)。
departureDate原出團日期(YYYY-MM-DD)。
returnDate原回程日期(YYYY-MM-DD)。
groupCode團號(group-code),未產生為 null。
residualCostTwd殘餘成本(TWD 整數):已核准的逐筆成本合計 + 房費底價成本合計。
approvedCostCount已核准成本筆數。
pendingCostCount待覆核成本筆數(UI 提示「還有待覆核成本」)。
roomCostTwd房費殘餘成本(房費底價成本合計,整數 TWD)。
conversion結轉狀態:已結轉為特殊損益時的費用列資訊(expenseId / 金額 / 歸屬月 / 摘要);未結轉為 null。
expenseIdamountTwdperioddescriptiontoko 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回應欄位 · data
id新建立成本列的 ID(dc_ 前綴)。
expenseProofId隨附憑證的 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回應欄位 · data
ok固定為 true:成本列已更新。
toko ledger cost-update '<costId>' --category 'example-category'{
"ok": true,
"data": {
"ok": true
}
}toko ledger cost-delete刪除一筆未轉請款的成本(departure_cost.manage)
參數
<costId>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true:成本列已刪除。
toko ledger cost-delete '<costId>'{
"ok": true,
"data": {
"ok": true
}
}toko ledger approve-proof核准支出證明單(ledger.approve;責任分離)
參數
<proofId>位置參數 · 必填--confirm回應欄位 · data
ok固定為 true:憑證已核准。
toko ledger approve-proof '<proofId>'{
"ok": true,
"data": {
"ok": true
}
}toko ledger approve-declaration覆核嚮導自報待覆核成本(ledger.approve;責任分離)
參數
<costId>位置參數 · 必填--confirm回應欄位 · data
ok固定為 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回應欄位 · data
payableId新建立應付單的 ID(pay_ 前綴)。
payableNumber應付單編號(租戶內流水序號,出款核簽用)。
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回應欄位 · data
id新建立的殘餘成本營業費用列 ID(opx_ 前綴)。
residualCostTwd結轉的殘餘成本金額(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回應欄位 · data
ok固定為 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 領隊嚮導 / supplier 供應商 / staff 員工。
payeeRefId收款對象識別 key:供應商為其 ID,領隊 / 員工為收款人姓名。
payeeName收款對象名稱。
payeeAccountName收款人戶名(supplier 取 suppliers / guide 取 guides;staff 暫無主檔 → null)。
payeeBankCode收款銀行代號(同上來源;無主檔為 null)。
payeeAccountNumber收款帳號(同上來源;無主檔為 null,遮罩回傳)。
grossTwd當月已核准未付的請款單淨額合計(TWD 整數)。
items彙整明細(日期 + 團名 + 金額,唯讀派生,不另存)。
payableId請款單 ID。
payableNumber請款單人類可讀單號。
date梯次出發日('YYYY-MM-DD');無連梯次時 null。
tripLabel團名;無連梯次時 null。
amountTwd該請款單的應付淨額(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收款帳戶 ID。
code帳戶代碼(租戶內唯一穩定識別)。
displayName帳戶顯示名。
kind帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。
gatewayProvider綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `accounts/gateway-providers.ts`。
bankName銀行名稱;現金/閘道帳戶為 null。
accountNo銀行帳號;現金/閘道帳戶為 null。
bankCodebankBranchaccountHoldercanReceive可收款(幾乎都 true)。
canRemit可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。
canChargeback可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。
canPaySupplier付款渠道:出團準備的付款登記區可選它付供應商(#1375)。
isDeprecated廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。
isSettlementMaster主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。
payoutAccountId撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。
currency帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位(小者在前)。
usedCount被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。
currencyLocked幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。
createdAt建立時間。
updatedAt最後更新時間。
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 僅回傳轉帳檔字串
--jsontoko 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回應欄位 · data
id新建立出款批次的 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回應欄位 · data
ok固定為 true:出款批次已確認送出。
toko payouts confirm-batch '<pob_id>'{
"ok": true,
"data": {
"ok": true
}
}toko payouts issue-confirm-token為供應商批次列簽發廠商自助確認 token(idempotent,回 token)
參數
<pobl_id>位置參數 · 必填--confirm回應欄位 · data
token廠商自助確認 token(拼成對外確認頁網址;未過期重複簽發回原 token)。
expiresAttoken 失效時點(簽發起 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費用列 ID。
categoryId費用科目 ID。
categoryCode費用科目代碼(如 rent / salary_admin)。
categoryDisplayName費用科目顯示名。
categoryKind費用科目大類(opex / tax / platform_fee / special)。
period歸屬月(YYYY-MM,損益表據此彙整;可與支付日不同月)。
incurredOn發生 / 支付日期(YYYY-MM-DD);金流商內扣 / 攤提無單一發生日者為 null。
amountTwd金額(整數 TWD,恆正;損 / 益由 direction 表達)。
direction損益方向:'expense' 費用(預設)| 'income' 特殊收入(僅 kind='special' 科目)。
description摘要(廠商 / 品名,如 台中房租 / 委外廣告投放)。
paidFromAccountId出帳帳戶 ID;金流商內扣者為 null。
paidFromAccountName出帳帳戶顯示名。
frontedByUserId代墊者 user ID;非空代表由此人代墊待回補(走請款回補代墊者)。
frontedByName代墊者姓名。
payableId若走出款核簽,連結的請款單 ID;否則 null。
payableNumber連結請款單的人類可讀單號。
recurring月固定標記(人工登記時備註「月固定」;自動生成走範本表,非此欄)。
status'draft'(月固定範本自動生成、待確認,不入損益)| 'confirmed'(計入損益)。
origin'manual'(手動登記)| 'recurring'(月固定範本自動生成)| 'departure_conversion'(取消梯次結轉,§3.4)。
sourceTemplateId生成來源範本(origin='recurring');手動登記為 null。
note備註。
createdByUserId經手人 user ID(建立此費用列者)。
createdAt建立時間。
updatedAt最後更新時間。
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費用類別 ID。
code科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。
displayName顯示名(如 房租 / 行政薪資 / 營業稅)。
kind費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。
isActive是否啟用(停用不刪,既有費用列仍引用得到)。
createdAt建立時間。
updatedAt最後更新時間。
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回應欄位 · data
ok固定為 true:營業費用列已新增。
id新建立營業費用列的 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回應欄位 · data
ok固定為 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結算期間(YYYY-MM)。
regions各區毛利明細(出團月落 period 的梯次按區 roll-up)。
region派生 region key(穩定,由 trip 屬性派生)。
label顯示標籤(destination 原文 / 衍生)。
revenueTwd本區收入(出團月落 period 的梯次合計 = 訂單收入 + 已認列退改費,TWD 整數)。
cancellationFeeTwd本區已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 拆出來呈現,會計才對得出「這區的收入有多少不是出團賺的」。
directCostTwd本區真實直接成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。
marginTwd本區毛利 = revenue − directCost。
departures本區梯次數(出團月落 period)。
grossMarginTwd各區毛利加總(整數 TWD)。
revenueTotalTwd各區營收加總(整數 TWD)。
adminFeeIncomeTwd行政手續費收入(退款收取的行政手續費,只計未出團 / 取消單,TWD 整數)。
otherIncomeTwd其他收入合計 = adminFeeIncome(整數 TWD)。GS「額外收入總計」改由 special income 列 承載(specialIncomeTwd,於特殊損益帶號區認列),**不在此重複加總**(防雙計)。
expensesByKind公司營業費用按 kind roll-up(opex / tax / platform_fee,只計已確認)。
kind'opex' / 'tax' / 'platform_fee'。
amountTwd該 kind 本期費用合計(整數 TWD)。
count該 kind 本期費用筆數。
operatingExpenseTotalTwd公司營業費用合計 = Σ opex / tax / platform_fee(整數 TWD)。
special特殊損益逐筆(kind='special',一次性、獨立列、損 / 益雙向,只計已確認)。
id費用列 ID。
categoryId費用科目 ID(特殊損益科目)。
categoryDisplayName費用科目顯示名。
description摘要(如 取消神山床位沒收訂金 / 保險理賠)。
amountTwd金額(整數 TWD ≥ 0,DB CHECK operating_expenses_amount_nonneg)。恆正;損 / 益由 `direction` 表達(0055 特殊損益雙向)。
direction'expense' 損(扣減淨利)| 'income' 益(增益淨利;GS「額外收入」的載體)。
specialExpenseTwd特殊損合計(direction='expense',整數 TWD ≥ 0)。
specialIncomeTwd特殊益合計(direction='income',整數 TWD ≥ 0)= GS「額外收入總計」的載體。
specialTotalTwd特殊損益淨額(**帶號**)= specialExpense − specialIncome(整數 TWD;淨益時為負)。 淨利計算從淨利扣減此值——income 為正貢獻(損 1000 + 益 300 → specialTotal 700 → 淨利 −700)。
netProfitTwd公司淨利 = grossMargin + otherIncome − operatingExpenseTotal − specialTotal(帶號)。
netMarginPct淨利率(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報表年份(西元四位數)。
month報表月份(1-12,月界以 Asia/Taipei 計)。
totalOrders本月建立的 tour 訂單數(依 created_at 計)。
paidOrders本月有實收現金的 tour 訂單數(月內有 inbound 交易)。
cancelledOrders本月取消的 tour 訂單數(依 `orders.cancelled_at` 計,Asia/Taipei 月界)。 取消時刻不明的單(`cancelled_at IS NULL`)任何月份都不計 —— 見 repo 內註解。
cancelledOrdersUnknownDate取消時刻不明的 tour 訂單數(`cancelled_at IS NULL`)。**不分月份** —— 它們 不屬於任何一個月,所以每個月的報表都回報同一個值。> 0 時畫面要講出來: 否則這批單在每個月的報表裡都不出現,逐月讀完也看不出它們存在 —— 而它們確實 被取消了。(不要拿它跟訂單清單的取消總數對:報表側是 tour line 口徑、清單側是 `o.kind`,兩者本來就不相等,見 #20。)
totalRevenue本月實際收到的現金。
refundedAmount本月退還客人的現金,含退款與信用卡爭議退款(chargeback)。
netCash本月淨現金:實收減退還現金,再扣手續費。
newCustomers本月新註冊會員數(排除 staff 角色)。
byTrip依行程銷售排行(前 10 名,按本月實收現金的攤提份額)。跨出團/跨行程訂單 的現金按 order-money/allocation 份額分(#12),Σ revenue = totalRevenue 守恆。
tripId行程 ID。
tripTitle團名。
orderCount該行程本月有實收現金份額的訂單數。
revenuecollected_cash by trip:本月實收現金攤提份額(tour-scoped)。
byProvider依金流商分組的本月實收現金。
provider金流商代碼(如 ecpay / test)。
paymentChannel該組實際包含的收款通路,以「、」分隔。金額仍依金流商分組。
orderCount該金流商本月有實收現金的訂單數。
amountcollected_cash by provider:本月實收現金(tour-scoped)。
dailyRevenuecollected_cash by day:本月逐日實收現金(tour-scoped,Asia/Taipei 日界), 整月零填滿(無入帳的日子 amount=0)。Σ amount === totalRevenue,與 KPI 對帳。
day日期(YYYY-MM-DD,Asia/Taipei 日界)。
amount當日實收現金(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廠商 ID。
name廠商名稱。
categoryHint慣用類別提示(租戶自定,非硬枚舉)。
payeeAccountName收款人戶名(批次轉帳檔欄 (1))。
payeeBankCode收款銀行代號(批次轉帳檔欄 (3))。
payeeAccountNumber收款帳號(批次轉帳檔欄 (2),遮罩回傳)。
status狀態:active 啟用 / inactive 停用(停用不刪)。
createdAt建立時間。
updatedAt最後更新時間。
toko suppliers list{
"ok": true,
"data": [
{
"id": "…",
"name": "…",
"categoryHint": "…",
"payeeAccountName": "…",
"payeeBankCode": "…",
"payeeAccountNumber": "…",
"status": "active",
"createdAt": "…",
"updatedAt": "…"
}
]
}toko suppliers get單一廠商明細(含遮罩收款資料)
參數
<sup_id>位置參數 · 必填--json回應欄位 · data
id廠商 ID。
name廠商名稱。
categoryHint慣用類別提示(租戶自定,非硬枚舉)。
payeeAccountName收款人戶名(批次轉帳檔欄 (1))。
payeeBankCode收款銀行代號(批次轉帳檔欄 (3))。
payeeAccountNumber收款帳號(批次轉帳檔欄 (2),遮罩回傳)。
status狀態:active 啟用 / inactive 停用(停用不刪)。
createdAt建立時間。
updatedAt最後更新時間。
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回應欄位 · data
ok固定為 true:廠商已新增。
id新建立廠商的 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回應欄位 · data
ok固定為 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稽核事件 ID。
actorUserId操作者的使用者 ID;系統事件(webhook/排程等非人為列)為 null。
actorEmail操作者 Email;系統事件或帳號已刪時為 null。
actorName操作者顯示名;系統事件或帳號已刪時為 null。
action動作代碼,例如 order.create、traveler.decrypt。
targetType被操作對象的類型,例如 order、member。
targetId被操作對象的 ID。
metadata該事件的附帶內容(欄位隨動作而異的自由結構 JSON)。
ipAddress發起請求的來源 IP;無法取得時為 null。
createdAt事件發生時間。**只用來顯示** —— 它到毫秒為止(JSON 序列化也是),翻頁請用 `cursor`。
cursor這一列的 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本月(Asia/Taipei)稽核事件總數。
eventsToday今日(Asia/Taipei)稽核事件總數。
writesThisMonth本月寫入類事件數(排除 *.read 讀取事件)。
distinctActorsThisMonth本月有動作紀錄的不重複操作者人數。
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業務的使用者 ID。
name業務顯示姓名。
email業務登入 Email。
role業務角色代碼(admin/sales/op/accountant)。
orderCount承作訂單總數(歸屬此業務、含各狀態的旅遊團訂單)。
paidCount成交訂單數(未取消,且已付清或已完成)。
cancelledCount已取消訂單數。
revenue業績額(TWD 整數):歸屬於該業務、未取消訂單的應收合計。
commissionTwd估算佣金 = round(revenue × sales_commission_bps / 10000)(tenant_settings 費率)。
bonusTwd月度第一名加碼 = round(revenue × monthly_top_bonus_bps / 10000),僅當期 rank 1 且 revenue > 0;其餘為 0。與 isMonthlyTop 同步。
isMonthlyTop當期 rank 1(revenue > 0)=月度第一,享 bonus。
avgOrderTwd客單均價 = 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待派發(pending_review)訂單筆數。
pendingTotalTwd待派發訂單的應收金額合計(新台幣)。
longestWaitHours目前待派發訂單中,最長已等待的時數。
thisMonthAssigned本月(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範本 ID。
key穩定識別碼(NULL = 未指定)。
stageSOP 階段(受理 → 出團完成)。
channel發送管道:line 或 email。
title範本標題。
bodySingle單人版內文(含 {{...}} 合併變數)。
bodyMulti多人版變體;NULL = 只有單人版。
isActive是否為該階段目前啟用的範本。
createdAt建立時間。
updatedAt最後更新時間。
updatedBy最後更新者姓名;未知或帳號已刪除時為 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範本 ID。
key穩定識別碼(NULL = 未指定)。
stageSOP 階段(受理 → 出團完成)。
channel發送管道:line 或 email。
title範本標題。
bodySingle單人版內文(含 {{...}} 合併變數)。
bodyMulti多人版變體;NULL = 只有單人版。
isActive是否為該階段目前啟用的範本。
createdAt建立時間。
updatedAt最後更新時間。
updatedBy最後更新者姓名;未知或帳號已刪除時為 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回應欄位 · data
id新建立的訊息範本 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回應欄位 · data
ok是否成功更新訊息範本。
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回應欄位 · data
ok是否成功切換訊息範本的啟用狀態。
toko message-templates set-active '<id>' --active{
"ok": true,
"data": {
"ok": true
}
}toko message-templates delete刪除訊息範本(硬刪,清除草稿)
參數
<id>位置參數 · 必填--confirm回應欄位 · data
ok是否成功刪除訊息範本。
toko message-templates delete '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko message-templates stages-update更新 message-template-stages/[id]
參數
<id>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
oktoko message-templates stages-update '<id>'{
"ok": true,
"data": {
"ok": "…"
}
}toko message-templates stages-delete刪除 message-template-stages/[id]
參數
<id>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
okremovednamesortOrderisActivetoko 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階段 ID('mts_<ulid>')。
name階段顯示名(FK 錨點;改名 ON UPDATE CASCADE 連動範本列)。
sortOrderisActive停用 = 不供新範本選用(既有綁此階段的範本不受影響)。
templateCount綁此階段的範本數(>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回應欄位 · data
okidtoko 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角色 ID(內建角色為其代碼)。
name角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。
label角色顯示名稱。
isSystem是否為系統內建角色(內建角色不可改名或刪除)。
permissionCount該角色目前擁有的 (resource, action) 數量(內建角色含後台調整)。
customized內建角色的權限與程式預設不同時為 true;自訂角色恆為 false。
memberCount持有此角色的使用者人數。
toko roles list{
"ok": true,
"data": [
{
"id": "…",
"name": "…",
"label": "…",
"isSystem": true,
"permissionCount": 0,
"customized": true,
"memberCount": 0
}
]
}toko roles get單一角色 + 完整權限矩陣
參數
<roleId>位置參數 · 必填--json回應欄位 · data
id角色 ID(內建角色為其代碼)。
name角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。
label角色顯示名稱。
isSystem是否為系統內建角色(內建角色不可改名或刪除)。
editable權限可否調整:自訂角色與業務、線控、會計可以;管理員、會員、嚮導不行。
orderScope訂單資料範圍:'own' 只看名下訂單、'all' 全租戶(含旅客證件解密)。
permissions此角色授予的完整 (resource, action) 權限清單(內建角色含後台調整)。
resource權限資源代碼,例如 order、member。
action權限動作代碼,例如 read、update。
defaultPermissions內建角色的程式預設權限;自訂角色為 null。
baseRole承接的內建角色代碼(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權限資源代碼,例如 order、member。
label中文名。
actionsaction動作代碼,例如 read、set-role。
label中文說明;指派權限的人看的是這個。
risk選填有值表示高風險,內容是授出去會發生什麼事。
adminOnly選填有值表示預設只給管理員,內容是給其他角色前要知道的事。
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回應欄位 · data
id新建立的角色 ID。
toko roles create --name 'example-name' --label 'example-label'{
"ok": true,
"data": {
"id": "…"
}
}toko roles copy複製既有角色成新的自訂角色(帶入來源當下的權限與訂單資料範圍)
參數
<sourceRoleId>位置參數 · 必填--name <code>新角色代碼,小寫英數與底線、2–32 字且須以字母開頭,建立後不可改
--label <顯示名>新角色顯示名稱,呈現於後台角色清單
--confirm回應欄位 · data
id新建立的角色 ID。
name新角色代碼。
label新角色顯示名稱。
orderScope訂單資料範圍,照抄來源角色:own 只看自己名下訂單、all 全租戶。
baseRole承接的內建角色代碼(sales、op 或 accountant);來源沒有承接任何內建角色時為 null。
permissions帶入的權限,`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回應欄位 · data
ok是否成功更新角色。
toko roles update '<roleId>' --label 'example-label'{
"ok": true,
"data": {
"ok": true
}
}toko roles delete刪除自訂角色(仍有成員使用時拒絕)
參數
<roleId>位置參數 · 必填--confirm回應欄位 · data
ok是否成功刪除角色。
toko roles delete '<roleId>'{
"ok": true,
"data": {
"ok": true
}
}toko settings
租戶設定:公司檔 / 收款帳戶 / 費用類別 / 模組 / 寄件網域 / 整合憑證
toko settings payment-provider查詢租戶預設金流商、平台能力與憑證遮罩
參數
--json回應欄位 · data
selectedswitchingAllowedtestAllowedproviderstoko 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--json回應欄位 · data
oktoko settings set-payment-provider --operation switch --provider manual{
"ok": true,
"data": {
"ok": true
}
}toko settings workflow-controls查詢新付款與新契約的暫停設定
參數
--json回應欄位 · data
newPaymentsPausednewAgreementsPausedtoko 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--json回應欄位 · data
newPaymentsPausednewAgreementsPausedtoko 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設定列 ID(單例,恆為 'singleton')。
companyName公司全名,顯示於發票、合約與對外信件抬頭。**必填**(#87,DB NOT NULL + 非空白 CHECK)。
companyPhone公司聯絡電話,顯示於對外文件;null = 未設定。
companyEmail公司對外聯絡信箱,自建前台的站台資訊輸出它;null = 未設定。
taxId公司統一編號(8 位數字),用於開立發票;null = 未設定。
companyAddress公司登記地址,顯示於對外文件;null = 未設定。
logoUrl公司 Logo 圖片網址,用於後台與對外頁面品牌呈現;null = 未設定。
homeSeoTitle首頁標題(含品牌段)整句覆寫,平台前台與自建前台共用;null = 用品牌名與標語組成。
siteTagline公開站標語(SEO/首頁);null = 未設定。
seoDefaultDescription公開站預設 SEO meta description;null = 未設定。
ogImageUrl社群分享預設 Open Graph 圖片網址;null = 未設定。
emailReplyTo系統寄信時的回覆收件信箱;null = 未設定。
lineOfficialUrl官方 LINE 加好友連結(issue 748);null = 未設定。
facebookUrlFacebook 粉專網址;null = 未設定。
instagramUrlInstagram 網址;null = 未設定。
youtubeUrlYouTube 頻道網址;null = 未設定。
assignmentModeS5: 'auto_round_robin' | 'auto_customer_choice' | 'manual_review'
defaultAssigneeUserIdS5: fallback assignee when round-robin finds no active sales, etc.
allowSalesClaimorder-assignment §6:業務自派搶單開關(per-tenant opt-in,預設 false)。
passportExpiryWarningDays護照效期提醒天數(document-expiry §4.1;NOT NULL DEFAULT 180)。
guideCertExpiryWarningDays嚮導證照到期提醒天數(#563;NOT NULL DEFAULT 60)。回程日 + 此天數 > 到期日即警示。
guideDispatchNearGap派嚮導清單的「快成團」門檻人數(#1377;NOT NULL DEFAULT 2)。
groupCodePattern團號 token 樣板(如 '{YY}{region}{airline?}{MMDD}{seq}')。NULL = 內建預設。
groupCodeSeqStyle序號樣式:'alpha' | 'alpha_no_io' | 'numeric'(NOT NULL DEFAULT 'alpha')。
groupCodeSeqWidthnumeric 序號補零寬度(NOT NULL DEFAULT 2;alpha 樣式忽略)。
ecpayFeeBps預估綠界手續費率(270 = 2.70%)。NOT NULL DEFAULT 270。
fongshouFeeBps預估豐收款手續費率(50 = 0.50%)。NOT NULL DEFAULT 50。
profitTaxBps預估發票 / 營所稅率(500 = 5.00%)。NOT NULL DEFAULT 500。
salesCommissionBps業務抽成率(1000 = 10.00%)。NOT NULL DEFAULT 1000。
monthlyTopBonusBps月度第一名加碼率(500 = 5.00%)。NOT NULL DEFAULT 500。
senderLocalPart寄件人 local-part,未填視為 'info'。
storefrontTemplate前台店面模板 key(storefront-templates §3)。可能對不上 registry(打錯、模板 改名/下架)—— 前台渲染一律經 resolveStorefrontTemplate() fallback `minimal`。
customStorefrontUrlwebsiteModeactiveCustomStorefrontUrlcustomStorefrontTripPathga4MeasurementId轉換追蹤 ID(specs/conversion-tracking.md)。NULL = 不載入該追蹤碼。
metaPixelIdgoogleAdsIdcustomerCancelUnpaidEnabled未付款單可否由客人自行線上取消。
customerCancelPaidEnabled已付款(含只付訂金)單可否由客人自行線上取消。
customerCancelPaidMinDaysBefore已付款單的出發日門檻:距出發 < 此天數即不可線上取消。
customerRescheduleMinDaysBefore自助換梯門檻(customer-cancellation §8.1):null = 不開放,N = 來源與目標距出發 ≥ N 天。
customerRescheduleSurplus自助換梯後新梯較便宜時的差額處理(§8.5)。
cancellationFeeTiers租戶預設退改費階梯(已正規化、降序)。`[]` = 不收退改費。
daysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
refundRemitFeeTwd退款轉帳費(customer-cancellation §3.4,按單一次)。走匯出的退款才收,刷退恆 0。
refundApprovalPolicy退款核准權限(#1405)。見 `refunds/approval-policy`。
approverRoles可核准退款的角色名單。null = 不另外限縮,持有 `refund.approve` 的角色都可核准。 不是 null 時一律含管理員。
accountantCanCreate內建會計角色可開退款單並送審(`refund.create`)。
selfApprovalEnabled建單人可以核准自己的退款單。關 = 維持現狀的責任分離:只擋建單人 (`CREATOR_CANNOT_APPROVE`),送審人不受限。
customerCancelReminder客人自助取消提醒文字(customer-cancellation §5.1);null = 不顯示。
lotteryFilingFeeTiers送件行政費的次數階梯(customer-cancellation §3.6,**每人**,已正規化、升序)。 `[]` = 不收。計次範圍是該訂單所屬的備案鏈。
fromCount累計未中籤 ≥ 此次數時適用本列(最小 1)。
totalTwd到 `fromCount` 次為止的**累計總額**(整數 TWD,每位旅客各自計)。
tourAgreementEnabled契約流程總開關(預設關)。
tourAgreementTravelForm舊 API 的單一旅遊型態;只供相容使用。
tourAgreementDomesticTravelFormtourAgreementOverseasTravelFormcompanyRepresentative乙方負責人;null = 未設定 → 契約 fail-closed。
travelAgencyRegistrationNo旅行業註冊編號;null = 未設定 → 契約 fail-closed。
courtJurisdiction合意管轄法院;null = 未設定 → 契約 fail-closed。
tourAgreementChangeDaysDefault可變更第三人期限:免抽籤梯次預設(NOT NULL DEFAULT 35)。
tourAgreementChangeBufferDays可變更第三人期限:抽籤日前的緩衝天數(NOT NULL DEFAULT 5)。
tourAgreementLotteryDeadlineTypeKey選填tourAgreementReviewHardBlock審閱期硬擋 24 小時(預設關,只記錄提供 / 簽署時間)。
tourAgreementGuardianSigning未成年由法定代理人代簽(預設開)。
tourAgreementSoftBlock出團軟擋:未簽列入出團前待辦(預設關;系統永不硬擋)。
escortLeadLabel隨團人員職稱:`leader` 的顯示文字(issue 587;NOT NULL DEFAULT '主要隨團人員')。
escortAssistantLabel隨團人員職稱:`assistant` 的顯示文字(NOT NULL DEFAULT '協同')。
updatedAt設定最後更新時間。
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收款帳戶 ID。
code帳戶代碼(租戶內唯一穩定識別)。
displayName帳戶顯示名。
kind帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。
gatewayProvider綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `accounts/gateway-providers.ts`。
bankName銀行名稱;現金/閘道帳戶為 null。
accountNo銀行帳號;現金/閘道帳戶為 null。
bankCodebankBranchaccountHoldercanReceive可收款(幾乎都 true)。
canRemit可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。
canChargeback可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。
canPaySupplier付款渠道:出團準備的付款登記區可選它付供應商(#1375)。
isDeprecated廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。
isSettlementMaster主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。
payoutAccountId撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。
currency帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位(小者在前)。
usedCount被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。
currencyLocked幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。
createdAt建立時間。
updatedAt最後更新時間。
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路由設定 ID。
feeCategory費用類型代碼(租戶自定唯一鍵,如 tour_fee/lodging/equipment)。
displayName費用類型顯示名。
finalAccountId此費用類型最終結算進的收款帳戶 ID。
finalAccountName最終收款帳戶名稱;無對應帳戶時為 null。
finalAccountCodefinal 帳戶代號。
isActive此路由是否啟用。
createdAt建立時間。
updatedAt最後更新時間。
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費用類別 ID。
code科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。
displayName顯示名(如 房租 / 行政薪資 / 營業稅)。
kind費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。
isActive是否啟用(停用不刪,既有費用列仍引用得到)。
createdAt建立時間。
updatedAt最後更新時間。
toko settings expense-categories list{
"ok": true,
"data": [
{
"id": "…",
"code": "…",
"displayName": "…",
"kind": "opex",
"isActive": true,
"createdAt": "…",
"updatedAt": "…"
}
]
}toko settings modules租戶啟用的方案模組(唯讀;供應由平台 CLI 管)
參數
--json回應欄位 · data
tourclimbinglodgingaccountinglotteryapi_accessheadless_storefrontcustom_domainaffiliated_salestoko 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員工的使用者 ID(作為指派對象)。
name員工顯示姓名。
email員工登入 Email。
role員工角色代碼(sales/admin 等可指派角色)。
thisMonthAssigned本月(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自有寄件網域;未設定時為 null。
resendDomainId寄件服務商(Resend)的網域識別碼;未設定時為 null。
sendingDomainStatus網域驗證狀態(如 pending/verified);未設定時為 null。
senderLocalPart寄件人信箱的帳號部分(@ 前段);未填視為 info。
records待設定的 DNS 記錄清單(SPF/DKIM 等);Resend 不可達或未設定時為空陣列。
recordDNS 記錄用途分類(如 DKIM/SPF 等,來自 Resend)。
name記錄主機名(需在網域 DNS 新增的 host)。
type記錄類型(如 TXT/MX/CNAME)。
value記錄值(需填入 DNS 的內容)。
ttl選填存活時間(TTL);未指定時省略。
status選填此筆記錄的驗證狀態(如 pending/verified);未指定時省略。
priority選填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整合代號(`ecpay` / `travelinvoice`… / 轉換追蹤的 `ga4`、`meta`)。列不存在=該家未綁定。
merchantId金鑰綁定的帳號 ID(明文,顯示 / 診斷用):金流是特店 ID,`ga4` 是 Measurement ID,`meta` 是 Pixel ID。
secretsMask金鑰的遮罩碼(`****` + 末 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回應欄位 · data
ok是否成功更新租戶設定。
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回應欄位 · data
ok是否成功更新公開站 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回應欄位 · data
ok是否成功更新內外帳參考預估淨利費率。
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回應欄位 · data
ok是否成功更新訂單指派模式設定。
toko settings assignment set --mode auto_round_robin{
"ok": true,
"data": {
"ok": true
}
}toko settings ecpayECPay 憑證(set 三欄一起寫 / clear 解除綁定;write-only)
參數
--merchant-id <id>綠界 ECPay 特店編號(MerchantID),用於金流請款與簽章
--hash-key <k>綠界 ECPay HashKey,CheckMacValue 簽章用密鑰;寫入後即 KMS 加密儲存且永不回傳
--hash-iv <iv>綠界 ECPay HashIV,CheckMacValue 簽章用初始向量;寫入後即 KMS 加密儲存且永不回傳
--confirm回應欄位 · data
ok是否成功清除 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回應欄位 · data
ok是否成功啟用自有寄件網域。
domain啟用的寄件網域(由綁定的站台網域派生)。
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回應欄位 · data
id新建立的收款帳戶 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回應欄位 · data
id新建立或更新的費用類型路由 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--active <true|false>回應欄位 · data
id新建立的費用類別 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回應欄位 · data
oktoko 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回應欄位 · data
oktoko settings destination-rules-delete '<id>'{
"ok": true,
"data": {
"ok": true
}
}toko settings departure-owner-rotation-get查詢 settings/departure-owner-rotation
參數
--data <json>--json回應欄位 · data
domesticmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。
overseasmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 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回應欄位 · data
domesticmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。
overseasmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 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[]
idregionCoderegionName地區中文名稱。
assigneeUserId受派業務 userId;null = assignee 離職/刪帳號後被 SET NULL(規則退化為未命中)。
assigneeName受派業務姓名;未指派或帳號已刪除時為 null。
assigneeRolecreatedAtupdatedAttoko 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回應欄位 · data
idtoko 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回應欄位 · data
oktoko 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回應欄位 · data
oktoko 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[]
idtext項目文字(租戶內唯一)。
included預設歸「含」(true)或「不含」(false)。
displayOrdercreatedAtupdatedAttoko 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回應欄位 · data
idtoko 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回應欄位 · data
oktoko settings group-code-pattern --data '{"pattern":"{region}{YY}{MMDD}-{seq}","seqStyle":"alpha","seqWidth":2}'{
"ok": true,
"data": {
"ok": true
}
}toko settings guide-portal-policySet guide login mode and roster access days
參數
--data <json>JSON object with the fields from the linked API request.
--json--confirm回應欄位 · data
oktoko 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回應欄位 · data
oktoko 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回應欄位 · data
oktoko 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[]
idcodedisplayNamedisplayOrderisActivecreatedAtupdatedAttoko 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回應欄位 · data
idtoko 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回應欄位 · data
oktoko 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回應欄位 · data
oktoko 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[]
idcategoryIdcategoryCodecategoryDisplayNamecategoryKindamountTwddescriptionpaidFromAccountIdpaidFromAccountNameisActivecreatedByUserIdcreatedAtupdatedAttoko 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回應欄位 · data
idtoko 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回應欄位 · data
oktoko settings storefront-update{
"ok": true,
"data": {
"ok": true
}
}toko settings storefront-list查詢 settings/storefront
參數
--data <json>--json回應欄位 · data
bannersimageUrlaltlinkUrlnamefaqsquestionanswercategoriesnametagimageUrlwebsiteModeactiveCustomStorefrontUrltemplatecustomStorefrontUrlcustomStorefrontTripPathslotsaboutContentMdxtoko 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回應欄位 · data
oktoko 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員工的使用者 ID。
email員工登入 Email(帳號識別)。
name員工顯示姓名。
role員工角色代碼(admin/sales/op/accountant)。
createdAt帳號建立時間。
bannedAccount frozen via ban (離職 / 停權). False after a temporary ban ends, also before the next sign-in clears it.
twoFactorEnabled是否已完成 TOTP 兩步驟驗證註冊。
emailVerifiedEmail 是否已驗證。**不是**啟用判準:員工邀請流程不寄信(一次性密碼當場交付), 所以受邀者走完整條流程這個旗標也不會變 true。啟用看 `activated`。
lastLoginAt最後一次登入時間;`null` = 從來沒有人登入過這個帳號。代理登入不計。
activated派生的「已啟用」狀態:至少成功登入過一次,代表發出去的一次性密碼有人在用。
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回應欄位 · data
userId新建立員工的使用者 ID。
tempPassword一次性明文暫時密碼,僅此次回傳(請立即轉交並要求員工首次登入改密)。
email新員工的登入 Email。
role指派的員工角色(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回應欄位 · data
ok是否成功變更員工角色。
toko staff set-role '<userId>' --role admin{
"ok": true,
"data": {
"ok": true
}
}toko staff remove移除員工(降為 customer,保留 user 紀錄)
參數
<userId>位置參數 · 必填--confirm回應欄位 · data
ok是否成功移除員工身分(降為一般顧客)。
toko staff remove '<userId>'{
"ok": true,
"data": {
"ok": true
}
}toko staff ban執行 staff/[userId]/ban
參數
<userId>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
oktoko staff ban '<userId>'{
"ok": true,
"data": {
"ok": "…"
}
}toko staff unban執行 staff/[userId]/unban
參數
<userId>位置參數 · 必填--data <json>--json--confirm回應欄位 · data
oktoko 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
itemsidtoEmailsubjecttemplateKeycategorystatuserrorattemptsorderIddepartureIdguideIdcreatedAtsentAtcanRetryretryRecipientretryUnavailableReasontotalpagepageSizeasOftoko 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
htmltextcontentStateidtoEmailsubjecttemplateKeycategorystatuserrorattemptsorderIddepartureIdguideIdcreatedAtsentAtcanRetryretryRecipientretryUnavailableReasontoko 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回應欄位 · data
retriedtoko email-history retry '<id>'{
"ok": true,
"data": {
"retried": true
}
}toko feedback
預覽公開問題回報或功能需求,確認後開啟 GitHub 草稿
toko feedback bug準備 bug 回報;GitHub 範本自動加上 bug label
參數
--no-browser--jsontoko feedback bugtoko feedback feature準備功能需求;GitHub 範本自動加上 enhancement label
參數
--no-browser--jsontoko feedback featuretoko 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回應欄位 · data
personIdchains依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。
headOrderId鏈首訂單(分組鍵)。
headOrderNumberfilingCount送件紀錄筆數(這條鏈上)。
adjustmentTotal調整差額加總(這條鏈上,可負)。
count目前送件次數加上調整差額,下限為 0。
nextSeq下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。
filingsidorderIdorderNumbertravelerName送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。
createdAtadjustmentsidorderId這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。
orderNumberdeltareasonactorName下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。
createdAttoko 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
personIdchains依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。
headOrderId鏈首訂單(分組鍵)。
headOrderNumberfilingCount送件紀錄筆數(這條鏈上)。
adjustmentTotal調整差額加總(這條鏈上,可負)。
count目前送件次數加上調整差額,下限為 0。
nextSeq下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。
filingsidorderIdorderNumbertravelerName送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。
createdAtadjustmentsidorderId這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。
orderNumberdeltareasonactorName下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。
createdAttoko 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.
--jsontoko 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回應欄位 · data
oktoko 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
rowsorderIdorderNumbercustomerNamelastCustomerMessageAttotalpagepageSizetoko 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>--jsontoko skill showtoko skill install建立或更新專案的 skill 入口,保留自訂內容
參數
--project <directory>--jsontoko skill installtoko travelinvoice
travelinvoice
toko travelinvoice allowance執行 travelinvoice/[id]/allowance
參數
<id>位置參數 · 必填--data <json>JSON object with the fields from the linked API request.
--json--confirm回應欄位 · data
okresultallowanceIdallowanceNotoko 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回應欄位 · data
okresultinvalidationIdtoko travelinvoice invalidate '<id>' --data '{"reason":"example-re"}'{
"ok": true,
"data": {
"ok": true,
"result": {
"invalidationId": "…"
}
}
}toko travelinvoice get查詢 travelinvoice/[id]
參數
<id>位置參數 · 必填--data <json>--json回應欄位 · data
idorderIdorderNumbermerchantOrderNoprovidercategorybuyerNamebuyerUbntotalAmtTwdstatusdeclaredStatusinvoiceNumberinvoiceTransNo平台開立流水號;pending 列有值代表平台已受理預約開立。
displayUrltourNametourNotourDatelastErrorlastSyncedAtcreatedAttoko 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回應欄位 · data
okresultdeclaredStatusstatus查回後的本地收據狀態(預約收據回補後可能轉 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回應欄位 · data
okresultidstatustoko 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回應欄位 · data
okresultidstatustoko 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回應欄位 · data
okresultidmerchantOrderNostatusinvoiceNumberlastError落缺件(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回應欄位 · data
idmerchantOrderNostatusinvoiceNumberlastError落缺件(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
rowsidorderIdorderNumbermerchantOrderNoprovidercategorybuyerNamebuyerUbntotalAmtTwdstatusdeclaredStatusinvoiceNumberinvoiceTransNo平台開立流水號;pending 列有值代表平台已受理預約開立。
displayUrltourNametourNotourDatelastErrorlastSyncedAtcreatedAttotalpagepageSizetoko 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>--jsontoko version check