toko

API 參考 2026-11-03

進階套組

API 版本 2026-11-03 的形狀,取自定名時凍結的快照。定名後新增的端點與欄位不列出; 它們也出現在這個版本,見最新的參考。標成 deprecated 的欄位會在較新的版本移除,遷移方式見changelog。

/departures

設定梯次分配模式

PATCH/api/v1/departures/{depId}/allocation-mode
lottery.manage模組:lottery

參數

depId路徑
string· min 1

梯次 ID

mode必填
enum
fcfslottery

分配模式:fcfs(先到先得)或 lottery(抽籤)

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

departureId
string

被更新的梯次 id。

mode
"fcfs" | "lottery"

更新後的佔位模式:fcfs 先到先得/lottery 抽籤。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/departures/<depId>/allocation-mode" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "fcfs"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "departureId": "…",
    "mode": "fcfs"
  }
}

Use the canonical tenant operation.

GET/api/v1/departures/{depId}/backup-candidates
order.create模組:lottery

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

main
object
id
string
tripId
string
departureDate
string
returnDate
string
priceTwd
number

牌價 `departures.price_twd`(備案同價的基準)。

agencyPriceTwd
number

同業通路有效單價(見 `effectiveAgencyUnitPrice`)。

capacity
number
bookedCount
number
allocationMode
"fcfs" | "lottery"
label
string | null

梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。

isPrivate
boolean

不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。

candidates
object[]
id
string
tripId
string
departureDate
string
returnDate
string
priceTwd
number

牌價 `departures.price_twd`(備案同價的基準)。

agencyPriceTwd
number

同業通路有效單價(見 `effectiveAgencyUnitPrice`)。

capacity
number
bookedCount
number
allocationMode
"fcfs" | "lottery"
label
string | null

梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。

isPrivate
boolean

不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/backup-candidates" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "main": {
      "id": "…",
      "tripId": "…",
      "departureDate": "…",
      "returnDate": "…",
      "priceTwd": 0,
      "agencyPriceTwd": 0,
      "capacity": 0,
      "bookedCount": 0,
      "allocationMode": "fcfs",
      "label": "…",
      "isPrivate": true
    },
    "candidates": [
      {
        "id": "…",
        "tripId": "…",
        "departureDate": "…",
        "returnDate": "…",
        "priceTwd": 0,
        "agencyPriceTwd": 0,
        "capacity": 0,
        "bookedCount": 0,
        "allocationMode": "fcfs",
        "label": "…",
        "isPrivate": true
      }
    ]
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/cancel-group-not-confirmed
departure.update模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

cancelled
number

本次真的翻成 cancelled 的訂單數。

alreadyCancelled
number

已經是未成團取消狀態、本次不重複取消的訂單數(重跑時的正常值)。

emailed
number

本次寄出(信進了佇列)的通知數。

emailSkippedAlreadySent
number

已寄過通知、本次略過的訂單數。

emailSkippedNoTemplate
number

取消成立但沒寄成,因為租戶沒有啟用中的「未成團通知」範本。**不留 claim** —— 設好範本後重按同一顆按鈕會補寄。

emailSkippedNoRecipient
number

取消成立但沒寄成,因為訂購人沒有 email。**與缺範本分開數**:缺範本的後續動作是 去設範本再按一次,這種按幾次都沒用,要改走電話或其他管道。混成一個數字等於叫 承辦對這張單做一件永遠不會生效的事。

unprocessedDepartureIneligible
number

因**梯次**中途失格(被標記成團 / 已結團)而未處理的訂單數 —— 含發現當下那張與 其後全部未跑到的單。>0 = 這批提早中止。刻意**不併進其他數字**:那些的後續動作是 去看那張單,這種是去看梯次。

crossDepartureSkipped
object[]

**跨梯訂單**:同時掛在本梯與別梯的單,一律不碰(見批次說明)。清單而不是計數 —— 這些單要承辦逐張人工處理,沒有訂單號等於沒有回報。

orderId
string
orderNumber
string
failed
number

**取消**沒成立的訂單數(其餘訂單不受影響)。**只數 `phase='cancel'`** —— 取消已經 commit、只是通知寄不出去的單不算,那張單真的取消了,把它報成失敗等於對線控謊稱 「這張還沒取消」,而他會去做一件已經做完的事。

failures
object[]

失敗清單(辨識到訂單號)。`phase` 分「取消沒成立」與「取消成立但通知炸了」—— 後續動作完全不同。**不帶例外訊息**:DB 例外會帶表名 / 約束名 / 衝突鍵的值(可能 含 email),那些留 server log,不經 server action 回瀏覽器。

orderId
string
orderNumber
string
phase
"cancel" | "notify"
selectedNotEligible
object[]

**只有選單版會有值**:選了、但不在本梯名單上的單(不掛在本梯、已出團、或已被其他 事由取消)—— 一張都沒動。清單而不是計數,理由同 `crossDepartureSkipped`。整梯版恆為空。

orderId
string
orderNumber
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/cancel-group-not-confirmed" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "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": "…"
      }
    ]
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/complete
departure.update模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/complete" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/confirmation
departure.update模組:tour

參數

depId路徑
string· min 1

Departure ID

confirmed必填
boolean

Confirm or withdraw group confirmation

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/confirmation" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmed": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

登錄梯次成本

POST/api/v1/departures/{depId}/costs
departure_cost.create模組:tour

參數

depId路徑
string· min 1

梯次 ID

category必填
string· min 1

成本科目類別,決定歸入哪個分類帳

vendorName選填
string

供應商/受款對象名稱

description選填
string

成本說明備註

amountTwd必填
integer

成本金額(台幣,整數)

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的梯次成本列 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/costs" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "example-category",
  "amountTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}
PATCH/api/v1/departures/{depId}/costs/{costId}
departure_cost.manage模組:tour

參數

costId路徑
string· min 1

成本列 ID

category必填
string· min 1

成本科目類別,決定歸入哪個分類帳

vendorName選填
string

供應商/受款對象名稱

description選填
string

成本說明備註

amountTwd必填
integer

成本金額(台幣,整數)

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/departures/{depId}/costs/<costId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "example-category",
  "amountTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
DELETE/api/v1/departures/{depId}/costs/{costId}
departure_cost.manage模組:tour

參數

costId路徑
string· min 1

成本列 ID

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/departures/{depId}/costs/<costId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/delete
trip.manage模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/delete" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

該梯次財務摘要

GET/api/v1/departures/{depId}/finance-summary
departure.update模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data

header
object

梯次表頭(團號/行程名/出發日等基本資訊)。

id
string

梯次 id(dep_ 前綴)。

tripTitle
string

所屬行程標題。

tripSlug
string

所屬行程網址 slug。

departureDate
string

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

returnDate
string

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

finance
object

應收/已收金額彙整(TWD)。

receivableTwd
number

梯次應收:tour 訂單的攤提份額(orders/allocation;排除已取消單)。 **含代收暫收款**(裝備押金等)—— 客人確實欠這筆錢,收款計畫與待收都照它走。 要「本團收入」請用 revenueTwd,不要拿這個當收入(issue #578)。

custodialTwd
number

應收之中的代收暫收款份額(裝備押金等;要退還,不是收入)。

revenueTwd
number

本團收入 = 應收 − 代收暫收款。毛利、損益、月報表一律用這個。

collectedTwd
number

實收:tour 訂單 payment_transactions(direction='in') 的攤提份額。

cashReturnedTwd
number

客戶現金退回(refund/chargeback/reversal)的攤提份額。

netCollectedTwd
number

已收淨額 = 實收 − 退回。

outstandingTwd
number

待收 = 應收 − (實收 − 退回),floor 0。

costTwd
number

成本:departure_costs 真實額(房費另計,見成本登記簿)。

costBilledTwd
number

已轉請款成本。

costUnbilledTwd
number

未轉請款成本;不含即付(當下已付、不轉請款)。

anomalyOrderCount
number

異常單數:overpaid / partially_refunded / refund pending 的 tour 訂單。

cost
object

成本彙整(各類直接成本合計,TWD)。

totalTwd
number

內帳真實成本合計(TWD 整數,各成本列金額加總)。

billedTwd
number

已轉請款的成本合計(TWD 整數)。

paidOnSpotTwd
number

即付的成本合計(TWD 整數):當下已付,不轉請款。

unbilledTwd
number

尚未轉請款的成本合計(TWD 整數);不含即付列。

declarableTwd
number

外帳可申報金額合計(TWD 整數,各列憑證金額加總)。

nonDeclarableTwd
number

無憑證的不可申報成本合計(TWD 整數,逐列取 金額−憑證 的正值,不可跨列抵減)。

count
number

成本列筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/finance-summary" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
    }
  }
}

該梯次抽籤訂單清單

GET/api/v1/departures/{depId}/lottery-orders
order.read模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data[]

orderId
string

訂單 id。

orderNumber
string

訂單編號。

customerName
string

訂購人姓名。

partySize
number

佔位人數。

lotteryState
"applied" | "won" | "lost" | null

抽籤狀態:applied 已應募/won 中籤/lost 未中籤。null = 落在受管制抽籤梯次但沒標 應募的單(後台 K 單、事後改成抽籤的梯次)——只因抽籤實名制占用而被列出(§3.7)。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。 只有 `lotteryState='applied'` 時可能為 true。

applicationKey
string

Current application (`lotteryApplicationKey`). A decision sends it back to reject an old page.

undoDecisionId選填
string | null | undefined

Latest reversible decision. The write entry checks later work under the order lock.

backupChoiceCount
number

客人自選的有序備案筆數(order_backup_choices;0 = 無備案)。

collectedTwd
number

已收現金(payment_transactions direction='in');抽籤未中安置時的訂金結轉基準。

failoverFromOrderId
string | null

落腳譜系:本單若是由某主單 force-place / cascade 落腳而成立的備案單,指向原主單 id。 null = 本單即主單(非備案落腳單)。供線控從備案列回溯主單。

awaitingPlacement
boolean

true when lottery_state='lost' and still active (not cancelled). Means backup cascade exhausted — awaiting manual placement or explicit cancel.

identityHoldPending
boolean

是否仍占用抽籤實名資格。為 true 時可顯示「解除實名占用」動作。

identityHoldReleased
boolean

抽籤實名占用是否已由線控手動解除。

failover
LotteryFailoverSummary | null

最近一次未中籤自動轉備案:`placed` 落腳、`reapplied` 重新應募、`stopped` 停止並待人工安置。 `blocker` 為停止原因,null=清單走完。`skipped` 列被跳過的順位與原因。null=未曾自動轉備案。

outcome
"placed" | "reapplied" | "stopped"

placed = a general backup took the order; reapplied = a new application; stopped = awaits placement.

blocker
LotteryFailoverBlocker | null

Why the failover stopped. null = every backup choice was tried. Only for `stopped`.

skipped
object[]

Backup choices that the failover skipped, in rank order.

rank
number
departureId
string
reason
"identity_missing" | "not_same_trip" | "price_changed" | "roster_invalid" | "unavailable"
請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/lottery-orders" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
    }
  ]
}

該梯次旅客名單

GET/api/v1/departures/{depId}/manifest
order.read模組:tour

參數

depId路徑
string· min 1

梯次 ID

includeCancelled選填
boolean

是否也列出已取消訂單的旅客(true/false);省略則不列

回應欄位 · data[]

travelerId
string

旅客 id。外部系統用它對人,不靠姓名。

orderId
string

所屬訂單 id。

orderNumber
string

所屬訂單編號。

travelerName
string

旅客姓名。

phone
string

聯絡電話。

email
string

聯絡 Email。

isPrimary
boolean

是否為該訂單的主要聯絡人(訂購人)。

gender
"male" | "female" | "other" | null

性別(明文 enum-like):'male'|'female'|'other'|null(未填)。

birthDate
string | null

生日 ISO `YYYY-MM-DD`;null = 未填。

diet
string | null

飲食需求(葷素)明文;null = 未填。

medicalNotes
string | null

醫療 / 過敏 / 病史備註明文;null = 未填。

specialNeeds
string | null

「飲食 · 特殊需求」欄的合併顯示字串(diet + medical_notes,以 ` · ` 併接)。 結構化欄落地後改吃 diet / medical_notes(不再湊 roommate_pref —— 分房需求回歸分房面板)。 兩者皆空 → null。

staffNote
string | null

該訂單的承辦備註(issue 1659,`orders.staff_note`)。同一張單的每位旅客列帶同一份; null = 沒有備註。與 `specialNeeds` 分開,不併進飲食 / 過敏字串。

emergencyContactName
string | null

緊急聯絡人姓名;null = 未填。

emergencyContactPhone
string | null

緊急聯絡人電話;null = 未填。

consentPending
boolean

該訂單是否仍缺最新版 PDPA 同意書(per-order,同訂單所有旅客共享此旗標)。 true = 未簽 / 只簽過舊版;與 dashboard KPI、催簽 badge 同一述詞。

orderStatus
string

Single display status (派生自三軸,與 deriveOrderDisplayStatus 同 precedence)。

amount
number

每人分攤的應收(整單應收 ÷ 人數,四捨五入,TWD)。加總可能差幾元;對帳用 `orderReceivableTwd`。

orderReceivableTwd
number | null

**整單**會計應收(TWD,不是每人分攤)。同一張單的每一列都帶同一個數字。 未取消=訂單應收。已取消=`cancellationFeeTwd`+`refundFeesTwd`:取消時訂單應收 歸零,公司留下的是這兩筆錢。退款執行完後,「應收 −(收款 − 退款)= 0」。 null=退改費尚未核算(見 `cancellationFeePending`)。

cancellationFeePending
boolean

true=已取消、退改費尚未核算、手上還有可退現金:整單應收還定不下來。

cancellationFeeTwd
number | null

已取消單留下的退改費(整單)。未取消=null;尚未核算=null。

refundFeesTwd
number | null

已取消單已執行退款的行政手續費+匯款手續費(整單)。未取消=null。

companionGroupId
string | null

本梯次的同行組 id(departure-prep §2.11);null = 不屬任何組。

companionGroupCode
string | null

同行組代號(A、B…);null = 不屬任何組。

companionGroupColor
number | null

同行組顏色序號(0 起);null = 不屬任何組。

climbingExperience
object[]

登山經歷(新到舊)。登山模組未啟用時恆為空陣列。

label
string

行程 / 山岳名稱(自填為自由文字;order 來源 = 行程名稱快照)。

climbedOn
string | null

約略完成日 `YYYY-MM-DD`;null = 未填。

source
"order" | "self"

來源:order = 完團後系統沉澱;self = 會員自填或承辦代填。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/manifest" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "travelerId": "…",
      "orderId": "…",
      "orderNumber": "…",
      "travelerName": "…",
      "phone": "…",
      "email": "…",
      "isPrimary": true,
      "gender": "male",
      "birthDate": "…",
      "diet": "…",
      "medicalNotes": "…",
      "specialNeeds": "…",
      "staffNote": "…",
      "emergencyContactName": "…",
      "emergencyContactPhone": "…",
      "consentPending": true,
      "orderStatus": "…",
      "amount": 0,
      "orderReceivableTwd": 0,
      "cancellationFeePending": true,
      "cancellationFeeTwd": 0,
      "refundFeesTwd": 0,
      "companionGroupId": "…",
      "companionGroupCode": "…",
      "companionGroupColor": 0,
      "climbingExperience": [
        {
          "label": "…",
          "climbedOn": "…",
          "source": "order"
        }
      ]
    }
  ]
}

成本轉請款:以選定的未轉成本列建立一張

POST/api/v1/departures/{depId}/payables
payable.create模組:tour

參數

depId路徑
string· min 1

梯次 ID

costIds必填
array· min 1

要轉成請款單的成本列 ID 清單,至少一筆

payeeType必填
enum
supplierguidestaff_commissionother

受款人類型:supplier(供應商)/ guide(領隊)/ staff_commission(員工佣金)/ other(其他)

payeeName必填
string· min 1

受款人姓名/戶名(必填)

payeeBankAccount選填
string

受款人銀行帳號

payeeBankName選填
string

受款人銀行名稱

payeeTaxId選填
string

受款人統一編號/稅籍編號

submitImmediately選填
boolean

設為 true 時建立後立即送出核簽,否則僅存為草稿

回應欄位 · data

ok
boolean

轉請款成功旗標,恆為 true。

payableId
string

新建立的出款單(payable)id。

payableNumber
string

出款單編號。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/payables" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "costIds": [
    "example-costIds"
  ],
  "payeeType": "supplier",
  "payeeName": "example-payeeName"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "payableId": "…",
    "payableNumber": "…"
  }
}

梯次實際收退款 CSV,回傳 filename 與含 BOM 的 csv

GET/api/v1/departures/{depId}/payments-export
payment.read模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data

filename
string
csv
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/payments-export" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "filename": "…",
    "csv": "…"
  }
}
GET/api/v1/departures/{depId}/permit-applications
departure_prep.read模組:climbing

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data[]

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/permit-applications" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}
POST/api/v1/departures/{depId}/permit-applications
departure_prep.manage模組:climbing

參數

office選填
enum
one_stoppoliceforestryother

申請處:one_stop(國家公園一站式)/ police(警政署入山)/ forestry(林務局山屋/營地)/ other(其他)。建單時必填

officeLabel選填
string· max 100

申請處名稱;office = other 時必填,例:一葉蘭許可

route選填
string· max 200

路線(站方表單上的路線名)

groupLabel選填
string· max 50

組別,例:A 組。分組送件時用來分辨同一梯的多張單

partySize選填
integer· max 99 · min 1

申請人數(1–99)

entryDate選填
string

入園日(YYYY-MM-DD)

exitDate選填
string

離園日(YYYY-MM-DD),不得早於入園日

teamName選填
string· max 100

隊名(站方表單上的隊伍名稱)

applicantName選填
string· max 100

申請人姓名

applicantIdNumber選填
string· max 30

申請人身分證明碼(加密存放);需要 permit_pii.read,沒有時回 403

applicantAccount選填
string· max 200

申請用的帳號或信箱

leaderKind選填
enum
same_as_applicantguidetravelerother

領隊來源:same_as_applicant(同申請人)/ guide(嚮導,帶 leaderGuideId)/ traveler(本團旅客,帶 leaderTravelerId)/ other(手填 leaderName 與 leaderIdNumber)

leaderGuideId選填
string

leaderKind = guide 時的嚮導 ID。伺服器端從嚮導資料取姓名與身分證快照

leaderTravelerId選填
string

leaderKind = traveler 時的旅客 ID(須在本梯)。伺服器端取姓名與身分證快照

leaderName選填
string· max 100

領隊姓名;只在 leaderKind = other 時使用

leaderIdNumber選填
string· max 30

領隊身分證明碼;只在 leaderKind = other 時使用。需要 permit_pii.read,沒有時回 403

applicationNo選填
string· max 20

申請編號(英數與連字號,6–20 字)。改號時直接給新號,舊號留在歷程

oneStopSerial選填
string· max 50

一站式序號

caseNo選填
string· max 50

項目案件編號

submittedAt選填
string

申請(送出)時間(ISO 8601,含時區)

status選填
enum
draftsubmitted_no_numbersubmittedin_reviewwaitlistedlost_to_waitlistwon_pending_paymentwon_needs_documentsapprovedlostrejecteddeniedwaitlist_failedcancelled

狀態。弱的狀態不蓋強的:較弱時不套用,回應 applied.status.reason = weaker_status。voided 只能由重送產生

statusNote選填
string· max 1000

狀態說明

checkedAt選填
string

最近一次查籤的時間(ISO 8601,含時區)

siteDetail選填
string· max 5000

站方明細原文(查詢頁的文字摘要)

waitlistRank選填
integer· min 1

備取順位

eligibility選填
enum
pendinggrantednot_granted

入園資格:pending(待定)/ granted(取得)/ not_granted(未取得)

eligibilityNote選填
string· max 1000

資格說明

bedNumbers選填
string· max 500

床位/營位編號,原文照存

paymentDueAt選填
string

繳費期限(ISO 8601,含時區;林務局中籤後繳費)

latestMailSummary選填
string· max 2000

最近來信摘要。不要放身分證

orderIds選填
array· max 50

對應的訂單 ID(整組取代,須在本梯)。空陣列 = 整梯的單

idempotencyKey選填
string· 格式限定

冪等鍵(8–64 字英數或連字號)。同一把 key 再送一次不重複寫入,回傳第一次的結果;內容不同回 409 idempotency_conflict

replacesId選填
string

重送時被取代的舊單 ID。舊單會在同一個交易改成 voided(已作廢(重送))

depId路徑
string· min 1

梯次 ID

回應欄位 · data

application
object

建立後的申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

applied
object

每個有帶的欄位是否套用。

created
boolean

是否建了新單;冪等重送時沿用第一次的值。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/permit-applications" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}

出團準備整包讀取

GET/api/v1/departures/{depId}/prep
departure_prep.read模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data

departureId
string

梯次 id。

guides
object[]

隨團人員指派(leader 在前),含指派狀態。

id
string

指派紀錄 id。

guideId
string

被指派的嚮導 id。

guideName
string

被指派的嚮導姓名。

role
"assistant" | "leader"

指派角色:leader 主要隨團人員/assistant 協同。

status
"confirmed" | "tentative"

指派狀態:tentative 預塞暫定/confirmed 正式確認。

guideStartDate
string | null
guideEndDate
string | null
effectiveStartDate
string
effectiveEndDate
string
isNameBound
boolean
permitSwappedAt
string | null

勾「已換領」的時間(ISO);null = 未勾(issue 1731)。

permitSwappedByName
string | null

勾「已換領」的人的名稱;帳號已刪或未勾時為 null。

transport
object[]

派車紀錄。

id
string
description
string | null
driverName
string | null
vehicleInfo
string | null
fareNote
string | null
status
"arranged" | "pending"
catering
object[]

餐食紀錄。

id
string
supplier
string | null
mealPlan
string | null
headcountNote
string | null
status
"arranged" | "pending"
pretripStay
{ declaration: PreTripStayDeclaration; registrations: PreTripStayRegistrationRow[]; } | null

出發前夜住宿:宣告 + 全部登記(含已釋回列,看 releaseReason)。人數與性別彙總由 呼叫端從登記列算。訂房模組未啟用或行程沒指定據點時為 null。

declaration
object
id
string | null

實體列 id;**尚未實體化時為 null**(ADR 0022)。分頁的顯示條件是行程設定,不是這一列, 所以「有分頁但還沒有列」是正常狀態,第一筆登記或第一次發名單連結才會把它建出來。

departureId
string
departureDate
string
propertyId
string
propertyName
string
roomTypeId
string
roomTypeName
string
tripRoomTypeId
string | null

行程當下指定的床位池;null = 行程已改回旅客自理。**與 `roomTypeId` 不同時,這個出團 走的是實體化當下那一份**(ADR 0022 的 Consequence:畫面要說得出這件事)。

stayNight
string

住宿夜 = 出發日前一晚(由 departure_date 現算,非讀 `check_in` 欄)。

rosterLinkExpiresAt
string | null

只讓後台判斷是否已有有效連結;token 本體不進 server render。

rosterLinkActive
boolean
departureConfirmed
boolean

成團(`departures.confirmed_at` 有值)。旅客自助登記連結只在成團後可產生(issue 463)。

registrations
object[]
id
string
travelerId
string | null
fullName
string

活動登記現讀 travelers;旅客退團刪除後顯示不含 PII 的佔位文字。

gender
string | null
phone
string | null
orderNumber
string | null
orderCancelled
boolean

訂單是否已取消;T8 後對應登記應同時帶 releaseReason。

arrivalTime
string | null
night
string
cleaningFeeCollectedAt
string | null
cleaningFeeCollectedByName
string | null
releaseReason
PreTripStayReleaseReason | null
releasedAt
string | null
rentals
object[]

本梯裝備租借單(含明細)。登山未對此梯生效時為空陣列。

orderOnDeparture
boolean

Whether the order currently includes this rental departure.

deliveredAt選填
string | undefined | null
depositClearedAt選填
string | undefined | null
id
string

租借單 id(equipmentRental_ 前綴)。

rentalCode
string

人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。

orderId
string

掛載的訂單 id。

orderNumber
string | null

訂單編號;無對應訂單時為 null。

departureId
string | null

綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。

departureLabel
string | null

梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。

renterName
string | null

租借人姓名(可空)。

rentStartDate
string | null

租期起日(YYYY-MM-DD;可空)。

rentEndDate
string | null

租期迄日(YYYY-MM-DD;可空)。

returnedAt
string | null

歸還驗收時間(尚未歸還為 null)。

returnState
"cancelled" | "overdue" | "rented" | "returned"

歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。

inspectedAt
string | null

驗收時間(尚未驗收為 null)。

damageCostTwd
number | null

破損/遺失賠償金額(TWD;無為 null)。

reconState
"deposit_pending" | "pending" | "reconciled"

對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。

cancelledAt
string | null

取消時間(未取消為 null)。

cancelReason
string | null

取消原因(未取消為 null)。

notes
string | null

備註(可空)。

createdAt
string

建單時間。

updatedAt
string

最後更新時間。

lines
object[]

租借明細(借出的品項清單)。

id
string

租借明細 id(equipmentRentalLine_ 前綴)。

equipmentItemId
string

借出的裝備主檔品項 id。

itemName
string | null

裝備品項目前的名稱。

quantity
number

借出數量。

rentPriceTwdSnapshot
number

成交單位總價快照(每日單價 × 計價日數;TWD)。

depositTwdSnapshot
number

成交每件押金快照(TWD,不乘天數)。

returnedQuantity
number | null

已歸還數量(尚未歸還為 null)。

rentTotalTwd
number

成交租金合計(Σ rent snapshot × qty)。

depositTotalTwd
number

成交押金合計(Σ deposit snapshot × qty)。

documents
object[]

證件追蹤(只回既有列)。登山未對此梯生效時為空陣列。

id
string
docType
string

證件種類 key(`departure_document_types.key`)。

applyStatus
"applying" | "approved" | "todo"
fileReady
boolean
uploadedToCloud
boolean
fileUri
string | null
appliedAt
string | null
approvedAt
string | null
note
string | null
notApplicableAt
string | null

標「本團不需要」的時間;null = 沒標。

notApplicableByUserId
string | null
notApplicableReason
string | null

不需要的原因;有標記才有值。

checklist
object[]

團層級出團待辦(出團前在前,含已勾或有狀態文字但事後停用的項目),每項帶狀態文字。

id
string | null

勾稽列 id;null = 目錄有此項但本梯次還沒有勾稽列。

itemKey
string
label
string
phase
"post" | "pre"

目錄階段。UI 依此分「出團前」「出團後」兩區;完成分母只計 'pre'。

isActive
boolean

目錄啟用狀態。false 只可能出現在「已勾但事後停用」的列(見 listChecklist)。

required
boolean

這一梯要做:項目啟用中,而且行程沒設定或有勾選(issue 1369)。false 的列只因為本梯已勾、 寫過字或標過不適用才列出,不計入進度。

checkedAt
string | null
checkedByUserId
string | null
checkedByName
string | null

勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。

note
string | null

狀態文字(issue 1245);null = 沒有字。與勾選彼此獨立。

noteUpdatedAt
string | null

最後寫字的時間;沒有字時為 null。

noteUpdatedByUserId
string | null

最後寫字的人;沒有字或帳號刪除後為 null。

noteUpdatedByName
string | null

最後寫字的人的顯示名(同 `checkedByName`,帳號刪除後為 null)。

notApplicableAt
string | null

標「本團不適用」的時間;null = 沒標(issue 1369)。

notApplicableByName
string | null

標記者的顯示名;帳號刪除後為 null。

notApplicableReason
string | null

不適用的原因;有標記才有值。

travelerChecks
object

旅客層級出團待辦:欄(items)+ 已勾的格(checks)+ 有狀態文字的格(notes),都以 travelerId 對人。勾選與狀態文字彼此獨立,所以分兩份稀疏清單。

items
object[]
itemKey
string
label
string
isActive
boolean

false 只可能出現在「已勾或寫過字但事後停用」的項目。

checks
object[]
travelerId
string
itemKey
string
checkedAt
string
checkedByUserId
string | null
checkedByName
string | null

勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。

notes
object[]
travelerId
string
itemKey
string
note
string
noteUpdatedAt
string
noteUpdatedByUserId
string | null
noteUpdatedByName
string | null

最後寫字的人的顯示名(帳號刪除後為 null)。

insurance
object[]

投保(旅責險 / 登山險兩軸,依 kind 分)。

id
string
kind
"climbing" | "liability"
insurer
string | null
policyNo
string | null
status
"done" | "pending"
scheduledDate
string | null

排定日 'YYYY-MM-DD'(可以開始辦的日,不是死線);null = 未排定。

insuredCount
number | null

投保人數;null = 未填。

note
string | null
請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/prep" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "departureId": "…",
    "guides": [
      {
        "id": "…",
        "guideId": "…",
        "guideName": "…",
        "role": "assistant",
        "status": "confirmed",
        "guideStartDate": "…",
        "guideEndDate": "…",
        "effectiveStartDate": "…",
        "effectiveEndDate": "…",
        "isNameBound": true,
        "permitSwappedAt": "…",
        "permitSwappedByName": "…"
      }
    ],
    "transport": [
      {
        "id": "…",
        "description": "…",
        "driverName": "…",
        "vehicleInfo": "…",
        "fareNote": "…",
        "status": "arranged"
      }
    ],
    "catering": [
      {
        "id": "…",
        "supplier": "…",
        "mealPlan": "…",
        "headcountNote": "…",
        "status": "arranged"
      }
    ],
    "pretripStay": null,
    "rentals": [
      {
        "orderOnDeparture": true,
        "deliveredAt": "…",
        "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
      }
    ],
    "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": "…"
      }
    ]
  }
}

新增餐食紀錄

POST/api/v1/departures/{depId}/prep/catering
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

supplier選填
string

餐食供應商名稱

mealPlan選填
string

餐食安排說明(如餐數、菜色)

headcountNote選填
string

人數備註(如素食、特殊餐需求)

status選填
string

餐食安排狀態,預設 pending

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的餐食紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/catering" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier": "example-supplier",
  "mealPlan": "example-mealPlan",
  "headcountNote": "example-headcountNote"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

更新餐食紀錄

PATCH/api/v1/departures/{depId}/prep/catering/{id}
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

id路徑
string· min 1

餐食紀錄 ID

supplier選填
string

餐食供應商名稱;省略不動,給 null 清空

mealPlan選填
string

餐食安排說明(如餐數、菜色);省略不動,給 null 清空

headcountNote選填
string

人數備註(如素食、特殊餐需求);省略不動,給 null 清空

status選填
string

餐食安排狀態(pending / arranged);省略不動

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/departures/<depId>/prep/catering/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier": "example-supplier",
  "mealPlan": "example-mealPlan",
  "headcountNote": "example-headcountNote"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

刪除餐食紀錄

DELETE/api/v1/departures/{depId}/prep/catering/{id}
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

id路徑
string· min 1

餐食紀錄 ID

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/departures/<depId>/prep/catering/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

設定出團待辦某項勾選狀態

POST/api/v1/departures/{depId}/prep/checklist
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

itemKey必填
string· min 1

出團待辦項目的代碼

checked必填
boolean

該檢查項目是否已完成勾選

回應欄位 · data

ok
boolean

設定成功旗標,恆為 true。

id
string

出團待辦勾稽紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/checklist" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "itemKey": "example-itemKey",
  "checked": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

設定梯次期限警戒

POST/api/v1/departures/{depId}/prep/deadlines
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

deadlines必填
object
softDates選填
object

期限種類 key → 軟日期(建議開始,ISO 日期);空字串清空;未列的 key 保留既有軟日期

回應欄位 · data

ok
boolean

設定成功旗標,恆為 true。

departureId
string

被設定期限的梯次 id。

deadlines
object

本次套用的硬 deadline 異動(key → 日期;null = 已清除)。寫入的列來源為 manual。

softDates
object

本次套用的軟日期異動(key → 日期;null = 已清空)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/deadlines" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "deadlines": {
    "example-key": "example-deadlines"
  }
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "departureId": "…",
    "deadlines": "…",
    "softDates": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/deadlines/done
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

Departure ID

typeKey必填
string· min 1

Deadline type key

done必填
boolean

Target status

回應欄位 · data

changed
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/deadlines/done" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "typeKey": "example-typeKey",
  "done": true
}'
回應
{
  "ok": true,
  "data": {
    "changed": true
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/deadlines/not-applicable
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

Departure ID

typeKey必填
string· min 1

Deadline type key

notApplicable必填
boolean

Target status

reason選填
string· min 1

Required when marking not applicable

回應欄位 · data

changed
boolean
reason
string | null
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/deadlines/not-applicable" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "typeKey": "example-typeKey",
  "notApplicable": true
}'
回應
{
  "ok": true,
  "data": {
    "changed": true,
    "reason": "…"
  }
}

依關鍵日期回推規則重算梯次期限

POST/api/v1/departures/{depId}/prep/deadlines/recompute
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

keys選填
array· min 1

只重算這些期限種類 key(至少一個);省略 = 全部啟用中的事項

includeManual選填
boolean

true = 把指定事項的人工覆寫改回公式值(還原);必須搭配 keys,不得整梯次一次還原。預設 false 只覆寫公式列

回應欄位 · data

departureId
string

被重算的梯次 id。

rows
object[]

各事項的公式結果;written=false 表示該列是人工覆寫、本次未動。

key
string
label
string
softDate
string
deadlineDate
string
written
boolean

false = 該列是人工覆寫、本次未動(includeManual=false)。

missingHolidayYears
number[]
skipped
object[]

規則無法套用而略過的事項(key / label / 原因)。

key
string
label
string
message
string
missingHolidayYears
number[]

假日表未維護、但工作天回推觸及的年度;非空即「假日資料不完整」。

removed
string[]

被清掉的事項 key:規則已停用或算不出公式值;還原時連人工列一起移除。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/deadlines/recompute" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "keys": [
    "example-keys"
  ],
  "includeManual": true
}'
回應
{
  "ok": true,
  "data": {
    "departureId": "…",
    "rows": [
      {
        "key": "…",
        "label": "…",
        "softDate": "…",
        "deadlineDate": "…",
        "written": true,
        "missingHolidayYears": [
          0
        ]
      }
    ],
    "skipped": [
      {
        "key": "…",
        "label": "…",
        "message": "…"
      }
    ],
    "missingHolidayYears": [
      0
    ],
    "removed": [
      "…"
    ]
  }
}

upsert 一種證件追蹤狀態

POST/api/v1/departures/{depId}/prep/documents
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

docType必填
string· min 1

證件/文件種類代碼(如入山申請、保險名冊)

applyStatus選填
enum
todoapplyingapproved

申辦狀態:todo(待辦)/ applying(申請中)/ approved(已核准)

fileReady選填
boolean

文件檔案是否已備妥

uploadedToCloud選填
boolean

文件是否已上傳雲端

fileUri選填
string

文件檔案連結;給 null 清空

note選填
string

備註;給 null 清空

回應欄位 · data

ok
boolean

upsert 成功旗標,恆為 true。

id
string

證件追蹤紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/documents" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "docType": "example-docType"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

upsert 某裝備品項的需求數

POST/api/v1/departures/{depId}/prep/equipment-needs
departure_prep.manage模組:climbing

參數

depId路徑
string· min 1

梯次 ID

equipmentItemId必填
string· min 1

裝備品項 ID

quantity必填
integer

該品項的需求數量

note選填
string

需求備註;給 null 清空

回應欄位 · data

ok
boolean

upsert 成功旗標,恆為 true。

id
string

裝備需求紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/equipment-needs" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "equipmentItemId": "example-equipmentItemId",
  "quantity": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

刪除裝備需求列

DELETE/api/v1/departures/{depId}/prep/equipment-needs/{id}
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

id路徑
string· min 1

裝備需求列 ID

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/departures/<depId>/prep/equipment-needs/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

指派 / 重派嚮導到梯次

POST/api/v1/departures/{depId}/prep/guides
departure_prep.manage模組:tour

參數

guideStartDate選填
string

帶團開始日期;與結束日期成對,null 回復行程預設

guideEndDate選填
string

帶團結束日期;與開始日期成對

isNameBound選填
boolean

是否為綁名指派

nameBoundChangeReason選填
string· max 500 · min 1

解除綁名或變更綁名角色的原因

depId路徑
string· min 1

梯次 ID

guideId必填
string· min 1

嚮導 ID

role必填
enum
leaderassistant

指派角色:leader(主要隨團人員)或 assistant(協同)

status選填
enum
tentativeconfirmed

指派狀態:tentative(暫定)或 confirmed(已確認)

回應欄位 · data

ok
boolean

指派成功旗標,恆為 true。

id
string

指派紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/guides" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "guideId": "example-guideId",
  "role": "leader"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

新增投保紀錄

POST/api/v1/departures/{depId}/prep/insurance
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

kind必填
string· min 1

保險種類:liability(旅責險)/ climbing(登山險)

insurer選填
string

保險公司名稱

policyNo選填
string

保單號碼

status選填
string

投保狀態,預設 pending

scheduledDate選填
string

排定日 YYYY-MM-DD(旅責:排定辦理日;登山:排定送出日)。可以開始辦的日,不是死線;省略 = 未填

insuredCount選填
integer· max 9999 · min 0

投保人數;省略 = 未填

note選填
string

備註;給 null 清空

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的投保紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/insurance" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "example-kind"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

更新投保紀錄

PATCH/api/v1/departures/{depId}/prep/insurance/{id}
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

id路徑
string· min 1

投保紀錄 ID

insurer選填
string

保險公司名稱;省略不動,給 null 清空

policyNo選填
string

保單號碼;省略不動,給 null 清空

status選填
string

投保狀態(pending / done);省略不動

scheduledDate選填
string

排定日 YYYY-MM-DD(旅責:排定辦理日;登山:排定送出日)。可以開始辦的日,不是死線;省略不動,給 null 清空

insuredCount選填
integer· max 9999 · min 0

投保人數;省略不動,給 null 清空

note選填
string

備註;省略不動,給 null 清空

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/departures/<depId>/prep/insurance/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "insurer": "example-insurer",
  "policyNo": "example-policyNo",
  "status": "example-status"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

刪除投保紀錄

DELETE/api/v1/departures/{depId}/prep/insurance/{id}
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

id路徑
string· min 1

投保紀錄 ID

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/departures/<depId>/prep/insurance/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
GET/api/v1/departures/{depId}/prep/ops
departure_prep.read模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

assignments
object[]
id
string
userId
string
userName
string
candidates
object[]
id
string
name
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/prep/ops" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "assignments": [
      {
        "id": "…",
        "userId": "…",
        "userName": "…"
      }
    ],
    "candidates": [
      {
        "id": "…",
        "name": "…"
      }
    ]
  }
}
POST/api/v1/departures/{depId}/prep/ops
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

Departure ID

userId必填
string· min 1

Staff user ID

回應欄位 · data

ok
true
id
string
created
boolean

true = 這次真的新增;false = 命中既有列(idempotent)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/ops" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "example-userId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…",
    "created": true
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/ops-defaults/apply
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

transport
number
catering
number
insurance
number
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/ops-defaults/apply" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "transport": 0,
    "catering": 0,
    "insurance": 0
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/pretrip-stays
departure_prep.manage模組:lodging

參數

depId路徑
string· min 1

Departure ID

travelerId必填
string· min 1

Traveler ID

arrivalTime選填
string· 格式限定

Arrival time HH:MM

回應欄位 · data

ok
true
registrationId
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/pretrip-stays" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "travelerId": "example-travelerId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "registrationId": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/pretrip-stays/{registrationId}/arrival
departure_prep.manage模組:lodging

參數

depId路徑
string· min 1

Departure ID

registrationId路徑
string· min 1

Pretrip stay registration ID

arrivalTime選填
string· 格式限定

Arrival time HH:MM

回應欄位 · data

ok
true
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/pretrip-stays/<registrationId>/arrival" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "arrivalTime": "08:00"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/pretrip-stays/{registrationId}/cancel
departure_prep.manage模組:lodging

參數

depId路徑
string· min 1

Departure ID

registrationId路徑
string· min 1

Pretrip stay registration ID

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/pretrip-stays/<registrationId>/cancel" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/pretrip-stays/{registrationId}/cleaning-fee
departure_prep.manage模組:lodging

參數

depId路徑
string· min 1

Departure ID

registrationId路徑
string· min 1

Pretrip stay registration ID

collected必填
boolean

Cleaning fee collected

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/pretrip-stays/<registrationId>/cleaning-fee" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "collected": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/pretrip-stays/roster-link
departure_prep.manage模組:lodging

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

token
string
expiresAt
string
url
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/pretrip-stays/roster-link" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "token": "…",
    "expiresAt": "…",
    "url": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/prep/pretrip-stays/self-links
departure_prep.manage模組:lodging

參數

depId路徑
string· min 1

Departure ID

orderId選填
string· min 1

Limit to one order

mode必填
enum
ensurerotate

Keep or rotate the link

回應欄位 · data

links
object[]
orderId
string
orderNumber
string
url
string
expiresAt
string
rotated
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/pretrip-stays/self-links" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "ensure"
}'
回應
{
  "ok": true,
  "data": {
    "links": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "url": "…",
        "expiresAt": "…",
        "rotated": true
      }
    ]
  }
}

從裝備需求開租借單

POST/api/v1/departures/{depId}/prep/rentals
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

orderId必填
string· min 1

要掛這筆租借費用的訂單 ID

renterName選填
string

租借人姓名;給 null 清空

rentStartDate選填
string

Rental start date

rentEndDate選填
string· 格式限定

Rental end date

lines必填
array

租借品項明細(品項 + 數量),數量需大於 0 才計入

回應欄位 · data

ok
boolean

開單成功旗標,恆為 true。

rentalId
string

新開立的裝備租借單 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/rentals" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "example-orderId",
  "lines": [
    {
      "itemId": "example-itemId",
      "qty": 1
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "rentalId": "…"
  }
}

新增派車紀錄

POST/api/v1/departures/{depId}/prep/transport
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

description選填
string

派車說明(如路線、接送地點)

driverName選填
string

司機姓名

vehicleInfo選填
string

車輛資訊(如車型、車牌)

fareNote選填
string

車資備註

status選填
string

派車狀態,預設 pending

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的派車紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/prep/transport" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "example-description",
  "driverName": "example-driverName",
  "vehicleInfo": "example-vehicleInfo"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

更新派車紀錄

PATCH/api/v1/departures/{depId}/prep/transport/{id}
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

id路徑
string· min 1

派車紀錄 ID

description選填
string

派車說明(如路線、接送地點);省略不動,給 null 清空

driverName選填
string

司機姓名;省略不動,給 null 清空

vehicleInfo選填
string

車輛資訊(如車型、車牌);省略不動,給 null 清空

fareNote選填
string

車資備註;省略不動,給 null 清空

status選填
string

派車狀態(pending / arranged);省略不動

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/departures/<depId>/prep/transport/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "example-description",
  "driverName": "example-driverName",
  "vehicleInfo": "example-vehicleInfo"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

刪除派車紀錄

DELETE/api/v1/departures/{depId}/prep/transport/{id}
departure_prep.manage模組:tour

參數

depId路徑
string· min 1

梯次 ID

id路徑
string· min 1

派車紀錄 ID

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/departures/<depId>/prep/transport/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

分房表匯出資料列

GET/api/v1/departures/{depId}/rooming-export
departure_prep.read | departure.update模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data[]

travelerId
string

旅客 id。外部系統用它對人,不靠姓名。

fullName
string

旅客姓名。

gender
string

性別(中文標籤:男/女/其他)。

roomLabel
string

房號/房間標籤(未排房為「未分房」)。

bedInfo
string

床位資訊(房型中文標籤 + 床位)。

roommates
string

同房其他旅客姓名(依房號分組派生)。

specialRequest
string

特殊需求(房友偏好等自由文字)。

contactSummary
string

聯絡摘要(電話已遮罩,只露末 3 碼)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/rooming-export" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "travelerId": "…",
      "fullName": "…",
      "gender": "…",
      "roomLabel": "…",
      "bedInfo": "…",
      "roommates": "…",
      "specialRequest": "…",
      "contactSummary": "…"
    }
  ]
}

該梯次分房檢視

GET/api/v1/departures/{depId}/rooms
departure_prep.read | departure.update模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data

departure
object

梯次表頭(id/起訖日/行程名/容量等)。

id
string

梯次 id(dep_ 前綴)。

departureDate
string

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

returnDate
string

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

tripTitle
string

所屬行程標題。

tripSlug
string

所屬行程網址 slug。

capacity
number

名額上限(人數)。

bookedCount
number

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

rooms
object[]

此梯次的所有房間(含入住旅客)。

id
string

房間 id。

roomLabel
string

房號/房間標籤。

roomType
string

房型(如 single 單人/double 雙人/dorm 通舖)。

bedCount
number

床位數。

bedConfig
string | null

床位配置說明(可空)。

accommodationName
string | null

住宿名稱(梯次配套派生房才有;可空)。

accommodationDate
string | null

住宿日期(YYYY-MM-DD;可空)。

baseCostTwd
number

房間底價成本(TWD)。

upgradeFeeTwd
number

房型升等補款(TWD)。

notes
string | null

備註(可空)。

departureLodgingId
string | null

null = 手動建立的房;non-null = 梯次配套自動派生房的來源 ID。

assignedTravelers
object[]

已入住此房的旅客。

id
string

旅客 id。

fullName
string

旅客姓名。

orderId
string

所屬訂單 id。

orderNumber
string

所屬訂單編號。

isPrimary
boolean

是否為該訂單的主要聯絡人(訂購人)。

gender
string | null

性別(分房 gender 衝突偵測用):'male'|'female'|'other'|null。

roomPreference
string | null

下單登記的房型偏好(chip 上顯示配房意向 badge)。

roommatePref
string | null

指定房友 id / 特殊需求自由文字。

companionGroup
CompanionGroupRef | null

本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。

groupId
string
code
string

代號(A、B…,第 27 組起 AA)。

colorIndex
number

顏色序號(0 起,循環)。UI 用它挑色票。

unassignedTravelers
object[]

尚未分房的旅客清單。

assignedElsewhere選填
boolean | undefined

True when the traveler has a room in another departure.

id
string

旅客 id。

fullName
string

旅客姓名。

orderId
string

所屬訂單 id。

orderNumber
string

所屬訂單編號。

isPrimary
boolean

是否為該訂單的主要聯絡人(訂購人)。

gender
string | null

性別:'male'|'female'|'other'|null。

birthDate選填
string | undefined

出生日期(YYYY-MM-DD;可空)。

roomPreference
string | null

下單登記的房型偏好(auto-pair 起點提示)。

roommatePref
string | null

指定房友 id / 特殊需求自由文字。

companionGroup
CompanionGroupRef | null

本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。

groupId
string
code
string

代號(A、B…,第 27 組起 AA)。

colorIndex
number

顏色序號(0 起,循環)。UI 用它挑色票。

stats
object

分房統計彙總(總人數/已分房數/房間數/升等補款合計)。

totalTravelers
number

此梯次旅客總人數。

assignedCount
number

已分配房間的旅客數。

roomCount
number

房間數。

totalUpgradeFee
number

升等補款合計(TWD 整數)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/rooms" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
    }
  }
}

建立一間梯次房間

POST/api/v1/departures/{depId}/rooms
departure.update模組:tour

參數

depId路徑
string· min 1

梯次 ID

roomLabel必填
string· min 1

房間代號/標籤(如 101、A 房)

roomType必填
string· min 1

房型(如 雙人房、四人房)

bedCount必填
integer· min 1

床位數,必須大於 0

bedConfig選填
string

床型配置說明(如 2 大床、1 大 2 小)

accommodationName選填
string

住宿地點/旅宿名稱

accommodationDate選填
string

入住日期,須為 YYYY-MM-DD 且為真實存在的曆日;形狀不合回 409 conflict

baseCostTwd選填
integer· min 0

房間基本成本(台幣),預設 0

upgradeFeeTwd選填
integer· min 0

房型升等補款金額(台幣),預設 0

notes選填
string

房間備註

回應欄位 · data

ok
boolean

建立成功旗標,恆為 true。

id
string

新建立的房間 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/rooms" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "roomLabel": "example-roomLabel",
  "roomType": "example-roomType",
  "bedCount": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

編輯房間

PATCH/api/v1/departures/{depId}/rooms/{roomId}
departure.update模組:tour

參數

roomId路徑
string· min 1

房間 ID

roomLabel選填
string

房間代號/標籤;未給則不變

roomType選填
string

房型;未給則不變

bedCount選填
integer· min 1

床位數;未給則不變

bedConfig選填
string

床型配置說明;給 null 清空、未給則不變

accommodationName選填
string

住宿地點名稱;給 null 清空、未給則不變

accommodationDate選填
string

入住日期,須為 YYYY-MM-DD 且為真實存在的曆日(形狀不合回 409 conflict);給 null 清空、未給則不變

baseCostTwd選填
integer· min 0

房間基本成本(台幣);未給則不變

upgradeFeeTwd選填
integer· min 0

房型升等補款金額(台幣);未給則不變

notes選填
string

房間備註;給 null 清空、未給則不變

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/departures/{depId}/rooms/<roomId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "roomLabel": "example-roomLabel",
  "roomType": "example-roomType",
  "bedCount": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}

刪除房間

DELETE/api/v1/departures/{depId}/rooms/{roomId}
departure.update模組:tour

參數

roomId路徑
string· min 1

房間 ID

回應欄位 · data

ok
boolean

刪除成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/departures/{depId}/rooms/<roomId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

線控確認 auto-pair 建議分組:

POST/api/v1/departures/{depId}/rooms/auto-pair-apply
departure.update模組:tour

參數

depId路徑
string· min 1

梯次 ID

travelerIds必填
array· min 1

要編入同一房的旅客 ID 清單,至少一人

roomType選填
string· min 1

建立房間的房型,預設 shared(合住)

回應欄位 · data

ok
boolean

套用成功旗標,恆為 true。

roomId
string

建議分組寫入後所在的房間 id。

travelerIds
string[]

被排入該房的旅客 id 清單。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/rooms/auto-pair-apply" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "travelerIds": [
    "example-travelerIds"
  ]
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "roomId": "…",
    "travelerIds": [
      "…"
    ]
  }
}

對某梯次「尚未排房」的旅客

GET/api/v1/departures/{depId}/rooms/auto-pair-preview
departure.update模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data

suggestion
object

auto-pair 引擎產出的分房建議(未寫入,供線控確認)。

groups
object[]

建議的分房組合(每組一間房,含旅客與需確認註記)。

kind
"auto_same_gender" | "roommate_request" | "single" | "special_request"
travelerIds
string[]
needsConfirmation選填
boolean | undefined

需線控人工確認(跨性別指定房友 / gender='other')。

note選填
string | undefined

給線控看的提示(特殊需求原文、超過床數、單人房卻又指名房友…)。

unmatched
object[]

無法安全自動配對、待人工處理的旅客。

travelerId
string
reason
"gender_missing" | "needs_confirmation" | "no_same_gender_pair"
names
object

travelerId → 顯示名(建議分組渲染用)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/rooms/auto-pair-preview" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "suggestion": {
      "groups": [
        {
          "kind": "auto_same_gender",
          "travelerIds": [
            "…"
          ],
          "needsConfirmation": true,
          "note": "…"
        }
      ],
      "unmatched": [
        {
          "travelerId": "…",
          "reason": "gender_missing"
        }
      ]
    },
    "names": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/send-balance-slips
departure.update模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

sent
number

真的寄出(信進了佇列)的訂單數。

excludedAgencyOrders
number

同業單不寄信、不建連結,請經同業收款。

skipped
number

逐單略過數 = `skippedAlreadySent` + `skippedNoTemplate` + `skippedNoRecipient` + `skippedNotEligible`。 **不含**因梯次失格而中止未跑到的單(那些在 `unsentDepartureIneligible`)。

skippedAlreadySent
number

略過細分:已寄過(claim 命中)。重跑仍會略過,正常。

skippedNoTemplate
number

略過細分:連結已建但租戶沒有啟用中的「收尾款」範本而沒寄成。這種略過**不留 claim** —— 補設範本後重跑同一批次會補寄。

skippedNoRecipient
number

略過細分:連結已建但沒有收件人而沒寄成。訂購人沒有 email。補設範本不會補寄,承辦要另行聯繫。

skippedNotEligible
number

略過細分:撈出來之後才發現不符資格(尾款已結清 / 期間被取消)。

unsentDepartureIneligible
number

因**梯次**中途失格(被取消 / 被退回成團)而未寄的訂單數 —— 含發現當下那張與其後 全部未跑到的單。>0 = 這批提早中止。刻意**不併進 `skipped`**:那三種略過的後續動作 是去看那張單,這種是去看梯次。

failed
number

例外中斷的訂單數(其餘訂單不受影響)。

failures
object[]

失敗清單(辨識到訂單號)。`reason` 只給分類字串 —— DB 例外訊息會帶表名 / 約束名 / 衝突鍵的值(可能含 email),那些留 server log,不經 server action 回瀏覽器。

orderId
string
orderNumber
string
reason
"internal_error"
noCandidates
BalanceSlipIneligibleBreakdown | null

本梯沒有任何符合條件的單時,各張單為什麼不符(#1456);有符合的單時 null。 結果全是 0 時,承辦要看得出是「沒有符合的單」,不是「按了沒反應」。

total
number

本梯的訂單數(含已取消)。

cancelled
number
waitlisted
number

候補中(還沒有席位)。

lotteryNotWon
number

抽籤梯次未中籤。

unpaid
number
partiallyPaid
number

已付款但未付足訂金。

paid
number

已付清(含溢收)。

other
number
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/send-balance-slips" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/send-consent-reminders
departure.update模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

sent
number
skippedNoPending
number

沒有待簽的自訂同意書(已簽齊或不適用)。

skippedNoRecipient
number

訂購人帳號沒有 email,系統寄不出去。

failed
number
failures
object[]
orderNumber
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/send-consent-reminders" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "sent": 0,
    "skippedNoPending": 0,
    "skippedNoRecipient": 0,
    "failed": 0,
    "failures": [
      {
        "orderNumber": "…"
      }
    ]
  }
}

Use the canonical tenant operation.

POST/api/v1/departures/{depId}/submission-export
departure.submission_export模組:tour

參數

depId路徑
string· min 1

Departure ID

assignments必填
array· min 1

Order group assignments; null skips an order

acknowledgedIssueCount必填
integer

Acknowledged traveler issue count from preview

回應欄位 · data

kind
"toko.departure-submission"
v
1
exportedAt
string

匯出時間(ISO 8601,UTC)。承辦貼上後用來核對不是上一梯的資料。

trip
object
code
string
name
string
departure
object
groupCode
string | null

團號;還沒產生時為 null。

entryDate
string

入園日 = 出發日 + 入園日偏移。

startDate
string

出發日 YYYY-MM-DD。

endDate
string

回程日 YYYY-MM-DD。

groups
object[]
no
number
travelers
object[]
name
string
gender
string
birthDate
string
idNumber
string
phone
string
email
string
address
string
emergencyName
string
emergencyPhone
string
validation
string
orderNumber
string
passportNo
string
nationality
string
nationalityName
string
passportFile
SubmissionPassportFile | null

護照影本的下載網址(passport-ocr §0.5)。沒有影本時為 null。網址 30 分鐘到期, 兌換時另要登入身分與 `departure.submission_export`。

url
string
contentType
string
expiresAt
string

網址到期時間(ISO 8601,UTC)。

staff
object[]

加帶的隨團人員,不屬於任何一組(issue 1416)。沒勾任何人為空陣列。

kind
"staff"
guideId
string
role
"assistant" | "leader"

leader 主要/assistant 協同。

status
"confirmed" | "tentative"

tentative 預塞/confirmed 正式。

englishName
string

英文姓名(與護照一致);未填為空字串。

name
string
phone
string
email
string
address
string
gender
string
birthDate
string
idNumber
string
emergencyName
string
emergencyPhone
string
validation
string
passportNo
string
nationality
string
nationalityName
string
counts
object

送件人數:客人(各組合計)+隨團。

travelers
number
staff
number
total
number
source
object
tool
"toko"
請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/submission-export" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
    }
  }
}

Use the canonical tenant operation.

GET/api/v1/departures/{depId}/submission-preview
departure.submission_export模組:tour

參數

depId路徑
string· min 1

Departure ID

回應欄位 · data

departure
object
departureId
string
groupCode
string | null

團號;還沒產生時為 null。

tripCode
string

行程的中性代碼(slug)。

tripTitle
string
startDate
string

出發日 YYYY-MM-DD。

endDate
string

回程日 YYYY-MM-DD。

entryDate
string

入園日 = 出發日 + 入園日偏移。

entryDateOffsetDays
number
orders
object[]
orderId
string
orderNumber
string
leadName
string | null

主要聯絡人(訂單第一位旅客)姓名,讓承辦認得是哪一張單。

travelerCount
number
travelers
object[]

這張單的全部旅客,順序同匯出。`companionGroup` 是旅客在本梯次的同行組(§2.11), 給承辦當「誰跟誰一夥」的提示,跨訂單也對得上(issue 1171)。

name
string | null
companionGroup
CompanionGroupRef | null
groupId
string
code
string

代號(A、B…,第 27 組起 AA)。

colorIndex
number

顏色序號(0 起,循環)。UI 用它挑色票。

lastGroup
SubmissionLastGroup | null

上一次匯出時這張單的組別(已重編)。`null` = 沒有可沿用的紀錄:沒匯出過、這張單 當時不在梯次上、或人數變了。

group
number | null
issues
object[]

有驗證問題的旅客;沒有問題的旅客不列。

travelerName
string | null
messages
string[]
staff
object[]

這一梯的全部已派隨團人員,`included` = 已勾加帶進送籤名單(issue 1416)。

assignmentId
string

指派紀錄 id。

guideId
string
nickname
string

暱稱(後台顯示名)。

legalName
string | null

正式姓名;未填為 null(送籤檢查會列「姓名未填」)。

role
"assistant" | "leader"

leader 主要/assistant 協同。

status
"confirmed" | "tentative"

tentative 預塞/confirmed 正式。

included
boolean

已勾「加帶進送籤名單」。

issues
string[]

送籤檢查問題(資料待補);沒有問題為空陣列。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/submission-preview" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": [
          "…"
        ]
      }
    ]
  }
}

Use the canonical tenant operation.

PUT/api/v1/departures/{depId}/submission-staff
departure.submission_export模組:tour

參數

depId路徑
string· min 1

Departure ID

guideIds必填
array

Assigned guide IDs to include in the submission list; omitted guides are removed

回應欄位 · data

guideIds
string[]
請求
curl -X PUT "https://your-tenant.example.com/api/v1/departures/<depId>/submission-staff" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "guideIds": [
    "example-guideIds"
  ]
}'
回應
{
  "ok": true,
  "data": {
    "guideIds": [
      "…"
    ]
  }
}

梯次的付款登記

GET/api/v1/departures/{depId}/supplier-payments
payment.read模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data

departureId
string
payments
object[]
id
string
departureId
string
groupCode
string | null

團號;未產生為 null。

tripTitle
string
departureDate
string

出發日(YYYY-MM-DD)。

paidOn
string

付款日期(YYYY-MM-DD)。

handlerUserId
string
handlerName
string

經手人姓名。

receivingAccountId
string

付款渠道(收款帳戶 ID)。

channelName
string

付款帳戶名稱(例:小編機)。

payee
string

付給誰/項目。

note
string | null

說明;未填為 null。

amountTwd
number

金額(TWD 整數);退費為負數。

createdAt
string

登記時間(ISO 8601,UTC)。

updatedAt
string

最後修改時間(ISO 8601,UTC)。

totalTwd
number
請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/supplier-payments" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "departureId": "…",
    "payments": [
      {
        "id": "…",
        "departureId": "…",
        "groupCode": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "paidOn": "…",
        "handlerUserId": "…",
        "handlerName": "…",
        "receivingAccountId": "…",
        "channelName": "…",
        "payee": "…",
        "note": "…",
        "amountTwd": 0,
        "createdAt": "…",
        "updatedAt": "…"
      }
    ],
    "totalTwd": 0
  }
}

該梯次的有效報名調查項

GET/api/v1/departures/{depId}/survey
trip.read模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data[]

id
string
kind
"multi" | "quantity" | "single" | "text"
label
string
description
string | null
required
boolean
options
object[]
id
string
label
string
disabled
boolean

本梯次停用(新答案不可選;既有答案保留並標示)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/survey" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "kind": "multi",
      "label": "…",
      "description": "…",
      "required": true,
      "options": [
        {
          "id": "…",
          "label": "…",
          "disabled": true
        }
      ]
    }
  ]
}

Use the canonical tenant operation.

PATCH/api/v1/departures/{depId}/survey-options/{optionId}
departure.update模組:tour

參數

depId路徑
string· min 1

Departure ID

optionId路徑
string· min 1

Survey option ID

disabled必填
boolean

Disable option for this departure

回應欄位 · data

ok
true
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/departures/<depId>/survey-options/<optionId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "disabled": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}

該梯次套用的成本範本列

GET/api/v1/departures/{depId}/template-costs
departure.update模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data[]

id
string

梯次成本列 ID。

category
string

成本分類(如 交通 / 餐費 / 保險)。

vendorName
string | null

供應商 / 廠商名(可空)。

description
string | null

摘要說明(可空)。

amountTwd
number

內帳成本金額(TWD;數量 × 單價派生)。

invoiceAmountTwd
number

報帳/發票金額(TWD;is_declarable=true 時同步 amount,否則 0)。

isDeclarable
boolean

是否有合法憑證可報帳(開發票)。

quantityMode
QuantityMode | null

數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。

headcountComponents
HeadcountComponent[] | null

headcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。

groupDivisor
number | null

headcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。

quantity
number | null

實際套用的數量(依 quantityMode 派生)。

unitPriceTwd
number | null

內帳單價(TWD;外幣列可為 null)。

currency
string

幣別('TWD' = 台幣列)。

unitPriceForeign
number | null

外幣單價;TWD 列 null。

foreignAmount
number | null

外幣金額快照 = unit_price_foreign × quantity;TWD 列 null。

internalRate
string | null

內帳匯率快照(numeric 字串);TWD 列 null。

externalRate
string | null

外帳匯率快照(numeric 字串);TWD 列 null。

isManualOverride
boolean

是否為線控手動改寫(true 時重算會跳過此列,不覆蓋手改值)。

payableId
string | null

已轉請款 → 鎖定(不可手改 / 重算)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/template-costs" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}

重設為範本算法

POST/api/v1/departures/{depId}/template-costs/{id}/clear-override
departure_cost.manage模組:tour

參數

id路徑
string· min 1

範本成本列 ID

回應欄位 · data

ok
boolean

清除手改鎖並重算成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/{depId}/template-costs/<id>/clear-override" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

線控手改某範本成本列

POST/api/v1/departures/{depId}/template-costs/{id}/override
departure_cost.manage模組:tour

參數

id路徑
string· min 1

範本成本列 ID

amountTwd必填
integer

手動指定的成本金額(台幣),設定後停止自動重算

回應欄位 · data

ok
boolean

手改金額成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/{depId}/template-costs/<id>/override" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amountTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

套用行程綁定範本到本梯次

POST/api/v1/departures/{depId}/template-costs/apply
departure_cost.create模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data

ok
boolean

套用成功旗標,恆為 true。

inserted
number

本次新補插入的範本成本行數(冪等,已存在的不重複插)。

skippedForeign
number

因匯率未備妥而跳過的外幣行數。補齊匯率後再套用,會自動補上這些行。

請求
curl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/template-costs/apply" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "inserted": 0,
    "skippedForeign": 0
  }
}

該梯次各訂單旅客資料完整度

GET/api/v1/departures/{depId}/validation-summary
order.read模組:tour

參數

depId路徑
string· min 1

梯次 ID

回應欄位 · data[]

orderId
string

訂單 id。

orderNumber
string

訂單編號。

errorCount
number

該訂單的 error(必補缺漏)項目數。

warningCount
number

該訂單的 warning(建議補齊)項目數。

incompleteTravelerCount
number

至少有一項 error 或 warning 的旅客數(資料待補人數)。

errorTravelerCount
number

含 error 的旅客數(出團前置紅標用)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/validation-summary" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "orderId": "…",
      "orderNumber": "…",
      "errorCount": 0,
      "warningCount": 0,
      "incompleteTravelerCount": 0,
      "errorTravelerCount": 0
    }
  ]
}

團控主列表:以出發日為主軸、彙整 order/付款/同意書

GET/api/v1/departures/control
order.read模組:tour

參數

range選填
enum
future_7future_60future_90future_180future_365this_monthnext_monthcustom

時間視窗:future_60 / future_90 / future_180(預設)/ future_365(未來 N 天)、this_month(本月)、next_month(下個月)、custom(自訂,配 from / to)

from選填
string

自訂區間起日 YYYY-MM-DD(含),range=custom 時必填

to選填
string

自訂區間迄日 YYYY-MM-DD(含),range=custom 時必填;from ≤ to,最長 731 天,超過回 400

trip選填
string

行程 ID,只看該行程的梯次

status選填
string

梯次狀態篩選(如 open / closed)

attention選填
boolean

設為 true 時只回傳需要關注的梯次:有人未結清、有訂單未簽同意書,或有缺件(已成團未派主要隨團人員、未派承辦、隨團人員不足(已成團、需要數已填且確認人數少於需要數)、期限逾期或將到期、資料待補或資格待審、未分房)。已結束的梯次預設不列;同時指定 status 時,那些梯次只看付款與同意書

mine選填
boolean

設為 true 時只回傳我是承辦小編的梯次;只對 op / admin 生效,其他角色忽略

回應欄位 · data[]

id
string

梯次 id。

tripId
string

所屬行程 id。

tripTitle
string

行程名稱。

tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

hasPreTripNight
boolean

行程有行前集合夜:出發日前一晚集合(trips.md §3)。

tripSlug
string

行程公開頁網址代稱(slug)。

groupCode
string | null

團號(可空)。

label
string | null

梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);null = 無。

isPrivate
boolean

不對外販售(issue 509 ①):前台藏、後台照建。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

capacity
number

團位容量(總名額)。

bookedCount
number

已佔位人數。

status
string

梯次狀態(如 open 開放/closed 關閉)。

salesOpenAt
string | null

排定的開賣時間 ISO 字串;null = 沒排程(trips.md §2.2a,issue 1643)。

salesOpenFailedReason
string | null

自動開賣被擋下的原因;null = 沒失敗。

confirmedAt
string | null

成團時間 ISO 字串;null = 尚未成團(group-confirmation §2,與 status 正交)。

minGroupSize
number | null

行程層最低成團人數門檻;null = 未設門檻(不提示達標)。

allocationMode
"fcfs" | "lottery"

佔位模式:fcfs 先到先得/lottery 抽籤。

leaderNames
string[]

已排主要隨團人員姓名(confirmed + tentative 皆列;空 = 未指派)。

assistantNames
string[]

已排協作 / 助教姓名(空 = 未指派協作)。

nameBoundGuideNames
string[]

Names on assignments that require a reason for replacement or removal.

confirmedLeaderCount
number

已確認(status='confirmed')的主要隨團人員人數;0 = 沒有確認的主要隨團人員(tentative 不算)。

confirmedGuideCount
number

已確認(status='confirmed')的主要+協同人數合計(issue 1117 的「已派」)。

permitSwappedCount
number

已確認指派中勾了「已換領」的人數(issue 1731)。

requiredGuideCount
number | null

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

notes
string | null

梯次備註(集合上下車點、代收註記…;null = 無)。

opNames
string[]

承辦小編姓名;空陣列不代表本梯不需承辦。

opNotRequiredReason選填
string | null | undefined

明確標記本梯不需承辦的原因;null = 未標記。

priceTwd
number

定價(TWD)。

agencyPriceTwd
number | null

同業/旅行社報價(TWD;未設為 null)。

promoActive
boolean

是否有進行中的促銷價。

promoPriceTwd
number | null

促銷價(TWD;無促銷為 null)。

promoAgencyPriceTwd
number | null

同業促銷價(TWD;無促銷為 null)。

daysUntilDeparture
number

距出發天數(負值表示已出發)。

salesClosePassed選填
boolean | undefined

有效停止售票時間已過(同 `updateDepartureStatus` 的守衛)。true 時改回售票中一定被拒, 梯次總覽的「恢復售票」改成停用並寫原因(issue 1654)。省略視同 false。

travelerCount
number

旅客總人數(未取消訂單的 party_size 加總)。

paidCount
number

已付款人數(party_size 加總;不含取消)。

pendingCount
number

未結清人數(未付/部分付/已付訂金;不含取消)= unpaidCount + balanceDueCount。

unpaidCount
number

完全未付人數(payment_state = unpaid;不含取消)。

balanceDueCount
number

待收尾款人數(已付部分或訂金、還沒付清:partially_paid / deposit_paid;不含取消)。

cancelledCount
number

已取消人數(僅供參考,不計入總數)。

ordersWithoutConsent
number

尚未簽署同意書(PDPA)的訂單數。

codedRevenueTwd
number

有折扣訂單的應收營收合計(TWD;排除取消/退款)。

discountTotalTwd
number

折扣金額合計(TWD)。

profitShareTotalTwd
number

利潤分潤金額合計(TWD)。

lottery
DepartureLottery | null

梯次層抽籤結果:`result` 為 none(未送件)/pending(待抽籤)/waitlisted(備取中)/ won(已中籤)/lost(未中籤),`waitlistedCount` 為同梯還在備取的張數。先到先得梯次為 null。

result
"lost" | "none" | "pending" | "waitlisted" | "won"
waitlistedCount
number
lotteryWaitlistEnabled
boolean

行程開了「抽籤結果含備取」(issue 1691):抽籤梯次才出現「備取」標記鍵。

stage
"cancelled" | "closed" | "confirming" | "departed" | "enrolling" | "prep" | "rooming" | "sales_closed"

生命週期階段。

metThreshold
boolean

已達最低成團人數;門檻未設時為 false。

rooming
DepartureRooming | null

分房進度;null = 這一梯不用分房(通鋪團或沒有房)。

roomCount
number
assignedCount
number
totalTravelers
number
請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/control" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "tripId": "…",
      "tripTitle": "…",
      "tripShortName": "…",
      "hasPreTripNight": true,
      "tripSlug": "…",
      "groupCode": "…",
      "label": "…",
      "isPrivate": true,
      "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,
      "ordersWithoutConsent": 0,
      "codedRevenueTwd": 0,
      "discountTotalTwd": 0,
      "profitShareTotalTwd": 0,
      "lottery": null,
      "lotteryWaitlistEnabled": true,
      "stage": "cancelled",
      "metThreshold": true,
      "rooming": null
    }
  ]
}

多梯次的分房進度統計

GET/api/v1/departures/room-stats
order.read模組:tour

參數

ids必填
string· min 1

要查詢的梯次 ID 清單,以逗號分隔(例:a,b,c)

請求
curl -X GET "https://your-tenant.example.com/api/v1/departures/room-stats?ids=example-ids" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {}
}

/discount-codes

list all discount codes

GET/api/v1/discount-codes
discount.read

回應欄位 · data[]

id
string

折扣碼 id(disc_ 前綴)。

code
string

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

label
string

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

discountType
"fixed" | "percentage"

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

discountValue
number

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

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

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

discountStep
number | null

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

profitShareType
ProfitShareType | null

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

profitShareValue
number | null

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

profitSharePayee
string | null

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

isActive
boolean

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

validFrom
string | null

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

validUntil
string | null

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

maxRedemptions
number | null

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

redemptionCount
number

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

minOrderTwd
number | null

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

minTravelerCount
number | null

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

appliesToAll
boolean

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

maxRedemptionsPerCustomer
number | null

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

allowedPriceChannels
string[] | null

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

allowedCustomerTypes
string[] | null

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

stackable
boolean

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

notes
string | null

內部備註;null = 無。

createdAt
string

建立時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/discount-codes" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}

create a discount code

POST/api/v1/discount-codes
discount.manage

參數

code必填
string· max 64 · min 1

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

label必填
string· max 200 · min 1

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

discountType必填
enum
fixedpercentage

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

discountValue必填
integer

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

discountBasis選填
enum
per_orderper_travelersper_amount

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

discountStep選填
integer

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

profitShareType選填
enum
fixedpercentage

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

profitShareValue選填
integer

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

profitSharePayee選填
string· max 200

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

isActive選填
boolean

是否啟用;停用後前台無法套用

validFrom選填
string· 格式限定

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

validUntil選填
string· 格式限定

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

maxRedemptions選填
integer

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

minOrderTwd選填
integer

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

minTravelerCount選填
integer

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

appliesToAll選填
boolean

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

tripIds選填
array

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

maxRedemptionsPerCustomer選填
integer

每位客戶可使用次數上限;null 為不限

allowedPriceChannels選填
array

可套用的價格渠道(direct 直客 / agency 同業);空陣列為不限。促銷價不是渠道:促銷價的直客單仍算 direct

allowedCustomerTypes選填
array

可套用的客戶類型(direct 直客 / agency_contact 同業聯絡人);空陣列為不限

stackable選填
boolean

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

notes選填
string· max 2000

內部備註(不對外顯示)

回應欄位 · data

id
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/discount-codes" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "label": "example-label",
  "discountType": "fixed",
  "discountValue": 1
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

full discount code detail

GET/api/v1/discount-codes/{id}
discount.read

參數

id路徑
string· min 1

折扣碼 id(路徑參數)

回應欄位 · data

id
string

折扣碼 id(disc_ 前綴)。

code
string

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

label
string

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

discountType
"fixed" | "percentage"

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

discountValue
number

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

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

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

discountStep
number | null

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

profitShareType
ProfitShareType | null

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

profitShareValue
number | null

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

profitSharePayee
string | null

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

isActive
boolean

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

validFrom
string | null

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

validUntil
string | null

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

maxRedemptions
number | null

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

redemptionCount
number

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

minOrderTwd
number | null

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

minTravelerCount
number | null

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

appliesToAll
boolean

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

maxRedemptionsPerCustomer
number | null

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

allowedPriceChannels
string[] | null

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

allowedCustomerTypes
string[] | null

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

stackable
boolean

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

notes
string | null

內部備註;null = 無。

createdAt
string

建立時間。

tripIds
string[]

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

redemptions
object[]

逐筆兌換紀錄。

orderId
string

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

orderNumber
string

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

codeSnapshot
string

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

originalTotalTwd
number

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

discountTwd
number

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

profitShareTwd
number

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

orderStatus
string

訂單當前狀態。

createdAt
string

兌換(下單)時間。

totalDiscountTwd
number

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

totalProfitShareTwd
number

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

totalPaidTwd
number

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/discount-codes/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
  }
}

update a discount code

PATCH/api/v1/discount-codes/{id}
discount.manage

參數

id路徑
string· min 1

折扣碼 id(路徑參數)

code必填
string· max 64 · min 1

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

label必填
string· max 200 · min 1

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

discountType必填
enum
fixedpercentage

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

discountValue必填
integer

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

discountBasis選填
enum
per_orderper_travelersper_amount

計算方式:per_order 整張訂單折一次、per_travelers 每 N 位旅客折一次、per_amount 每滿 N 元(折前金額)折一次;後兩者只限 fixed,折扣 = discountValue × 倍數,總額不超過訂單金額。省略時沿用現值;改成 percentage 而省略時退回 per_order

discountStep選填
integer

N:每幾位旅客或每滿幾元(TWD);per_order 時須為 null。省略時沿用現值

profitShareType選填
enum
fixedpercentage

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

profitShareValue選填
integer

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

profitSharePayee選填
string· max 200

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

isActive選填
boolean

是否啟用;停用後前台無法套用

validFrom選填
string· 格式限定

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

validUntil選填
string· 格式限定

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

maxRedemptions選填
integer

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

minOrderTwd選填
integer

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

minTravelerCount選填
integer

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

appliesToAll選填
boolean

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

tripIds選填
array

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

maxRedemptionsPerCustomer選填
integer

每位客戶可使用次數上限;null 為不限

allowedPriceChannels選填
array

可套用的價格渠道(direct 直客 / agency 同業);空陣列為不限。促銷價不是渠道:促銷價的直客單仍算 direct

allowedCustomerTypes選填
array

可套用的客戶類型(direct 直客 / agency_contact 同業聯絡人);空陣列為不限

stackable選填
boolean

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

notes選填
string· max 2000

內部備註(不對外顯示)

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/discount-codes/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "label": "example-label",
  "discountType": "fixed",
  "discountValue": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

redemption/profit-share report for

GET/api/v1/discount-codes/{id}/redemptions
discount.read

參數

id路徑
string· min 1

折扣碼 id(路徑參數)

回應欄位 · data

id
string

折扣碼 id(disc_ 前綴)。

code
string

折扣碼字串。

label
string

折扣碼顯示名稱。

redemptionCount
number

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

totalDiscountTwd
number

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

totalProfitShareTwd
number

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

totalPaidTwd
number

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

redemptions
object[]

逐筆兌換紀錄。

orderId
string

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

orderNumber
string

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

codeSnapshot
string

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

originalTotalTwd
number

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

discountTwd
number

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

profitShareTwd
number

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

orderStatus
string

訂單當前狀態。

createdAt
string

兌換(下單)時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/discount-codes/<id>/redemptions" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
      }
    ]
  }
}

activate / deactivate a discount

POST/api/v1/discount-codes/{id}/set-active
discount.manage

參數

id路徑
string· min 1

折扣碼 id(路徑參數)

isActive必填
boolean

目標啟用狀態:true 啟用、false 停用

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/discount-codes/<id>/set-active" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

read-only checkout preview of a code's

GET/api/v1/discount-codes/preview
discount.read

參數

code必填
string· min 1

欲試算的折扣碼字串

kind必填
enum
tourlodging

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

tripId選填
string

行程 id(kind=tour 時必填)

total必填
integer

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

priceChannel選填
string

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

customerType選填
string

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

userId選填
string

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

travelerCount選填
integer

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/discount-codes/preview?code=example-code&kind=tour&total=1" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": null
}

Use the canonical tenant operation.

GET/api/v1/discount-codes/profit-shares
discount.read

參數

discountCodeId選填
string

Discount code filter

payeeSnapshot選填
string

Payee filter

回應欄位 · data

rows
object[]
orderDiscountId
string
orderId
string
orderNumber
string
codeSnapshot
string
profitShareTwd
number
payeeSnapshot
string | null
createdAt
string
summary
object[]
payeeSnapshot
string | null
pendingCount
number
pendingTwd
number
請求
curl -X GET "https://your-tenant.example.com/api/v1/discount-codes/profit-shares" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "orderDiscountId": "…",
        "orderId": "…",
        "orderNumber": "…",
        "codeSnapshot": "…",
        "profitShareTwd": 0,
        "payeeSnapshot": "…",
        "createdAt": "…"
      }
    ],
    "summary": [
      {
        "payeeSnapshot": "…",
        "pendingCount": 0,
        "pendingTwd": 0
      }
    ]
  }
}

分潤轉請款

POST/api/v1/discount-codes/profit-shares/convert
payable.create

參數

orderDiscountIds必填
array· min 1

Pending profit share IDs

payeeType必填
enum
staff_commissionother

Payee type

payeeName必填
string· min 1

Payee name

payeeBankAccount選填
string

Bank account

payeeBankName選填
string

Bank name

payeeBankBranch選填
string

Bank branch

payeeTaxId選填
string

Tax ID

taxAmountTwd選填
integer

Tax amount TWD

submitImmediately選填
boolean

Submit the new payable

回應欄位 · data

payableId
string
payableNumber
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/discount-codes/profit-shares/convert" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "orderDiscountIds": [
    "example-orderDiscountIds"
  ],
  "payeeType": "staff_commission",
  "payeeName": "example-payeeName"
}'
回應
{
  "ok": true,
  "data": {
    "payableId": "…",
    "payableNumber": "…"
  }
}

/group-codes

航空碼對照表

GET/api/v1/group-codes/airlines
group_code.manage模組:tour

參數

activeOnly選填
enum
truefalse10

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

回應欄位 · data[]

code
string

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

name
string

航空公司名稱。

isActive
boolean

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

displayOrder
number

顯示排序(由小到大)。

usedCount
number

被多少梯次引用。

請求
curl -X GET "https://your-tenant.example.com/api/v1/group-codes/airlines" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "code": "…",
      "name": "…",
      "isActive": true,
      "displayOrder": 0,
      "usedCount": 0
    }
  ]
}
POST/api/v1/group-codes/airlines
group_code.manage模組:tour

參數

code必填
string

對照表碼,2–8 碼大寫英數,最後一碼是字母(自動轉大寫)

name必填
string· max 100 · min 1

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

isActive選填
boolean

是否啟用(停用後不再供新團號選用)

displayOrder選填
integer· max 9999 · min 0

排序權重,數字越小越前面

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/group-codes/airlines" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
PATCH/api/v1/group-codes/airlines
group_code.manage模組:tour

參數

code必填
string

要更新的對照表碼(不可變更碼本身)

name必填
string· max 100 · min 1

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

isActive選填
boolean

是否啟用(停用後不再供新團號選用)

displayOrder選填
integer· max 9999 · min 0

排序權重,數字越小越前面

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

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

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/group-codes/airlines" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
DELETE/api/v1/group-codes/airlines
group_code.manage模組:tour

參數

code必填
string

要刪除的對照表碼。有梯次引用的碼不能刪,只能改名稱或停用

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

刪除的航空碼。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/group-codes/airlines?code=example-code" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}

前綴團號反查多梯次

GET/api/v1/group-codes/departures
group_code.manage模組:tour

參數

prefix必填
string· min 1

團號前綴,反查同地區同航空的所有梯次(如 26EGTK)

回應欄位 · data[]

id
string

梯次 id(dep_ 前綴)。

tripId
string

所屬行程 id(trip_ 前綴)。

tripTitle
string

所屬行程標題。

tripSlug
string

所屬行程網址 slug。

departureDate
string

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

groupCode
string

完整團號。

regionCode
string | null

地區代碼;null = 未設。

airlineCode
string | null

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/group-codes/departures?prefix=example-prefix" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "tripId": "…",
      "tripTitle": "…",
      "tripSlug": "…",
      "departureDate": "…",
      "groupCode": "…",
      "regionCode": "…",
      "airlineCode": "…"
    }
  ]
}

精確團號反查單一梯次

GET/api/v1/group-codes/departures/{id}
group_code.manage模組:tour

參數

id路徑
string· min 1

完整團號,反查單一梯次(大小寫不敏感)

回應欄位 · data

id
string

梯次 id(dep_ 前綴)。

tripId
string

所屬行程 id(trip_ 前綴)。

tripTitle
string

所屬行程標題。

tripSlug
string

所屬行程網址 slug。

departureDate
string

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

groupCode
string

完整團號。

regionCode
string | null

地區代碼;null = 未設。

airlineCode
string | null

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/group-codes/departures/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "tripId": "…",
    "tripTitle": "…",
    "tripSlug": "…",
    "departureDate": "…",
    "groupCode": "…",
    "regionCode": "…",
    "airlineCode": "…"
  }
}

地區碼對照表

GET/api/v1/group-codes/regions
group_code.manage模組:tour

參數

activeOnly選填
enum
truefalse10

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

回應欄位 · data[]

code
string

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

name
string

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

isActive
boolean

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

displayOrder
number

顯示排序(由小到大)。

usedCount
number

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/group-codes/regions" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "code": "…",
      "name": "…",
      "isActive": true,
      "displayOrder": 0,
      "usedCount": 0
    }
  ]
}
POST/api/v1/group-codes/regions
group_code.manage模組:tour

參數

code必填
string

對照表碼,2–8 碼大寫英數,最後一碼是字母(自動轉大寫)

name必填
string· max 100 · min 1

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

isActive選填
boolean

是否啟用(停用後不再供新團號選用)

displayOrder選填
integer· max 9999 · min 0

排序權重,數字越小越前面

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

新增或更新的地區代碼。

請求
curl -X POST "https://your-tenant.example.com/api/v1/group-codes/regions" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
PATCH/api/v1/group-codes/regions
group_code.manage模組:tour

參數

code必填
string

要更新的對照表碼(不可變更碼本身)

name必填
string· max 100 · min 1

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

isActive選填
boolean

是否啟用(停用後不再供新團號選用)

displayOrder選填
integer· max 9999 · min 0

排序權重,數字越小越前面

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

新增或更新的地區代碼。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/group-codes/regions" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}
DELETE/api/v1/group-codes/regions
group_code.manage模組:tour

參數

code必填
string

要刪除的對照表碼。有梯次引用的碼不能刪,只能改名稱或停用

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

code
string

刪除的地區碼。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/group-codes/regions?code=example-code" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "code": "…"
  }
}

/holidays

List the tenant holiday calendar

GET/api/v1/holidays
public_holiday.read

參數

year選填
integer· max 9999 · min 1000

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

回應欄位 · data

rows
object[]

假日列(依日期排序)。

date
string

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

name
string

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

isWorkday
boolean

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/holidays" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "date": "…",
        "name": "…",
        "isWorkday": true
      }
    ]
  }
}

Update or delete a tenant holiday

PUT/api/v1/holidays/{date}
public_holiday.manage

參數

date路徑
string· min 1

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

name必填
string· max 100 · min 1

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

isWorkday選填
boolean

是否為補班日:true 表示原假日改上班、false 表示國定假日;影響行前作業工作日倒數

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X PUT "https://your-tenant.example.com/api/v1/holidays/<date>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
DELETE/api/v1/holidays/{date}
public_holiday.manage

參數

date路徑
string· min 1

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

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/holidays/<date>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/holidays/batch
public_holiday.manage

參數

rows必填
array· max 1000 · min 1

Holiday rows; atomic upsert

回應欄位 · data

imported
number
請求
curl -X POST "https://your-tenant.example.com/api/v1/holidays/batch" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "date": "2026-10-13",
      "name": "example-name",
      "isWorkday": true
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "imported": 0
  }
}

Count holidays and makeup workdays for a year.

GET/api/v1/holidays/stats
public_holiday.read

參數

year必填
integer· max 9999 · min 1000

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

回應欄位 · data

holidayCount
number

該年度放假日數。

makeupCount
number

該年度補班日數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/holidays/stats?year=1000" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "holidayCount": 0,
    "makeupCount": 0
  }
}

/images

list/search the trip image gallery

GET/api/v1/images
image.read

參數

tripId選填
string

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

q選填
string

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

page選填
integer

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

pageSize選填
integer· max 200

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

回應欄位 · data

rows
object[]

當頁圖片列。

id
string

圖片資源 id(timg_ 前綴)。

tripId
string | null

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

tripTitle
string | null

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

tripSlug
string | null

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

url
string

圖片公開 URL。

caption
string | null

圖說文字;null = 無。

displayOrder
number

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

createdAt
string

上傳建立時間。

total
number

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

page
number

目前頁碼(1 起算)。

pageSize
number

每頁筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/images" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": "…",
        "tripId": "…",
        "tripTitle": "…",
        "tripSlug": "…",
        "url": "…",
        "caption": "…",
        "displayOrder": 0,
        "createdAt": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}
POST/api/v1/images
image.manage

參數

tripId必填
string· min 1

要掛上此圖片的行程 ID

url必填
string· max 2000

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

caption選填
string· max 500

圖片說明文字,選填

displayOrder選填
integer· max 9999 · min 0

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

回應欄位 · data

id
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/images" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tripId": "example-tripId",
  "url": "https://example.com"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

remove a trip image

DELETE/api/v1/images/{id}
image.manage

參數

id路徑
string· min 1

欲刪除的行程圖片 ID

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/images/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

the trip picker for attaching images: draft +

GET/api/v1/images/trips
image.read

回應欄位 · data[]

id
string

行程 id(trip_ 前綴)。

title
string

行程標題。

請求
curl -X GET "https://your-tenant.example.com/api/v1/images/trips" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "title": "…"
    }
  ]
}

upload an image file into the gallery

POST/api/v1/images/upload
image.manage

參數

contentBase64必填
string· min 1

圖片檔案內容的 base64 編碼字串(JPEG / PNG / WebP,上限 8MB)

tripId選填
string· min 1

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

caption選填
string· max 500

圖片說明文字,選填

回應欄位 · data

id
string

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

url
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/images/upload" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "contentBase64": "example-contentBase64"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "url": "…"
  }
}

/lodging

list staff-side direct lodging bookings

GET/api/v1/lodging/bookings
lodging.read

參數

status選填
string

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

q選填
string

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

回應欄位 · data[]

orderId
string

訂單 id(ord_ 前綴)。

orderNumber
string

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

status
string

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

bookingState
string

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

paymentState
string

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

refundState
string

退款軸狀態。

totalTwd
number

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

createdAt
string

訂單建立時間。

bookerName
string

訂購人姓名。

bookerEmail
string

訂購人 email。

propertyId
string

住宿館 id(prop_ 前綴)。

propertyName
string

住宿館名稱。

roomTypeId
string

房型 id(rt_ 前綴)。

roomTypeName
string

房型名稱。

checkIn
string

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

checkOut
string

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

units
number

訂購房間數。

guestCount
number

入住總人數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/bookings" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "orderId": "…",
      "orderNumber": "…",
      "status": "…",
      "bookingState": "…",
      "paymentState": "…",
      "refundState": "…",
      "totalTwd": 0,
      "createdAt": "…",
      "bookerName": "…",
      "bookerEmail": "…",
      "propertyId": "…",
      "propertyName": "…",
      "roomTypeId": "…",
      "roomTypeName": "…",
      "checkIn": "…",
      "checkOut": "…",
      "units": 0,
      "guestCount": 0
    }
  ]
}
POST/api/v1/lodging/bookings
order.create模組:lodging

參數

propertyId必填
string· min 1

旅宿物件 ID

roomTypeId必填
string· min 1

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

checkIn必填
string· min 1

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

checkOut必填
string· min 1

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

units必填
integer

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

guestCount必填
integer

入住人數(1-100,不得超過房型總容納人數)

bookerEmail必填
string· min 1

訂房人 Email(須為已註冊會員)

paymentMethod必填
enum
cashatmmanual

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

receivingAccountId選填
string

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

notes選填
string

代訂備註

回應欄位 · data

orderId
string

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

retentionDeferred
boolean

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/bookings" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "propertyId": "example-propertyId",
  "roomTypeId": "example-roomTypeId",
  "checkIn": "example-checkIn",
  "checkOut": "example-checkOut",
  "units": 1,
  "guestCount": 1,
  "bookerEmail": "customer@example.com",
  "paymentMethod": "cash"
}'
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "retentionDeferred": true
  }
}

single lodging booking detail.

GET/api/v1/lodging/bookings/{orderId}
lodging.read

參數

orderId路徑
string· min 1

旅宿訂單 ID

回應欄位 · data

orderId
string

訂單 id(ord_ 前綴)。

orderNumber
string

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

status
string

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

bookingState
string

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

paymentState
string

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

refundState
string

退款軸狀態。

totalTwd
number

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

createdAt
string

訂單建立時間。

bookerName
string

訂購人姓名。

bookerEmail
string

訂購人 email。

propertyId
string

住宿館 id(prop_ 前綴)。

propertyName
string

住宿館名稱。

roomTypeId
string

房型 id(rt_ 前綴)。

roomTypeName
string

房型名稱。

checkIn
string

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

checkOut
string

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

units
number

訂購房間數。

guestCount
number

入住總人數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/bookings/<orderId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "orderNumber": "…",
    "status": "…",
    "bookingState": "…",
    "paymentState": "…",
    "refundState": "…",
    "totalTwd": 0,
    "createdAt": "…",
    "bookerName": "…",
    "bookerEmail": "…",
    "propertyId": "…",
    "propertyName": "…",
    "roomTypeId": "…",
    "roomTypeName": "…",
    "checkIn": "…",
    "checkOut": "…",
    "units": 0,
    "guestCount": 0
  }
}

cancel a direct lodging

POST/api/v1/lodging/bookings/{orderId}/cancel
order.update

參數

orderId路徑
string· min 1

旅宿訂單 ID

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/bookings/<orderId>/cancel" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

delete a gallery

DELETE/api/v1/lodging/images/{id}
lodging.manage模組:lodging

參數

id路徑
string· min 1

圖片 ID

kind必填
enum
propertyroom-type

圖片所屬相簿:property 旅宿相簿/room-type 房型相簿

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/lodging/images/<id>?kind=property" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

list tenant lodging properties

GET/api/v1/lodging/properties
lodging.read

回應欄位 · data[]

id
object

住宿館 id(prop_ 前綴)。

length
number

Returns the length of a String object.

slug
string

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

name
string

住宿館名稱。

kind
string

類型:hotel 旅館 / camp 營地。

isOverseas
boolean

是否為海外住宿。

location
string | null

地點描述;null = 未設。

description
string | null

簡介文字;null = 未設。

contentMdx
string | null

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

facilities
unknown

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

coverImageUrl
string | null

封面圖 URL;null = 未設。

usageHint
string

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

checkInTime
string | null

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

checkOutTime
string | null

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

checkInInfo
string | null

入住須知;null = 未設。

houseRules
string | null

館內規範;null = 未設。

cancellationPolicy
string | null

取消政策;null = 未設。

addressRegion
string | null

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

addressLocality
string | null

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

streetAddress
string | null

街道地址;null = 未設。

postalCode
string | null

郵遞區號;null = 未設。

latitude
number | null

緯度;null = 未設。

longitude
number | null

經度;null = 未設。

phone
string | null

聯絡電話;null = 未設。

petsAllowed
boolean | null

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

smokingAllowed
boolean | null

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

status
string

狀態:active 啟用 / inactive 停用。

seoTitle
string | null

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

seoDescription
string | null

SEO 描述;null = 未設。

ogImageUrl
string | null

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

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/properties" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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,
      "status": "…",
      "seoTitle": "…",
      "seoDescription": "…",
      "ogImageUrl": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

create a property

POST/api/v1/lodging/properties
lodging.manage模組:lodging

參數

slug選填
string

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

name必填
string· max 200 · min 1

旅宿名稱(對外顯示)

kind選填
enum
camphotel

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

isOverseas選填
boolean

是否為海外旅宿,預設否

location選填
string· max 200

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

description選填
string· max 2000

旅宿介紹文字

usageHint選填
enum
directpackagebothinternal

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

coverImageUrl選填
string· max 2000

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

回應欄位 · data

id
string

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

slug
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/properties" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…"
  }
}

single lodging property

GET/api/v1/lodging/properties/{id}
lodging.read

參數

id路徑
string· min 1

旅宿物件 ID

回應欄位 · data

id
object

住宿館 id(prop_ 前綴)。

length
number

Returns the length of a String object.

slug
string

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

name
string

住宿館名稱。

kind
string

類型:hotel 旅館 / camp 營地。

isOverseas
boolean

是否為海外住宿。

location
string | null

地點描述;null = 未設。

description
string | null

簡介文字;null = 未設。

contentMdx
string | null

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

facilities
unknown

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

coverImageUrl
string | null

封面圖 URL;null = 未設。

usageHint
string

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

checkInTime
string | null

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

checkOutTime
string | null

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

checkInInfo
string | null

入住須知;null = 未設。

houseRules
string | null

館內規範;null = 未設。

cancellationPolicy
string | null

取消政策;null = 未設。

addressRegion
string | null

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

addressLocality
string | null

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

streetAddress
string | null

街道地址;null = 未設。

postalCode
string | null

郵遞區號;null = 未設。

latitude
number | null

緯度;null = 未設。

longitude
number | null

經度;null = 未設。

phone
string | null

聯絡電話;null = 未設。

petsAllowed
boolean | null

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

smokingAllowed
boolean | null

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

status
string

狀態:active 啟用 / inactive 停用。

seoTitle
string | null

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

seoDescription
string | null

SEO 描述;null = 未設。

ogImageUrl
string | null

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

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/properties/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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,
    "status": "…",
    "seoTitle": "…",
    "seoDescription": "…",
    "ogImageUrl": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}

update a property

PATCH/api/v1/lodging/properties/{id}
lodging.manage模組:lodging

參數

id路徑
string· min 1

旅宿物件 ID

name選填
string· max 200 · min 1

旅宿名稱(對外顯示)

slug選填
string

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

location選填
string· max 200

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

description選填
string· max 2000

旅宿介紹文字

usageHint選填
enum
directpackagebothinternal

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

checkInTime選填
string· max 10

入住時間(如 15:00)

checkOutTime選填
string· max 10

退房時間(如 11:00)

checkInInfo選填
string· max 2000

入住須知與報到說明

houseRules選填
string· max 2000

住宿規範

cancellationPolicy選填
string· max 2000

取消政策說明

addressRegion選填
string· max 50

地址行政區(縣市層級)

addressLocality選填
string· max 50

地址鄉鎮市區

streetAddress選填
string· max 200

街道地址

postalCode選填
string· max 10

郵遞區號

latitude選填
integer· max 90

緯度(-90 至 90)

longitude選填
integer· max 180

經度(-180 至 180)

phone選填
string· max 50

聯絡電話

petsAllowed選填
enum
allowdisallowunset

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

smokingAllowed選填
enum
allowdisallowunset

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

facilities選填
array

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

seoTitle選填
string

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

seoDescription選填
string

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

ogImageUrl選填
string

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

coverImageUrl選填
string· max 2000

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

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/lodging/properties/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "slug": "example-slug",
  "location": "example-location"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

archive

POST/api/v1/lodging/properties/{id}/archive
lodging.manage模組:lodging

參數

id路徑
string· min 1

旅宿物件 ID

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/properties/<id>/archive" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

property gallery images.

GET/api/v1/lodging/properties/{id}/images
lodging.read

參數

id路徑
string· min 1

旅宿物件 ID

回應欄位 · data[]

id
string

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

url
string

圖片公開 URL。

caption
string | null

圖說文字;null = 無。

displayOrder
number

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/properties/<id>/images" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "url": "…",
      "caption": "…",
      "displayOrder": 0
    }
  ]
}

add a property gallery image

POST/api/v1/lodging/properties/{id}/images
lodging.manage模組:lodging

參數

id路徑
string· min 1

旅宿物件 ID

url必填
string· min 1

圖片網址

caption選填
string

圖片說明文字(可省略)

displayOrder選填
integer

在相簿中的排序序號,數字越小越前面,預設 0

回應欄位 · data

id
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/properties/<id>/images" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "example-url"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

room types for one property

GET/api/v1/lodging/properties/{id}/room-types
lodging.read

參數

id路徑
string· min 1

旅宿物件 ID

回應欄位 · data[]

id
object

房型 id(rt_ 前綴)。

length
number

Returns the length of a String object.

propertyId
object

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

length
number

Returns the length of a String object.

name
string

房型名稱。

inventoryUnit
string

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

unitsTotal
number

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

capacityPerUnit
number

每單位可住人數。

lowAvailabilityThreshold
number | null

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

basePriceTwd
number

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

description
string | null

房型描述;null = 未設。

facilities
unknown

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

bedConfig
unknown

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

floorSizeSqm
number | null

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

status
string

狀態:active 啟用 / inactive 停用。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/properties/<id>/room-types" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}

create a room type under this property

POST/api/v1/lodging/properties/{id}/room-types
lodging.manage模組:lodging

參數

id路徑
string· min 1

所屬旅宿物件 ID

name必填
string· max 200 · min 1

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

inventoryUnit選填
enum
roombed

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

unitsTotal必填
integer· max 10000 · min 1

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

capacityPerUnit選填
integer· max 100 · min 1

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

lowAvailabilityThreshold選填
integer· max 10000 · min 0

剩餘單元數低水位門檻;null 表示不提示

basePriceTwd必填
integer· max 10000000 · min 0

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

description選填
string· max 2000

房型介紹文字

floorSizeSqm選填
integer

房間坪數(平方公尺)

bedType選填
string

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

bedCount選填
integer

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

facilities選填
array

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

回應欄位 · data

id
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/properties/<id>/room-types" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "unitsTotal": 1,
  "basePriceTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

single room type

GET/api/v1/lodging/room-types/{id}
lodging.read

參數

id路徑
string· min 1

房型 ID

回應欄位 · data

id
object

房型 id(rt_ 前綴)。

length
number

Returns the length of a String object.

propertyId
object

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

length
number

Returns the length of a String object.

name
string

房型名稱。

inventoryUnit
string

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

unitsTotal
number

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

capacityPerUnit
number

每單位可住人數。

lowAvailabilityThreshold
number | null

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

basePriceTwd
number

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

description
string | null

房型描述;null = 未設。

facilities
unknown

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

bedConfig
unknown

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

floorSizeSqm
number | null

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

status
string

狀態:active 啟用 / inactive 停用。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/room-types/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
  }
}

update a room type

PATCH/api/v1/lodging/room-types/{id}
lodging.manage模組:lodging

參數

id路徑
string· min 1

房型 ID

name選填
string· max 200 · min 1

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

inventoryUnit選填
enum
roombed

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

unitsTotal選填
integer· max 10000 · min 1

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

capacityPerUnit選填
integer· max 100 · min 1

每單元可容納人數

lowAvailabilityThreshold選填
integer· max 10000 · min 0

剩餘單元數低水位門檻;null 表示清除提示

basePriceTwd選填
integer· max 10000000 · min 0

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

description選填
string· max 2000

房型介紹文字

floorSizeSqm選填
integer

房間坪數(平方公尺)

bedType選填
string

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

bedCount選填
integer

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

facilities選填
array

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

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/lodging/room-types/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "inventoryUnit": "room",
  "unitsTotal": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

archive

POST/api/v1/lodging/room-types/{id}/archive
lodging.manage模組:lodging

參數

id路徑
string· min 1

房型 ID

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/room-types/<id>/archive" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

per-night availability +

GET/api/v1/lodging/room-types/{id}/availability
lodging.read

參數

id路徑
string· min 1

房型 ID

checkIn必填
string· min 1

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

checkOut必填
string· min 1

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

回應欄位 · data

available
number

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

nights
number

住宿晚數。

totalPriceTwd
number

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

perNight
object[]

逐晚可售明細。

night
string

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

capacity
number

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

booked
number

該晚已訂數。

remaining
number

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

priceTwd
number

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

status
string

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/room-types/<id>/availability?checkIn=example-checkIn&checkOut=example-checkOut" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "available": 0,
    "nights": 0,
    "totalPriceTwd": 0,
    "perNight": [
      {
        "night": "…",
        "capacity": 0,
        "booked": 0,
        "remaining": 0,
        "priceTwd": 0,
        "status": "…"
      }
    ]
  }
}

per-night

GET/api/v1/lodging/room-types/{id}/availability/breakdown
lodging.read

參數

id路徑
string· min 1

房型 ID

from必填
string· min 1

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

to必填
string· min 1

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

回應欄位 · data[]

night
string

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

directBooked
number

該晚散客直訂的已訂數。

packageBooked
number

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

pretripBooked
number

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/room-types/<id>/availability/breakdown?from=example-from&to=example-to" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "night": "…",
      "directBooked": 0,
      "packageBooked": 0,
      "pretripBooked": 0
    }
  ]
}

room-type gallery images.

GET/api/v1/lodging/room-types/{id}/images
lodging.read

參數

id路徑
string· min 1

房型 ID

回應欄位 · data[]

id
string

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

url
string

圖片公開 URL。

caption
string | null

圖說文字;null = 無。

displayOrder
number

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/room-types/<id>/images" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "url": "…",
      "caption": "…",
      "displayOrder": 0
    }
  ]
}

add a room-type gallery image

POST/api/v1/lodging/room-types/{id}/images
lodging.manage模組:lodging

參數

id路徑
string· min 1

房型 ID

url必填
string· min 1

圖片網址

caption選填
string

圖片說明文字(可省略)

displayOrder選填
integer

在相簿中的排序序號,數字越小越前面,預設 0

回應欄位 · data

id
string

新建立房型圖片的 id(rtimg_ 前綴)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/room-types/<id>/images" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "example-url"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

batch-override the

POST/api/v1/lodging/room-types/{id}/nights/override
lodging.manage模組:lodging

參數

id路徑
string· min 1

房型 ID

from必填
string

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

to必填
string

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

priceTwd選填
integer· max 10000000 · min 0

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

capacity選填
integer· max 10000 · min 1

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

status選填
enum
openclosed

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

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/lodging/room-types/<id>/nights/override" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-10-13",
  "to": "2026-10-13"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

旅宿 dashboard overview

GET/api/v1/lodging/stats
lodging.read

回應欄位 · data

tonightCheckInUnits
number

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

tonightCheckInGuests
number

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

weekOccupancyPct
number

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

next7AvailableUnits
number

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

pendingPaymentCount
number

待收款訂單筆數。

pendingPaymentTwd
number

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/lodging/stats" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "tonightCheckInUnits": 0,
    "tonightCheckInGuests": 0,
    "weekOccupancyPct": 0,
    "next7AvailableUnits": 0,
    "pendingPaymentCount": 0,
    "pendingPaymentTwd": 0
  }
}

/trips

GET/api/v1/trips
trip.read模組:tour

參數

status選填
string

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

q選填
string

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

groupCode選填
string

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

回應欄位 · data[]

id
string

行程 id(trip_ 前綴)。

slug
string

行程網址 slug。

title
string

行程標題。

destination
string

目的地名稱。

durationDays
number

天數。

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

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

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

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

isHidden
boolean

不對外顯示(#1435)。

isLinkOnly
boolean

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

foreignTravelersOnly
boolean

限外籍旅客(issue 1519)。

updatedAt
string

最後更新時間。

isClimbing
boolean

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

isOverseas
boolean

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

hasPreTripNight
boolean

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

activeDepartureCount
number

Count of departures with status='selling'.

nextDepartureDate
string | null

Earliest selling departure_date, ISO date string, or null.

representativeGroupCode
string | null

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/trips" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "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": "…"
    }
  ]
}

the same core write command

POST/api/v1/trips
trip.manage模組:tour

參數

tags選填
array· max 20

自由行程標籤;最多 20 個,每個最多 50 字。省略不變,空陣列清空

slug必填
string

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

title必填
string· max 200 · min 1

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

shortName選填
string· max 30

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

summary選填
string· max 500

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

contentMdx選填
string· max 50000

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

lotteryNoticeMdx選填
string· max 50000

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

destination必填
string· max 100 · min 1

目的地名稱

durationDays必填
integer· max 60 · min 1

行程天數

guideStartDay選填
integer· min 1

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

guideEndDay選填
integer· min 1

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

difficultyLevel選填
integer· max 5 · min 1

對客難度(1 輕鬆、2 入門、3 中等、4 進階、5 挑戰);null 表示未分級,不影響內部資格審核

priceFromTwd必填
integer· max 10000000 · min 0

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

directPriceTwd選填
integer· max 10000000 · min 0

直客定價(新台幣),留空(null)則退回起價繼承

agencyPriceTwd選填
integer· max 10000000 · min 0

同業定價(新台幣),留空(null)則退回直客/起價繼承

depositMode選填
enum
nonefixedpercent

訂金計算方式(none 不收/fixed 固定金額/percent 百分比)

depositAmountTwd選填
integer· max 10000000 · min 0

訂金固定金額(新台幣),depositMode 為 fixed 時生效。按人或按單由 depositBasis 決定

depositBasis選填
enum
per_personper_order

固定金額訂金的計算單位(per_person 每人,應付訂金=金額 × 人數/per_order 每張訂單一筆)。新行程預設 per_person;梯次覆寫的固定金額也照這個單位

depositPercent選填
integer· max 100 · min 1

訂金百分比(1–100),depositMode 為 percent 時生效

balanceDueDaysBeforeDeparture選填
integer· max 365 · min 0

尾款應繳截止日(出發前幾天)

feeInclusions選填
array· max 30

費用包含項目清單,每項含勾選狀態(ok)與說明文字(text)

notices選填
array· max 30

注意事項清單;最多 30 項,每項最多 200 字。省略不變,空陣列清空

cancellationFeeTiers選填
array· max 20

退改費階梯覆寫:距出發 ≥ daysBefore 天扣 feePercent%(佔成交總額)或 feeFixedTwd 元/人,二選一;null = 繼承租戶預設

isClimbing選填
boolean

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

isOverseas選填
boolean

是否為海外團

isHidden選填
boolean

不對外顯示:官網、站內搜尋與搜尋引擎都看不到,梯次不對外販售;後台照常可建單

isLinkOnly選填
boolean

僅限連結:不出現在官網列表、搜尋、sitemap 與前台 API 的行程列表,行程頁不給搜尋引擎收錄;拿到行程網址的人照常報名。與 isHidden 互斥;只送其中一個 true 時,另一個自動改成 false

manualCancellationRefund選填
boolean

取消後先由承辦核算扣除額,再開退款單

equipmentRentalEnabled選填
boolean

是否可租借裝備(需同時為登山團;開後此行程的梯次才能開租借單 / 登記裝備需求)

hasPreTripNight選填
boolean

是否有行前集合夜(出發日前一晚集合夜宿;集合日恆為出發日 −1)

meetingDay選填
integer· max 30 · min 1

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

pretripStayRoomTypeId選填
string

出發前夜住宿據點的床位池 id;null 表示不住公司據點

pretripStayExternalArranged選填
boolean

出發前夜住宿是否由公司安排外部住宿(民宿等);與據點床位池互斥

gradeScore選填
integer· max 100 · min 0

登山難度評分(0–100),null 表示未評級

requiresAlpineExperience選填
boolean

是否需具備高山經驗

gradeLabel選填
string· max 50

難度等級標籤文字

minGroupSize選填
integer· max 1000 · min 1

最低成團人數門檻,null 表示不設門檻

defaultCapacity選填
integer· max 200 · min 1

新增梯次時席次欄的預設值,null 表示沒設(表單用固定預設)

salesCloseDaysBefore選填
integer· max 365 · min 0

停止售票預設:出發日前 N 天的 00:00 自動把售票中的梯次改為已關閉;null 表示不自動關。梯次未自訂停止售票時間時繼承此值

meetingTime選填
string· 格式限定

集合時間預設(HH:mm,台北牆鐘),null 表示清空;梯次未填時繼承

meetingPlace選填
string· max 200

集合地點預設,null 表示清空;梯次未填時繼承

pretripBriefingUrl選填
string· max 2000

行前說明網址(http/https),所有梯次共用,null 表示清空。首次收款通知以 {{行前說明網址}} 代入;未填時通知刪掉含這個變數的整行

paymentReceivedBody選填
string· max 5000

收款後通知內文,所有梯次共用,null 表示清空。有值時首次收款通知(PAYMENT_RECEIVED)的內文改用它,主旨與啟用開關仍沿用範本;可用範本的 merge 變數

waitlistEnabled選填
boolean

是否開放候補

foreignTravelersOnly選填
boolean

限外籍旅客。true 時前台結帳擋下國籍空白或台灣的旅客;建單 API 與 K 單同樣擋,要送 allowDomesticTravelers 才放行

lotteryIdentityGuardEnabled選填
boolean

是否啟用抽籤實名制:同一證件在任一受管制抽籤梯次同時只能有一筆待決申請

lotteryWaitlistEnabled選填
boolean

抽籤結果含備取:主管機關會把申請排進備取的路線(例:排雲山莊)。true 時團控出現「備取」標記鍵。與 waitlistEnabled(一般梯次滿席候補)無關

defaultAllocationMode選填
enum
fcfslottery

預設分配模式(fcfs 先到先得/lottery 抽籤):新增梯次未指定時繼承此值,梯次可逐梯覆寫;改動不回寫既有梯次。lottery 需抽籤模組

travelersPerGuide選填
integer· max 99 · min 1

每幾位旅客配一位隨團人員(1–99),null 表示不自動算。成團時以已佔位人數算 ceil(人數 / 此值),帶入仍未填的梯次 requiredGuideCount

defaultGuideCount選填
integer· max 99 · min 0

預設需要幾位嚮導(0–99;0 = 不需嚮導),null 表示沒設。新增梯次沒指定 requiredGuideCount 時帶入;改動不回寫既有梯次

lotteryLeadDays選填
integer· max 365 · min 1

抽籤日在出發日前幾天(1–365),null 表示未設。退改費階梯首列門檻須為此值 + 1;抽籤梯次的可變更第三人期限 = 此值 + 緩衝天數;租戶抽籤日期來源的期限日 = 出發日前此天數

lotteryDrawTime選填
string· 格式限定

抽籤時刻預設(HH:MM,台北時間),null 表示未設。抽籤梯次到抽籤日的這個時刻,前台停收新單;後台建單不受影響。抽籤時程表的時段開始與梯次覆寫優先;都沒設時抽籤日 00:00 停收

agreementChangeBufferDays選填
integer· max 365 · min 0

抽籤梯次緩衝天數的行程覆寫(0–365),null 表示沿用公司設定。抽籤梯次的可變更第三人期限 = 抽籤前幾天 + 此值

agreementTravelForm選填
enum
individualgroup

本行程契約的旅遊型態(individual 個別/group 團體),null 表示沿用公司設定。國內/國外仍由 isOverseas 決定

agreementExempt選填
boolean

此行程不需旅遊契約。true 時這條行程的訂單不產生契約、不寄簽約邀請,並撤銷待簽契約;改回 false 後照一般規則補產生

coverImageUrl選填
string· max 2000

行程封面圖網址(http/https,或本站圖庫資產路徑);null 清空

seoTitle選填
string· max 200

SEO 標題,覆寫前台頁面 title

seoDescription選填
string· max 500

SEO 描述,覆寫前台 meta description

ogImageUrl選填
string· max 2000

Open Graph 社群分享圖網址(http/https,或本站圖庫資產路徑);null 清空

status選填
enum
draftpublishedarchived

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

pnlRegionId選填
string· max 60

損益分區 id(pnl_regions),null 表示未指派、退回系統派生

回應欄位 · data

id
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "example-slug",
  "title": "example-title",
  "destination": "example-destination",
  "durationDays": 1,
  "priceFromTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

full admin trip detail

GET/api/v1/trips/{id}
trip.read模組:tour

參數

id路徑
string· min 1

行程 ID(路徑參數)

回應欄位 · data

id
object

行程 id(trip_ 前綴)。

length
number

Returns the length of a String object.

slug
string

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

title
string

行程標題。

shortName選填
string | null | undefined

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

summary
string | null

一句話摘要;null = 未設。

contentMdx
string | null

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

lotteryNoticeMdx選填
string | null | undefined
destination
string

目的地名稱。

durationDays
number

天數。

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

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

coverImageUrl
string | null

封面圖 URL;null = 未設。

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

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

isHidden
boolean

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

isLinkOnly
boolean

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

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

isClimbing
boolean

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

isOverseas
boolean

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

equipmentRentalEnabled
boolean

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

hasPreTripNight
boolean

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

meetingDay
number

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

minGroupSize
number | null

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

pretripStayRoomTypeId
string | null

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

pretripStayExternalArranged
boolean

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

gradeScore
number | null

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

difficultyLevel
number | null
tags
string[]
requiresAlpineExperience
boolean

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

gradeLabel
string | null

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

waitlistEnabled
boolean

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

defaultAllocationMode
"fcfs" | "lottery"

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

lotteryLeadDays選填
number | null | undefined

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

lotteryDrawTime選填
string | null | undefined

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

agreementChangeBufferDays選填
number | null | undefined

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

agreementTravelForm選填
TourAgreementTravelForm | null | undefined

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

agreementExempt選填
boolean | undefined

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

foreignTravelersOnly
boolean

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

travelersPerGuide選填
number | null | undefined

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

defaultGuideCount選填
number | null | undefined

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

defaultCapacity
number | null

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

meetingTime
string | null

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

meetingPlace
string | null

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

pretripBriefingUrl選填
string | null | undefined

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

paymentReceivedBody選填
string | null | undefined

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

salesCloseDaysBefore
number | null

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

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

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

notices
string[]

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

cancellationFeeTiers
CancellationFeeTier[] | null

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

manualCancellationRefund
boolean
seoTitle
string | null

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

seoDescription
string | null

SEO 描述;null = 未設。

ogImageUrl
string | null

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

images
object[]

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

id
string

圖片資源 id(timg_ 前綴)。

url
string

圖片公開 URL。

caption
string | null

圖說文字;null = 無。

displayOrder
number

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

departures
object[]

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

id
string

梯次 id(dep_ 前綴)。

tripId
string

所屬行程 id(trip_ 前綴)。

departureDate
string

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

returnDate
string

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

priceTwd
number

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

capacity
number

名額上限(人數)。

bookedCount
number

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

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

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

notes
string | null

內部備註;null = 無。

allocationMode
"fcfs" | "lottery"

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

label選填
string | null | undefined

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

isPrivate選填
boolean | undefined

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

agencyPriceTwd選填
number | null | undefined

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

depositMode選填
DepositMode | null | undefined

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

depositAmountTwd選填
number | null | undefined

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

depositPercent選填
number | null | undefined

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

groupCode選填
string | null | undefined

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

regionCode選填
string | null | undefined

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

airlineCode選填
string | null | undefined

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

promoActive選填
boolean | undefined

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

promoPriceTwd選填
number | null | undefined

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

promoAgencyPriceTwd選填
number | null | undefined

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

salesCloseAt選填
string | undefined | null

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

effectiveSalesCloseAt選填
string | undefined | null

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

salesAutoClosedAt選填
string | undefined | null

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

salesClosePassed選填
boolean | undefined

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

salesOpenAt選填
string | undefined | null

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

salesOpenFailedReason選填
string | null | undefined

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

meetingTime選填
string | null | undefined

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

meetingPlace選填
string | null | undefined

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

agreementChangeDays選填
number | null | undefined

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

entryDateOffsetDays選填
number | undefined

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

lotteryLeadDays選填
number | null | undefined

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

lotteryDrawTime選填
string | null | undefined

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

lotteryChangeDays選填
number | null | undefined

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

lotteryDrawDate選填
string | null | undefined

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

effectiveLotteryDrawTime選填
string | null | undefined

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

lotteryApplicationClosed選填
boolean | undefined

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

requiredGuideCount選填
number | null | undefined

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/trips/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": {
      "length": 0
    },
    "slug": "…",
    "title": "…",
    "shortName": "…",
    "summary": "…",
    "contentMdx": "…",
    "lotteryNoticeMdx": "…",
    "destination": "…",
    "durationDays": 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,
    "gradeLabel": "…",
    "waitlistEnabled": true,
    "defaultAllocationMode": "fcfs",
    "lotteryLeadDays": 0,
    "lotteryDrawTime": "…",
    "agreementChangeBufferDays": 0,
    "agreementTravelForm": null,
    "agreementExempt": true,
    "foreignTravelersOnly": true,
    "travelersPerGuide": 0,
    "defaultGuideCount": 0,
    "defaultCapacity": 0,
    "meetingTime": "…",
    "meetingPlace": "…",
    "pretripBriefingUrl": "…",
    "paymentReceivedBody": "…",
    "salesCloseDaysBefore": 0,
    "feeInclusions": "…",
    "notices": [
      "…"
    ],
    "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": "…",
        "lotteryChangeDays": 0,
        "lotteryDrawDate": "…",
        "effectiveLotteryDrawTime": "…",
        "lotteryApplicationClosed": true,
        "requiredGuideCount": 0
      }
    ]
  }
}
PATCH/api/v1/trips/{id}
trip.manage模組:tour

參數

id路徑
string· min 1

行程 ID(路徑參數)

tags選填
array· max 20

自由行程標籤;最多 20 個,每個最多 50 字。省略不變,空陣列清空

slug選填
string

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

title選填
string· max 200 · min 1

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

shortName選填
string· max 30

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

summary選填
string· max 500

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

contentMdx選填
string· max 50000

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

lotteryNoticeMdx選填
string· max 50000

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

destination選填
string· max 100 · min 1

目的地名稱

durationDays選填
integer· max 60 · min 1

行程天數

guideStartDay選填
integer· min 1

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

guideEndDay選填
integer· min 1

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

difficultyLevel選填
integer· max 5 · min 1

對客難度(1 輕鬆、2 入門、3 中等、4 進階、5 挑戰);null 表示未分級,不影響內部資格審核

priceFromTwd選填
integer· max 10000000 · min 0

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

directPriceTwd選填
integer· max 10000000 · min 0

直客定價(新台幣),留空(null)則退回起價繼承

agencyPriceTwd選填
integer· max 10000000 · min 0

同業定價(新台幣),留空(null)則退回直客/起價繼承

depositMode選填
enum
nonefixedpercent

訂金計算方式(none 不收/fixed 固定金額/percent 百分比)

depositAmountTwd選填
integer· max 10000000 · min 0

訂金固定金額(新台幣),depositMode 為 fixed 時生效。按人或按單由 depositBasis 決定

depositBasis選填
enum
per_personper_order

固定金額訂金的計算單位(per_person 每人,應付訂金=金額 × 人數/per_order 每張訂單一筆)。新行程預設 per_person;梯次覆寫的固定金額也照這個單位

depositPercent選填
integer· max 100 · min 1

訂金百分比(1–100),depositMode 為 percent 時生效

balanceDueDaysBeforeDeparture選填
integer· max 365 · min 0

尾款應繳截止日(出發前幾天)

feeInclusions選填
array· max 30

費用包含項目清單,每項含勾選狀態(ok)與說明文字(text)

notices選填
array· max 30

注意事項清單;最多 30 項,每項最多 200 字。省略不變,空陣列清空

cancellationFeeTiers選填
array· max 20

退改費階梯覆寫:距出發 ≥ daysBefore 天扣 feePercent%(佔成交總額)或 feeFixedTwd 元/人,二選一;null = 繼承租戶預設

isClimbing選填
boolean

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

isOverseas選填
boolean

是否為海外團

isHidden選填
boolean

不對外顯示:官網、站內搜尋與搜尋引擎都看不到,梯次不對外販售;後台照常可建單

isLinkOnly選填
boolean

僅限連結:不出現在官網列表、搜尋、sitemap 與前台 API 的行程列表,行程頁不給搜尋引擎收錄;拿到行程網址的人照常報名。與 isHidden 互斥;只送其中一個 true 時,另一個自動改成 false

manualCancellationRefund選填
boolean

取消後先由承辦核算扣除額,再開退款單

equipmentRentalEnabled選填
boolean

是否可租借裝備(需同時為登山團;開後此行程的梯次才能開租借單 / 登記裝備需求)

hasPreTripNight選填
boolean

是否有行前集合夜(出發日前一晚集合夜宿;集合日恆為出發日 −1)

meetingDay選填
integer· max 30 · min 1

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

pretripStayRoomTypeId選填
string

出發前夜住宿據點的床位池 id;null 表示不住公司據點

pretripStayExternalArranged選填
boolean

出發前夜住宿是否由公司安排外部住宿(民宿等);與據點床位池互斥

gradeScore選填
integer· max 100 · min 0

登山難度評分(0–100),null 表示未評級

requiresAlpineExperience選填
boolean

是否需具備高山經驗

gradeLabel選填
string· max 50

難度等級標籤文字

minGroupSize選填
integer· max 1000 · min 1

最低成團人數門檻,null 表示不設門檻

defaultCapacity選填
integer· max 200 · min 1

新增梯次時席次欄的預設值,null 表示沒設(表單用固定預設)

salesCloseDaysBefore選填
integer· max 365 · min 0

停止售票預設:出發日前 N 天的 00:00 自動把售票中的梯次改為已關閉;null 表示不自動關。梯次未自訂停止售票時間時繼承此值

meetingTime選填
string· 格式限定

集合時間預設(HH:mm,台北牆鐘),null 表示清空;梯次未填時繼承

meetingPlace選填
string· max 200

集合地點預設,null 表示清空;梯次未填時繼承

pretripBriefingUrl選填
string· max 2000

行前說明網址(http/https),所有梯次共用,null 表示清空。首次收款通知以 {{行前說明網址}} 代入;未填時通知刪掉含這個變數的整行

paymentReceivedBody選填
string· max 5000

收款後通知內文,所有梯次共用,null 表示清空。有值時首次收款通知(PAYMENT_RECEIVED)的內文改用它,主旨與啟用開關仍沿用範本;可用範本的 merge 變數

waitlistEnabled選填
boolean

是否開放候補

foreignTravelersOnly選填
boolean

限外籍旅客。true 時前台結帳擋下國籍空白或台灣的旅客;建單 API 與 K 單同樣擋,要送 allowDomesticTravelers 才放行

lotteryIdentityGuardEnabled選填
boolean

是否啟用抽籤實名制:同一證件在任一受管制抽籤梯次同時只能有一筆待決申請

lotteryWaitlistEnabled選填
boolean

抽籤結果含備取:主管機關會把申請排進備取的路線(例:排雲山莊)。true 時團控出現「備取」標記鍵。與 waitlistEnabled(一般梯次滿席候補)無關

defaultAllocationMode選填
enum
fcfslottery

預設分配模式(fcfs 先到先得/lottery 抽籤):新增梯次未指定時繼承此值,梯次可逐梯覆寫;改動不回寫既有梯次。lottery 需抽籤模組

travelersPerGuide選填
integer· max 99 · min 1

每幾位旅客配一位隨團人員(1–99),null 表示不自動算。成團時以已佔位人數算 ceil(人數 / 此值),帶入仍未填的梯次 requiredGuideCount

defaultGuideCount選填
integer· max 99 · min 0

預設需要幾位嚮導(0–99;0 = 不需嚮導),null 表示沒設。新增梯次沒指定 requiredGuideCount 時帶入;改動不回寫既有梯次

lotteryLeadDays選填
integer· max 365 · min 1

抽籤日在出發日前幾天(1–365),null 表示未設。退改費階梯首列門檻須為此值 + 1;抽籤梯次的可變更第三人期限 = 此值 + 緩衝天數;租戶抽籤日期來源的期限日 = 出發日前此天數

lotteryDrawTime選填
string· 格式限定

抽籤時刻預設(HH:MM,台北時間),null 表示未設。抽籤梯次到抽籤日的這個時刻,前台停收新單;後台建單不受影響。抽籤時程表的時段開始與梯次覆寫優先;都沒設時抽籤日 00:00 停收

agreementChangeBufferDays選填
integer· max 365 · min 0

抽籤梯次緩衝天數的行程覆寫(0–365),null 表示沿用公司設定。抽籤梯次的可變更第三人期限 = 抽籤前幾天 + 此值

agreementTravelForm選填
enum
individualgroup

本行程契約的旅遊型態(individual 個別/group 團體),null 表示沿用公司設定。國內/國外仍由 isOverseas 決定

agreementExempt選填
boolean

此行程不需旅遊契約。true 時這條行程的訂單不產生契約、不寄簽約邀請,並撤銷待簽契約;改回 false 後照一般規則補產生

coverImageUrl選填
string· max 2000

行程封面圖網址(http/https,或本站圖庫資產路徑);null 清空

seoTitle選填
string· max 200

SEO 標題,覆寫前台頁面 title

seoDescription選填
string· max 500

SEO 描述,覆寫前台 meta description

ogImageUrl選填
string· max 2000

Open Graph 社群分享圖網址(http/https,或本站圖庫資產路徑);null 清空

pnlRegionId選填
string· max 60

損益分區 id(pnl_regions),null 表示未指派、退回系統派生

status選填
enum
draftpublishedarchived

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

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/trips/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "example-tags"
  ],
  "slug": "example-slug",
  "title": "example-title"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

bind / unbind a trip's cost templates

PUT/api/v1/trips/{id}/cost-template
cost_template.manage模組:tour

參數

id路徑
string· min 1

行程 ID(路徑參數)

templateIds選填
array

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

templateId選填
string· min 1

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

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X PUT "https://your-tenant.example.com/api/v1/trips/<id>/cost-template" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "templateIds": [
    "example-templateIds"
  ],
  "templateId": "example-templateId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

add a departure to a trip

POST/api/v1/trips/{id}/departures
trip.manage模組:tour

參數

id路徑
string· min 1

行程 ID(路徑參數),新梯次所屬的行程

departureDate必填
string

出發日期(YYYY-MM-DD)

returnDate必填
string

回程日期(YYYY-MM-DD),須晚於出發日

priceTwd必填
integer· max 10000000 · min 0

梯次直客售價(新台幣)

capacity必填
integer· max 200 · min 1

梯次總名額(座位上限)

agencyPriceTwd選填
integer· max 10000000 · min 0

梯次同業售價(新台幣)

depositMode選填
enum
nonefixedpercent

訂金計算方式(none 不收/fixed 固定金額/percent 百分比)

depositAmountTwd選填
integer· max 10000000 · min 0

梯次訂金固定金額(新台幣),depositMode 為 fixed 時生效。按人或按單照行程的 depositBasis

depositPercent選填
integer· max 100 · min 1

訂金百分比(1–100),depositMode 為 percent 時生效

status選填
enum
sellingclosedcancelledcompleted

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

label選填
string· max 30

梯次標籤/副標(最多 30 字,例:包、包1、外籍包),只顯示在後台;省略 = 無

isPrivate選填
boolean

不對外販售:前台不顯示、客人不可自助報名,但後台 K 單看得到、建得了;省略 = false

allocationMode選填
enum
fcfslottery

分配模式(fcfs 先到先得/lottery 抽籤);省略 = 繼承行程的 defaultAllocationMode。lottery 需抽籤模組

regionCode選填
string· 格式限定

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

airlineCode選填
string· 格式限定

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

salesCloseAt選填
string· 格式限定

停止售票時間(YYYY-MM-DDTHH:MM,台北牆鐘),到點自動把售票中改為已關閉;省略則繼承行程的「出發前 N 天」預設

salesOpenAt選填
string· 格式限定

開賣時間(YYYY-MM-DDTHH:MM,台北牆鐘)。梯次先建成已關閉,到點自動改為售票中;須晚於現在、早於停止售票時間。省略 = 照舊人工上架

meetingTime選填
string· 格式限定

集合時間(HH:mm,台北牆鐘);省略 = 繼承行程層預設

meetingPlace選填
string· max 200

集合地點;省略 = 繼承行程層預設

agreementChangeDays選填
integer· max 365 · min 0

可變更第三人期限(出發前 N 日,對應契約「旅客之變更權」條);免抽籤梯次省略則用租戶預設,團體抽籤契約未設定有效日期來源時必填

entryDateOffsetDays選填
integer· max 60 · min 0

實際入園日相對出發日的偏移天數(入園日 = 出發日 + N);省略 = 0。錨定入園日的關鍵日期由此回推

lotteryLeadDays選填
integer· max 365 · min 1

抽籤日在出發日前幾天的逐梯覆寫(1–365);省略或 null = 繼承行程的 lotteryLeadDays。只影響期限與契約,不改退改費階梯

lotteryDrawTime選填
string· 格式限定

抽籤時刻的逐梯覆寫(HH:MM,台北時間);省略或 null = 繼承行程的 lotteryDrawTime。抽籤時程表上有這梯的時段開始時,時段開始優先

requiredGuideCount選填
integer· max 99 · min 0

需要的隨團人員數(主要+協同合計,0–99;0 = 不需嚮導);省略或 null = 帶入行程的 defaultGuideCount(沒設 = 未填);仍未填且行程有設 travelersPerGuide 時,成團以 ceil(已佔位人數 / 比例) 帶入

回應欄位 · data

id
string

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/<id>/departures" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureDate": "2026-10-13",
  "returnDate": "2026-10-13",
  "priceTwd": 1,
  "capacity": 1
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

為某梯次預留自家旅宿配套

POST/api/v1/trips/{id}/departures/{depId}/lodging
trip.manage模組:lodging

參數

id路徑
string· min 1

行程 ID(路徑參數),梯次所屬的行程

depId路徑
string· min 1

梯次 ID(路徑參數),要預留旅宿的梯次

propertyId必填
string· min 1

自家旅宿物件 ID

roomTypeId必填
string· min 1

該旅宿的房型 ID

checkIn必填
string· 格式限定

入住日(YYYY-MM-DD)

checkOut必填
string· 格式限定

退房日(YYYY-MM-DD),須晚於入住日,且區間最多 60 晚

blockUnits必填
integer

整塊預留的房間間數

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/<id>/departures/<depId>/lodging" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "propertyId": "example-propertyId",
  "roomTypeId": "example-roomTypeId",
  "checkIn": "2026-10-13",
  "checkOut": "2026-10-13",
  "blockUnits": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

釋回某梯次的自家旅宿配套預留

DELETE/api/v1/trips/{id}/lodging/{dlId}
trip.manage模組:lodging

參數

id路徑
string· min 1

行程 ID(路徑參數),預留所屬的行程

dlId路徑
string· min 1

梯次旅宿配套預留 ID(路徑參數),要釋回的預留

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/trips/<id>/lodging/<dlId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
GET/api/v1/trips/{id}/ops-defaults
departure_prep.read模組:tour

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

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

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

kind
"climbing" | "liability"
insurer
string | null
workdaysBefore選填
number | undefined
請求
curl -X GET "https://your-tenant.example.com/api/v1/trips/<id>/ops-defaults" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "transport": [
      {
        "key": "…",
        "description": "…",
        "vehicleInfo": "…",
        "fareNote": "…"
      }
    ],
    "catering": [
      {
        "key": "…",
        "supplier": "…",
        "mealPlan": "…",
        "headcountNote": "…"
      }
    ],
    "insurance": [
      {
        "kind": "climbing",
        "insurer": "…",
        "workdaysBefore": 0
      }
    ]
  }
}

Use the canonical tenant operation.

PUT/api/v1/trips/{id}/ops-defaults
departure_prep.manage模組:tour

參數

id路徑
string· min 1

Resource ID

defaults必填
object

Replace transport, catering, and insurance defaults; null clears defaults

回應欄位 · data

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

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

kind
"climbing" | "liability"
insurer
string | null
workdaysBefore選填
number | undefined
請求
curl -X PUT "https://your-tenant.example.com/api/v1/trips/<id>/ops-defaults" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "defaults": {
    "transport": [
      {}
    ],
    "catering": [
      {}
    ],
    "insurance": [
      {
        "kind": "liability"
      }
    ]
  }
}'
回應
{
  "ok": true,
  "data": {
    "defaults": null
  }
}

Use the canonical tenant operation.

GET/api/v1/trips/{id}/survey
trip.manage模組:tour

參數

id路徑
string· min 1

Resource ID

回應欄位 · data[]

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

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

displayOrder
number
isActive
boolean
請求
curl -X GET "https://your-tenant.example.com/api/v1/trips/<id>/survey" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "tripId": "…",
      "kind": "multi",
      "label": "…",
      "description": "…",
      "required": true,
      "displayOrder": 0,
      "isActive": true,
      "options": [
        {
          "id": "…",
          "label": "…",
          "equipmentItemId": "…",
          "displayOrder": 0,
          "isActive": true
        }
      ]
    }
  ]
}

Use the canonical tenant operation.

PATCH/api/v1/trips/{id}/survey/options/{optionId}
trip.manage模組:tour

參數

id路徑
string· min 1

Resource ID

optionId路徑
string· min 1

Option ID

label選填
string· min 1

Option label

isActive選填
boolean

Option enabled

equipmentItemId選填
string· min 1

Equipment item; null to unlink

回應欄位 · data

found
boolean
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/trips/<id>/survey/options/<optionId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "example-label",
  "isActive": true,
  "equipmentItemId": "example-equipmentItemId"
}'
回應
{
  "ok": true,
  "data": {
    "found": true
  }
}

Use the canonical tenant operation.

POST/api/v1/trips/{id}/survey/questions
trip.manage模組:tour

參數

id路徑
string· min 1

Resource ID

kind必填
enum
textsinglemultiquantity

Question kind

label必填
string· min 1

Question label

description選填
string

Question description

required選填
boolean

Answer required

options選填
array

Option labels

回應欄位 · data

id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/<id>/survey/questions" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "text",
  "label": "example-label"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

Use the canonical tenant operation.

PATCH/api/v1/trips/{id}/survey/questions/{questionId}
trip.manage模組:tour

參數

id路徑
string· min 1

Resource ID

questionId路徑
string· min 1

Question ID

label選填
string· min 1

Question label

description選填
string

Description

required選填
boolean

Answer required

回應欄位 · data

found
boolean
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/trips/<id>/survey/questions/<questionId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "example-label",
  "description": "example-description",
  "required": true
}'
回應
{
  "ok": true,
  "data": {
    "found": true
  }
}

Use the canonical tenant operation.

POST/api/v1/trips/{id}/survey/questions/{questionId}/active
trip.manage模組:tour

參數

id路徑
string· min 1

Resource ID

questionId路徑
string· min 1

Question ID

isActive必填
boolean

Question enabled

回應欄位 · data

found
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/<id>/survey/questions/<questionId>/active" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "found": true
  }
}

Use the canonical tenant operation.

POST/api/v1/trips/{id}/survey/questions/{questionId}/options
trip.manage模組:tour

參數

id路徑
string· min 1

Resource ID

questionId路徑
string· min 1

Question ID

label必填
string· min 1

Option label

回應欄位 · data

id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/<id>/survey/questions/<questionId>/options" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "example-label"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

批次新增梯次 commit

POST/api/v1/trips/batch-departures
trip.manage模組:tour

參數

rows必填
array· max 1000 · min 1

回應欄位 · data

result
object

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

importBatchId
string

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

createdTripCount
number

新建行程數。

createdDepartureCount
number

新建梯次數。

skippedCount
number

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

errorCount
number

失敗列數。

results
object[]

逐列匯入結果。

rowNumber
number

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

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

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

message
string | null

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

tripId選填
string | undefined

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

departureId選填
string | undefined

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

groupCode選填
string | undefined

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

incompleteTrips
object[]

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

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

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/batch-departures" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "tripId": "example-tripId",
      "departureDate": "2026-10-13",
      "returnDate": "2026-10-13",
      "priceTwd": "example-priceTwd",
      "capacity": "example-capacity",
      "allocationMode": "",
      "meetingTime": "example-meetingTime",
      "meetingPlace": "example-meetingPlace",
      "agreementChangeDays": "example-agreementCha",
      "entryDateOffsetDays": "2026-10-13",
      "isPrivate": true,
      "label": "example-label"
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "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"
          ]
        }
      ]
    }
  }
}

批次新增梯次 dry-run

POST/api/v1/trips/batch-departures/validate
trip.manage模組:tour

參數

rows必填
array· max 1000 · min 1

回應欄位 · data

result
object

試算(dry-run)結果:逐列預覽 + 彙總,列號 = 第幾列(1 起)。

rows
object[]
rowNumber
number

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

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

該列匯入判定:new_trip 新建行程 / append_departure 附加梯次 / skip 略過 / error 錯誤。

message
string | null

error / skip 的人話原因(繁中);new_trip / append_departure 為空。

parsed
object

解析後的欄位值。

slug
string
title
string | null
summary
string | null
destination
string | null
durationDays
number | null
isClimbing
boolean
isOverseas
boolean
hasPreTripNight
ImportedCell<boolean>

行前集合夜三態;null = 留空(繼承既有行程)。見 {@link ImportedCell}。

gradeScore
ImportedCell<number>

登山難度評鑑分數(0–100,可小數)。

requiresAlpineExperience
ImportedCell<boolean>

是否需具備高山經驗(是/否)。

lotteryLeadDays
ImportedCell<number | "overseas">

30 / 60 / 120 依租戶預設產生階梯;海外使用個別契約範本。

overseasIndividualCancellation選填
ImportedCell<boolean> | undefined

明示套用海外個別契約範本;留空不套用。

depositMode
ImportedCell<DepositMode>

訂金方式(不收 / 固定金額 / 比例)。

depositAmountTwd
ImportedCell<number>

訂金金額(TWD 正整數;方式=固定金額時必填)。

depositPercent
ImportedCell<number>

訂金比例(1–100;方式=比例時必填)。

departureDate
string | null
returnDate
string | null
priceTwd
number | null
capacity
ImportedCell<number>

留空 = null(補梯次時沿用行程的預設名額);非整數 → 'invalid'。

notes
string | null
label
string | null

梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);留空 = null。

isPrivate
ImportedCell<boolean>

不對外販售(issue 509 ①)。留空 = 否;填了無法辨識的值 → 'invalid'(dry-run error)。

allocationMode
ImportedCell<AllocationMode>

分配模式(issue 511)。留空 = 繼承母行程的預設分配模式(createDeparture copy-on-create); 填了無法辨識的值 → 'invalid'(dry-run error);抽籤但平台未啟用抽籤模組 → error。

regionCode
string | null
airlineCode
string | null
agencyPriceTwd
ImportedCell<number>

同業價(TWD 整數 ≥ 0);留空 = 退回常規定價鏈。

departureDepositMode
ImportedCell<DepositMode>

梯次訂金方式覆寫;留空 = 繼承行程的訂金設定。

departureDepositAmountTwd
ImportedCell<number>

梯次訂金金額(方式=固定金額時必填)。

departureDepositPercent
ImportedCell<number>

梯次訂金比例(方式=比例時必填,1–100)。

salesCloseAt
ImportedCell<string>

逐梯停止售票時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘);只填日期 = 當天 00:00;留空 = 繼承行程層。

salesOpenAt
ImportedCell<string>

開賣時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘,issue 1643);解析同停止售票日。有值時梯次建成 已關閉,排程到點開賣;留空 = 照舊。

meetingTime
ImportedCell<string>

集合時間 `HH:mm`(台北牆鐘);留空 = 讀取時繼承行程層。

meetingPlace
string | null

集合地點(≤ 200 字);留空 = 讀取時繼承行程層。

agreementChangeDays
ImportedCell<number>

可變更第三人期限(出發前 N 日,0–365);留空 = 免抽籤梯次用租戶預設,團體契約的抽籤梯次缺值不產生契約,個別契約不適用。

entryDateOffsetDays
ImportedCell<number>

實際入園日偏移(入園日 = 出發日 + N,0–行程天數−1);留空 = 0。

requiredGuideCount
ImportedCell<number>

需要的隨團人員數(1–99,issue 1117);留空 = 未填,成團時再依行程比例帶入。

promoPriceTwd
ImportedCell<number>

促銷直客價(TWD 正整數);有值 = 啟用梯次促銷;留空 = 不促銷。

promoAgencyPriceTwd
ImportedCell<number>

促銷同業價(TWD 正整數);須搭配促銷直客價;留空 = 同業不參與促銷。

opAssignee
string | null

承辦(issue 1102):後台帳號 Email,或唯一對到帳號的姓名;原樣保留,比對在 resolveRows。 留空 = 不掛承辦。補梯次列與「梯次已存在」的列也套用。

existingTripDefaultAllocationMode選填
AllocationMode | null | undefined

該 slug 在 DB 已有行程時,其 `default_allocation_mode`(issue 511):預覽對留空的補梯次列 印出「繼承後會落成什麼」用。slug 在 DB 不存在 → null。

warnings
object[]

建完後擋開賣的缺項(#613 2026-10-20)。只提醒、不擋建檔;只有會建檔的列 (new_trip / append_departure)才有。判準見 {@link importRowWarnings}。

code
"agreement_change_days_missing" | "meeting_info_missing"
message
string
summary
object
totalRows
number

資料列總數。

newTripCount
number

判定為「新建行程」的列數。

appendDepartureCount
number

判定為「附加梯次到既有行程」的列數。

skipCount
number

略過列數。

errorCount
number

有錯誤的列數。

unsellableCount
number

會建檔、但建完後開賣會被擋的梯次數(至少一則 warning 的列)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/batch-departures/validate" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "tripId": "example-tripId",
      "departureDate": "2026-10-13",
      "returnDate": "2026-10-13",
      "priceTwd": "example-priceTwd",
      "capacity": "example-capacity",
      "allocationMode": "",
      "meetingTime": "example-meetingTime",
      "meetingPlace": "example-meetingPlace",
      "agreementChangeDays": "example-agreementCha",
      "entryDateOffsetDays": "2026-10-13",
      "isPrivate": true,
      "label": "example-label"
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "result": {
      "rows": [
        {
          "rowNumber": 0,
          "status": "append_departure",
          "message": "…",
          "parsed": {
            "slug": "…",
            "title": "…",
            "summary": "…",
            "destination": "…",
            "durationDays": 0,
            "isClimbing": true,
            "isOverseas": true,
            "hasPreTripNight": "…",
            "gradeScore": "…",
            "requiresAlpineExperience": "…",
            "lotteryLeadDays": "overseas",
            "overseasIndividualCancellation": "…",
            "depositMode": "…",
            "depositAmountTwd": "…",
            "depositPercent": "…",
            "departureDate": "…",
            "returnDate": "…",
            "priceTwd": 0,
            "capacity": "…",
            "notes": "…",
            "label": "…",
            "isPrivate": "…",
            "allocationMode": "…",
            "regionCode": "…",
            "airlineCode": "…",
            "agencyPriceTwd": "…",
            "departureDepositMode": "…",
            "departureDepositAmountTwd": "…",
            "departureDepositPercent": "…",
            "salesCloseAt": "…",
            "salesOpenAt": "…",
            "meetingTime": "…",
            "meetingPlace": "…",
            "agreementChangeDays": "…",
            "entryDateOffsetDays": "…",
            "requiredGuideCount": "…",
            "promoPriceTwd": "…",
            "promoAgencyPriceTwd": "…",
            "opAssignee": "…"
          },
          "existingTripDefaultAllocationMode": null,
          "warnings": [
            {
              "code": "agreement_change_days_missing",
              "message": "…"
            }
          ]
        }
      ],
      "summary": {
        "totalRows": 0,
        "newTripCount": 0,
        "appendDepartureCount": 0,
        "skipCount": 0,
        "errorCount": 0,
        "unsellableCount": 0
      }
    }
  }
}

Use the canonical tenant operation.

POST/api/v1/trips/cancellation-tiers/preview
trip.manage模組:tour

參數

tripIds必填
array· max 200 · min 1

Selected trip IDs

回應欄位 · data

changes
object[]

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

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

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

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

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

tenantTiers
object[]

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

daysBefore
number

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

feePercent選填
number | undefined

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

feeFixedTwd選填
number | undefined

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

onSaleCount
number

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

orderCount
number

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/cancellation-tiers/preview" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}

Use the canonical tenant operation.

POST/api/v1/trips/cancellation-tiers/reapply
trip.manage模組:tour

參數

tripIds必填
array· max 200 · min 1

Selected trip IDs

confirmedTripIds必填
array· max 200

Confirmed affected trip IDs from preview

confirmedTenantTiers必填
array· max 100

Tenant tiers from preview

回應欄位 · data

changes
object[]

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

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

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

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

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

tenantTiers
object[]

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

daysBefore
number

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

feePercent選填
number | undefined

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

feeFixedTwd選填
number | undefined

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

onSaleCount
number

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

orderCount
number

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/cancellation-tiers/reapply" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}

active cost templates for

GET/api/v1/trips/cost-templates
cost_template.read模組:tour

參數

status選填
string

成本範本狀態篩選;目前僅回傳啟用中(active)範本

回應欄位 · data[]

id
string

成本範本 id(ct_ 前綴)。

name
string

成本範本名稱。

請求
curl -X GET "https://your-tenant.example.com/api/v1/trips/cost-templates" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…"
    }
  ]
}

group-code lookup over HTTP.

GET/api/v1/trips/departures
trip.read模組:tour

參數

groupCode選填
string· min 1

完整團號,精確比對單一梯次

groupCodePrefix選填
string· min 1

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/trips/departures" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": "…"
}

per-row edit of an existing

PATCH/api/v1/trips/departures/{departureId}
trip.manage模組:tour

參數

departureId路徑
string· min 1

梯次 ID(路徑參數)

departureDate選填
string

出發日期(YYYY-MM-DD),與回程日一起提供

returnDate選填
string

回程日期(YYYY-MM-DD),不得早於出發日

capacity選填
integer· max 200 · min 1

梯次總名額(座位上限),不得低於已報名人數

priceTwd選填
integer· max 10000000 · min 0

梯次直客售價(新台幣)

agencyPriceTwd選填
integer· max 10000000 · min 0

梯次同業售價(新台幣),null 表示清空、退回常規定價鏈

depositMode選填
enum
nonefixedpercent

訂金計算方式(none 不收/fixed 固定金額/percent 百分比),null 表示退回繼承

depositAmountTwd選填
integer· max 10000000 · min 0

梯次訂金固定金額(新台幣),depositMode 為 fixed 時生效,null 表示清空。按人或按單照行程的 depositBasis

depositPercent選填
integer· max 100 · min 1

訂金百分比(1–100),depositMode 為 percent 時生效,null 表示清空

promoActive選填
boolean

是否啟用梯次促銷覆寫價

promoPriceTwd選填
integer· max 10000000 · min 1

直客促銷價(新台幣),啟用促銷時必填,null 表示清空

promoAgencyPriceTwd選填
integer· max 10000000 · min 1

同業促銷價(新台幣),null 表示同業退回常規鏈

salesCloseAt選填
string· 格式限定

停止售票時間(YYYY-MM-DDTHH:MM,台北牆鐘),到點自動把售票中改為已關閉;null 表示清空、退回繼承行程的「出發前 N 天」預設

salesOpenAt選填
string· 格式限定

開賣時間(YYYY-MM-DDTHH:MM,台北牆鐘),到點自動把已關閉改為售票中;只有已關閉的梯次可設,須晚於現在、早於停止售票時間。null 表示取消排程

meetingTime選填
string· 格式限定

集合時間(HH:mm,台北牆鐘),null 表示清空、退回繼承行程層預設

meetingPlace選填
string· max 200

集合地點,null 表示清空、退回繼承行程層預設

agreementChangeDays選填
integer· max 365 · min 0

可變更第三人期限(出發前 N 日,對應契約「旅客之變更權」條),null 表示退回租戶預設

entryDateOffsetDays選填
integer· max 60 · min 0

實際入園日相對出發日的偏移天數(入園日 = 出發日 + N);改動會重算公式產生的關鍵日期

lotteryLeadDays選填
integer· max 365 · min 1

抽籤日在出發日前幾天的逐梯覆寫(1–365),null 表示退回繼承行程的 lotteryLeadDays;改動會重算公式產生的關鍵日期

lotteryDrawTime選填
string· 格式限定

抽籤時刻的逐梯覆寫(HH:MM,台北時間);省略或 null = 繼承行程的 lotteryDrawTime。抽籤時程表上有這梯的時段開始時,時段開始優先

requiredGuideCount選填
integer· max 99 · min 0

需要的隨團人員數(主要+協同合計,0–99;0 = 不需嚮導),null 表示清空成未填。已確認指派數少於此值時,團控缺件列「隨團人員不足」

label選填
string· max 30

梯次標籤/副標(最多 30 字),null 表示清空

isPrivate選填
boolean

不對外販售:true 前台不顯示、客人不可自助報名(後台仍可建單);false 恢復對外

allocationMode選填
enum
fcfslottery

分配模式(fcfs 先到先得/lottery 抽籤),null 表示退回繼承行程的 defaultAllocationMode。lottery 需抽籤模組

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪來源尚未同步,每日排程會補做;梯次本身已更新。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/trips/departures/<departureId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureDate": "2026-10-13",
  "returnDate": "2026-10-13",
  "capacity": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}

manual group-code

POST/api/v1/trips/departures/{departureId}/group-code
departure.update模組:tour

參數

departureId路徑
string· min 1

要覆寫團號的梯次 ID

groupCode必填
string

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

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

groupCode
string

設定後的團號。

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/departures/<departureId>/group-code" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "groupCode": "example-groupCode"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "groupCode": "…"
  }
}

auto

POST/api/v1/trips/departures/{departureId}/group-code/generate
departure.update模組:tour

參數

departureId路徑
string· min 1

要產生團號的梯次 ID

regionCode必填
string

地區碼,2–8 碼大寫英數(自動轉大寫)

airlineCode選填
string

航空碼(選填),2–8 碼大寫英數;國內團留空省略航空段

departureDate必填
string

出發日期(ISO 格式 YYYY-MM-DD,取 MMDD 組成團號)

回應欄位 · data

groupCode
string

自動產生的團號。

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/departures/<departureId>/group-code/generate" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "regionCode": "example-regionCode",
  "departureDate": "2026-10-13"
}'
回應
{
  "ok": true,
  "data": {
    "groupCode": "…"
  }
}

change a departure's

POST/api/v1/trips/departures/{departureId}/status
trip.status模組:tour

參數

departureId路徑
string· min 1

梯次 ID(路徑參數)

status必填
enum
sellingclosedcancelledcompleted

目標梯次狀態(selling 銷售中/closed 關閉/cancelled 取消/completed 完成)

回應欄位 · data

ok
boolean

操作成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪來源尚未同步,每日排程會補做;梯次狀態本身已變更。

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/departures/<departureId>/status" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "selling"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}

匯出行程

GET/api/v1/trips/export
trip.read模組:tour

參數

status選填
string

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

q選填
string

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

groupCode選填
string

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

回應欄位 · data

rows
object[]

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

id
string

行程 id(trip_ 前綴)。

slug
string

行程網址 slug。

title
string

行程標題。

destination
string

目的地名稱。

durationDays
number

天數。

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

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

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

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

isHidden
boolean

不對外顯示(#1435)。

isLinkOnly
boolean

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

foreignTravelersOnly
boolean

限外籍旅客(issue 1519)。

updatedAt
string

最後更新時間。

isClimbing
boolean

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

isOverseas
boolean

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

hasPreTripNight
boolean

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

activeDepartureCount
number

Count of departures with status='selling'.

nextDepartureDate
string | null

Earliest selling departure_date, ISO date string, or null.

representativeGroupCode
string | null

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

total
number

匯出總筆數。

truncated
boolean

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/trips/export" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "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
  }
}

行程批次匯入 commit:上傳檔

POST/api/v1/trips/import
trip.manage模組:tour

參數

filename必填
string· min 1

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

contentBase64必填
string· min 1

檔案內容的 base64 編碼字串(上限 5 MB)

回應欄位 · data

filename
string

已匯入的檔名。

result
object

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

importBatchId
string

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

createdTripCount
number

新建行程數。

createdDepartureCount
number

新建梯次數。

skippedCount
number

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

errorCount
number

失敗列數。

results
object[]

逐列匯入結果。

rowNumber
number

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

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

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

message
string | null

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

tripId選填
string | undefined

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

departureId選填
string | undefined

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

groupCode選填
string | undefined

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

incompleteTrips
object[]

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

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

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/import" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "example-filename",
  "contentBase64": "example-contentBase64"
}'
回應
{
  "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"
          ]
        }
      ]
    }
  }
}

行程批次匯入 dry-run:上傳檔

POST/api/v1/trips/import/validate
trip.manage模組:tour

參數

filename必填
string· min 1

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

contentBase64必填
string· min 1

檔案內容的 base64 編碼字串(上限 5 MB)

回應欄位 · data

filename
string

已驗證的檔名。

result
object

試算(dry-run)結果(逐列預覽 + 彙總,不寫入)。

rows
object[]

逐列預覽結果。

rowNumber
number

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

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

該列匯入判定:new_trip 新建行程 / append_departure 附加梯次 / skip 略過 / error 錯誤。

message
string | null

error / skip 的人話原因(繁中);new_trip / append_departure 為空。

parsed
object

解析後的欄位值。

slug
string
title
string | null
summary
string | null
destination
string | null
durationDays
number | null
isClimbing
boolean
isOverseas
boolean
hasPreTripNight
ImportedCell<boolean>

行前集合夜三態;null = 留空(繼承既有行程)。見 {@link ImportedCell}。

gradeScore
ImportedCell<number>

登山難度評鑑分數(0–100,可小數)。

requiresAlpineExperience
ImportedCell<boolean>

是否需具備高山經驗(是/否)。

lotteryLeadDays
ImportedCell<number | "overseas">

30 / 60 / 120 依租戶預設產生階梯;海外使用個別契約範本。

overseasIndividualCancellation選填
ImportedCell<boolean> | undefined

明示套用海外個別契約範本;留空不套用。

depositMode
ImportedCell<DepositMode>

訂金方式(不收 / 固定金額 / 比例)。

depositAmountTwd
ImportedCell<number>

訂金金額(TWD 正整數;方式=固定金額時必填)。

depositPercent
ImportedCell<number>

訂金比例(1–100;方式=比例時必填)。

departureDate
string | null
returnDate
string | null
priceTwd
number | null
capacity
ImportedCell<number>

留空 = null(補梯次時沿用行程的預設名額);非整數 → 'invalid'。

notes
string | null
label
string | null

梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);留空 = null。

isPrivate
ImportedCell<boolean>

不對外販售(issue 509 ①)。留空 = 否;填了無法辨識的值 → 'invalid'(dry-run error)。

allocationMode
ImportedCell<AllocationMode>

分配模式(issue 511)。留空 = 繼承母行程的預設分配模式(createDeparture copy-on-create); 填了無法辨識的值 → 'invalid'(dry-run error);抽籤但平台未啟用抽籤模組 → error。

regionCode
string | null
airlineCode
string | null
agencyPriceTwd
ImportedCell<number>

同業價(TWD 整數 ≥ 0);留空 = 退回常規定價鏈。

departureDepositMode
ImportedCell<DepositMode>

梯次訂金方式覆寫;留空 = 繼承行程的訂金設定。

departureDepositAmountTwd
ImportedCell<number>

梯次訂金金額(方式=固定金額時必填)。

departureDepositPercent
ImportedCell<number>

梯次訂金比例(方式=比例時必填,1–100)。

salesCloseAt
ImportedCell<string>

逐梯停止售票時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘);只填日期 = 當天 00:00;留空 = 繼承行程層。

salesOpenAt
ImportedCell<string>

開賣時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘,issue 1643);解析同停止售票日。有值時梯次建成 已關閉,排程到點開賣;留空 = 照舊。

meetingTime
ImportedCell<string>

集合時間 `HH:mm`(台北牆鐘);留空 = 讀取時繼承行程層。

meetingPlace
string | null

集合地點(≤ 200 字);留空 = 讀取時繼承行程層。

agreementChangeDays
ImportedCell<number>

可變更第三人期限(出發前 N 日,0–365);留空 = 免抽籤梯次用租戶預設,團體契約的抽籤梯次缺值不產生契約,個別契約不適用。

entryDateOffsetDays
ImportedCell<number>

實際入園日偏移(入園日 = 出發日 + N,0–行程天數−1);留空 = 0。

requiredGuideCount
ImportedCell<number>

需要的隨團人員數(1–99,issue 1117);留空 = 未填,成團時再依行程比例帶入。

promoPriceTwd
ImportedCell<number>

促銷直客價(TWD 正整數);有值 = 啟用梯次促銷;留空 = 不促銷。

promoAgencyPriceTwd
ImportedCell<number>

促銷同業價(TWD 正整數);須搭配促銷直客價;留空 = 同業不參與促銷。

opAssignee
string | null

承辦(issue 1102):後台帳號 Email,或唯一對到帳號的姓名;原樣保留,比對在 resolveRows。 留空 = 不掛承辦。補梯次列與「梯次已存在」的列也套用。

existingTripDefaultAllocationMode選填
AllocationMode | null | undefined

該 slug 在 DB 已有行程時,其 `default_allocation_mode`(issue 511):預覽對留空的補梯次列 印出「繼承後會落成什麼」用。slug 在 DB 不存在 → null。

warnings
object[]

建完後擋開賣的缺項(#613 2026-10-20)。只提醒、不擋建檔;只有會建檔的列 (new_trip / append_departure)才有。判準見 {@link importRowWarnings}。

code
"agreement_change_days_missing" | "meeting_info_missing"
message
string
summary
object

各狀態列數彙總。

totalRows
number

資料列總數。

newTripCount
number

判定為「新建行程」的列數。

appendDepartureCount
number

判定為「附加梯次到既有行程」的列數。

skipCount
number

略過列數。

errorCount
number

有錯誤的列數。

unsellableCount
number

會建檔、但建完後開賣會被擋的梯次數(至少一則 warning 的列)。

fileError
string | null

整檔層級的致命錯誤(如超列上限、空檔、無法解析),非空時 rows 為空。

columns
object[]

表頭各欄的辨識結果(issue 613):認成哪個欄位、認不得的欄、重複或不匯入的欄。 預覽據此列出欄位對應,讓使用者用下拉指定。讀不到表頭列(壞檔、空檔)時為空陣列; 「找不到可辨識的表頭欄位」時仍帶回整列,使用者才能當場指定。

index
number

在表頭列中的第幾格(0-based)。

header
string

原始標題(trim 後)。

key
string

洗過的標題(記憶對應的 key);空標題為 `''`(記不起來、沒有下拉)。

target
ImportHeaderTarget | null

辨識結果:欄位、`'ignore'`(不匯入),或 `null`(認不得)。

source
"alias" | "memory" | null

`alias` = 別名表;`memory` = 租戶記憶對應;`null` = 認不得或空標題。

writes
"agency_price_twd" | "agreement_change_days" | "airline_code" | "allocation_mode" | "capacity" | "departure_date" | "departure_deposit_amount_twd" | "departure_deposit_mode" | "departure_deposit_percent" | "deposit_amount_twd" | "deposit_mode" | "deposit_percent" | "destination" | "duration_days" | "entry_date_offset_days" | "grade_score" | "has_pre_trip_night" | "is_climbing" | "is_overseas" | "is_private" | "label" | "lottery_lead_days" | "meeting_place" | "meeting_time" | "notes" | "op_assignee" | "overseas_individual_cancellation" | "price_twd" | "promo_agency_price_twd" | "promo_price_twd" | "region_code" | "required_guide_count" | "requires_alpine_experience" | "return_date" | "sales_close_at" | "sales_open_at" | "slug" | "summary" | "title" | null

真正讀進哪個欄位;`null` = 這一欄不匯入(原因在 `note`)。

note選填
string | undefined

不匯入的原因(預覽的欄位對應表顯示)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/trips/import/validate" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "example-filename",
  "contentBase64": "example-contentBase64"
}'
回應
{
  "ok": true,
  "data": {
    "filename": "…",
    "result": {
      "rows": [
        {
          "rowNumber": 0,
          "status": "append_departure",
          "message": "…",
          "parsed": {
            "slug": "…",
            "title": "…",
            "summary": "…",
            "destination": "…",
            "durationDays": 0,
            "isClimbing": true,
            "isOverseas": true,
            "hasPreTripNight": "…",
            "gradeScore": "…",
            "requiresAlpineExperience": "…",
            "lotteryLeadDays": "overseas",
            "overseasIndividualCancellation": "…",
            "depositMode": "…",
            "depositAmountTwd": "…",
            "depositPercent": "…",
            "departureDate": "…",
            "returnDate": "…",
            "priceTwd": 0,
            "capacity": "…",
            "notes": "…",
            "label": "…",
            "isPrivate": "…",
            "allocationMode": "…",
            "regionCode": "…",
            "airlineCode": "…",
            "agencyPriceTwd": "…",
            "departureDepositMode": "…",
            "departureDepositAmountTwd": "…",
            "departureDepositPercent": "…",
            "salesCloseAt": "…",
            "salesOpenAt": "…",
            "meetingTime": "…",
            "meetingPlace": "…",
            "agreementChangeDays": "…",
            "entryDateOffsetDays": "…",
            "requiredGuideCount": "…",
            "promoPriceTwd": "…",
            "promoAgencyPriceTwd": "…",
            "opAssignee": "…"
          },
          "existingTripDefaultAllocationMode": null,
          "warnings": [
            {
              "code": "agreement_change_days_missing",
              "message": "…"
            }
          ]
        }
      ],
      "summary": {
        "totalRows": 0,
        "newTripCount": 0,
        "appendDepartureCount": 0,
        "skipCount": 0,
        "errorCount": 0,
        "unsellableCount": 0
      },
      "fileError": "…",
      "columns": [
        {
          "index": 0,
          "header": "…",
          "key": "…",
          "target": null,
          "source": "alias",
          "writes": "agency_price_twd",
          "note": "…"
        }
      ]
    }
  }
}

/agencies

同業

GET/api/v1/agencies
agency.read

參數

status選填
enum
activearchived

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

owner選填
string

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

hasTaxId選填
enum
yesno

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

回應欄位 · data[]

id
string

同業 id(前綴 `agc_`)。

name
string

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

taxId
string | null

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

contactName
string | null

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

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

address
string | null

公司地址(未填 → null)。

paymentTerm
string | null

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

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

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

ownerName
string | null

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

status
"active" | "archived"

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

note
string | null

內部備註(未填 → null)。

orderCount
number

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

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/agencies" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}
POST/api/v1/agencies
agency.manage

參數

name必填
string· max 200 · min 1

同業公司名稱(B2B 旅行社或個人團主名稱)

taxId選填
string· max 32

統一編號(選填)

contactName選填
string· max 100

主要聯絡人姓名(選填)

phone選填
string· max 64

聯絡電話(選填)

email選填
string · email· max 200

聯絡 Email(選填;留空字串視為未填)

address選填
string· max 300

公司地址(選填)

paymentTerm選填
string· max 100

付款條件/帳期約定(選填,如月結 30 天)

ownerUserId選填
string· max 128

指派的負責業務使用者 ID(選填)

status選填
enum
activearchived

同業狀態(active 啟用中/archived 已封存;預設 active)

note選填
string· max 2000

內部備註(選填)

回應欄位 · data

id
string

新建立同業的 ID(agc_ 前綴)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/agencies" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

單一同業完整資料

GET/api/v1/agencies/{id}
agency.read

參數

id路徑
string· min 1

同業 ID

回應欄位 · data

id
string

同業 id(前綴 `agc_`)。

name
string

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

taxId
string | null

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

contactName
string | null

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

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

address
string | null

公司地址(未填 → null)。

paymentTerm
string | null

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

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

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

ownerName
string | null

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

status
"active" | "archived"

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

note
string | null

內部備註(未填 → null)。

orderCount
number

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

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/agencies/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
  }
}
PATCH/api/v1/agencies/{id}
agency.manage

參數

id路徑
string· min 1

要更新的同業 ID

name選填
string· max 200 · min 1

同業公司名稱(省略則不更動)

taxId選填
string· max 32

統一編號(省略則不更動)

contactName選填
string· max 100

主要聯絡人姓名(省略則不更動)

phone選填
string· max 64

聯絡電話(省略則不更動)

email選填
string · email· max 200

聯絡 Email(省略則不更動;空字串視為清空)

address選填
string· max 300

公司地址(省略則不更動)

paymentTerm選填
string· max 100

付款條件/帳期約定(省略則不更動)

ownerUserId選填
string· max 128

指派的負責業務使用者 ID(省略則不更動)

status選填
enum
activearchived

同業狀態(active 啟用中/archived 已封存;省略則不更動)

note選填
string· max 2000

內部備註(省略則不更動)

回應欄位 · data

ok
boolean

固定為 true:同業資料已更新。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/agencies/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "taxId": "example-taxId",
  "contactName": "example-contactName"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

上下架同業

POST/api/v1/agencies/{id}/status
agency.manage

參數

id路徑
string· min 1

同業 ID

status必填
enum
activearchived

目標狀態(active 上架啟用/archived 下架封存)

回應欄位 · data

ok
boolean

固定為 true:同業啟用/停用狀態已更新。

請求
curl -X POST "https://your-tenant.example.com/api/v1/agencies/<id>/status" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

負責業務指派候選清單

GET/api/v1/agencies/assignable-staff
agency.read

回應欄位 · data[]

userId
string

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

name
string

員工顯示名。

role
string

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

請求
curl -X GET "https://your-tenant.example.com/api/v1/agencies/assignable-staff" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "name": "…",
      "role": "…"
    }
  ]
}

同業名單匯出

GET/api/v1/agencies/export
agency.read

參數

status選填
enum
activearchived

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

owner選填
string

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

hasTaxId選填
enum
yesno

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

回應欄位 · data

rows
object[]

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

id
string

同業 id(前綴 `agc_`)。

name
string

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

taxId
string | null

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

contactName
string | null

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

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

address
string | null

公司地址(未填 → null)。

paymentTerm
string | null

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

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

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

ownerName
string | null

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

status
"active" | "archived"

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

note
string | null

內部備註(未填 → null)。

orderCount
number

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

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/agencies/export" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
      }
    ]
  }
}

/members

list/search the tenant customer

GET/api/v1/members
member.read

參數

q選填
string

關鍵字,模糊比對會員姓名、Email 或電話

county選填
string

縣市篩選,僅回傳通訊地址在該縣市的會員

year選填
string· 格式限定

加入年份(西元四位數),僅回傳該年註冊的會員

page選填
integer

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

pageSize選填
integer· max 200

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

回應欄位 · data

rows
object[]

當前頁的會員列。

userId
string

會員(顧客)的 user id。

email
string

會員 Email(登入帳號)。

name
string

會員姓名。

createdAt
string

會員註冊時間。

phone
string | null

聯絡電話(未填 → null)。

address
string | null

通訊地址(未填 → null)。

birthDate
string | null

生日 YYYY-MM-DD(未填 → null)。

orderCount
number

累計訂單數(含所有狀態與 kind)。

paidOrderCount
number

成交訂單數(未取消,且已付清或已完成)。

totalSpent
number

累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。

lastOrderAt
string | null

最後一筆訂單建立時間(無訂單 → null)。

pdpaSignedAt
string | null

最新版 PDPA 同意書簽署時間(未簽 → null)。

anonymizedAt
string | null

PDPA 匿名化時間;非空 = 已匿名化。

createdByUserId
string | null

後台代建者 user id(member-admin-create);null = 客戶自助註冊。

createdByName
string | null

代建者姓名(join `user`);自助註冊 → null。

total
number

符合篩選的會員總數。

page
number

當前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/members" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
  }
}
POST/api/v1/members
member.create

參數

email必填
string · email· max 120

會員登入 Email,也是啟用信的收件地址

name必填
string· max 100 · min 1

會員姓名

phone選填
string· max 40

聯絡電話(選填)

回應欄位 · data

userId
string

新建會員的使用者 ID。

email
string

正規化(小寫)後的登入 Email。

name
string

會員姓名。

activationSent
boolean

啟用信是否已送出請求;false 時請客戶在登入頁走「忘記密碼」取得設定密碼連結。

請求
curl -X POST "https://your-tenant.example.com/api/v1/members" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "userId": "…",
    "email": "…",
    "name": "…",
    "activationSent": true
  }
}

full member detail

GET/api/v1/members/{id}
member.read

參數

id路徑
string· min 1

會員(顧客)的使用者 ID

回應欄位 · data

profile
object

會員基本資料 + 訂單彙整。

userId
string

會員(顧客)的 user id。

email
string

會員 Email(登入帳號)。

name
string

會員姓名。

createdAt
string

會員註冊時間。

phone
string | null

聯絡電話(未填 → null)。

address
string | null

通訊地址(未填 → null)。

birthDate
string | null

生日 YYYY-MM-DD(未填 → null)。

orderCount
number

累計訂單數(含所有狀態與 kind)。

paidOrderCount
number

成交訂單數(未取消,且已付清或已完成)。

totalSpent
number

累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。

lastOrderAt
string | null

最後一筆訂單建立時間(無訂單 → null)。

pdpaSignedAt
string | null

最新版 PDPA 同意書簽署時間(未簽 → null)。

anonymizedAt
string | null

PDPA 匿名化時間;非空 = 已匿名化。

createdByUserId
string | null

後台代建者 user id(member-admin-create);null = 客戶自助註冊。

createdByName
string | null

代建者姓名(join `user`);自助註冊 → null。

orders
object[]

近期訂單列表(上限 50 筆,含 lodging)。

id
string

訂單 id。

orderNumber
string

人類可讀訂單編號。

status
string

金流模型 v2:deriveOrderDisplayStatus(booking/payment/refund) 派生的單一顯示狀態。

total
number

該會員所有訂單的應收總額(TWD 整數)。

createdAt
string

訂單建立時間。

tripTitle
string

行程 / 產品標題。

consents
object[]

已簽署的同意書紀錄(上限 50 筆)。

id
string

簽署紀錄 id。

kind
string

同意書類型:系統種類(pdpa / tour_agreement / cancellation_policy / refund_policy) 或租戶自訂種類的 id(`cnsk_…`)。

kindLabel
string | null

自訂種類的名稱;系統種類為 null。

travelerName
string | null

代簽時被代簽旅客的姓名(逐旅客的自訂同意書);本人簽署為 null。

version
number

簽署當下的範本版本號。

signedAt
string

簽署時間。

ipAddress
string | null

簽署時來源 IP(未記錄 → null)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/members/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
      }
    ]
  }
}

irreversible PDPA anonymization of one

POST/api/v1/members/{id}/anonymize
member.update

參數

id路徑
string· min 1

欲匿名化的會員(顧客)使用者 ID

reason選填
string

匿名化原因,記入稽核紀錄備查

回應欄位 · data

ok
boolean

固定為 true:會員個資已匿名化(PDPA 刪除權)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/members/<id>/anonymize" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

把官方 LINE 機器人蒐集的 LINE userId 綁到會員

PUT/api/v1/members/{id}/line-user-id
member.update

參數

id路徑
string· min 1

會員(顧客)使用者 ID

lineUserId必填
string· 格式限定

LINE userId:U 開頭加 32 碼小寫十六進位

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/members/<id>/line-user-id" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "lineUserId": "U0123456789abcdef0123456789abcdef"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

解除綁定

DELETE/api/v1/members/{id}/line-user-id
member.update

參數

id路徑
string· min 1

會員(顧客)使用者 ID

回應欄位 · data

ok
boolean
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/members/<id>/line-user-id" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

以 LINE userId 完整比對會員

GET/api/v1/members/by-line-user-id
member.read

參數

lineUserId必填
string· 格式限定

LINE userId:U 開頭加 32 碼小寫十六進位

請求
curl -X GET "https://your-tenant.example.com/api/v1/members/by-line-user-id?lineUserId=U0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": "…"
}

given a batch of member

GET/api/v1/members/expiry-warnings
member.read

參數

ids必填
string

以逗號分隔的會員使用者 ID 批次,上限 200 個,回傳其中護照即將到期者

回應欄位 · data

userIds
string[]

證件即將到期(或已過期)需提醒的會員 user id 清單。

請求
curl -X GET "https://your-tenant.example.com/api/v1/members/expiry-warnings?ids=example-ids" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "userIds": [
      "…"
    ]
  }
}

K 單訂購人 Email 的完整比對

GET/api/v1/members/lookup
order.create

參數

email必填
string· min 1

訂購人 Email,完整比對、不分大小寫

請求
curl -X GET "https://your-tenant.example.com/api/v1/members/lookup?email=customer%40example.com" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": "…"
}

member directory KPI cards

GET/api/v1/members/stats
member.read

回應欄位 · data

totalMembers
number

會員(顧客)總數(排除員工帳號)。

newThisMonth
number

本月新增會員數(自助 + 代建)。

newThisMonthStaffCreated
number

本月新增中由後台代建的數量(member-admin-create §4)。

staffCreated
number

累計由後台代建的會員數(`member_profiles.created_by_user_id IS NOT NULL`)。

withOrders
number

有下過訂單的會員數。

averageOrders
number

平均訂單數(只計有訂單者,避免零訂單稀釋)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/members/stats" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "totalMembers": 0,
    "newThisMonth": 0,
    "newThisMonthStaffCreated": 0,
    "staffCreated": 0,
    "withOrders": 0,
    "averageOrders": 0
  }
}

/orders

list/search/filter orders

GET/api/v1/orders
order.read

參數

status選填
string

依訂單顯示狀態篩選(如 pending、paid、cancelled)

assignment選填
string

依派發狀態篩選(如 unassigned、assigned)

rooming選填
string

依分房狀態篩選

dateFrom選填
string

出發日期區間起(格式 YYYY-MM-DD,含當日)

dateTo選填
string

出發日期區間迄(格式 YYYY-MM-DD,含當日)

q選填
string

關鍵字搜尋(訂單編號、訂購人姓名或 Email 等)

agencyId選填
string

依合作旅行社 ID 篩選(同業單)

page選填
integer

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

pageSize選填
integer· max 200

每頁筆數,上限 200

回應欄位 · data

rows
object[]

當前頁的訂單列(每筆商品明細一列)。

kind
"lodging" | "tour"
id
string

訂單 id(前綴 `ord_`)。

orderNumber
string

人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。

bookingState
string

預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。

paymentState
string

付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。

refundState
string

退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。

grossReceivableTwd
number

應收(TWD 整數,派生自應收分類帳)。

collectedTwd
number

收到現金(TWD 整數,派生)。

customerCashAppliedTwd
number

客戶現金淨套用(收款減已退現金,TWD 整數,派生)。

refundableCashTwd
number

可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。

outstandingTwd
number

未收(應收減客戶現金淨套用,TWD 整數,派生)。

partySize
number

參團人數(tour 訂單)。

createdAt
string

訂單建立時間。

notes
string | null

訂單備註(未填 → null)。

userId
string

下單客戶的 user id(同庫 user 表)。

userName
string

下單客戶顯示名。

userEmail
string

下單客戶 Email。

primaryTravelerName
string | null

主要旅客姓名(is_primary,未登記 → null)。

primaryTravelerPhone
string | null

主要旅客電話(未登記 → null)。

tripId
string

行程 id(tour 訂單經梯次反查;lodging 為空字串)。

tripTitle
string

行程 / 產品標題。

tripShortName
string | null

行程內部簡稱(issue 1414);未填或訂房訂單為 null。

tripSlug
string

行程 slug。

departureId
string

梯次 id(tour 訂單;lodging 為空字串)。

departureDate
string

出發日 YYYY-MM-DD(lodging 為入住日)。

returnDate
string

回程日 YYYY-MM-DD(lodging 為退房日)。

assignedToUserId
string | null

派發給哪位業務的 user id(未派發 → null)。

assigneeName
string | null

承辦業務顯示名(未派發 / 查無 → null)。

assignmentStatus
string

派發狀態:unassigned / assigned / reassigned / pending_review。

assignedAt
string | null

最近一次派發時間(未派發 → null)。

assignedByUserId
string | null

執行派發者的 user id(未派發 → null)。

createdByUserId
string | null

S5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.

pendingConsent
boolean

是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。

roomingStatus
"assigned" | "needs_single" | "registered" | "unregistered"

分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。

lotteryState
string | null

抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。

failoverFromOrderId
string | null

備案訂單所對應的原訂單 ID。

isOverdue
boolean

是否有已到期、尚未收齊的收款計畫。

total
number

符合篩選的訂單總數(DISTINCT 訂單,非列數)。

page
number

當前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/orders" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "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
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}

代客 K 單,手動建立一張 tour 訂單

POST/api/v1/orders
order.create模組:tour

參數

tripId必填
string· min 1

行程 ID

departureId必填
string· min 1

梯次 ID,決定佔位的出發團

primaryEmail必填
string· min 1

訂購人 Email,須對應已註冊會員

partySize必填
integer

報名人數,決定佔位數,須為 1 至 20 之間整數

travelers必填
array

旅客名單,筆數須與報名人數一致。每筆至少要有 fullName,一般後台證件可後補;受管制抽籤需 idNumber 或 passportNo,受限名額需 idNumber;birthDate 若給值須為存在的 YYYY-MM-DD 日期;climbingRecords 可代填該旅客的登山經歷(label 必填、gradeScore 0–20 僅存參考且不計分、climbedOn YYYY-MM-DD、hasAlpineExperience;每位最多 20 筆),掛在該旅客本人身上、不掛帳號,須啟用登山模組,否則回 403

paymentMethod必填
enum
cashatmmanual

收款方式:cash 現金、atm 轉帳、manual 人工

customerType選填
enum
directagency

客戶類型:direct 直客、agency 同業,預設直客

agencyId選填
string

同業 ID(agc_ 前綴),把這張單掛到該同業。只在 customerType=agency 時接受;須為啟用中的同業,否則回 422

paymentPlan選填
enum
fulldeposit

付款方案:full 全額、deposit 訂金,預設全額

receivingAccountId選填
string

收款帳戶 ID,指定本筆款項入帳的帳戶

discountCode選填
string

優惠碼;由建單流程驗證並套用折扣,無效時拒絕建單

notes選填
string

訂單備註

assigneeUserId選填
string

指定業績歸屬業務的使用者 ID,省略或等於自己則歸屬建單者;指定他人需具備訂單指派權限

allowDomesticTravelers選填
boolean

行程限外籍旅客時仍要建立:true 放行國籍空白或台灣的旅客,並留稽核紀錄。省略時這類旅客回 422

回應欄位 · data

orderId
string

新建立訂單的 ID(ord_ 前綴)。

orderNumber
string

訂單編號(租戶內流水序號,對外顯示用)。

retentionDeferred
boolean

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tripId": "example-tripId",
  "departureId": "example-departureId",
  "primaryEmail": "customer@example.com",
  "partySize": 1,
  "travelers": [
    {
      "fullName": "Example Traveler",
      "passportNo": "EX1234567"
    }
  ],
  "paymentMethod": "cash"
}'
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "orderNumber": "…",
    "retentionDeferred": true
  }
}

full kind-aware order detail

GET/api/v1/orders/{id}
order.read

參數

id路徑
string· min 1

訂單 ID

回應欄位 · data

participationVersion
number
departureChanges
object[]
id
string
participationVersion
number
actorName
string
reason
string
createdAt
string
snapshot
object
documents
object
agreementEnabled
boolean
versioningReady
boolean
agreementCount
number
agreementPending
number
agreementHistory
number
consents
object[]
label
string
version
number
pending
number
retained
number
due
boolean
passportExpiryWarnings
number
fingerprint
string
crossTrip選填
CrossTripChangeSnapshot | undefined
sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
price_twd
number | null
agency_price_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
promo_active
boolean | null
promo_price_twd
number | null
promo_agency_price_twd
number | null
trip
object
direct_price_twd
number | null
agency_price_twd
number | null
price_from_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
deposit_basis
DepositBasis | null

schema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。

unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

basis
"per_amount" | "per_travelers"
step
number

N:每幾位旅客 / 每滿幾元。

unitTwd
number

每次折多少(碼的折扣值)。

units
number

折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
selfService選填
SelfServiceChangeSnapshot | undefined
repricing
object

The target fare at its current price. Same shape as a cross-trip quote, without answers.

sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
trip
object
unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
fee
object
tier
CancellationFeeTier | null
daysBefore
number

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

feePercent選填
number | undefined

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

feeFixedTwd選填
number | undefined

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

amountTwd
number
description
string

charge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。

surplus
"keep_overpaid" | "refund_draft"
remitFeeTwd
number
lottery選填
LotteryChangeSnapshot | undefined
sourceMode
string
targetMode
string
stateBefore
string | null
stateAfter
"applied" | "won" | null

`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.

placement選填
true | undefined
failover選填
Omit<LotteryFailoverStep, "applicationKey"> | undefined

Set when the backup failover made the change. A general target confirms the seat (`won`).

skipped
object[]

Backup choices that the failover skipped before this one.

rank
number
departureId
string
reason
"identity_missing" | "not_same_trip" | "price_changed" | "roster_invalid" | "unavailable"
hitRank
number

Rank of the backup choice that this step tries.

remainingDepartureIds
string[]

Backup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.

applicationKeyBefore
string
applicationId選填
string | undefined

Set on confirmation: the new application uses the departure change ID.

legacyChain選填
LegacyChainNode[] | undefined
effectiveCreditTwd選填
number | undefined
policyTotalTwd選填
number | undefined
refundDrafts選填
{ id: string; orderId: string; amountTwd: number; }[] | undefined
participationVersion
number
equipment
object
blocked
boolean
rentals
object[]
rentalId
string
rentalCode
string
departureId
string | null
rentStartDate
string | null
rentEndDate
string | null
returnState
string
reconState
string
deliveredAt
string | null
depositClearedAt
string | null
rentTotalTwd
number
depositTotalTwd
number
depositBalanceTwddeprecated · 下一個版本移除
number
replacesRentalId
string | null
ready
boolean
blocker
string | null
lines
object[]
itemId
string
name
string | null
quantity
number
committedQuantity
number
paymentWindowStartedAt選填
string | undefined
sourceFingerprint
string
rosterFingerprint
string
source
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
target
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
arrangements選填
DepartureChangeArrangements | undefined
roomFeeBeforeTwd
number
roomFeeAfterTwd
number
otherRoomOrderCount
number
otherRoomFeeDeltaTwd
number
otherRefundDraftTwd
number
releasedRoomCount
number
releasedPretripStayCount
number
tasks
object[]
travelerId
string
kind
"pretrip_stay" | "room" | "survey"
label
string
fingerprint
string
totalTwd
number
unitPriceTwd
number
discountTwd
number
chargeLines
object[]
id
string
type
string
amount_twd
number
description
string
depositTwd
number
balanceTwd
number
balanceDueAt
string | null
receipts
object
blocked
boolean
receipts
object[]
id
string
merchantOrderNo
string
status
string
invoiceNumber
string | null
invoiceTransNo
string | null
submitted
boolean
operationPending
boolean
lastError
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
totalAmtTwd
number
updatedAt
string
resolution
"cancel_scheduled" | "invalidate" | "none" | "reconcile" | "reprepare"
target
object
tourName
string
tourNo
string | null
tourDate
string
totalAmtTwd
number
collectedTwd
number
returnedTwd
number
paidRefundFeesTwd
number
customerCashAppliedTwd
number
outstandingTwd
number
refundHeadroom
object
grossReceivableTwd
number

當前應收。

refundableCashTwd
number

可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。

assessedCancellationFeeTwd
number

此實收單保留的退改費;舊資料沿用人工核算基準。

openRefundGrossTwd
number

同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。

openRefundCount
number

同單其他未執行退款的張數。

openReceivableReductionTwd
number

同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。

carriedToLiveBackupsTwd
number

已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。

assessmentPending
boolean

人工核算單、退改費尚未核算。

baseTwd
number

額度基準 = 可退現金 − 上面三項扣減,下限 0。

overpaymentRefundTwd
number
depositOutstandingTwd
number
nextPaymentPurpose
"full" | "deposit" | "balance" | null
nextPaymentTwd
number
moneyFingerprint
string
refundDraftId選填
string | undefined
legacyChain
{ collectedTwd: number; returnedTwd: number; paidRefundFeesTwd: number; effectiveCreditTwd: number; refundableTwd: number; openRefundCount: number; nodes: { orderId: string; orderNumber: string; collectedTwd: number; returnedTwd: number; openRefundCount: number; }[]; } | null
collectedTwd
number
returnedTwd
number
paidRefundFeesTwd
number
effectiveCreditTwd
number
refundableTwd
number
openRefundCount
number
nodes
object[]
orderId
string
orderNumber
string
collectedTwd
number
returnedTwd
number
openRefundCount
number
arrangements
{ departureId: string; tasks: ArrangementTask[]; } | null

Current arrangement tasks after a departure change. Null means this order has no departure change.

departureId
string
tasks
object[]
travelerId
string
kind
"pretrip_stay" | "room" | "survey"
label
string
actions
object

訂單可行動作。每個動作是 `{ ok: true }`(部分動作另帶欄位,例:`cancel.path`、 `createRefund.headroom`)或 `{ ok: false, reason }`。`reason` 沿用對應寫入端點的 原因碼;`forbidden` 表示呼叫者沒有該動作的權限。

cancel
Availability<CancelBlockReason, { path: CancelPath; }>

`cancelOrder` / `cancelLodgingBooking` / `cancelFailoverChildOrder` / `cancelLotteryLostOrder`(依 `path`)。`lottery_lost` 的權限是 lottery.manage 加抽籤模組。

transferDeparture
Availability<DepartureChangeFailure, object>

General departure change with completed payment records. The selected target is checked during preview and confirmation.

adjust
Availability<"ORDER_TERMINAL", object>

掛帳 / 折讓 / 沖正(`applyManualAdjustment` / `reverseChargeLine`)。

editTravelers
TravelerEditAvailability

旅客新增 / 編輯 / 移除(`addTraveler` / `updateTraveler` / `removeTraveler`)。名單凍結中 回 `EDIT_WINDOW_CLOSED` 加 `rosterFreezeUnlockable: true`(見 `TravelerEditAvailability`)。

editRooming
Availability<"ORDER_TERMINAL", object>

分房需求登記(`updateRoomingPreference`)。

markPaid
Availability<ManualPaymentBlockReason, object>

手動登記收款(`markOrderManuallyPaid`)。`settled`:寫入端回冪等成功、不入帳。

balancePayment
Availability<BalanceGateReason, { remainingTwd: number; }>

補尾款連結 / 繳款單(`prepareBalancePayment`,可收分期的 `balance_link` 收款入口)。

balanceSlip
Availability<BalanceGateReason, { remainingTwd: number; }>

寄尾款繳款單(`sendBalanceSlipInTx`,可收分期的 `balance_slip` 收款入口)。訂金制同 `balancePayment`,全額單收全額列的餘額(issue 1522)。

payLink
Availability<BalanceGateReason, { remainingTwd: number; }>

自填金額付款連結(`issueOrderPayLink`,可收分期的 `pay_link` 收款入口,issue 1487)。已付訂金時同 `balancePayment`; 訂金未付時掛目前這一期,`remainingTwd` 是這一期的餘額。

createRefund
Availability<never, { headroom: RefundHeadroom; }>

建立退款。只看權限;金額上限與「為何是 0」在 `headroom`(`describeNoHeadroom`), 與建立 / 送審 / 標記已付三道 guard 讀同一份可退額度。

splitTraveler
Availability<SplitTravelerBlockReason, { otherDepartures: boolean; }>

拆出旅客(`splitTraveler`)。`otherDepartures`:能不能拆到別梯;整單不能換梯時只能同梯另開單。 名單凍結時拆到別梯要帶 `acknowledgeRosterFreeze: true`(見 `editTravelers.rosterFreezeUnlockable`)。旅客、款項與目標梯次的資格在寫入端鎖內重驗。

heldCashTransfer
Availability<HeldCashTransferBlockReason, object>

用保留款折抵,本單是轉入目標(`transferHeldCash`)。來源單在寫入端鎖內重驗。

reduceReceivable
Availability<ReduceReceivableBlockReason, object>

直接減少應收:折讓、沖正原始應收、跨行程換梯的負數調整(`assertDirectAdjustmentAllowed`)。 「折讓必須經核准」開啟時,沒有核准權的人回 `APPROVAL_REQUIRED`。

requestDiscount
Availability<never, object>

手動少收申請(`requestManualDiscount`)。

decideDiscount
Availability<"ORDER_TERMINAL", object>

核准或拒絕手動少收申請(`decideManualDiscount`)。核准權與 `canApproveAllowance` 同一條。

requestFeeWaiver
Availability<never, object>

申請減免退改費(`requestCancellationFeeWaiver`,#1621)。權限同建立退款單。

decideFeeWaiver
Availability<never, object>

核准或拒絕退改費減免。核准權同少收申請(`canApproveAllowance`+order.adjust)。

revokeReceipt
Availability<never, object>

撤銷或申請撤銷人工收款(`revokeManualReceipt` / `requestManualReceiptRevocation`)。只看權限, 不看這張單有沒有人工收款登記;逐筆的撤銷條件在寫入端。

submitRefund
Availability<never, object>

退款草稿送審(`submitRefund`)。退款單本身的狀態閘在寫入端。

cancelRefund
Availability<never, object>

退款草稿作廢(`cancelRefund`)。

approveRefund
Availability<never, object>

核准退款(`approveRefund`)。

rejectRefund
Availability<never, object>

駁回退款(`rejectRefund`)。

markRefundPaid
Availability<never, object>

標記退款已付與綠界刷退(`markRefundPaid`)。

assign
Availability<never, object>

派發:待審派發單走首次派發(`assignOrder`,order.assign),其他單走重派 (`reassignOrder`,order.reassign)。

updateOrder
Availability<never, object>

訂單層的其他更新(order.update):解除實名占用、代登登山紀錄、護照、同意書、 重寄信件、跨行程換梯報價。

reviewScreening
Availability<never, object>

審核登山資格(screening.review)。

manageAgreement
Availability<never, object>

管理旅遊契約(tour_agreement.manage)。

viewAgreementEvidence
Availability<never, object>

檢視旅遊契約簽署證據(tour_agreement.evidence)。

revealPii
Availability<never, object>

顯示證號全碼、檢視護照影本(order.reveal_pii)。

readConversation
Availability<never, object>

讀訂單對話(order_conversation.read)。

kind
"lodging" | "tour"

訂單種類(kind-agnostic 外殼)。'tour' 用既有 tour 區塊(梯次/分房/登山審核); 'lodging' 隱藏 tour-only 區、改顯示住宿 header(見 `lodging`)。共用的金流/旅客/ 派發/同意書區塊兩者皆 order-scoped 通用。

id
string

訂單 id(前綴 `ord_`)。

orderNumber
string

人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。

bookingState
string

預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。

paymentState
string

付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。

refundState
string

退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。

grossReceivableTwd
number

應收(TWD 整數,派生自應收分類帳)。

collectedTwd
number

收到現金(TWD 整數,派生)。

customerCashAppliedTwd
number

客戶現金淨套用(收款減已退現金,TWD 整數,派生)。

refundableCashTwd
number

可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。

outstandingTwd
number

未收(應收減客戶現金淨套用,TWD 整數,派生)。

partySize
number

參團人數(tour 訂單)。

createdAt
string

訂單建立時間。

notes
string | null

訂單備註(未填 → null)。

userId
string

下單客戶的 user id(同庫 user 表)。

userName
string

下單客戶顯示名。

userEmail
string

下單客戶 Email。

primaryTravelerName
string | null

主要旅客姓名(is_primary,未登記 → null)。

primaryTravelerPhone
string | null

主要旅客電話(未登記 → null)。

tripId
string

行程 id(tour 訂單經梯次反查;lodging 為空字串)。

tripTitle
string

行程 / 產品標題。

tripShortName
string | null

行程內部簡稱(issue 1414);未填或訂房訂單為 null。

tripSlug
string

行程 slug。

departureId
string

梯次 id(tour 訂單;lodging 為空字串)。

departureDate
string

出發日 YYYY-MM-DD(lodging 為入住日)。

returnDate
string

回程日 YYYY-MM-DD(lodging 為退房日)。

assignedToUserId
string | null

派發給哪位業務的 user id(未派發 → null)。

assigneeName
string | null

承辦業務顯示名(未派發 / 查無 → null)。

assignmentStatus
string

派發狀態:unassigned / assigned / reassigned / pending_review。

assignedAt
string | null

最近一次派發時間(未派發 → null)。

assignedByUserId
string | null

執行派發者的 user id(未派發 → null)。

createdByUserId
string | null

S5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.

pendingConsent
boolean

是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。

roomingStatus
"assigned" | "needs_single" | "registered" | "unregistered"

分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。

lotteryState
string | null

抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。

failoverFromOrderId
string | null

備案訂單所對應的原訂單 ID。

isOverdue
boolean

是否有已到期、尚未收齊的收款計畫。

cancellationFeeTwd
number | null

取消時公司留下的錢:退改費加上已付、不退的換梯手續費(customer-cancellation §8.9)。 NULL = 尚未核算,0 = 已核算且扣 0;兩者不可互換。

cancellationChangeFeeTwd
number | null

`cancellationFeeTwd` 裡屬於已付換梯手續費、不退的部分(customer-cancellation §8.9)。 退改費 = `cancellationFeeTwd` − 這筆。null = 沒有。

cancellationFeeWaivedTwd
number

已核准的退改費減免合計(#1621)。`cancellationFeeTwd` 已是減免後的數字。0 = 沒有減免。

staffNote
string | null

承辦備註(issue 1659,`orders.staff_note`)。只給後台;null = 沒有備註。

cancellationRefundPending
boolean
cancellationMoney
object

取消單現金與未執行退款摘要。

openRefundCount
number

未執行退款單張數。

openRefundAmountTwd
number

未執行退款單的實際退款金額合計。

openRefundAdminFeesTwd
number

未執行退款單的**行政手續費**合計(`refunds.admin_fee_twd`)。與匯款手續費分成兩欄,顯示面 才叫得出名字 —— 合併成一個「手續費」會把這筆行政費講成匯款費。

openRefundRemitFeesTwd
number

未執行退款單的**匯款手續費**合計(`refunds.remit_fee_twd`;spec 稱轉帳費,§3.4)。

retainedCashTwd
number

可退現金扣退改費;無未執行退款單且退改費已核算時,與保留款帳同口徑。

tripIsOverseas
boolean

行程是否出國(`trips.is_overseas`;lodging 為 false)。旅客編輯器據此顯示英文姓名 / 國籍欄(#459)。

tripCancellationFeeTiers
CancellationFeeTier[] | null

行程自己的退改階梯(`trips.cancellation_fee_tiers` 解析後);null = 未覆寫,沿用租戶預設。 實際生效的階梯由呼叫端用 `resolveFeeTiers` 合成,與取消時同一個優先順序。

agencyPaymentDueDate
string | null

客戶分類:同業單(`orders.agency_id`)帶同業名稱;直客單為 null。

agency
{ id: string; name: string; contactName: string | null; phone: string | null; consentConfirmed: { at: Date; byName: string | null; } | null; } | null
id
string
name
string
contactName
string | null

同業主檔的聯絡窗口(#1782)。訂單頁顯示「聯絡窗口」,訂購人不變。

phone
string | null
consentConfirmed
{ at: Date; byName: string | null; } | null

「同業已代為取得旅客同意」的勾選(#1479)。沒有勾選時為 null。

at
string
byName
string | null
departureLabel
string | null

梯次標籤 / 副標(issue 509 ①;lodging 為 null)。訂單頁的「梯次」欄接在日期後顯示。

lodging
AdminLodgingHeader | null

lodging 住宿 header(房型/住期/房數/人數);tour 為 null。

propertyName
string
propertySlug
string
roomTypeName
string
checkIn
string

入住日 YYYY-MM-DD。

checkOut
string

退房日 YYYY-MM-DD(不含當晚)。

units
number
guestCount
number
travelers
object[]

旅客名單(含 PII 遮罩欄;主要旅客排前)。

id
string

旅客 id(前綴 `trv_`)。

fullName
string

旅客姓名。

idNumberMask
string | null

遮罩碼(jsonb→mask,零解密);NULL = 未填。全碼走 reveal action(Task 7)。

passportNoMask
string | null

護照號碼遮罩碼(零解密);NULL = 未填。全碼走 order-scoped reveal。

birthDate
string | null

生日 YYYY-MM-DD(未填 → null)。

phone
string | null

聯絡電話(未填 → null)。

email
string | null

聯絡 Email(未填 → null)。

lineId
string | null

LINE ID(未填 → null)。明文。

lineDisplayName
string | null
englishName
string | null

英文姓名(#459,海外團;未填 → null)。明文,已 normalize 大寫。

nationality
string | null

國籍(#459,海外團;未填 → null)。明文。

passportExpiryDate
string | null

護照效期(#609,海外團;未填 → null)`YYYY-MM-DD`。明文 date 欄。

emergencyContactName
string | null

緊急聯絡人姓名(未填 → null)。

emergencyContactPhone
string | null

緊急聯絡人電話(未填 → null)。

isPrimary
boolean

是否為主要旅客(訂單聯絡人)。

gender
string | null

性別(分房硬約束 + 顯示):'male'|'female'|'other'|null。明文。

roomPreference
string | null

分房房型偏好(下單登記)。

roommatePref
string | null

指定房友 / 特殊需求自由文字。

diet
string | null

飲食需求(葷素)明文;null = 未填。非 PII,不走 reveal。

medicalNotes
string | null

醫療 / 過敏 / 病史備註明文;null = 未填。非 PII,不走 reveal。

address
string | null

通訊地址(未填 → null)。

roomLabel
string | null

團控已排房號的房間 label(null = 待團控分房)。

chargeLines
object[]

應收分類帳(itemized)。

id
string

應收明細列 id。

type
string

應收類型:base(原始價)/ room_upgrade(房升補款)/ adjustment / failover_deposit_credit 等。

amountTwd
number

金額(TWD 整數,signed;credit / 沖銷為負)。

description
string

明細說明文字。

sourceType
string

來源:system(系統派生)/ manual(人工登錄)等。

reversesChargeLineId
string | null

若為沖銷列,指向被沖銷的應收明細列 id(否則 null)。

createdByUserId
string | null

開立這筆費用列的使用者 id;系統派生或匯入列為 null。

createdAt
string

建立時間。

transactions
object[]

現金分類帳。

id
string

現金交易列 id。

direction
string

金流方向:in(收款)/ out(退款、扣款、沖銷)。

type
string

交易類型:payment / refund / chargeback / reversal。

amountTwd
number

交易金額(TWD 整數,正值)。

feeTwd
number

金流商手續費(TWD 整數)。

netTwd
number

淨額 = amount − fee(TWD 整數)。

provider
string

金流商:manual / ecpay / test 等。

providerTradeNo
string | null

金流商交易序號(manual 入帳可能為 null)。

merchantTradeNo
string | null

The merchant order reference of this transaction's payment attempt.

moneyReceiptId
string | null

Public receipt ID for a proven money-core binding. Unbound historical rows retain null.

refundId
string | null

若屬退款,指向 refunds 列 id(否則 null)。

bankReference
string | null

銀行參考號:手動收款是客人的匯款後五碼,退款是匯款憑證號(未填為 null)。

remittanceId
string | null

同源匯款關聯鍵:這列來自一筆拆到多張訂單的匯款時非 null,同一筆匯款的各列共用同一個值。

registrationId
string | null

登記收款的批次鍵(#1411):撤銷人工收款時,原收款與反向紀錄共用同一個值。

bankCreditedOn
string | null

入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填,其他為 null。

overTheCounter
boolean

臨櫃存款(沒有末五碼)。

receivingAccountName
string | null

收款帳戶顯示名稱(未歸戶為 null)。

transferCounterpartOrderId
string | null

保留款轉移(`type='transfer'`,issue 1407)的對方訂單:轉出列指向目標單,轉入列指向 來源單。其他列為 null。

transferCounterpartOrderNumber
string | null

對方訂單編號(同上)。

transferActorName
string | null

執行這次保留款轉移的員工名稱(取自稽核紀錄;其他列為 null)。

occurredAt
string

交易發生時間。

schedules
object[]

收款計畫(current + historical)。

id
string

收款計畫列 id。

purpose
string

用途:full(全額)/ deposit(訂金)/ balance(尾款)/ adjustment(補款)。

targetAmountTwd
number

應收目標金額(TWD 整數)。

status
string

計畫狀態:open(未收齊)/ satisfied(已收齊)。

appliedTwd
number

已套用到此列的現金(H3 唯一基準 `appliedCashForSchedule`;含 replaces 鏈)。

dueAt
string | null

到期日(null = 未設)。

sequence
number

排序序號(deposit → balance → adjustment)。

intents
object[]

付款意圖(+ 最新 attempt)。

id
string
purpose
string
amountTwd
number
status
string
scheduleId
string | null
invalidationReason
string | null

Reason for closing this checkout. departure_change permits a verified late payment.

invalidatedAmountTwd
number | null

Original checkout amount in TWD when the intent became invalid.

attemptProvider
string | null
attemptMethod
string | null
attemptStatus
string | null
bankCode
string | null
virtualAccount
string | null
payExpireAt
string | null
refunds
object[]

退款工作流。

id
string
refundNumber
string
status
"approved" | "cancelled" | "draft" | "failed" | "paid" | "processing" | "submitted"
refundKind
string
amountTwd
number
method
string
reason
string
createdAt
string
paidAt
string | null
executionMethod
string | null

執行方式:chargeback 刷退 / remit 匯出;未定為 null(customer-cancellation §3.4)。

gatewayExecutionMode選填
"manual" | "api" | undefined
remitFeeTwd
number

轉帳費(按單一次;remit 才有值)。承辦核放時可調降。

splitGroupId
string | null

拆單組(#1406):同一筆退款拆成刷退+匯款時,各張共用。null = 沒有拆單。

gatewayLocked
boolean

原路退刷 claim 已佔但無成功紀錄 = DoAction 結果不明,退款單被鎖住(mark-paid 一律 回 GATEWAY_IN_FLIGHT_OR_UNKNOWN)。判準取 clearRefundGatewayClaim 的 NOT_LOCKED 守衛 (別在 UI 端重刻)再加狀態閘:已 paid / cancelled 的殘留 claim 不該露出解鎖入口。

gatewayNeedsReview
boolean

近 90 天已完成帳務且明確記錄自動退刷降級,供對帳辨識;不提供重試入口。

payee
{ accountName: string | null; bankCode: string | null; branchCode: string | null; accountNumber: string | null; } | null

收款人四欄(匯款單才有值)。付款前承辦可改(issue 1698)。含完整帳號:`/api/v1` 對沒有 `refund.create` 權限的呼叫者回 null,和後台訂單頁的顯示條件相同。

accountName
string | null
bankCode
string | null
branchCode
string | null
accountNumber
string | null
consents
object[]
kind
string
kindLabel
string | null

自訂種類的名稱(#586);系統種類為 null,由畫面依 `kind` 查標籤。

version
number
signedAt
string
signerName
string | null

送出的帳號。逐旅客的自訂同意書是代簽人(訂購人)。

travelerName
string | null

被代簽旅客的姓名;訂單層簽署為 null。旅客列移除後也是 null(紀錄本身仍在)。

travelerId
string | null

被代簽旅客的 id(無 FK,旅客移除後仍保留作證據)。

ipAddress
string | null
auditLog
object[]
id
string
action
string
actorUserId
string | null
actorUserName
string | null
metadata
unknown
ipAddress
string | null
createdAt
string
orderDiscount
AdminOrderDiscountRow | null
codeSnapshot
string
originalTotalTwd
number
discountTwd
number
profitShareTwd
number
profitSharePayeeSnapshot
string | null
請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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,
                "depositBalanceTwd": 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
          },
          "overpaymentRefundTwd": 0,
          "depositOutstandingTwd": 0,
          "nextPaymentPurpose": "full",
          "nextPaymentTwd": 0,
          "moneyFingerprint": "…",
          "refundDraftId": "…"
        }
      }
    ],
    "legacyChain": "…",
    "arrangements": {
      "departureId": "dep_example",
      "tasks": [
        {
          "travelerId": "trv_example",
          "kind": "room",
          "label": "尚未分房,保留原房型與房友偏好"
        }
      ]
    },
    "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
      },
      "heldCashTransfer": {
        "ok": false,
        "reason": "over_outstanding"
      },
      "reduceReceivable": {
        "ok": false,
        "reason": "APPROVAL_REQUIRED"
      },
      "approveRefund": {
        "ok": false,
        "reason": "forbidden"
      }
    },
    "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,
    "cancellationFeeTwd": 0,
    "cancellationChangeFeeTwd": 0,
    "cancellationFeeWaivedTwd": 0,
    "staffNote": "…",
    "cancellationRefundPending": true,
    "cancellationMoney": {
      "openRefundCount": 0,
      "openRefundAmountTwd": 0,
      "openRefundAdminFeesTwd": 0,
      "openRefundRemitFeesTwd": 0,
      "retainedCashTwd": 0
    },
    "tripIsOverseas": true,
    "tripCancellationFeeTiers": null,
    "agencyPaymentDueDate": "…",
    "agency": "…",
    "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": "…",
        "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
  }
}

manual charge adjustment

POST/api/v1/orders/{id}/adjust
order.adjust

參數

id路徑
string· min 1

訂單 ID

kind必填
enum
surchargeallowance

調整類型:surcharge 加收、allowance 減免

amountTwd必填
integer

調整金額(新台幣,正整數)

description必填
string· min 1

調整事由說明

回應欄位 · data

ok
boolean

固定為 true:訂單金額調整已套用。

retentionDeferred
boolean

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/adjust" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "surcharge",
  "amountTwd": 1,
  "description": "example-description"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}

Use the canonical tenant operation.

GET/api/v1/orders/{id}/agreements
tour_agreement.manage

參數

id路徑
string· min 1

Resource ID

回應欄位 · data[]

id
string
orderId
string
departureId
string
departureDate
string

梯次出發日(ISO date);一張單多梯時用來標示這份契約屬哪一梯。

participationVersion選填
number | undefined
isCurrent選填
boolean | undefined
travelerId
string | null
travelerName
string | null
status
"pending" | "revoked" | "signed"
templateVersion
number
contractDate
string
providedAt
string
tokenExpiresAt
string
signedAt
string | null
signerName
string | null
signerIp
string | null
article32Agreed
boolean | null
signingPayload
Record<string, unknown> | null
evidenceSha256
string | null
contentSha256
string
hasPdf
boolean
deliveredAt
string | null
deliveryAddress
string | null
revokedAt
string | null
revokeReason
string | null
lastSyncedAt
string | null

sync 最後檢視時間(排程漂移訊號的基準)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/<id>/agreements" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…",
      "lastSyncedAt": "…"
    }
  ]
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/agreements/{agreementId}/reissue
tour_agreement.manage

參數

id路徑
string· min 1

Resource ID

agreementId路徑
string· min 1

Agreement ID

回應欄位 · data

ok
true
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/agreements/<agreementId>/reissue" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/agreements/{agreementId}/resend-copy
tour_agreement.manage

參數

id路徑
string· min 1

Resource ID

agreementId路徑
string· min 1

Agreement ID

回應欄位 · data

delivery
"failed" | "no_email" | "queued" | "sent"
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/agreements/<agreementId>/resend-copy" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "delivery": "failed"
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/agreements/{agreementId}/revoke
tour_agreement.manage

參數

id路徑
string· min 1

Resource ID

agreementId路徑
string· min 1

Agreement ID

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/agreements/<agreementId>/revoke" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/agreements/{agreementId}/sign-link
tour_agreement.manage

參數

id路徑
string· min 1

Resource ID

agreementId路徑
string· min 1

Agreement ID

回應欄位 · data

ok
true
url
string
expiresAt
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/agreements/<agreementId>/sign-link" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "url": "…",
    "expiresAt": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/agreements/generate
tour_agreement.manage

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

skipped
SyncSkipReason | null

整單層級略過原因;null = 有處理逐旅客。

issued
string[]
revoked
string[]
failures
object[]
travelerId
string
travelerName
string
reason
"missing_vars" | "no_email" | "unknown_vars"
vars
string[]
missingTemplateTypes
"domestic_group" | "domestic_individual" | "overseas_group" | "overseas_individual"[]

這張單上「行程類型對得到種類、但該種類沒有範本」的契約種類(#585)。非空 = 那些梯次 fail-closed 不產生,既有待簽列也已撤銷。呼叫端必須顯示,否則就成了第 6 種靜默失效。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/agreements/generate" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "skipped": null,
    "issued": [
      "…"
    ],
    "revoked": [
      "…"
    ],
    "failures": [
      {
        "travelerId": "…",
        "travelerName": "…",
        "reason": "missing_vars",
        "vars": [
          "…"
        ]
      }
    ],
    "missingTemplateTypes": [
      "domestic_group"
    ]
  }
}

首次派發訂單給承辦業務

POST/api/v1/orders/{id}/assign
order.assign模組:tour

參數

requestId必填
string· 格式限定

提交識別;重送同一提交時沿用此值

id路徑
string· min 1

訂單 ID

assigneeUserId必填
string· min 1

受派業務的使用者 ID

reason選填
string· max 500

派發事由說明(上限 500 字)

回應欄位 · data

ok
boolean

固定為 true:訂單已指派承辦。

idempotent
boolean

true = 原提交已完成,或受派者相同,本次沒有再次派發。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/assign" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "requestId": "2026-10-13",
  "assigneeUserId": "example-assigneeUserId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "idempotent": true
  }
}

Use the canonical tenant operation.

PUT/api/v1/orders/{id}/backup-choices
order.update模組:lottery

參數

id路徑
string· min 1

Resource ID

departureIds必填
array

Ordered backup departures

回應欄位 · data

ok
true
chosen
string[]
請求
curl -X PUT "https://your-tenant.example.com/api/v1/orders/<id>/backup-choices" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureIds": [
    "example-departureIds"
  ]
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "chosen": [
      "…"
    ]
  }
}

產生/重用尾款

POST/api/v1/orders/{id}/balance-link
order.update

參數

id路徑
string· min 1

訂單 ID

回應欄位 · data

ok
boolean

固定為 true:尾款付款連結已產生。

amountTwd
number

本次尾款金額(TWD 整數)。

scheduleId
string

對應的收款計畫 ID。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/balance-link" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "amountTwd": 0,
    "scheduleId": "…"
  }
}

cancel a tour order

POST/api/v1/orders/{id}/cancel
order.update

參數

id路徑
string· min 1

訂單 ID

reason選填
string

取消事由說明

cancellationReason選填
enum
admincustomer_requestno_showother

取消政策事由;新單與舊鏈使用相同政策

disposition選填
enum
refundkeep

可退款項的去向:refund 開退款草稿,keep 留在原單成為保留款。admin 不帶時為 keep(退改費記 0);customer_request 不帶時照舊退款;其他事由不可帶;舊鏈只能 refund

回應欄位 · data

ok
boolean

固定為 true:訂單已取消(座位釋出、booking_state 轉 cancelled)。

refunds
object[]
orderId
string
orderNumber
string
refundId
string
refundNumber
string
amountTwd
number
remitFeeTwd選填
number | undefined
retentionDeferred
boolean

true = 回訪來源尚未同步,每日排程會補做;取消本身已完成。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/cancel" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason",
  "cancellationReason": "admin",
  "disposition": "refund"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "refunds": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "refundId": "…",
        "refundNumber": "…",
        "amountTwd": 0,
        "remitFeeTwd": 0
      }
    ],
    "retentionDeferred": true
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/cancel-failover
order.update

參數

id路徑
string· min 1

Resource ID

reason選填
string

Cancellation reason

cancellationReason選填
enum
admincustomer_requestno_showother

取消政策事由;不因舊子單身分免收退改費

回應欄位 · data

ok
true
headOrderId
string

鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。

refunds
object[]

實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。

orderId
string
orderNumber
string
refundId
string
refundError
string | null

需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。

refundTotals
object

本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。

amountTwd
number
adminFeeTwd
number
remitFeeTwd
number
filingFee
FilingFeeBreakdown | null

逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。

totalTwd
number

逐旅客費率的加總。

lines
object[]

逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。

seq
number
feeTwd
number

這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。

travelerName
string | null

送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 null —— `traveler_id` 是不帶 FK 的快照 id,join 不到是合法狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/cancel-failover" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason",
  "cancellationReason": "customer_request"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "headOrderId": "…",
    "refunds": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "refundId": "…"
      }
    ],
    "refundError": "…",
    "refundTotals": {
      "amountTwd": 0,
      "adminFeeTwd": 0,
      "remitFeeTwd": 0
    },
    "filingFee": null
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/cancel-lottery-lost
lottery.manage模組:lottery

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
true
notified
"failed" | "no_recipient" | "no_template" | "sent" | "skipped"
headOrderId
string

鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。

refunds
object[]

實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。

orderId
string
orderNumber
string
refundId
string
refundError
string | null

需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。

refundTotals
object

本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。

amountTwd
number
adminFeeTwd
number
remitFeeTwd
number
filingFee
FilingFeeBreakdown | null

逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。

totalTwd
number

逐旅客費率的加總。

lines
object[]

逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。

seq
number
feeTwd
number

這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。

travelerName
string | null

送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 null —— `traveler_id` 是不帶 FK 的快照 id,join 不到是合法狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/cancel-lottery-lost" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "notified": "failed",
    "headOrderId": "…",
    "refunds": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "refundId": "…"
      }
    ],
    "refundError": "…",
    "refundTotals": {
      "amountTwd": 0,
      "adminFeeTwd": 0,
      "remitFeeTwd": 0
    },
    "filingFee": null
  }
}

業務自派搶單

POST/api/v1/orders/{id}/claim
order.claim

參數

id路徑
string· min 1

訂單 ID

回應欄位 · data

ok
boolean

固定為 true:訂單已由當前承辦認領。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/claim" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
GET/api/v1/orders/{id}/cross-trip-quote
order.update

參數

q選填
string· max 100

搜尋行程名稱、日期、梯次標籤或 ID;最多回傳 50 筆

id路徑
string· min 1

回應欄位 · data[]

departureId
string
label
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/<id>/cross-trip-quote" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "departureId": "…",
      "label": "…"
    }
  ]
}
POST/api/v1/orders/{id}/cross-trip-quote
order.update

參數

targetDepartureId必填
string· min 1
adjustment選填
object
id路徑
string· min 1

回應欄位 · data

quote
object
orderId
string
participationVersion
number
sourceVersion
string
quoteFingerprint
string
quotedAt
string
expiresAt
string
confirmationAvailable
boolean

True when this order can continue to the departure change preview.

source
object
departureId
string
tripId
string
title
string
date
string
target
object
departureId
string
tripId
string
title
string
date
string
priceChannel
"agency" | "direct"
priceSource
"departure" | "legacy" | "promo" | "trip"
partySize
number
originalFareTwd
number
targetFareTwd
number
originalDiscountTwd
number
targetDiscountTwd
number
originalProfitShareTwd
number
targetProfitShareTwd
number
discount
object
code
string | null
status
"applied" | "none" | "rejected"
reason
DiscountReason | null
existingLines
object[]
id
string
type
string
description
string
amountTwd
number
category
"adjustment" | "ancillary" | "discount" | "fare"
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null | undefined
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
originalReceivableTwd
number
targetReceivableTwd
number
differenceTwd
number
collectedTwd
number
returnedCashTwd
number
paidRefundFeesTwd
number
effectivePaidTwd
number
outstandingTwd
number
refundableTwd
number
overpaymentRefundTwd
number
depositTargetTwd
number
depositOutstandingTwd
number
balanceOutstandingTwd
number
depositDueAt
string | null
balanceDueAt
string | null

Null when the target is a lottery departure: the due date is set at the win.

tasks
string[]
blockers
string[]
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/cross-trip-quote" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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": [
        "…"
      ]
    }
  }
}
POST/api/v1/orders/{id}/departure-change-equipment
order.update模組:climbing

參數

rentalId必填
string· min 1
targetDepartureId必填
string· min 1
participationVersion必填
integer
mode必填
enum
releaserebook
reason必填
string· max 500 · min 1
rentStartDate選填
string
rentEndDate選填
string
lines選填
array· max 100 · min 1
id路徑
string· min 1

Order ID

回應欄位 · data

replacementRentalId
string | null

新建的替代租借單 ID;釋出時為 null。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/departure-change-equipment" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rentalId": "example-rentalId",
  "targetDepartureId": "example-targetDepartureId",
  "participationVersion": 1,
  "mode": "release",
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "replacementRentalId": "…",
    "retentionDeferred": true
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/force-place
lottery.manage模組:lottery

參數

id路徑
string· min 1

Resource ID

targetDepartureId必填
string· min 1

Target departure ID

回應欄位 · data

retentionDeferred
boolean

true = 回訪來源或期間尚未同步,每日排程會補做;安置本身已完成。

ok
true
orderId
string
departureChangeId
string
backupOrderIddeprecated · 下一個版本移除
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/force-place" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "targetDepartureId": "example-targetDepartureId"
}'
回應
{
  "ok": true,
  "data": {
    "retentionDeferred": true,
    "ok": "…",
    "orderId": "…",
    "departureChangeId": "…",
    "backupOrderId": "…"
  }
}

線控手動抽籤裁決:won

POST/api/v1/orders/{id}/lottery/resolve
lottery.manage

參數

id路徑
string· min 1

訂單 ID

outcome必填
enum
wonlost

抽籤裁決結果:won 中籤確認、lost 未中籤(啟動備案或取消)

applicationKey選填
string· max 200 · min 1

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).

回應欄位 · data

ok
boolean

固定為 true:抽籤結果已登錄。

outcome
"lost" | "won"

抽籤結果:won 中籤 / lost 未中籤。

balanceNotice
LotteryWonBalanceNotice | null

中籤後的尾款通知(lost 為 null):sent 已寄出、already_sent 之前寄過、 not_eligible 沒有待收尾款、no_template 租戶沒有啟用中的收尾款範本、 no_recipient 沒有收件人(同業單或訂購人沒有 email)、failed 寄送失敗。

retentionDeferred
boolean

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/lottery/resolve" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "won"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "outcome": "lost",
    "balanceNotice": null,
    "retentionDeferred": true
  }
}
POST/api/v1/orders/{id}/mark-paid
payment.update

參數

id路徑
string· min 1

訂單 ID

amountTwd選填
integer

本次收款金額,TWD 正整數;省略則結清全部待收餘額

idempotencyKey選填
string· 格式限定

收款冪等鍵,8 至 64 字英數或連字號;重送同鍵不重複入帳

bankReference選填
string· max 40

匯款後五碼或銀行交易參考號,上限 40 字

providerTradeNo選填
string· max 40

金流訂單編號;收款帳戶是第三方金流時必填

bankCreditedOn選填
string

入帳日期 YYYY-MM-DD;收款帳戶是銀行時必填

overTheCounter選填
boolean

臨櫃存款;銀行帳戶勾選後免填匯款後五碼

note選填
string

對帳備註,記錄人工核款說明

receivingAccountId必填
string· min 1

收款帳戶 ID,指定本筆款項入帳的帳戶

回應欄位 · data

idempotent
boolean

true = 此請求已入帳或訂單已結清,本次未重複入帳。

collectedTwd
number

本次入帳金額;冪等重送為 0。

customerCashAppliedTwd
number

入帳後已收現金淨額。

outstandingTwd
number

入帳後待收餘額。

paymentState
"deposit_paid" | "overpaid" | "paid" | "partially_paid" | "unpaid"

入帳後付款狀態。

retentionDeferred
boolean

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/mark-paid" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "receivingAccountId": "example-receivingAccountId"
}'
回應
{
  "ok": true,
  "data": {
    "idempotent": true,
    "collectedTwd": 0,
    "customerCashAppliedTwd": 0,
    "outstandingTwd": 0,
    "paymentState": "deposit_paid",
    "retentionDeferred": true
  }
}

某罐頭範本代入本訂單變數後的

GET/api/v1/orders/{id}/message-preview
order.read

參數

id路徑
string· min 1

訂單 ID

templateId必填
string· min 1

訊息範本 ID(line 或 email 通道皆可)

回應欄位 · data

channel
string

範本通道:line 或 email。

subject
string

代入本訂單變數後的標題(email 為信件主旨)。

body
string

代入本訂單變數後的內文。

missingVars
string[]

範本引用但本訂單沒有值的變數名;成品裡仍是 `{{變數}}` 原樣,貼出前要手動處理。

請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/<id>/message-preview?templateId=example-templateId" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "channel": "…",
    "subject": "…",
    "body": "…",
    "missingVars": [
      "…"
    ]
  }
}

重新指派已派發訂單

POST/api/v1/orders/{id}/reassign
order.reassign模組:tour

參數

requestId必填
string· 格式限定

提交識別;重送同一提交時沿用此值

id路徑
string· min 1

訂單 ID

assigneeUserId必填
string· min 1

重新指派的承接業務使用者 ID

reason選填
string· max 500

重派事由說明(上限 500 字)

回應欄位 · data

ok
boolean

固定為 true:訂單已改派承辦。

idempotent
boolean

true = 原提交已完成,或受派者相同,本次沒有再次派發。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/reassign" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "requestId": "2026-10-13",
  "assigneeUserId": "example-assigneeUserId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "idempotent": true
  }
}

create + submit a customer refund

POST/api/v1/orders/{id}/refunds
refund.create

參數

creationSource選填
enum
manualheld_cash

Creation source; held cash requires server verification

id路徑
string· min 1

訂單 ID

refundKind必填
enum
receivable_reductionoverpayment_return

退款種類:receivable_reduction 一般退款、overpayment_return 多付退回

reason必填
string· min 1

退款事由說明

amountTwd必填
integer

退款總金額(新台幣,正整數)

executionMethod選填
enum
chargebackremit

退款執行方式:chargeback 原路退刷、remit 銀行匯款

originAccountId選填
string

出款來源帳戶 ID(匯款退款時指定)

adminFeeTwd選填
integer

手續費/行政費(新台幣,非負整數)

remitFeeTwd選填
integer

匯款轉帳費(新台幣,非負整數)

payeeAccountName選填
string

受款人戶名(匯款退款時選填)

payeeBankCode選填
string

受款銀行代碼(匯款退款時填寫)

payeeBranchCode選填
string· 格式限定

受款分行代碼(匯款退款時選填,4 碼數字;須存在於銀行/分行對照表,否則回 409 查無此分行)

payeeAccountNumber選填
string

受款銀行帳號(匯款退款時填寫)

lines選填
array

退款明細列;省略時依退款總額處理

回應欄位 · data

id
string

退款單 id(前綴 `rfnd_`)。

refundNumber
string

人類可讀退款單號。

status
"approved" | "cancelled" | "draft" | "failed" | "paid" | "processing" | "submitted"

退款工作流狀態:draft → submitted → approved → processing → paid。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/refunds" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "refundKind": "receivable_reduction",
  "reason": "example-reason",
  "amountTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "refundNumber": "…",
    "status": "approved"
  }
}

approve a submitted

POST/api/v1/orders/{id}/refunds/{refundId}/approve
refund.approve

參數

id路徑
string· min 1

訂單 ID(path)

refundId路徑
string· min 1

退款單 ID

回應欄位 · data

ok
boolean

固定為 true:退款申請已核准。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/refunds/<refundId>/approve" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

取消待執行的退款單

POST/api/v1/orders/{id}/refunds/{refundId}/cancel
refund.approve | refund.mark_paid

參數

id路徑
string· min 1

訂單 ID(path)

refundId路徑
string· min 1

退款單 ID

reason必填
string· max 500 · min 1

取消原因(必填,寫進稽核日誌)

remitNotSentVerified選填
boolean

已確認這筆匯款沒有送出銀行轉帳,或銀行已退件(取消已核准的匯款單時必填 true)

gatewayNoApplicationVerified選填
boolean

已確認金流商沒有受理申請、處理中或已完成的退款(取消已核准的人工刷退時必填 true)

回應欄位 · data

ok
boolean

固定為 true:退款單已取消(拆單組一起),可退額度回到訂單。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/refunds/<refundId>/cancel" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

解除原路退刷的 in-flight 鎖定

POST/api/v1/orders/{id}/refunds/{refundId}/clear-gateway-claim
refund.mark_paid

參數

id路徑
string· min 1

訂單 ID(path)

refundId路徑
string· min 1

退款單 ID

note必填
string· max 500 · min 1

查證依據(必填,寫進稽核日誌)

回應欄位 · data

ok
boolean

固定為 true:退刷鎖定已解除,退款單可重新標記已退(會再送一次退刷)。執行方式建單後 不可改,要改走人工匯款得另建一張 remit 退款單。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/refunds/<refundId>/clear-gateway-claim" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "example-note"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
POST/api/v1/orders/{id}/refunds/{refundId}/mark-paid
refund.mark_paid

參數

id路徑
string· min 1

訂單 ID(path)

refundId路徑
string· min 1

退款單 ID

receiptId選填
string

原路退刷必填:公開金流核心的原信用卡收款 ID

allocations選填
array· max 50 · min 1

首次送出時固定跨商卡款分配;總額必須等於退款金額

retryOf選填
string

重試時填已確認安全失敗的前次執行 ID

bankReference選填
string

出款的銀行交易參考號(匯款憑證)

receivingAccountId選填
string

出款帳戶 ID;remit 退款須指定具匯款能力的帳戶

remitFeeTwd選填
integer· min 0

核放時調降的匯款手續費(只能調降;差額回到退款金額)

回應欄位 · data

ok
boolean

指令已處理;pending 或 unknown 不代表已退款。

gateway
"downgraded" | "not_applicable" | "pending" | "skipped_no_charge" | "succeeded" | "unknown"

pending:已受理;unknown:結果不明;succeeded:已確認個別退款;not_applicable:非刷退或既有已付紀錄。

skipReason
RefundGatewaySkipReason | null

新執行不降級記帳;此相容欄位為 null。

providerRefundNo
string | null

已確認的個別退款編號;未完成時為 null。

retentionDeferred
boolean

true = 回訪來源尚未同步,每日排程會補做;退款帳務本身已完成。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/refunds/<refundId>/mark-paid" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "receiptId": "example-receiptId",
  "allocations": [
    {
      "receiptId": "example-receiptId",
      "amountTwd": 1
    }
  ],
  "retryOf": "example-retryOf"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "gateway": "downgraded",
    "skipReason": null,
    "providerRefundNo": "…",
    "retentionDeferred": true
  }
}

reject a submitted

POST/api/v1/orders/{id}/refunds/{refundId}/reject
refund.reject

參數

id路徑
string· min 1

訂單 ID(path)

refundId路徑
string· min 1

退款單 ID

reason選填
string

退件事由說明

回應欄位 · data

ok
boolean

固定為 true:退款申請已駁回。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/refunds/<refundId>/reject" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/release-identity-hold
order.update

參數

id路徑
string· min 1

Resource ID

reason必填
string· min 1

Required release reason

回應欄位 · data

ok
true
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/release-identity-hold" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
POST/api/v1/orders/{id}/resolve-screening-follow-up
screening.review模組:climbing

參數

id路徑
string· min 1

訂單 ID

回應欄位 · data

ok
boolean

固定 true:本單的待回覆審核追蹤已完成。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/resolve-screening-follow-up" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

reverse an existing charge line

POST/api/v1/orders/{id}/reverse
order.adjust

參數

id路徑
string· min 1

訂單 ID

chargeLineId必填
string· min 1

欲沖正的應收項目(charge line)ID

description必填
string· min 1

沖正事由說明

回應欄位 · data

ok
boolean

固定為 true:訂單已沖銷(沖回應收與已認列項)。

retentionDeferred
boolean

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

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/reverse" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chargeLineId": "example-chargeLineId",
  "description": "example-description"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}
POST/api/v1/orders/{id}/review-screening
screening.review模組:climbing

參數

id路徑
string· min 1

訂單 ID

decision必填
enum
approvereject

登山資格審核裁決:approve 核可、reject 駁回

travelerId選填
string· min 1

只裁決這一位旅客;省略 = 該單所有待審旅客一起裁決

disposition選填
enum
resupplementswitch_triprefund

駁回必填:resupplement 補件、switch_trip 換團、refund 退費;不自動取消或退款

templateId選填
string· min 1

駁回後寄送的訊息範本 ID;省略不寄信,寄信失敗不回滾駁回

note選填
string· max 500

審核註記說明(上限 500 字)

redecide選填
boolean

重新裁決一列正在漂移的已人工裁決紀錄(需指名 travelerId);預設 false

回應欄位 · data

ok
boolean

固定為 true:名單複核結果已登錄。

followUpState
unknown

處置後追蹤狀態;退費或核可為 null。

emailSent
boolean

通知已加入寄送佇列;false 包含未選範本或寄送失敗。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/review-screening" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "approve"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "followUpState": "…",
    "emailSent": true
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/send-balance-slip
order.update

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
true
emailSent
boolean

True when this call adds a queue entry. Delivery is still pending.

outcome
"already_sent" | "no_recipient" | "no_template" | "queued"

The queue result for this request.

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/send-balance-slip" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "emailSent": true,
    "outcome": "queued"
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/{id}/send-message
order.update

參數

id路徑
string· min 1

Resource ID

templateId必填
string· min 1

Email template ID

回應欄位 · data

ok
true
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/send-message" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "templateId": "example-templateId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
POST/api/v1/orders/{id}/settle-cancellation
refund.create

參數

id路徑
string· min 1

訂單 ID

deductionTwd必填
integer· max 2147483647

人工核算扣除額(新台幣,非負整數)

reason必填
string· max 1000 · min 1

實際損害核算依據

回應欄位 · data

refundId
string | null
refundNumber
string | null
deductionTwd
number
idempotent
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/settle-cancellation" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "deductionTwd": 1,
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "refundId": "…",
    "refundNumber": "…",
    "deductionTwd": 0,
    "idempotent": true
  }
}

Preview or confirm a traveler split

POST/api/v1/orders/{id}/split-traveler
order.update

參數

id路徑
string· min 1

Resource ID

travelerId必填
string· min 1

Traveler to move to the new order

targetDepartureId選填
string· min 1

Departure of the new order on the same trip. Omit to keep the same departure

transferTwd選填
integer· min 0

Paid amount to move to the new order. Omit to split the paid amount by receivable. Send the same value on preview and confirm

mode選填
enum
previewconfirm

Preview before confirmation

previewToken選填
string

Token from the preview response

requestId選填
string· max 200

Stable request ID for retries

reason選填
string· max 1000

Split reason

acknowledgeRosterFreeze選填
boolean

Staff confirms the roster freeze (6 days or less before departure). Needed only for another target departure. Without it the split answers edit_window_closed. Send the same value on preview and confirm

回應欄位 · data

ok
true
orderId
string
preview選填
TravelerSplitPreview | undefined

Present after a preview. Send its previewToken on the confirmation.

previewToken
string
sourceOrderId
string
travelerId
string
travelerName
string
sourceDepartureId
string
targetDepartureId
string
sameDeparture
boolean
unitPriceTwd
number
money
object
sourceReceivableBeforeTwd
number
sourceReceivableAfterTwd
number
newReceivableTwd
number
suggestedTransferTwd
number

系統建議值:依應收比例分配原單的有效已付款(§3.5)。

maxTransferTwd
number
transferTwd
number
transferOverridden
boolean
sourceOverpaymentTwd
number

拆出後原單多收、要開溢收退款草稿的金額。

keptOnSourceTwd
object

留在原單、不分攤的折扣、人工調整與房型升等合計(§6 M2)。

discountTwd
number
adjustmentTwd
number
roomUpgradeTwd
number
newOrderSchedules
object
firstPurpose
"deposit" | "full"
depositTwd
number
balanceTwd
number
depositOutstandingTwd
number
nextPurpose
"full" | "deposit" | "balance" | null
nextTwd
number
newOrderBalanceDueAt
string | null
clears
object

這位旅客目前在分房、同行組裡;拆出後清空。

room
boolean
companionGroup
boolean
newOrderId選填
string | undefined
newOrderNumber選填
string | undefined
splitId選填
string | undefined
transferTwd選填
number | undefined
refundDraftId選填
string | null | undefined

Overpayment refund draft on the source order. null = no overpayment.

idempotent選填
boolean | undefined

true = a retry of a completed request.

departureChange選填
{ ok: true; departureChangeId: string; } | { ok: false; reason: DepartureChangeFailure; } | undefined

The departure change of the new order, for another target departure. On failure the split stays done and the new order stays on the source departure.

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/split-traveler" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "travelerId": "example-travelerId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "orderId": "…",
    "preview": "…",
    "newOrderId": "…",
    "newOrderNumber": "…",
    "splitId": "…",
    "transferTwd": 0,
    "refundDraftId": "…",
    "idempotent": true,
    "departureChange": "…"
  }
}

Preview or confirm an in-place departure change.

POST/api/v1/orders/{id}/transfer-departure
order.update

參數

id路徑
string· min 1

Resource ID

targetDepartureId必填
string· min 1

Target departure ID

mode選填
enum
previewconfirm

Preview before confirmation

previewToken選填
string

Token from the preview response

requestId選填
string· max 200

Stable request ID for retries

reason選填
string· max 1000

Departure change reason

crossTrip選填
boolean

Set true for a target on another trip. Without it, the target must be on the same trip

adjustment選填
object

Cross-trip manual adjustment. A nonzero amount needs order.adjust. When the tenant requires allowance approval, a non-admin gets 409 for a negative amount. Send the same terms on preview and confirm

回應欄位 · data

ok
true
orderId
string
departureChangeId選填
string | undefined
backupOrderId選填deprecated · 下一個版本移除
string | undefined
preview選填
DepartureChangePreview | undefined

Includes current document requirements, retained consents, and passport expiry warnings.

arrangements
object
roomFeeBeforeTwd
number
roomFeeAfterTwd
number
otherRoomOrderCount
number
otherRoomFeeDeltaTwd
number
otherRefundDraftTwd
number
releasedRoomCount
number
releasedPretripStayCount
number
tasks
object[]
travelerId
string
kind
"pretrip_stay" | "room" | "survey"
label
string
fingerprint
string
previewToken
string
paymentWindowHours
number | null
expiresAt
string
documents
object
agreementEnabled
boolean
versioningReady
boolean
agreementCount
number
agreementPending
number
agreementHistory
number
consents
object[]
label
string
version
number
pending
number
retained
number
due
boolean
passportExpiryWarnings
number
fingerprint
string
crossTrip選填
CrossTripChangeSnapshot | undefined
sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
price_twd
number | null
agency_price_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
promo_active
boolean | null
promo_price_twd
number | null
promo_agency_price_twd
number | null
trip
object
direct_price_twd
number | null
agency_price_twd
number | null
price_from_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
deposit_basis
DepositBasis | null

schema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。

unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

basis
"per_amount" | "per_travelers"
step
number

N:每幾位旅客 / 每滿幾元。

unitTwd
number

每次折多少(碼的折扣值)。

units
number

折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
selfService選填
SelfServiceChangeSnapshot | undefined
repricing
object

The target fare at its current price. Same shape as a cross-trip quote, without answers.

sourceTripId
string
sourceTitle
string
targetTripId
string
targetTitle
string
priceChannel
string
priceSource
"departure" | "legacy" | "promo" | "trip"
pricing
object
departure
object
price_twd
number | null
agency_price_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
promo_active
boolean | null
promo_price_twd
number | null
promo_agency_price_twd
number | null
trip
object
direct_price_twd
number | null
agency_price_twd
number | null
price_from_twd
number | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
deposit_basis
DepositBasis | null

schema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。

unitPriceTwd
number
fareBeforeTwd
number
fareAfterTwd
number
adjustment
{ kind: "price_hold" | "negotiation" | "change_fee"; amountTwd: number; reason: string; } | null
kind
"change_fee" | "negotiation" | "price_hold"
amountTwd
number
reason
string
discount
CrossTripDiscount | null

The current code checked again for the target. null = the order has no current code.

orderDiscountId
string
discountCodeId
string | null
code
string
status
"applied" | "released"

applied = the order keeps the code. released = the order leaves it.

reason
DiscountReason | null
originalTotalTwd
number

Target fare that the discount is calculated from.

discountBeforeTwd
number
discountAfterTwd
number
calcAfter
DiscountCalc | null

重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。

basis
"per_amount" | "per_travelers"
step
number

N:每幾位旅客 / 每滿幾元。

unitTwd
number

每次折多少(碼的折扣值)。

units
number

折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。

profitShareBeforeTwd
number
profitShareAfterTwd
number
profitSharePayee
string | null
profitSharePayeeBeforeSnapshot
string | null
profitShareBilled
boolean

A profit share payable already covers this discount.

profitSharePaid
boolean

That payable is paid, so staff cannot cancel it.

discountLinesTwd
number

Open code discount lines that the change reverses, as a positive amount.

climbingActive
boolean
screenings
object[]

Source decisions. The target never inherits manual approvals or rejections.

id
string
traveler_id
string | null
verdict
string
reviewed_by_user_id
string | null
review_note
string | null
reviewed_at
string | null
disposition
string | null
disposition_note
string | null
follow_up_state
string | null
surveyAnswers
object[]

Source answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.

id
string
traveler_id
string
question_id
string
question_label
string
option_id
string | null
option_label_snapshot
string | null
quantity
number | null
text_value
string | null
fee
object
tier
CancellationFeeTier | null
daysBefore
number

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

feePercent選填
number | undefined

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

feeFixedTwd選填
number | undefined

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

amountTwd
number
description
string

charge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。

surplus
"keep_overpaid" | "refund_draft"
remitFeeTwd
number
lottery選填
LotteryChangeSnapshot | undefined
sourceMode
string
targetMode
string
stateBefore
string | null
stateAfter
"applied" | "won" | null

`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.

placement選填
true | undefined
failover選填
Omit<LotteryFailoverStep, "applicationKey"> | undefined

Set when the backup failover made the change. A general target confirms the seat (`won`).

skipped
object[]

Backup choices that the failover skipped before this one.

rank
number
departureId
string
reason
"identity_missing" | "not_same_trip" | "price_changed" | "roster_invalid" | "unavailable"
hitRank
number

Rank of the backup choice that this step tries.

remainingDepartureIds
string[]

Backup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.

applicationKeyBefore
string
applicationId選填
string | undefined

Set on confirmation: the new application uses the departure change ID.

legacyChain選填
LegacyChainNode[] | undefined
effectiveCreditTwd選填
number | undefined
policyTotalTwd選填
number | undefined
refundDrafts選填
{ id: string; orderId: string; amountTwd: number; }[] | undefined
participationVersion
number
equipment
object
blocked
boolean
rentals
object[]
rentalId
string
rentalCode
string
departureId
string | null
rentStartDate
string | null
rentEndDate
string | null
returnState
string
reconState
string
deliveredAt
string | null
depositClearedAt
string | null
rentTotalTwd
number
depositTotalTwd
number
depositBalanceTwddeprecated · 下一個版本移除
number
replacesRentalId
string | null
ready
boolean
blocker
string | null
lines
object[]
itemId
string
name
string | null
quantity
number
committedQuantity
number
paymentWindowStartedAt選填
string | undefined
sourceFingerprint
string
rosterFingerprint
string
source
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
target
object
id
string
trip_id
string
departure_date
string
return_date
string
status
string
allocation_mode
string
price_twd
number
label
string | null
deposit_mode
DepositMode | null
deposit_amount_twd
number | null
deposit_percent
number | null
totalTwd
number
unitPriceTwd
number
discountTwd
number
chargeLines
object[]
id
string
type
string
amount_twd
number
description
string
depositTwd
number
balanceTwd
number
balanceDueAt
string | null
receipts
object
blocked
boolean
receipts
object[]
id
string
merchantOrderNo
string
status
string
invoiceNumber
string | null
invoiceTransNo
string | null
submitted
boolean
operationPending
boolean
lastError
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
totalAmtTwd
number
updatedAt
string
resolution
"cancel_scheduled" | "invalidate" | "none" | "reconcile" | "reprepare"
target
object
tourName
string
tourNo
string | null
tourDate
string
totalAmtTwd
number
collectedTwd
number
returnedTwd
number
paidRefundFeesTwd
number
customerCashAppliedTwd
number
outstandingTwd
number
refundHeadroom
object
grossReceivableTwd
number

當前應收。

refundableCashTwd
number

可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。

assessedCancellationFeeTwd
number

此實收單保留的退改費;舊資料沿用人工核算基準。

openRefundGrossTwd
number

同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。

openRefundCount
number

同單其他未執行退款的張數。

openReceivableReductionTwd
number

同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。

carriedToLiveBackupsTwd
number

已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。

assessmentPending
boolean

人工核算單、退改費尚未核算。

baseTwd
number

額度基準 = 可退現金 − 上面三項扣減,下限 0。

overpaymentRefundTwd
number
depositOutstandingTwd
number
nextPaymentPurpose
"full" | "deposit" | "balance" | null
nextPaymentTwd
number
moneyFingerprint
string
refundDraftId選填
string | undefined
retentionDeferred選填
boolean | undefined

true = 回訪期間尚未同步,每日排程會補做;換梯本身已完成。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/transfer-departure" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "targetDepartureId": "example-targetDepartureId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "orderId": "…",
    "departureChangeId": "…",
    "backupOrderId": "…",
    "preview": "…",
    "retentionDeferred": true
  }
}

新增旅客到訂單

POST/api/v1/orders/{id}/travelers
order.update

參數

fullName選填
string· min 1

旅客全名,須與證件一致;新增旅客時必填,更新時可省略

phone選填
string

旅客聯絡電話

email選填
string

旅客電子郵件

birthDate選填
string

旅客出生日期(格式 YYYY-MM-DD)

lineId選填
string· max 100

旅客 LINE ID

lineDisplayName選填
string

旅客 LINE 顯示名稱

englishName選填
string· max 100

英文姓名,須與護照一致(大寫英文、空白、連字號、逗號),否則回 422;海外團用

nationality選填
string· max 100

國籍使用 ISO 3166-1 alpha-2 代碼;新增時省略代表 TW、更新時省略不改,空字串或 null 代表國籍未知,未知國名回 422

passportExpiryDate選填
string

護照效期(格式 YYYY-MM-DD);海外團效期提醒用

emergencyContactName選填
string

緊急聯絡人姓名

emergencyContactPhone選填
string

緊急聯絡人電話

gender選填
enum
malefemaleother

旅客性別:male 男、female 女、other 其他

roomPreference選填
string

房型偏好(用於分房作業)

roommatePref選填
string

指定同住室友(用於分房作業)

diet選填
string

飲食需求(葷 / 素 / 蛋奶素… 自由值),供餐食葷素彙總

medicalNotes選填
string

醫療 / 過敏 / 病史備註(自由文字),供出團安全警示

address選填
string

旅客通訊地址

idNumber選填
string

身分證字號,屬個資將加密保存

passportNo選填
string

護照號碼,屬個資將加密保存

surveyAnswers選填
array· max 100

行程自訂報名調查項的作答;給陣列 = 整份取代(必填題未答或選到停用選項回 422)。編輯時省略 = 不動既有答案;新增時省略 = 一題都沒答

id路徑
string· min 1

訂單 ID

seatMode選填
enum
roster_onlyadd_seat

roster_only=只補名單(席次已買,旅客數須小於人數);add_seat=加一席(人數與梯次席次加 1,應收加一人成交價)

acknowledgeRosterFreeze選填
boolean

員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED

回應欄位 · data

ok
boolean

固定為 true:旅客已新增至訂單。

travelerId
string

新建立旅客的 ID(trv_ 前綴)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/travelers" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fullName": "example-fullName",
  "phone": "example-phone",
  "email": "customer@example.com"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "travelerId": "…"
  }
}

更新旅客資料

PATCH/api/v1/orders/{id}/travelers/{travelerId}
order.update

參數

fullName選填
string· min 1

旅客全名,須與證件一致;新增旅客時必填,更新時可省略

phone選填
string

旅客聯絡電話

email選填
string

旅客電子郵件

birthDate選填
string

旅客出生日期(格式 YYYY-MM-DD)

lineId選填
string· max 100

旅客 LINE ID

lineDisplayName選填
string

旅客 LINE 顯示名稱

englishName選填
string· max 100

英文姓名,須與護照一致(大寫英文、空白、連字號、逗號),否則回 422;海外團用

nationality選填
string· max 100

國籍使用 ISO 3166-1 alpha-2 代碼;新增時省略代表 TW、更新時省略不改,空字串或 null 代表國籍未知,未知國名回 422

passportExpiryDate選填
string

護照效期(格式 YYYY-MM-DD);海外團效期提醒用

emergencyContactName選填
string

緊急聯絡人姓名

emergencyContactPhone選填
string

緊急聯絡人電話

gender選填
enum
malefemaleother

旅客性別:male 男、female 女、other 其他

roomPreference選填
string

房型偏好(用於分房作業)

roommatePref選填
string

指定同住室友(用於分房作業)

diet選填
string

飲食需求(葷 / 素 / 蛋奶素… 自由值),供餐食葷素彙總

medicalNotes選填
string

醫療 / 過敏 / 病史備註(自由文字),供出團安全警示

address選填
string

旅客通訊地址

idNumber選填
string

身分證字號,屬個資將加密保存

passportNo選填
string

護照號碼,屬個資將加密保存

surveyAnswers選填
array· max 100

行程自訂報名調查項的作答;給陣列 = 整份取代(必填題未答或選到停用選項回 422)。編輯時省略 = 不動既有答案;新增時省略 = 一題都沒答

id路徑
string· min 1

訂單 ID

travelerId路徑
string· min 1

旅客 ID

acknowledgeRosterFreeze選填
boolean

員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED

回應欄位 · data

ok
boolean

固定為 true:旅客資料已更新。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/orders/<id>/travelers/<travelerId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fullName": "example-fullName",
  "phone": "example-phone",
  "email": "customer@example.com"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

移除旅客

DELETE/api/v1/orders/{id}/travelers/{travelerId}
order.update

參數

id路徑
string· min 1

訂單 ID

travelerId路徑
string· min 1

旅客 ID

acknowledgeRosterFreeze選填
boolean

員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED

回應欄位 · data

ok
boolean

固定為 true:旅客已自訂單移除。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/orders/<id>/travelers/<travelerId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

GET/api/v1/orders/{id}/travelers/{travelerId}/climbing-records
order.update模組:climbing

參數

id路徑
string· min 1

Resource ID

travelerId路徑
string· min 1

Traveler ID

回應欄位 · data[]

id
string
label
string
gradeScore
number | null
systemGradeScore
number | null
hasAlpineExperience
boolean
climbedOn
string | null
createdAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/<id>/travelers/<travelerId>/climbing-records" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "label": "…",
      "gradeScore": 0,
      "systemGradeScore": 0,
      "hasAlpineExperience": true,
      "climbedOn": "…",
      "createdAt": "…"
    }
  ]
}
POST/api/v1/orders/{id}/travelers/{travelerId}/climbing-records
order.update模組:climbing

參數

id路徑
string· min 1

Resource ID

travelerId路徑
string· min 1

Traveler ID

label必填
string· max 200 · min 1

Route label

gradeScore選填
integer· max 20 · min 0

Reference grade score. This value does not affect screening. The system uses the route grade table.

hasAlpineExperience選填
boolean

Alpine experience

climbedOn選填
string· 格式限定

Climb date

回應欄位 · data

ok
true
recordId
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/travelers/<travelerId>/climbing-records" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "example-label"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "recordId": "…"
  }
}

Use the canonical tenant operation.

DELETE/api/v1/orders/{id}/travelers/{travelerId}/climbing-records/{recordId}
order.update模組:climbing

參數

id路徑
string· min 1

Resource ID

travelerId路徑
string· min 1

Traveler ID

recordId路徑
string· min 1

Climbing record ID

回應欄位 · data

ok
true
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/orders/<id>/travelers/<travelerId>/climbing-records/<recordId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}

顯示旅客證號/護照全碼

POST/api/v1/orders/{id}/travelers/{travelerId}/reveal
order.reveal_pii

參數

id路徑
string· min 1

訂單 ID

travelerId路徑
string· min 1

旅客 ID

field必填
enum
idNumberpassportNo

欲顯示全碼的個資欄位:idNumber 身分證字號、passportNo 護照號碼

回應欄位 · data

field
"idNumber" | "passportNo"

本次解密的欄位:idNumber 身分證字號 / passportNo 護照號碼。

value
string | null

解密後的證件明碼;null = 該欄未填。每次呼叫都會寫入解密稽核紀錄。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/travelers/<travelerId>/reveal" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "field": "idNumber"
}'
回應
{
  "ok": true,
  "data": {
    "field": "idNumber",
    "value": "…"
  }
}

更新旅客分房需求

PATCH/api/v1/orders/{id}/travelers/{travelerId}/rooming
order.update

參數

roomPreference選填
string

房型偏好(用於分房作業)

roommatePref選填
string

指定同住室友(用於分房作業)

id路徑
string· min 1

訂單 ID

travelerId路徑
string· min 1

旅客 ID

回應欄位 · data

ok
boolean

固定為 true:旅客分房設定已更新。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/orders/<id>/travelers/<travelerId>/rooming" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "roomPreference": "example-roomPreference",
  "roommatePref": "example-roommatePref"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

批次把多張訂單派給同一位業務

POST/api/v1/orders/bulk-assign
order.assign模組:tour

參數

requestId必填
string· 格式限定

提交識別;重送同一批次時沿用此值

orderIds必填
array· max 100 · min 1

欲批次派發的訂單 ID 陣列(1 至 100 筆)

assigneeUserId必填
string· min 1

受派業務的使用者 ID(所有訂單派給同一人)

reason選填
string· max 500

派發事由說明(上限 500 字)

回應欄位 · data

ok
boolean

固定為 true:批次指派已執行。

assignedCount
number

成功指派的訂單筆數。

skippedCount
number

略過的訂單筆數(如已指派或不在可指派範圍)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/bulk-assign" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "requestId": "2026-10-13",
  "orderIds": [
    "example-orderIds"
  ],
  "assigneeUserId": "example-assigneeUserId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "assignedCount": 0,
    "skippedCount": 0
  }
}

代客 K 單的折扣碼即時試算

POST/api/v1/orders/discount-preview
order.create

參數

code必填
string· min 1

欲試算的優惠碼字串

departureId必填
string· min 1

梯次 id(server 端反查行程,不信任 client 的 tripId)

partySize必填
integer

人數;折前小計由 server 依建單同一套定價解析(單價 × 人數),不收 client 的金額

customerType必填
enum
directagency

成交客戶類型:direct 直客價 / agency 同業價;決定價格通路與客戶分類 gating

primaryEmail選填
string

訂購人 email(選填);查得會員才納入每客戶兌換上限判定,空或查不到則該閘放行

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/discount-preview" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "departureId": "example-departureId",
  "partySize": 1,
  "customerType": "direct"
}'
回應
{
  "ok": true,
  "data": "…"
}

匯出訂單

GET/api/v1/orders/export
order.read

參數

status選填
string

依訂單顯示狀態篩選(如 pending、paid、cancelled)

assignment選填
string

依派發狀態篩選(如 unassigned、assigned)

rooming選填
string

依分房狀態篩選

dateFrom選填
string

出發日期區間起(格式 YYYY-MM-DD,含當日)

dateTo選填
string

出發日期區間迄(格式 YYYY-MM-DD,含當日)

q選填
string

關鍵字搜尋(訂單編號、訂購人姓名或 Email 等)

agencyId選填
string

依合作旅行社 ID 篩選(同業單)

回應欄位 · data

rows
object[]

符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。

kind
"lodging" | "tour"
id
string

訂單 id(前綴 `ord_`)。

orderNumber
string

人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。

bookingState
string

預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。

paymentState
string

付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。

refundState
string

退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。

grossReceivableTwd
number

應收(TWD 整數,派生自應收分類帳)。

collectedTwd
number

收到現金(TWD 整數,派生)。

customerCashAppliedTwd
number

客戶現金淨套用(收款減已退現金,TWD 整數,派生)。

refundableCashTwd
number

可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。

outstandingTwd
number

未收(應收減客戶現金淨套用,TWD 整數,派生)。

partySize
number

參團人數(tour 訂單)。

createdAt
string

訂單建立時間。

notes
string | null

訂單備註(未填 → null)。

userId
string

下單客戶的 user id(同庫 user 表)。

userName
string

下單客戶顯示名。

userEmail
string

下單客戶 Email。

primaryTravelerName
string | null

主要旅客姓名(is_primary,未登記 → null)。

primaryTravelerPhone
string | null

主要旅客電話(未登記 → null)。

tripId
string

行程 id(tour 訂單經梯次反查;lodging 為空字串)。

tripTitle
string

行程 / 產品標題。

tripShortName
string | null

行程內部簡稱(issue 1414);未填或訂房訂單為 null。

tripSlug
string

行程 slug。

departureId
string

梯次 id(tour 訂單;lodging 為空字串)。

departureDate
string

出發日 YYYY-MM-DD(lodging 為入住日)。

returnDate
string

回程日 YYYY-MM-DD(lodging 為退房日)。

assignedToUserId
string | null

派發給哪位業務的 user id(未派發 → null)。

assigneeName
string | null

承辦業務顯示名(未派發 / 查無 → null)。

assignmentStatus
string

派發狀態:unassigned / assigned / reassigned / pending_review。

assignedAt
string | null

最近一次派發時間(未派發 → null)。

assignedByUserId
string | null

執行派發者的 user id(未派發 → null)。

createdByUserId
string | null

S5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.

pendingConsent
boolean

是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。

roomingStatus
"assigned" | "needs_single" | "registered" | "unregistered"

分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。

lotteryState
string | null

抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。

lotteryWaitlisted
boolean

備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。

failoverFromOrderId
string | null

備案訂單所對應的原訂單 ID。

isOverdue
boolean

是否有已到期、尚未收齊的收款計畫。

total
number

符合篩選條件的總筆數。

truncated
boolean

是否因達安全上限而截斷(true 表未回傳完整結果,呼叫端應提示)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/export" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "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
      }
    ],
    "total": 0,
    "truncated": true
  }
}

代客 K 單的金額試算

POST/api/v1/orders/quote
order.create

參數

departureId必填
string· min 1

梯次 id(server 端反查行程,不信任 client 的 tripId)

customerType必填
enum
directagency

成交客戶類型:direct 直客價 / agency 同業價;決定價格通路與客戶分類 gating

partySize必填
integer· max 20 · min 1

人數;小計由 server 依建單同一套定價解析(單價 × 人數),不收 client 的金額

paymentPlan必填
enum
fulldeposit

付款方案:full 全額 / deposit 訂金;梯次沒有訂金規則時改成全額

code選填
string

優惠碼(選填);空字串視為沒有

primaryEmail選填
string

訂購人 email(選填);查得會員才納入每客戶兌換上限判定,空或查不到則該閘放行

回應欄位 · data

quote
object

金額試算:單價、小計、折扣、總計、實際付款方案與訂金 / 尾款。

unitPriceTwd
number
partySize
number
subtotalTwd
number

折前小計 = 單價 × 人數。

discountTwd
number
totalTwd
number

折後總計,也就是訂單應收。

paymentPlan
"deposit" | "full"

實際採用的付款方案:訂金方案拆不出尾款時改成全額。

depositDueTwd
number
balanceDueTwd
number
discount
ManualOrderQuoteDiscount

優惠碼結果:none 沒有碼 / applied 已折抵 / rejected 被拒(帶 reason,數字不折)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/quote" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureId": "example-departureId",
  "customerType": "direct",
  "partySize": 1,
  "paymentPlan": "full"
}'
回應
{
  "ok": true,
  "data": {
    "quote": {
      "unitPriceTwd": 0,
      "partySize": 0,
      "subtotalTwd": 0,
      "discountTwd": 0,
      "totalTwd": 0,
      "paymentPlan": "deposit",
      "depositDueTwd": 0,
      "balanceDueTwd": 0
    },
    "discount": "…"
  }
}

退款「標記已退款」用的出款帳戶下拉

GET/api/v1/orders/remit-accounts
refund.mark_paid

回應欄位 · data[]

id
string

收款帳戶 ID(標記已退款時當出款帳戶帶入)。

code
string

帳戶代碼(租戶自訂短碼)。

displayName
string

顯示名稱(下拉選項用)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/remit-accounts" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…"
    }
  ]
}

Use the canonical tenant operation.

GET/api/v1/orders/remittance-lookup
payment.update

參數

orderNumber必填
string· min 1

Order number

回應欄位 · data

orderId
string
orderNumber
string
customerName
string
tripTitle
string | null
outstandingTwd
number
bookingState
string
paymentState
"deposit_paid" | "overpaid" | "paid" | "partially_paid" | "unpaid"
請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/remittance-lookup?orderNumber=example-orderNumber" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "orderId": "…",
    "orderNumber": "…",
    "customerName": "…",
    "tripTitle": "…",
    "outstandingTwd": 0,
    "bookingState": "…",
    "paymentState": "deposit_paid"
  }
}
POST/api/v1/orders/screening-preview
order.create模組:climbing

參數

departureId必填
string· max 100
travelers必填
array· max 20 · min 1

回應欄位 · data

results
{ tripGradeScore: number | null; ability: number; result: ScreenResult; }[] | null

Advisory results from entered records. Submission recalculates each result.

請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/screening-preview" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureId": "example-departureId",
  "travelers": [
    {
      "climbingRecords": [
        {
          "label": "example-label"
        }
      ]
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "results": null
  }
}

Use the canonical tenant operation.

POST/api/v1/orders/split-remittance
payment.update

參數

totalTwd必填
integer

Total remittance amount TWD

allocations必填
array· min 2

Order allocations

idempotencyKey必填
string· 格式限定

Request retry key

bankReference選填
string· max 40

Bank reference

receivingAccountId必填
string· min 1

Actual receiving account ID

providerTradeNo選填
string· max 40

Gateway trade number; required for a gateway account

bankCreditedOn選填
string

Bank credited date YYYY-MM-DD; required for a bank account

overTheCounter選填
boolean

Over-the-counter deposit; a bank account then needs no bank reference

note選填
string

Note

回應欄位 · data

retentionDeferred
boolean
ok
true
idempotent
boolean
remittanceId
string
orders
object[]
orderId
string
orderNumber
string
collectedTwd
number
customerCashAppliedTwd
number
outstandingTwd
number
paymentState
"deposit_paid" | "overpaid" | "paid" | "partially_paid" | "unpaid"
請求
curl -X POST "https://your-tenant.example.com/api/v1/orders/split-remittance" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
      }
    ]
  }
}

order KPI counts

GET/api/v1/orders/stats
order.read

回應欄位 · data

pendingPayment
number

待付款訂單數(未取消 / 未完成 / 未退款且 payment_state=unpaid)。

depositPaid
number

已付訂金訂單數(payment_state=deposit_paid)。

paid
number

已收齊訂單數(payment_state in paid/overpaid)。

cancelled
number

已取消訂單數(booking_state=cancelled)。

refunded
number

有退款的訂單數(refund_state in refunded/partially_refunded)。

completed
number

已完成訂單數(booking_state=completed)。

thisMonthPaidTwd
number

本月實收現金(payment_transactions direction=in 加總,TWD 整數)。

thisMonthNewOrders
number

本月新建訂單數。

thisMonthCancelled
number

本月取消訂單數(依 `cancelled_at` 計,台北月界)。不依 `updated_at` —— 取消之後的 退款或備註會把單推到錯的月份。`cancelled_at IS NULL` 的單任何月份都不計。

請求
curl -X GET "https://your-tenant.example.com/api/v1/orders/stats" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "pendingPayment": 0,
    "depositPaid": 0,
    "paid": 0,
    "cancelled": 0,
    "refunded": 0,
    "completed": 0,
    "thisMonthPaidTwd": 0,
    "thisMonthNewOrders": 0,
    "thisMonthCancelled": 0
  }
}

/equipment

list the equipment master

GET/api/v1/equipment/items
equipment.read

參數

activeOnly選填
boolean

只列出啟用中(可租借)的品項

回應欄位 · data[]

id
string

裝備主檔品項 id(equipmentItem_ 前綴)。

name
string

品名。

category
string | null

分類(如帳篷/睡袋/爐具;未分類為 null)。

spec
string | null

規格描述(尺寸/型號等;可空)。

rentPriceTwd
number

每日租金單價(TWD)。

depositTwd
number

每件押金(TWD)。

totalCount
number

庫存總件數。

outCount
number

目前在外(已借出未歸還)件數。

maintenanceCount
number

維修中件數(不可借出)。

availableCount
number

可租 = total − out − maintenance(派生,便利 UI)。

isActive
boolean

是否啟用(可租借)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/equipment/items" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "category": "…",
      "spec": "…",
      "rentPriceTwd": 0,
      "depositTwd": 0,
      "totalCount": 0,
      "outCount": 0,
      "maintenanceCount": 0,
      "availableCount": 0,
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

create a master item

POST/api/v1/equipment/items
equipment.manage

參數

name必填
string· max 200 · min 1

裝備品項名稱

category選填
string· max 50

裝備分類(如帳篷、睡袋;選填)

spec選填
string· max 500

規格說明(如尺寸、型號;選填)

rentPriceTwd選填
integer· min 0

每日租金(台幣)

depositTwd選填
integer· min 0

每件押金(台幣)

totalCount選填
integer· min 0

總庫存數量

maintenanceCount選填
integer· min 0

維修中而不可租借的數量

isActive選填
boolean

是否啟用(可供租借)

回應欄位 · data

id
string

新建立的裝備品項 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/equipment/items" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

single equipment master item detail.

GET/api/v1/equipment/items/{id}
equipment.read

參數

id路徑
string· min 1

裝備品項 ID

回應欄位 · data

id
string

裝備主檔品項 id(equipmentItem_ 前綴)。

name
string

品名。

category
string | null

分類(如帳篷/睡袋/爐具;未分類為 null)。

spec
string | null

規格描述(尺寸/型號等;可空)。

rentPriceTwd
number

每日租金單價(TWD)。

depositTwd
number

每件押金(TWD)。

totalCount
number

庫存總件數。

outCount
number

目前在外(已借出未歸還)件數。

maintenanceCount
number

維修中件數(不可借出)。

availableCount
number

可租 = total − out − maintenance(派生,便利 UI)。

isActive
boolean

是否啟用(可租借)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/equipment/items/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "category": "…",
    "spec": "…",
    "rentPriceTwd": 0,
    "depositTwd": 0,
    "totalCount": 0,
    "outCount": 0,
    "maintenanceCount": 0,
    "availableCount": 0,
    "isActive": true,
    "createdAt": "…",
    "updatedAt": "…"
  }
}

update a master item

PATCH/api/v1/equipment/items/{id}
equipment.manage

參數

id路徑
string· min 1

要更新的裝備品項 ID

name必填
string· max 200 · min 1

裝備品項名稱

category選填
string· max 50

裝備分類(如帳篷、睡袋;選填)

spec選填
string· max 500

規格說明(如尺寸、型號;選填)

rentPriceTwd選填
integer· min 0

每日租金(台幣)

depositTwd選填
integer· min 0

每件押金(台幣)

totalCount選填
integer· min 0

總庫存數量

maintenanceCount選填
integer· min 0

維修中而不可租借的數量

isActive選填
boolean

是否啟用(可供租借)

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/equipment/items/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

list rental tickets

GET/api/v1/equipment/rentals
equipment.read

參數

returnState選填
enum
rentedreturnedoverduecancelled

依歸還狀態篩選:rented 在租中、returned 已歸還、overdue 逾期、cancelled 已取消

reconState選填
enum
pendingreconcileddeposit_pending

依驗收結算狀態篩選:pending 待驗收、reconciled 已結算、deposit_pending 待退押金

orderId選填
string

只列出綁定此訂單 ID 的租借單

departureId選填
string

只列出綁定此梯次 ID 的租借單

equipmentItemId選填
string

只列出含此裝備品項的租借單

rentFrom選填
string· 格式限定

租期區間起(含),格式 YYYY-MM-DD。判準是租期與區間**重疊**,跨月的單兩個月都查得到

rentTo選填
string· 格式限定

租期區間迄(含),格式 YYYY-MM-DD

回應欄位 · data[]

orderOnDeparture
boolean

Whether the order currently includes this rental departure.

deliveredAt選填
string | undefined | null
depositClearedAt選填
string | undefined | null
id
string

租借單 id(equipmentRental_ 前綴)。

rentalCode
string

人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。

orderId
string

掛載的訂單 id。

orderNumber
string | null

訂單編號;無對應訂單時為 null。

departureId
string | null

綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。

departureLabel
string | null

梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。

renterName
string | null

租借人姓名(可空)。

rentStartDate
string | null

租期起日(YYYY-MM-DD;可空)。

rentEndDate
string | null

租期迄日(YYYY-MM-DD;可空)。

returnedAt
string | null

歸還驗收時間(尚未歸還為 null)。

returnState
"cancelled" | "overdue" | "rented" | "returned"

歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。

inspectedAt
string | null

驗收時間(尚未驗收為 null)。

damageCostTwd
number | null

破損/遺失賠償金額(TWD;無為 null)。

reconState
"deposit_pending" | "pending" | "reconciled"

對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。

cancelledAt
string | null

取消時間(未取消為 null)。

cancelReason
string | null

取消原因(未取消為 null)。

notes
string | null

備註(可空)。

createdAt
string

建單時間。

updatedAt
string

最後更新時間。

lines
object[]

租借明細(借出的品項清單)。

id
string

租借明細 id(equipmentRentalLine_ 前綴)。

equipmentItemId
string

借出的裝備主檔品項 id。

itemName
string | null

裝備品項目前的名稱。

quantity
number

借出數量。

rentPriceTwdSnapshot
number

成交單位總價快照(每日單價 × 計價日數;TWD)。

depositTwdSnapshot
number

成交每件押金快照(TWD,不乘天數)。

returnedQuantity
number | null

已歸還數量(尚未歸還為 null)。

rentTotalTwd
number

成交租金合計(Σ rent snapshot × qty)。

depositTotalTwd
number

成交押金合計(Σ deposit snapshot × qty)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/equipment/rentals" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "orderOnDeparture": true,
      "deliveredAt": "…",
      "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
    }
  ]
}

open a rental ticket

POST/api/v1/equipment/rentals
equipment.manage

參數

orderId必填
string· min 1

租借單綁定的訂單 ID(租金與押金會掛入該訂單金流)

departureId必填
string· min 1

租借掛的梯次 ID(必填;該梯次的行程須為登山團且已開「可租借裝備」,訂單須報名此梯次)

renterName選填
string· max 100

租借人姓名(選填)

rentStartDate選填
string· 格式限定

租借起始日,格式 YYYY-MM-DD(選填)

rentEndDate選填
string· 格式限定

租借結束日,格式 YYYY-MM-DD(選填)

notes選填
string· max 1000

租借單備註(選填)

lines必填
array· min 1

租借明細清單(至少一筆品項)

回應欄位 · data

rentalId
string

新開立的租借單 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/equipment/rentals" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "example-orderId",
  "departureId": "example-departureId",
  "lines": [
    {
      "itemId": "example-itemId",
      "qty": 1
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "rentalId": "…"
  }
}

single rental ticket detail

GET/api/v1/equipment/rentals/{id}
equipment.read

參數

id路徑
string· min 1

租借單 ID

回應欄位 · data

orderOnDeparture
boolean

Whether the order currently includes this rental departure.

deliveredAt選填
string | undefined | null
depositClearedAt選填
string | undefined | null
id
string

租借單 id(equipmentRental_ 前綴)。

rentalCode
string

人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。

orderId
string

掛載的訂單 id。

orderNumber
string | null

訂單編號;無對應訂單時為 null。

departureId
string | null

綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。

departureLabel
string | null

梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。

renterName
string | null

租借人姓名(可空)。

rentStartDate
string | null

租期起日(YYYY-MM-DD;可空)。

rentEndDate
string | null

租期迄日(YYYY-MM-DD;可空)。

returnedAt
string | null

歸還驗收時間(尚未歸還為 null)。

returnState
"cancelled" | "overdue" | "rented" | "returned"

歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。

inspectedAt
string | null

驗收時間(尚未驗收為 null)。

damageCostTwd
number | null

破損/遺失賠償金額(TWD;無為 null)。

reconState
"deposit_pending" | "pending" | "reconciled"

對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。

cancelledAt
string | null

取消時間(未取消為 null)。

cancelReason
string | null

取消原因(未取消為 null)。

notes
string | null

備註(可空)。

createdAt
string

建單時間。

updatedAt
string

最後更新時間。

lines
object[]

租借明細(借出的品項清單)。

id
string

租借明細 id(equipmentRentalLine_ 前綴)。

equipmentItemId
string

借出的裝備主檔品項 id。

itemName
string | null

裝備品項目前的名稱。

quantity
number

借出數量。

rentPriceTwdSnapshot
number

成交單位總價快照(每日單價 × 計價日數;TWD)。

depositTwdSnapshot
number

成交每件押金快照(TWD,不乘天數)。

returnedQuantity
number | null

已歸還數量(尚未歸還為 null)。

rentTotalTwd
number

成交租金合計(Σ rent snapshot × qty)。

depositTotalTwd
number

成交押金合計(Σ deposit snapshot × qty)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/equipment/rentals/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "orderOnDeparture": true,
    "deliveredAt": "…",
    "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
  }
}

作廢一張開錯的租借單

POST/api/v1/equipment/rentals/{id}/cancel
equipment.manage

參數

id路徑
string· min 1

要取消的租借單 ID

reason必填
string· max 500 · min 1

取消原因(必填;只留在租借單與稽核紀錄,不會印在客人的收據上)

回應欄位 · data

ok
boolean

取消成功旗標,恆為 true。

reversedReceivableTwd
number

沖銷掉的應收金額(租金 + 押金);訂單本身已取消時為 0。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

請求
curl -X POST "https://your-tenant.example.com/api/v1/equipment/rentals/<id>/cancel" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "reversedReceivableTwd": 0,
    "retentionDeferred": true
  }
}
POST/api/v1/equipment/rentals/{id}/deliver
equipment.manage模組:climbing

參數

id路徑
string· min 1

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/equipment/rentals/<id>/deliver" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

flag a single rented ticket

POST/api/v1/equipment/rentals/{id}/mark-overdue
equipment.manage

參數

id路徑
string· min 1

要標記為逾期的租借單 ID

回應欄位 · data

ok
boolean

標記逾期成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/equipment/rentals/<id>/mark-overdue" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
POST/api/v1/equipment/rentals/{id}/reconcile-deposit
equipment.manage模組:climbing

參數

id路徑
string· min 1

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/equipment/rentals/<id>/reconcile-deposit" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

receive a rental back

POST/api/v1/equipment/rentals/{id}/return
equipment.manage

參數

id路徑
string· min 1

要驗收歸還的租借單 ID

returnedLines必填
array· min 1

各明細的歸還數量清單

damageCostTwd選填
integer· min 0

損壞賠償金額(台幣,選填)

回應欄位 · data

ok
boolean

驗收歸還成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/equipment/rentals/<id>/return" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "returnedLines": [
    {
      "lineId": "example-lineId",
      "returnedQty": 1
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

the minimal order picker

GET/api/v1/equipment/rentals/order-options
equipment.read

參數

limit選填
integer· max 200

回傳訂單筆數上限(最多 200,預設取最近多筆)

回應欄位 · data[]

orderId
string

訂單 id。

orderNumber
string | null

訂單編號(可空)。

customerName
string | null

訂購人姓名(可空)。

departures
object[]

這張單報名、且可租借裝備的梯次(issue 240)。通常恰好一個;legacy 匯入的多 line 單 可能多個,開單時要挑一個。 帶出發 / 回程日是為了讓開單表單把**租期預設成梯次日期**(issue #577):租期空著 不只讓清單的日期篩選沒東西可篩,租金還會退回計價 1 日(`computeBillableDays`), 與同一張卡片上印的現場付現估算對不起來。

departureId
string
label
string
departureDate
string
returnDate
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/equipment/rentals/order-options" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "orderId": "…",
      "orderNumber": "…",
      "customerName": "…",
      "departures": [
        {
          "departureId": "…",
          "label": "…",
          "departureDate": "…",
          "returnDate": "…"
        }
      ]
    }
  ]
}

/guide-roster

指派 / 重派 guide 到梯次

POST/api/v1/guide-roster/assignments
guide_roster.manage模組:tour

參數

guideStartDate選填
string

帶團開始日期;與結束日期成對,null 回復行程預設

guideEndDate選填
string

帶團結束日期;與開始日期成對

isNameBound選填
boolean

是否為綁名指派

nameBoundChangeReason選填
string· max 500 · min 1

解除綁名或變更綁名角色的原因

departureId必填
string· max 64 · min 1

指派的目標梯次 ID

guideId必填
string· max 64 · min 1

被指派的嚮導 ID

role必填
enum
leaderassistant

指派角色(leader 主要隨團人員/assistant 協同)

status必填
enum
tentativeconfirmed

指派狀態(tentative 預塞暫定/confirmed 正式確認)

回應欄位 · data

id
string

新建立(或重派後)的指派紀錄 id。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guide-roster/assignments" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureId": "example-departureId",
  "guideId": "example-guideId",
  "role": "leader",
  "status": "tentative"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

移除某筆指派

DELETE/api/v1/guide-roster/assignments/{id}
guide_roster.manage模組:tour

參數

id路徑
string· max 64 · min 1

要移除的指派紀錄 ID

nameBoundChangeReason選填
string· max 500 · min 1

移除綁名指派的原因(查詢參數)

回應欄位 · data

ok
boolean

移除成功旗標,恆為 true。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/guide-roster/assignments/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

正式確認某筆指派

POST/api/v1/guide-roster/assignments/{id}/confirm
guide_roster.manage模組:tour

參數

id路徑
string· max 64 · min 1

要正式確認的指派紀錄 ID

回應欄位 · data

ok
boolean

確認成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guide-roster/assignments/<id>/confirm" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

換主要隨團人員

POST/api/v1/guide-roster/change-leader
guide_roster.manage模組:tour

參數

guideStartDate選填
string

新任主要隨團人員帶團開始日期

guideEndDate選填
string

新任主要隨團人員帶團結束日期

isNameBound選填
boolean

新任指派是否綁名

nameBoundChangeReason選填
string· max 500 · min 1

變更綁名原因;省略時使用換人原因

departureId必填
string· max 64 · min 1

要換主要隨團人員的目標梯次 ID

fromGuideId選填
string· max 64 · min 1

原主要隨團人員的嚮導 ID(選填;省略表示該梯次原本沒有)

toGuideId必填
string· max 64 · min 1

新任主要隨團人員的嚮導 ID

reason必填
string· max 500 · min 1

換人的原因(必填,記入稽核)

回應欄位 · data

id
string

新任 leader 的指派紀錄 id。

removedGuideIds
string[]

被移除的舊 leader 嚮導 id 清單(DB 權威)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guide-roster/change-leader" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureId": "example-departureId",
  "toGuideId": "example-toGuideId",
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "removedGuideIds": [
      "…"
    ]
  }
}

pre-check whether assigning a guide

GET/api/v1/guide-roster/conflict-check
guide_roster.read模組:tour

參數

guideStartDate選填
string

預計帶團開始日期;與結束日期成對

guideEndDate選填
string

預計帶團結束日期;與開始日期成對

departureId必填
string· min 1

欲指派的目標梯次 ID

guideId必填
string· min 1

欲檢查檔期衝突的嚮導 ID

請求
curl -X GET "https://your-tenant.example.com/api/v1/guide-roster/conflict-check?departureId=example-departureId&guideId=example-guideId" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": null
}

schedule conflicts for the selected

GET/api/v1/guide-roster/conflicts
guide_roster.read模組:tour

參數

month必填
string· 格式限定

查詢月份(YYYY-MM 格式)

回應欄位 · data[]

guideId
string

發生衝突的嚮導 id。

guideName
string

發生衝突的嚮導姓名。

a
object

衝突梯次之一(含梯次 id/行程名/起訖日)。

departureId
string

梯次 id。

tripTitle
string

行程名稱。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

b
object

與 a 日期重疊的另一梯次(含梯次 id/行程名/起訖日)。

departureId
string

梯次 id。

tripTitle
string

行程名稱。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guide-roster/conflicts?month=2026-10" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "guideId": "…",
      "guideName": "…",
      "a": {
        "departureId": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "returnDate": "…"
      },
      "b": {
        "departureId": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "returnDate": "…"
      }
    }
  ]
}

departures overlapping the month

GET/api/v1/guide-roster/departures
guide_roster.read模組:tour

參數

month必填
string· 格式限定

查詢月份(YYYY-MM 格式)

includeCancelled選填
boolean

是否一併納入已取消的梯次(預設不納入)

回應欄位 · data[]

id
string

梯次 id。

tripId
string

所屬行程 id。

tripTitle
string

行程名稱。

tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

label
string | null

梯次標籤 / 副標(issue 509 ①);null = 無。排班下拉靠它分辨同日兩梯。

groupCode
string | null

團號(group-code spec §3.3);null = 尚未產生。排班 UI 用它指認梯次。

departureDate
string

出發日(YYYY-MM-DD)。

returnDate
string

回程日(YYYY-MM-DD)。

days
number

帶團天數(含頭尾)。

capacity
number

團位容量(總名額)。

bookedCount
number

已成團報名人數。

status
string

梯次狀態(如 open 開放/full 已滿/cancelled 已取消)。

assignments
object[]

該梯次所有指派(leader 在前)。

id
string

指派紀錄 id。

guideId
string

被指派的嚮導 id。

guideName
string

被指派的嚮導姓名。

role
"assistant" | "leader"

指派角色:leader 主要隨團人員/assistant 協同。

status
"confirmed" | "tentative"

指派狀態:tentative 預塞暫定/confirmed 正式確認。

guideStartDate
string | null
guideEndDate
string | null
effectiveStartDate
string
effectiveEndDate
string
isNameBound
boolean
permitSwappedAt
string | null

勾「已換領」的時間(ISO);null = 未勾(issue 1731)。

permitSwappedByName
string | null

勾「已換領」的人的名稱;帳號已刪或未勾時為 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guide-roster/departures?month=2026-10" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
        }
      ]
    }
  ]
}

roster

GET/api/v1/guide-roster/guides
guide_roster.read模組:tour

參數

month必填
string· 格式限定

查詢月份(YYYY-MM 格式)

includeInactive選填
boolean

是否一併列出已停用的嚮導(預設不列出)

回應欄位 · data[]

id
string

嚮導 id。

name
string

嚮導姓名。

rosterRole
"assistant" | "both" | "leader"

名冊職能:leader 主要隨團人員/assistant 協同/both 皆可。

specialties
string[]

可帶路線 / 專長;未設為空陣列。

status
string

嚮導狀態:active 啟用/inactive 停用。

internalNote
string | null

內部備註(只給後台看,派團時參考);null = 沒填,或檢視者沒有 `guide.read`。

maxDaysPerMonth
number | null

單一曆月實際帶團天數上限(跨月梯次按實際日期拆分計入各月);NULL = 不限。

monthDays
number

視窗涵蓋月份內 confirmed 指派實際落在月內的帶團天數合計。

monthTrips
number

視窗涵蓋月份內有帶團日的 confirmed 梯次數(每梯只算一次)。

hasTentative
boolean

視窗涵蓋月份內是否含 tentative(預塞)指派。

availability
"full" | "open" | "tentative"

派生載量狀態:任一涵蓋月達上限即 full。

monthLoads
object[]

視窗涵蓋的每個曆月的載量(依時間排序)。

month
string

曆月 `YYYY-MM`。

days
number

該月 confirmed 指派實際落在月內的帶團天數。

trips
number

該月有帶團日的 confirmed 梯次數(跨月梯次在兩個月各算一次)。

hasTentative
boolean

該月是否有 tentative(預塞)指派佔用日期。

availability
"full" | "open" | "tentative"

該月的派生載量狀態。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guide-roster/guides?month=2026-10" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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"
        }
      ]
    }
  ]
}

/guides

list/search guides

GET/api/v1/guides
guide.read模組:tour

參數

slug選填
string· min 1

依嚮導公開頁網址代稱(slug)精確查單筆(選填)

status選填
enum
allactiveinactive

嚮導狀態篩選(all 全部/active 啟用/inactive 停用)

q選填
string

關鍵字搜尋(比對嚮導姓名等欄位)

category選填
string

嚮導分類篩選:分類 ID(gcat_ 開頭,見 guide-categories)

page選填
integer

頁碼(從 1 起算)

pageSize選填
integer· max 200

每頁筆數(上限 200)

請求
curl -X GET "https://your-tenant.example.com/api/v1/guides" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": "…"
}

create a guide

POST/api/v1/guides
guide.manage模組:tour

參數

name必填
string· max 100 · min 1

嚮導姓名

slug選填
string

公開頁網址代稱(選填,英數與連字號;大寫自動轉小寫,省略則由姓名產生)

bio選填
string· max 20000

嚮導簡介/經歷(選填)

avatarUrl選填
string· max 2000

大頭照圖片網址(選填,http/https 或本站圖庫資產路徑)

specialties選填
string

專長領域(選填,以逗號分隔多項)

careerStartYear選填
integer

入行年份(西元年,1900~今年;選填)。年資由系統推算,回應的 yearsExperience 唯讀

contactPhone選填
string· max 40

聯絡電話(選填)

contactEmail選填
string · email· max 120

聯絡 Email(選填)

categoryId選填
string· min 1

嚮導分類 ID(gcat_ 開頭;null 為未分類;省略則用第一個啟用中的分類)

status選填
enum
activeinactive

嚮導狀態(active 啟用/inactive 停用;預設 active)

回應欄位 · data

id
string

新建立的嚮導 id。

slug
string

嚮導公開頁網址代稱(未帶則系統自動產生)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guides" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…"
  }
}

single guide detail

GET/api/v1/guides/{id}
guide.read模組:tour

參數

id路徑
string· min 1

嚮導 ID

回應欄位 · data

id
string

嚮導 id(guide_ 前綴)。

name
string

嚮導姓名。

slug
string

公開頁網址代稱(slug;小寫英數與連字號)。

bio
string | null

簡介/經歷(可空)。

avatarUrl
string | null

大頭照圖片網址(可空)。

specialties
string[]

專長領域清單。

careerStartYear
number | null

入行年份(西元年;可空)。

yearsExperience
number | null

帶團年資(年數;由入行年份與台北今年推算,唯讀;可空)。

contactPhone
string | null

聯絡電話(可空)。

contactEmail
string | null

聯絡 Email(可空)。

status
"active" | "inactive"

嚮導狀態:active 啟用/inactive 停用。

categoryId
string | null

嚮導分類 id(gcat_ 前綴;名稱與順序見 guide-categories)。null = 未分類。

internalNote
string | null

內部備註(只給後台看,前台不顯示;可空)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guides/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "slug": "…",
    "bio": "…",
    "avatarUrl": "…",
    "specialties": [
      "…"
    ],
    "careerStartYear": 0,
    "yearsExperience": 0,
    "contactPhone": "…",
    "contactEmail": "…",
    "status": "active",
    "categoryId": "…",
    "internalNote": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}

update a guide

PATCH/api/v1/guides/{id}
guide.manage模組:tour

參數

id路徑
string· min 1

要更新的嚮導 ID

name選填
string· max 100 · min 1

嚮導姓名(省略則不更動)

slug選填
string

公開頁網址代稱(英數與連字號;大寫自動轉小寫,省略則不更動)

bio選填
string· max 20000

嚮導簡介/經歷(省略則不更動)

avatarUrl選填
string· max 2000

大頭照圖片網址(http/https 或本站圖庫資產路徑;省略則不更動)

specialties選填
string

專長領域(以逗號分隔多項;省略則不更動)

careerStartYear選填
integer

入行年份(西元年,1900~今年;省略則不更動)。年資由系統推算,回應的 yearsExperience 唯讀

contactPhone選填
string· max 40

聯絡電話(省略則不更動)

contactEmail選填
string · email· max 120

聯絡 Email(省略則不更動)

categoryId選填
string· min 1

嚮導分類 ID(gcat_ 開頭;null 為未分類;省略則不更動)

status選填
enum
activeinactive

嚮導狀態(active 啟用/inactive 停用;省略則不更動)

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/guides/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "slug": "example-slug",
  "bio": "example-bio"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

archive a guide

POST/api/v1/guides/{id}/archive
guide.manage模組:tour

參數

id路徑
string· min 1

要封存(狀態改為停用)的嚮導 ID

回應欄位 · data

ok
boolean

封存成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guides/<id>/archive" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

GET/api/v1/guides/{id}/certificates
guide.read模組:tour

參數

id路徑
string· min 1

Resource ID

回應欄位 · data[]

id
string
typeId
string
typeName
string
certNumber
string | null

證號(明文)。只給 guide_pii.read 看,其餘讀者由呼叫端清成 null。

issuedOn
string
expiresOn
string | null

NULL = 終身有效。

attachmentUrl
string | null

私有掃描件 URL(/api/assets 以 guide_pii.read 閘讀取)。

hasPii
boolean

有沒有證號或掃描件。不看 `withPii` 一律照實回(只露有無、不露值), 讓 UI 對沒有 guide_pii.manage 的人藏起這一列的刪除鍵(刪整列 = 清掉兩欄)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guides/<id>/certificates" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "typeId": "…",
      "typeName": "…",
      "certNumber": "…",
      "issuedOn": "…",
      "expiresOn": "…",
      "attachmentUrl": "…",
      "hasPii": true
    }
  ]
}
POST/api/v1/guides/{id}/certificates
guide.manage模組:tour

參數

id路徑
string· min 1

Resource ID

typeId必填
string· min 1

Certificate type ID

issuedOn必填
string· 格式限定

Issue date

expiresOn必填
string· 格式限定

Expiry date; null for lifetime validity

certNumber選填
string· max 200

Certificate number; needs guide PII read and manage

回應欄位 · data

ok
true
id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/guides/<id>/certificates" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "typeId": "example-typeId",
  "issuedOn": "2026-10-13",
  "expiresOn": "2026-10-13"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}

Use the canonical tenant operation.

PUT/api/v1/guides/{id}/certificates/{certificateId}
guide.manage模組:tour

參數

id路徑
string· min 1

Resource ID

certificateId路徑
string· min 1

Certificate ID

typeId必填
string· min 1

Certificate type ID

issuedOn必填
string· 格式限定

Issue date

expiresOn必填
string· 格式限定

Expiry date; null for lifetime validity

certNumber選填
string· max 200

Certificate number; needs guide PII read and manage

回應欄位 · data

ok
true
id
string
請求
curl -X PUT "https://your-tenant.example.com/api/v1/guides/<id>/certificates/<certificateId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "typeId": "example-typeId",
  "issuedOn": "2026-10-13",
  "expiresOn": "2026-10-13"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}
DELETE/api/v1/guides/{id}/certificates/{certificateId}
guide.manage模組:tour

參數

id路徑
string· min 1

Resource ID

certificateId路徑
string· min 1

Certificate ID

回應欄位 · data

ok
boolean
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/guides/<id>/certificates/<certificateId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

開通某既有 guide 的嚮導 portal 登入帳號

POST/api/v1/guides/{id}/invite-account
guide.invite_account模組:tour

參數

id路徑
string· min 1

要開通登入帳號的嚮導 ID

name必填
string· max 100 · min 1

嚮導帳號的顯示姓名

回應欄位 · data

email
string

已開通登入帳號的 Email(= 嚮導資料的聯絡 Email)。

activationSent
boolean

是否已寄出啟用信。false 時帳號仍已建立,請嚮導在登入頁走「忘記密碼」。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guides/<id>/invite-account" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "email": "…",
    "activationSent": true
  }
}

嚮導投保個資

GET/api/v1/guides/{id}/pii
guide_pii.read模組:tour

參數

id路徑
string· min 1

嚮導 ID

回應欄位 · data

legalName
string | null

正式姓名。

gender
string | null

性別 male / female / other;未填為 null。

emergencyContactName
string | null
emergencyContactPhone
string | null
englishName
string | null

英文姓名(與護照一致)。

idNumberMask
string | null

身分證遮罩(例:*******789);null = 未填。

passportNoMask
string | null

護照號碼遮罩;null = 未填。

birthDate
string | null

生日(YYYY-MM-DD)。

nationality
string | null

國籍;空值 = 本國。

address
string | null

通訊地址。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guides/<id>/pii" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "legalName": "…",
    "gender": "…",
    "emergencyContactName": "…",
    "emergencyContactPhone": "…",
    "englishName": "…",
    "idNumberMask": "…",
    "passportNoMask": "…",
    "birthDate": "…",
    "nationality": "…",
    "address": "…"
  }
}

寫嚮導個資

PATCH/api/v1/guides/{id}/pii
guide_pii.manage模組:tour

參數

id路徑
string· min 1

嚮導 ID

legalName選填
string· max 300
gender選填
string· max 300
emergencyContactName選填
string· max 300
emergencyContactPhone選填
string· max 300
englishName選填
string· max 300
idNumber選填
string· max 300
passportNo選填
string· max 300
birthDate選填
string· max 300
nationality選填
string· max 300
address選填
string· max 300

回應欄位 · data

changedFields
"address" | "birthDate" | "emergencyContactName" | "emergencyContactPhone" | "englishName" | "gender" | "idNumber" | "legalName" | "nationality" | "passportNo"[]

這次實際寫入的欄位。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/guides/<id>/pii" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "legalName": "example-legalName",
  "gender": "example-gender",
  "emergencyContactName": "example-emergencyContactName"
}'
回應
{
  "ok": true,
  "data": {
    "changedFields": [
      "address"
    ]
  }
}

顯示嚮導證件全碼

POST/api/v1/guides/{id}/pii/reveal
guide_pii.read模組:tour

參數

id路徑
string· min 1

嚮導 ID

field必填
enum
idNumberpassportNo

欲顯示全碼的證件欄位:idNumber 身分證字號、passportNo 護照號碼

回應欄位 · data

field
"idNumber" | "passportNo"

本次解密的欄位:idNumber 身分證字號 / passportNo 護照號碼。

value
string | null

解密後的證件全碼;null = 該欄未填。每次呼叫都會寫入解密稽核紀錄。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guides/<id>/pii/reveal" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "field": "idNumber"
}'
回應
{
  "ok": true,
  "data": {
    "field": "idNumber",
    "value": "…"
  }
}

嚮導批次匯入 commit:上傳檔

POST/api/v1/guides/import
guide_pii.manage模組:tour

參數

filename必填
string· min 1

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

contentBase64必填
string· min 1

檔案內容的 base64 編碼字串(上限 5 MB)

回應欄位 · data

filename
string

已匯入的檔名。

result
object

匯入結果(新建 / 更新 / 失敗筆數與逐列結果)。

created
number

新建筆數。

updated
number

更新筆數。

failed
number

失敗筆數(含 dry-run 就是 error 的列)。

rows
object[]

逐列結果。

rowNumber
number

試算表列號。

status
"created" | "error" | "updated"

created 已建立 / updated 已更新 / error 失敗未寫入。

guideId
string | null

寫入的嚮導 id(成功列;部分寫入的失敗列也帶,指出哪位嚮導已被改過)。

name
string

暱稱。

message
string | null

失敗原因(error 列)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guides/import" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "example-filename",
  "contentBase64": "example-contentBase64"
}'
回應
{
  "ok": true,
  "data": {
    "filename": "…",
    "result": {
      "created": 0,
      "updated": 0,
      "failed": 0,
      "rows": [
        {
          "rowNumber": 0,
          "status": "created",
          "guideId": "…",
          "name": "…",
          "message": "…"
        }
      ]
    }
  }
}

嚮導批次匯入 dry-run:上傳檔

POST/api/v1/guides/import/validate
guide_pii.manage模組:tour

參數

filename必填
string· min 1

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

contentBase64必填
string· min 1

檔案內容的 base64 編碼字串(上限 5 MB)

回應欄位 · data

filename
string

已驗證的檔名。

result
object

試算(dry-run)結果(逐列預覽 + 彙總,不寫入)。

rows
object[]

逐列預覽。

rowNumber
number

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

status
"create" | "error" | "update"

create 新建 / update 更新既有嚮導 / error 不匯入。

message
string | null

錯誤原因(多個以「;」串接);非 error 列為 null。

name
string

暱稱。

guideId
string | null

對到的既有嚮導 id(update 列)。

matchedInactive
boolean

對到的既有嚮導是停用狀態(更新照做,不會重新啟用)。

legalName
string | null

正式姓名。

idNumberMask
string | null

身分證遮罩。

passportNoMask
string | null

護照遮罩。

birthDate
string | null

生日(YYYY-MM-DD)。

fields
string[]

這一列會寫入的欄位(表頭 canonical key)。

summary
object

彙總。

total
number

資料列總數。

create
number

會新建的列數。

update
number

會更新既有嚮導的列數。

error
number

有錯、不匯入的列數。

fileError選填
string | undefined

檔案層錯誤(壞檔 / 無表頭 / 超過列數上限);有值時 rows 為空。

請求
curl -X POST "https://your-tenant.example.com/api/v1/guides/import/validate" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "example-filename",
  "contentBase64": "example-contentBase64"
}'
回應
{
  "ok": true,
  "data": {
    "filename": "…",
    "result": {
      "rows": [
        {
          "rowNumber": 0,
          "status": "create",
          "message": "…",
          "name": "…",
          "guideId": "…",
          "matchedInactive": true,
          "legalName": "…",
          "idNumberMask": "…",
          "passportNoMask": "…",
          "birthDate": "…",
          "fields": [
            "…"
          ]
        }
      ],
      "summary": {
        "total": 0,
        "create": 0,
        "update": 0,
        "error": 0
      },
      "fileError": "…"
    }
  }
}
POST/api/v1/guides/roster-export
guide_pii.roster_export模組:tour

回應欄位 · data

kind
"toko.guide-roster"
version
1
exportedAt
string

ISO 8601 export time in UTC.

guides
object[]

Full tenant directory, including inactive guides. Ordered by stable ID.

id
string

Stable guide ID. Use this as the external join key.

status
"active" | "inactive"

active or inactive. Consumers must remove inactive guides from leader choices.

legalName
string | null

Legal name. Missing values remain null.

gender
"male" | "female" | "other" | null

Stored gender: male, female, or other. Never derived from the ID number.

birthDate
string | null

ISO date: YYYY-MM-DD.

idNumber
string | null

Full ID number, decrypted with the tenant and guide AAD.

phone
string | null

Stored contact phone. No format conversion.

email
string | null
address
string | null

Full address. The external form adapter must split this value.

emergencyContactName
string | null
emergencyContactPhone
string | null
nickname
string

Public display name. This does not replace the legal name.

請求
curl -X POST "https://your-tenant.example.com/api/v1/guides/roster-export" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "kind": "toko.guide-roster",
    "version": "…",
    "exportedAt": "…",
    "guides": [
      {
        "id": "…",
        "status": "active",
        "legalName": "…",
        "gender": "male",
        "birthDate": "…",
        "idNumber": "…",
        "phone": "…",
        "email": "…",
        "address": "…",
        "emergencyContactName": "…",
        "emergencyContactPhone": "…",
        "nickname": "…"
      }
    ]
  }
}

/journal

list/search 旅誌 posts

GET/api/v1/journal
journal.read

參數

status選填
enum
alldraftpublishedarchived

依狀態篩選:all 全部、draft 草稿、published 已發佈、archived 已封存

q選填
string

關鍵字搜尋(標題/內容)

page選填
integer

頁碼(從 1 起)

pageSize選填
integer· max 200

每頁筆數(上限 200)

回應欄位 · data

rows
object[]

本頁的手記文章列表。

id
string

手記文章 id(journalPost_ 前綴)。

slug
string

文章公開頁網址代稱(slug)。

title
string

文章標題。

excerpt
string | null

摘要(列表/SEO 用;可空)。

coverImageUrl
string | null

封面圖網址(可空)。

contentMdx
string

內文原始 MDX 內容。

authorGuideId
`guide_${string}` | null

作者嚮導 id(未指定作者時 null)。

length
number

Returns the length of a String object.

seoTitle
string | null

SEO 標題(覆寫 <title>;可空)。

seoDescription
string | null

SEO 描述(meta description;可空)。

ogImageUrl
string | null

Open Graph 分享圖網址(可空)。

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

文章狀態:draft 草稿/published 已發佈/archived 已封存。

publishedAt
string | null

首次發佈時間(尚未發佈為 null)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

total
number

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

page
number

目前頁碼(從 1 起)。

pageSize
number

每頁筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/journal" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
  }
}

create a 旅誌 post

POST/api/v1/journal
journal.manage

參數

title必填
string· max 200 · min 1

手記標題,顯示於前台與後台列表

slug選填
string· 格式限定

網址代稱(slug);僅小寫英數與連字號,省略時由系統依標題產生

excerpt選填
string· max 1000

摘要,列表與分享預覽用;null 清除

coverImageUrl選填
string· max 2000

封面圖網址(http/https 或本站圖庫資產路徑);null 清除

contentMdx必填
string· max 100000 · min 1

內文(MDX 格式)

authorGuideId選填
string

作者嚮導 ID;null 表示無指定作者

seoTitle選填
string· max 200

SEO 標題,省略時用 title;null 清除

seoDescription選填
string· max 500

SEO 描述(meta description);null 清除

ogImageUrl選填
string· max 2000

Open Graph 分享圖網址(http/https 或本站圖庫資產路徑);null 清除

status選填
enum
draftpublishedarchived

發佈狀態:draft 草稿、published 已發佈、archived 已封存

回應欄位 · data

id
string

新建立的手記文章 id。

slug
string

文章公開頁網址代稱(slug)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/journal" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "example-title",
  "contentMdx": "example-contentMdx"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…"
  }
}

full 旅誌 post detail

GET/api/v1/journal/{id}
journal.read

參數

id路徑
string· min 1

旅誌文章 ID

回應欄位 · data

id
string

手記文章 id(journalPost_ 前綴)。

slug
string

文章公開頁網址代稱(slug)。

title
string

文章標題。

excerpt
string | null

摘要(列表/SEO 用;可空)。

coverImageUrl
string | null

封面圖網址(可空)。

contentMdx
string

內文原始 MDX 內容。

authorGuideId
`guide_${string}` | null

作者嚮導 id(未指定作者時 null)。

length
number

Returns the length of a String object.

seoTitle
string | null

SEO 標題(覆寫 <title>;可空)。

seoDescription
string | null

SEO 描述(meta description;可空)。

ogImageUrl
string | null

Open Graph 分享圖網址(可空)。

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

文章狀態:draft 草稿/published 已發佈/archived 已封存。

publishedAt
string | null

首次發佈時間(尚未發佈為 null)。

createdAt
string

建檔時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/journal/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "slug": "…",
    "title": "…",
    "excerpt": "…",
    "coverImageUrl": "…",
    "contentMdx": "…",
    "authorGuideId": "…",
    "seoTitle": "…",
    "seoDescription": "…",
    "ogImageUrl": "…",
    "status": "archived",
    "publishedAt": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}

update a 旅誌 post

PATCH/api/v1/journal/{id}
journal.manage

參數

title必填
string· max 200 · min 1

手記標題,顯示於前台與後台列表

slug選填
string· 格式限定

網址代稱(slug);僅小寫英數與連字號,省略時由系統依標題產生

excerpt選填
string· max 1000

摘要,列表與分享預覽用;null 清除

coverImageUrl選填
string· max 2000

封面圖網址(http/https 或本站圖庫資產路徑);null 清除

contentMdx必填
string· max 100000 · min 1

內文(MDX 格式)

authorGuideId選填
string

作者嚮導 ID;null 表示無指定作者

seoTitle選填
string· max 200

SEO 標題,省略時用 title;null 清除

seoDescription選填
string· max 500

SEO 描述(meta description);null 清除

ogImageUrl選填
string· max 2000

Open Graph 分享圖網址(http/https 或本站圖庫資產路徑);null 清除

id路徑
string· min 1

旅誌文章 ID

status選填
enum
draftpublishedarchived

發佈狀態:draft 草稿、published 已發佈、archived 已封存;省略時沿用現值

回應欄位 · data

ok
boolean

更新成功旗標,恆為 true。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/journal/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "example-title",
  "contentMdx": "example-contentMdx"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

archive a 旅誌 post

POST/api/v1/journal/{id}/archive
journal.manage

參數

id路徑
string· min 1

旅誌文章 ID

回應欄位 · data

ok
boolean

封存成功旗標,恆為 true。

請求
curl -X POST "https://your-tenant.example.com/api/v1/journal/<id>/archive" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

active guides as author options for journal

GET/api/v1/journal/authors
journal.read

回應欄位 · data[]

value
string

作者嚮導 id(作為選項值)。

label
string

顯示用的嚮導姓名。

請求
curl -X GET "https://your-tenant.example.com/api/v1/journal/authors" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "value": "…",
      "label": "…"
    }
  ]
}

/rooms

指派旅客進房

POST/api/v1/rooms/{roomId}/travelers
departure.update模組:tour

參數

roomId路徑
string· min 1

目標房間 ID,旅客將被指派入住此房

travelerId必填
string· min 1

欲指派的旅客 ID,須與房間屬於同一梯次

回應欄位 · data

ok
boolean

指派入房成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

請求
curl -X POST "https://your-tenant.example.com/api/v1/rooms/<roomId>/travelers" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "travelerId": "example-travelerId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}

把旅客移出房間

DELETE/api/v1/rooms/travelers/{travelerId}
departure.update模組:tour

參數

travelerId路徑
string· min 1

欲移出房間的旅客 ID

回應欄位 · data

ok
boolean

移出房間成功旗標,恆為 true。

retentionDeferred
boolean

true = 回訪期間尚未同步,每日排程會補做;本次操作已完成。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/rooms/travelers/<travelerId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "retentionDeferred": true
  }
}

/exchange-rates

list the Bank-of-Taiwan published FX rate board

GET/api/v1/exchange-rates
account_transfer.read模組:accounting

參數

currency選填
string

幣別篩選(ISO 4217 三碼,如 JPY / USD);省略則回傳所有幣別

monthFrom選填
string· 格式限定

起始月份(YYYY-MM,含當月);省略則不設下界

monthTo選填
string· 格式限定

結束月份(YYYY-MM,含當月);省略則不設上界

回應欄位 · data[]

id
string

匯率牌價列 ID。

rateDate
string

掛牌日期('YYYY-MM-DD',Asia/Taipei)。

currency
string

ISO 4217('JPY' / 'IDR' / 'USD'…)。

cashBuy
string | null

各報價 canonical「1 外幣 = ? 台幣」(numeric → 字串原值保精度;NULL = 該幣別無此報價)。

cashSell
string | null

現金賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。

spotBuy
string | null

即期買入匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。

spotSell
string | null

即期賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。

source
"bot" | "manual"

牌價來源:bot 台銀自動抓取 / manual 租戶手動覆蓋。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/exchange-rates" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "rateDate": "…",
      "currency": "…",
      "cashBuy": "…",
      "cashSell": "…",
      "spotBuy": "…",
      "spotSell": "…",
      "source": "bot",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

manual FX rate override

PUT/api/v1/exchange-rates/manual
account_transfer.manage

參數

rateDate必填
string· 格式限定

匯率掛牌日期(YYYY-MM-DD),與幣別共同決定覆蓋哪一筆牌價

currency必填
string· 格式限定

幣別(ISO 4217 三碼大寫,如 JPY / USD)

cashBuy選填
string· 格式限定

現金買入匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

cashSell選填
string· 格式限定

現金賣出匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

spotBuy選填
string· 格式限定

即期買入匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

spotSell選填
string· 格式限定

即期賣出匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null

回應欄位 · data

ok
boolean

是否覆蓋寫入成功。

id
string

寫入 / 更新的 manual 匯率牌價列 ID。

請求
curl -X PUT "https://your-tenant.example.com/api/v1/exchange-rates/manual" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rateDate": "2026-10-13",
  "currency": "TWD"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

resolve the canonical "1 foreign unit =

GET/api/v1/exchange-rates/resolve
account_transfer.read

參數

currency必填
string· min 1

要換算的外幣幣別(ISO 4217 三碼,如 JPY / USD)

date必填
string· 格式限定

換算基準日期(YYYY-MM-DD),套用手動優先 + 往前承接的解析規則

quote選填
enum
cash_buycash_sellspot_buyspot_sell

報價類型:cash_buy 現金買入、cash_sell 現金賣出、spot_buy 即期買入、spot_sell 即期賣出;省略預設 spot_sell

回應欄位 · data

currency
string

換算的外幣幣別(ISO 4217 三碼)。

date
string

換算基準日期(YYYY-MM-DD)。

quote
"cash_buy" | "cash_sell" | "spot_buy" | "spot_sell"

使用的報價類型(cash_buy / cash_sell / spot_buy / spot_sell)。

rate
string | null

解析出的匯率「1 外幣 = ? 台幣」(字串保精度);查無適用牌價為 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/exchange-rates/resolve?currency=example-currency&date=2026-10-13" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "currency": "…",
    "date": "…",
    "quote": "cash_buy",
    "rate": "…"
  }
}

/payment-requests

list/search/filter 對外應付

GET/api/v1/payment-requests
payable.read

參數

status選填
enum
draftsubmittedapprovedpaidrejectedcancelledall

依狀態篩選(draft 草稿 / submitted 已送審 / approved 已核准 / paid 已付款 / rejected 已退件 / cancelled 已取消 / all 全部)

payeeType選填
enum
all

依收款對象類型篩選(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他 / all 全部)

departureId選填
string

依關聯梯次 id 篩選

createdByUserId選填
string

依建單人 user id 篩選

q選填
string

關鍵字搜尋(請款單號、收款對象名稱等)

page選填
integer

頁碼(從 1 起算)

pageSize選填
integer· max 200

每頁筆數(上限 200)

回應欄位 · data

rows
object[]

本頁請款單列。

id
string

請款單 ID。

requestNumber
string

請款單號(人可讀,每租戶流水號)。

status
"approved" | "cancelled" | "draft" | "paid" | "rejected" | "submitted"

核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。

payeeType
"guide" | "other" | "staff_commission" | "supplier"

收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。

payeeName
string

收款對象名稱。

amountTwd
number

請款總額(TWD 整數;= 細項小計合計,代扣稅前)。

netAmountTwd
number

實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。

taxAmountTwd
number

代扣稅額(TWD 整數)。

departureId
string | null

關聯梯次 ID;未歸屬特定出團為 null。

departureLabel
string | null

關聯梯次顯示標籤(行程名稱+出發日);無則為 null。

description
string

請款單摘要說明。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string

建單人 user ID。

createdByName
string | null

建單人姓名;查無為 null。

paidAt
string | null

標記付款完成時間;未付為 null。

submittedAt
string | null

送審時間;未送審為 null。

approvedAt
string | null

核准時間;未核准為 null。

paperSignedBy
string | null

紙本簽核人;未簽為 null。

total
number

符合篩選條件的總筆數(跨全部分頁)。

page
number

目前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payment-requests" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
  }
}
POST/api/v1/payment-requests
payable.create

參數

payeeType必填
enum
supplierguidestaff_commissionother

收款對象類型(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他)

payeeName必填
string· min 1

收款對象名稱

payeeBankAccount選填
string

收款銀行帳號

payeeBankName選填
string

收款銀行名稱

payeeBankBranch選填
string

收款銀行分行

payeeTaxId選填
string

收款對象統一編號 / 稅籍編號

departureId選填
string

關聯梯次 id(將此請款歸屬至特定出團)

description必填
string· min 1

請款單摘要說明

taxAmountTwd選填
integer

稅額(TWD),未填視為 0

items必填
array· min 1

請款細項陣列(至少一筆)

submitImmediately選填
boolean

是否建立後立即送審(true 則同交易送出,跳過草稿)

回應欄位 · data

id
string

新建立請款單的 id。

requestNumber
string

新建立請款單的單號(人可讀)。

status
"approved" | "cancelled" | "draft" | "paid" | "rejected" | "submitted"

建立後狀態(draft,或 submitImmediately 時為 submitted)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "payeeType": "supplier",
  "payeeName": "example-payeeName",
  "description": "example-description",
  "items": [
    {
      "category": "example-category",
      "description": "example-description",
      "quantity": 1,
      "unitPriceTwd": 1
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "requestNumber": "…",
    "status": "approved"
  }
}

單一對外應付請款單完整明細

GET/api/v1/payment-requests/{id}
payable.read

參數

id路徑
string· min 1

請款單 id(路徑參數)

回應欄位 · data

payeeBankAccount
string | null

收款銀行帳號。

payeeBankName
string | null

收款銀行名稱。

payeeBankBranch
string | null

收款銀行分行。

payeeTaxId
string | null

收款對象統一編號 / 稅籍編號。

submittedByUserId
string | null

送審人 user ID;未送審為 null。

submissionEventId
string | null

Audit event for the current submission.

submittedByName
string | null

送審人姓名;無則為 null。

approvedByUserId
string | null

核准人 user ID;未核准為 null。

approvedByName
string | null

核准人姓名;無則為 null。

paidByUserId
string | null

標記付款人 user ID;未付為 null。

paidByName
string | null

標記付款人姓名;無則為 null。

rejectedAt
string | null

退件時間;未退件為 null。

rejectedByName
string | null

退件人姓名;無則為 null。

rejectionReason
string | null

退件原因;無則為 null。

cancelledAt
string | null

取消時間;未取消為 null。

cancelledByName
string | null

取消人姓名;無則為 null。

cancellationReason
string | null

取消原因;無則為 null。

pdfGeneratedAt
string | null

請款單 PDF 產生時間;未產生為 null。

paperPrintedAt
string | null

紙本列印時間;未列印為 null。

bankReference
string | null

銀行匯款交易參考號(付款後回填);無則為 null。

sourceType
string | null

來源類別(`departure_cost` 梯次成本 / `profit_share` 折扣碼分潤 / `migration` 匯入); 手動建單為 null。**非 null = 細項與來源列連動,不可編輯**(見 `updatePaymentRequest`)。

items
object[]

請款細項清單。

id
string

請款細項 ID。

category
string

細項類別(如住宿、交通、餐食)。

description
string

細項說明。

quantity
number

數量。

unitPriceTwd
number

單價(TWD 整數;負值表折讓)。

totalTwd
number

細項小計(TWD 整數;= 數量 × 單價)。

notes
string | null

細項備註;無則為 null。

sortOrder
number

顯示排序(由小到大)。

audit
object[]

稽核軌跡(狀態機每次轉移一筆,時間新到舊或建立序)。

id
string

稽核記錄 ID。

action
string

動作代號(如 payable.create、payable.submit、payable.approve)。

createdAt
string

動作發生時間。

actorUserId
string | null

操作者 user ID;系統動作為 null。

actorName
string | null

操作者姓名;無則為 null。

metadata
unknown

動作附帶的結構化資料(欄位隨 action 而定)。

ipAddress
string | null

操作來源 IP;無則為 null。

id
string

請款單 ID。

requestNumber
string

請款單號(人可讀,每租戶流水號)。

status
"approved" | "cancelled" | "draft" | "paid" | "rejected" | "submitted"

核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。

payeeType
"guide" | "other" | "staff_commission" | "supplier"

收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。

payeeName
string

收款對象名稱。

amountTwd
number

請款總額(TWD 整數;= 細項小計合計,代扣稅前)。

netAmountTwd
number

實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。

taxAmountTwd
number

代扣稅額(TWD 整數)。

departureId
string | null

關聯梯次 ID;未歸屬特定出團為 null。

departureLabel
string | null

關聯梯次顯示標籤(行程名稱+出發日);無則為 null。

description
string

請款單摘要說明。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string

建單人 user ID。

createdByName
string | null

建單人姓名;查無為 null。

paidAt
string | null

標記付款完成時間;未付為 null。

submittedAt
string | null

送審時間;未送審為 null。

approvedAt
string | null

核准時間;未核准為 null。

paperSignedBy
string | null

紙本簽核人;未簽為 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payment-requests/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
  }
}
PATCH/api/v1/payment-requests/{id}
payable.create

參數

id路徑
string· min 1

請款單 id(路徑參數)

payeeType必填
enum
supplierguidestaff_commissionother

收款對象類型(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他)

payeeName必填
string· min 1

收款對象名稱

payeeBankAccount選填
string

收款銀行帳號;null 清空

payeeBankName選填
string

收款銀行名稱;null 清空

payeeBankBranch選填
string

收款銀行分行;null 清空

payeeTaxId選填
string

收款對象統一編號 / 稅籍編號;null 清空

departureId選填
string

關聯梯次 id;null 清空

description必填
string· min 1

請款單摘要說明

taxAmountTwd選填
integer

代扣稅額(TWD);省略則不動

items選填
array· min 1

請款細項陣列(整批取代);省略則不動細項

回應欄位 · data

ok
boolean

是否更新成功。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/payment-requests/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "payeeType": "supplier",
  "payeeName": "example-payeeName",
  "description": "example-description"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

核准請款單

POST/api/v1/payment-requests/{id}/approve
payable.approve

參數

id路徑
string· min 1

請款單 id(路徑參數)

operationId必填
string· max 128 · min 1

同次操作重試須沿用的識別

expectedSubmissionId必填
string· min 1

明細回傳的 submissionEventId

回應欄位 · data

ok
boolean

原核准操作已完成;重試不代表目前狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests/<id>/approve" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operationId": "payable-approve-20261023-001",
  "expectedSubmissionId": "al_example_submission"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

取消請款單

POST/api/v1/payment-requests/{id}/cancel
payable.cancel

參數

id路徑
string· min 1

請款單 id(路徑參數)

reason選填
string

取消原因;留空預設為「使用者取消」(上限 200 字)

回應欄位 · data

ok
boolean

是否取消成功(idempotent,已取消再呼叫仍為 true)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests/<id>/cancel" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

標記請款單已付

POST/api/v1/payment-requests/{id}/mark-paid
payable.mark_paid

參數

id路徑
string· min 1

請款單 id(路徑參數)

bankReference必填
string· min 1

網銀交易序號 / 轉帳憑證號(必填)

paperSignedBy選填
string

紙本簽核人姓名

receivingAccountId選填
string

出款帳戶 id(從哪個收款帳戶付出)

回應欄位 · data

ok
boolean

是否標記付款成功(approved→paid)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests/<id>/mark-paid" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "bankReference": "example-bankReference"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

標記 PDF/紙本已產生

POST/api/v1/payment-requests/{id}/mark-printed
payable.print

參數

id路徑
string· min 1

請款單 id(路徑參數)

回應欄位 · data

ok
boolean

是否標記 PDF / 紙本已產生成功(idempotent)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests/<id>/mark-printed" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

記錄紙本簽核人

POST/api/v1/payment-requests/{id}/mark-signed
payable.create

參數

id路徑
string· min 1

請款單 id(路徑參數)

signedBy必填
string· min 1

紙本簽核人姓名(必填)

回應欄位 · data

ok
boolean

是否記錄紙本簽核人成功。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests/<id>/mark-signed" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "signedBy": "example-signedBy"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

退回請款單

POST/api/v1/payment-requests/{id}/reject
payable.approve

參數

id路徑
string· min 1

請款單 id(路徑參數)

operationId必填
string· max 128 · min 1

同次操作重試須沿用的識別

expectedSubmissionId必填
string· min 1

明細回傳的 submissionEventId

reason必填
string· min 1

退件原因(必填,回饋給建單人)

回應欄位 · data

ok
boolean

原退回操作已完成;重試不代表目前狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests/<id>/reject" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operationId": "payable-reject-20261023-001",
  "expectedSubmissionId": "al_example_submission",
  "reason": "Please check the request details."
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

送審請款單

POST/api/v1/payment-requests/{id}/submit
payable.submit

參數

id路徑
string· min 1

請款單 id(路徑參數)

operationId必填
string· max 128 · min 1

同次操作重試須沿用的識別

回應欄位 · data

ok
boolean

原送審操作已完成;重試不代表目前狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payment-requests/<id>/submit" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operationId": "payable-submit-20261023-001"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

對外應付請款單 KPI 計數

GET/api/v1/payment-requests/stats
payable.read

回應欄位 · data

draftCount
number

草稿狀態的請款單數。

submittedCount
number

已送審待核准的請款單數。

approvedCount
number

已核准待付款的請款單數。

paidCount
number

已付款的請款單數。

thisMonthPaidCount
number

本月已付款的請款單數。

thisMonthAmount
number

本月已付款的實付淨額合計(TWD 整數;台北月起算)。

totalApprovedAmount
number

已核准未付的實付淨額合計(TWD 整數;待出款金額)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payment-requests/stats" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "draftCount": 0,
    "submittedCount": 0,
    "approvedCount": 0,
    "paidCount": 0,
    "thisMonthPaidCount": 0,
    "thisMonthAmount": 0,
    "totalApprovedAmount": 0
  }
}

由某梯次的

GET/api/v1/payment-requests/supplier-suggestions
payable.create

參數

departureId必填
string· min 1

梯次 id;用於推導該梯次住宿供應商的請款細項建議

回應欄位 · data[]

category
string

建議的請款細項類別(如住宿)。

description
string

建議的細項說明(住宿廠商 × 房型 × 晚數)。

quantity
number

建議數量(間數 × 晚數)。

unitPriceTwd
number

建議單價(TWD 整數;每間每晚成本)。

totalTwd
number

建議小計(TWD 整數;= 數量 × 單價)。

suggestedPayee
string | null

建議的收款對象(住宿供應商名稱);查無為 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payment-requests/supplier-suggestions?departureId=example-departureId" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "category": "…",
      "description": "…",
      "quantity": 0,
      "unitPriceTwd": 0,
      "totalTwd": 0,
      "suggestedPayee": "…"
    }
  ]
}

/payments

list/search/filter the customer→agency payment ledger

GET/api/v1/payments
payment.read

參數

departureId選填
string· min 1

依梯次 ID 篩選

status選填
string

依金流狀態篩選(paid 已收款 / pending 待付 / failed 失敗或逾期 / refunded 已退款 / needs_manual_review 需人工核對退款)

method選填
string

依付款方式篩選(如信用卡、ATM 轉帳)

dateFrom選填
string

收款日期區間起日(YYYY-MM-DD)

dateTo選填
string

收款日期區間迄日(YYYY-MM-DD)

q選填
string

關鍵字搜尋(訂單編號、客戶名稱等)

page選填
integer

頁碼(從 1 起算)

pageSize選填
integer· max 200

每頁筆數(上限 200)

回應欄位 · data

rows
object[]

本頁付款嘗試列。

reconciliationTransactions
object[]
id
string
amountTwd
number
accountName
string | null
status
"matched" | "pending" | "unassigned" | "unsupported"
id
string

付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。

orderId
string

所屬訂單 ID。

orderNumber
string

所屬訂單編號(人可讀)。

merchantTradeNo
string

provider_order_ref(= 我們產的 MerchantTradeNo)。

providerTradeNo
string | null

金流商回傳的交易序號(未成交或手動入帳為 null)。

provider
string

金流商代號(如 ecpay、test;手動入帳為 manual)。

paymentMethod
string

付款方式(如信用卡、ATM 虛擬帳號)。

amountTwd
number

此筆嘗試的金額(TWD 整數)。

purpose
string

收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。

receivingAccountName
string | null

錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。

status
string

attempt 狀態:pending | submitted | succeeded | failed | expired。

refunded
boolean

此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。

needsManualReview
boolean

此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。

paidAt
string | null

實際入帳(現金結算)時間;未結算為 null。

bankCreditedOn
string | null

銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。

createdAt
string

此筆付款嘗試的建立時間。

customerName
string

付款客戶姓名。

customerEmail
string

付款客戶 email。

tripTitle
string

訂單對應的行程名稱。

total
number

符合篩選條件的總筆數(跨全部分頁)。

page
number

目前頁碼(從 1 起算)。

pageSize
number

每頁筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payments" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "reconciliationTransactions": [
          {
            "id": "…",
            "amountTwd": 0,
            "accountName": "…",
            "status": "matched"
          }
        ],
        "id": "…",
        "orderId": "…",
        "orderNumber": "…",
        "merchantTradeNo": "…",
        "providerTradeNo": "…",
        "provider": "…",
        "paymentMethod": "…",
        "amountTwd": 0,
        "purpose": "…",
        "receivingAccountName": "…",
        "status": "…",
        "refunded": true,
        "needsManualReview": true,
        "paidAt": "…",
        "bankCreditedOn": "…",
        "createdAt": "…",
        "customerName": "…",
        "customerEmail": "…",
        "tripTitle": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}

匯出金流分類帳

GET/api/v1/payments/export
payment.read

參數

status選填
string

依金流狀態篩選(如 paid 已收款 / pending 待付 / failed 失敗 / refunded 已退款)

method選填
string

依付款方式篩選(如信用卡、ATM 轉帳)

dateFrom選填
string

收款日期區間起日(YYYY-MM-DD)

dateTo選填
string

收款日期區間迄日(YYYY-MM-DD)

q選填
string

關鍵字搜尋(訂單編號、客戶名稱等)

回應欄位 · data

rows
object[]

符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。

reconciliationTransactions
object[]
id
string
amountTwd
number
accountName
string | null
status
"matched" | "pending" | "unassigned" | "unsupported"
id
string

付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。

orderId
string

所屬訂單 ID。

orderNumber
string

所屬訂單編號(人可讀)。

merchantTradeNo
string

provider_order_ref(= 我們產的 MerchantTradeNo)。

providerTradeNo
string | null

金流商回傳的交易序號(未成交或手動入帳為 null)。

provider
string

金流商代號(如 ecpay、test;手動入帳為 manual)。

paymentMethod
string

付款方式(如信用卡、ATM 虛擬帳號)。

amountTwd
number

此筆嘗試的金額(TWD 整數)。

purpose
string

收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。

receivingAccountName
string | null

錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。

status
string

attempt 狀態:pending | submitted | succeeded | failed | expired。

refunded
boolean

此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。

needsManualReview
boolean

此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。

paidAt
string | null

實際入帳(現金結算)時間;未結算為 null。

bankCreditedOn
string | null

銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。

createdAt
string

此筆付款嘗試的建立時間。

customerName
string

付款客戶姓名。

customerEmail
string

付款客戶 email。

tripTitle
string

訂單對應的行程名稱。

total
number

符合篩選條件的總筆數。

truncated
boolean

是否因達安全上限而截斷(true 表未回傳完整結果,呼叫端應提示)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payments/export" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "reconciliationTransactions": [
          {
            "id": "…",
            "amountTwd": 0,
            "accountName": "…",
            "status": "matched"
          }
        ],
        "id": "…",
        "orderId": "…",
        "orderNumber": "…",
        "merchantTradeNo": "…",
        "providerTradeNo": "…",
        "provider": "…",
        "paymentMethod": "…",
        "amountTwd": 0,
        "purpose": "…",
        "receivingAccountName": "…",
        "status": "…",
        "refunded": true,
        "needsManualReview": true,
        "paidAt": "…",
        "bankCreditedOn": "…",
        "createdAt": "…",
        "customerName": "…",
        "customerEmail": "…",
        "tripTitle": "…"
      }
    ],
    "total": 0,
    "truncated": true
  }
}

payment KPI counts

GET/api/v1/payments/stats
payment.read

回應欄位 · data

pendingReconciliationCount
number
totalAmount
number

累計實收現金(payment_transactions in)。

paidCount
number

已成功收款的付款嘗試數。

paidEcpayCount
number

已成功收款裡走綠界(provider = ecpay)的嘗試數。

paidAtmCount
number

已成功收款裡走虛擬 ATM(method = atm)的嘗試數。

pendingCount
number

待付 / 處理中的付款嘗試數(pending、submitted)。

failedCount
number

失敗或逾期的付款嘗試數(failed、expired)。

refundedCount
number

有關聯退款 / 退單的付款嘗試數。

needsManualReviewCount
number

近期需要人工核對後退款的付款嘗試數。只算最近 90 天收到的異常回呼;更早的紀錄仍會 帶著 `PaymentRow.needsManualReview`,用 `status=needs_manual_review` 篩選查得到。

thisMonthAmount
number

本月累計實收現金(TWD 整數)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payments/stats" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "pendingReconciliationCount": 0,
    "totalAmount": 0,
    "paidCount": 0,
    "paidEcpayCount": 0,
    "paidAtmCount": 0,
    "pendingCount": 0,
    "failedCount": 0,
    "refundedCount": 0,
    "needsManualReviewCount": 0,
    "thisMonthAmount": 0
  }
}

/reconciliation

逐收款帳戶現金進出對帳

GET/api/v1/reconciliation/accounts
receiving_account.read

參數

dateFrom選填
string

對帳期間起日(YYYY-MM-DD,含當日),以 Asia/Taipei 牆鐘日界計;省略則不設下界

dateTo選填
string

對帳期間迄日(YYYY-MM-DD,含整日),以 Asia/Taipei 牆鐘日界計;省略則不設上界

回應欄位 · data[]

accountId
string | null

收款帳戶 id;null = 未歸戶桶。

code
string | null

帳戶代碼;未歸戶桶為 null。

displayName
string | null

帳戶顯示名;未歸戶桶為 null。

kind
ReceivingAccountKind | null

帳戶類型(bank / cash / gateway);未歸戶桶為 null。

inTwd
number

期間內 direction='in' 的金額合計。

outTwd
number

期間內 payment_transactions direction='out' 的金額合計(客戶退款 / gateway 出)。

payableOutTwd
number

期間內供應商出款合計(payables paid 的 net_amount_twd;非 order-scoped,獨立來源 §3.1)。 **不含掛出款批次的 payable**(payout_batch_line_id 非 NULL)——批次出帳事實是一筆 account_transfers(銀行一筆 net),個別 payable 再計入即雙計。

transferInTwd
number

期間內帳戶間移轉**轉入**合計(account_transfers to 端 amount_twd;spec §3.2 / §3.3 口徑)。 排除 refund_payout(markRefundPaid 同 tx 雙寫,現金列已計入 outTwd)與沖正列 / 被沖正列 (更正記錄,非銀行流水)。

transferOutTwd
number

期間內帳戶間移轉**轉出**合計(from 端 amount_twd + fee_twd 實際離帳額;同上排除規則)。

netTwd
number

淨額 = in + transferIn − out − payableOut − transferOut(純現金流向;對帳找銀行入帳用毛額)。

txCount
number

期間內這帳戶的活動筆數(payment_transactions + payables paid + 移轉兩側)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/accounts" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "accountId": "…",
      "code": "…",
      "displayName": "…",
      "kind": null,
      "inTwd": 0,
      "outTwd": 0,
      "payableOutTwd": 0,
      "transferInTwd": 0,
      "transferOutTwd": 0,
      "netTwd": 0,
      "txCount": 0
    }
  ]
}

未結掛帳追蹤

GET/api/v1/reconciliation/obligations
account_settlement.read模組:accounting

參數

period選填
string

月結來源期間(YYYY-MM),篩選由該期月結互抵推導出的掛帳;省略則不限期間

reason選填
string

掛帳原因代碼,篩選特定成因的掛帳;省略則不限原因

status選填
string

掛帳狀態(如未結清 / 已結清),篩選特定結清狀態;省略則含全部

回應欄位 · data[]

id
string

帳戶間掛帳 ID。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補目標總額(TWD 整數,恆正)。

settledAmountTwd
number

已結清金額(TWD 整數,0 ≤ settled ≤ amount)。

outstandingTwd
number

待結餘額(派生 = amount − settled,>= 0)。

reason
"adjustment" | "advance_repayment" | "period_settlement" | "refund_advance"

掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。

originPeriod
string

產生月份(YYYY-MM,Asia/Taipei)。

status
"outstanding" | "partially_settled" | "settled"

結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。

note
string | null

備註;無則為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/obligations" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "debtorAccountId": "…",
      "creditorAccountId": "…",
      "amountTwd": 0,
      "settledAmountTwd": 0,
      "outstandingTwd": 0,
      "reason": "adjustment",
      "originPeriod": "…",
      "status": "outstanding",
      "note": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

收款帳戶目錄清單

GET/api/v1/reconciliation/receiving-accounts
receiving_account.read

參數

activeOnly選填
boolean

是否只回傳啟用中的收款帳戶(true/false);省略則含停用

回應欄位 · data[]

id
string

收款帳戶 ID。

code
string

帳戶代碼(租戶內唯一穩定識別)。

displayName
string

帳戶顯示名。

kind
"bank" | "cash" | "gateway"

帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。

gatewayProvider
string | null

綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `payment/gateway-providers.ts`。

bankName
string | null

銀行名稱;現金/閘道帳戶為 null。

accountNo
string | null

銀行帳號;現金/閘道帳戶為 null。

bankCode
string | null
bankBranch
string | null
accountHolder
string | null
canReceive
boolean

可收款(幾乎都 true)。

canRemit
boolean

可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。

canChargeback
boolean

可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。

canPaySupplier
boolean

付款渠道:出團準備的付款登記區可選它付供應商(#1375)。

isDeprecated
boolean

廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。

isSettlementMaster
boolean

主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。

payoutAccountId
string | null

撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。

currency
string

帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。

isActive
boolean

此帳戶是否啟用。

displayOrder
number

後台清單排序序位(小者在前)。

usedCount
number

被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。

currencyLocked
boolean

幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/receiving-accounts" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}

退款執行清單

GET/api/v1/reconciliation/refund-executions
account_settlement.read模組:accounting

參數

status選填
enum
approvedpaid

退款狀態篩選:approved 待執行(已核准)、paid 已執行(已出款);省略則合併回傳兩者

回應欄位 · data

rows
object[]

退款執行列(合併 approved 待執行 + paid 已執行,或收斂為指定段)。

creationSource
"manual" | "held_cash" | null
id
string

退款單 ID。

refundNumber
string

退款單號(人可讀,每租戶流水號)。

orderId
string

所屬訂單 ID。

orderNumber
string | null

所屬訂單編號(人可讀);無則為 null。

status
"approved" | "cancelled" | "draft" | "failed" | "paid" | "processing" | "submitted"

退款工作流狀態:draft / submitted / approved / processing / paid / failed / cancelled。

refundKind
"overpayment_return" | "receivable_reduction"

退款種類:receivable_reduction 減應收退款(取消 / 降價 / 服務失敗)/ overpayment_return 溢收退還(不動應收,只退多收現金)。

affectsReceivable
boolean

是否減少應收(receivable_reduction 為 true、overpayment_return 為 false;溢收退還不列入 refund_state)。

amountTwd
number

退款金額(TWD 整數,正值)。

method
"bank_transfer" | "cash" | "manual" | "original_gateway"

退款方式:original_gateway 原路退刷 / bank_transfer 銀行匯款 / cash 現金 / manual 手動。

reason
string

退款原因說明。

createdAt
string

退款單建立時間。

paidAt
string | null

實際退款出款(現金結算)時間;未執行為 null。

createdByName
string | null

建單人姓名;無則為 null。

executionMethod
RefundExecutionMethod | null

退款執行方法:chargeback 原信用卡刷退 / remit 匯出;未指定為 null。

gatewayExecutionMode選填
"manual" | "api" | undefined
gatewayNeedsReview
boolean

近 90 天已完成帳務、且明確記錄自動退刷降級的退款,需人工核對;不代表可重試。

originAccountId
string | null

出款來源帳戶 ID(從哪個收款帳戶退出);未指定為 null。

adminFeeTwd
number

內扣手續費(TWD 整數;自退款金額中扣除的行政費)。

remitFeeTwd
number

匯款手續費(TWD 整數;銀行匯出的轉帳費)。

payeeAccountName
string | null

收款人戶名(匯款退款用);無則為 null。

payeeBankCode
string | null

收款銀行代碼(匯款退款用);無則為 null。

payeeBranchCode
string | null

收款分行代碼(匯款退款用,選填);無則為 null。

payeeAccountNumber
string | null

收款帳號(匯款退款用);無則為 null。

customerName
string | null

訂購人姓名;無則為 null。

orderCancellationFeeTwd
number | null

所屬訂單的退改費(TWD 整數,公司收下不退的錢);未收退改費為 null。不含已付、不退的 換梯手續費(customer-cancellation §8.9),那筆寫在退款單事由。

orderCancellationReason
string | null

所屬訂單的取消事由:lottery_lost 未中籤 / group_not_confirmed 未成團 / customer_request 客人取消 / admin 後台取消 / no_show 未報到 / other 其他;未取消為 null。

paidByName
string | null

標記已退款的人;未執行為 null。

payoutAccountId
string | null

實際出款帳戶 ID(已執行退款的出帳現金列歸戶);未執行或未歸戶為 null。

waitingDays
number | null

從登記到現在已等待的天數;已退款、已失敗、已取消的退款單為 null。

total
number

回傳的退款執行筆數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/refund-executions" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "creationSource": "manual",
        "id": "…",
        "refundNumber": "…",
        "orderId": "…",
        "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
  }
}

子系統 B 月結互抵派生總覽

GET/api/v1/reconciliation/settlement-overview
account_settlement.read模組:accounting

參數

period必填
string· 格式限定

要查詢月結互抵總覽的結算期(YYYY-MM)

回應欄位 · data

period
string

結算月份(YYYY-MM,Asia/Taipei)。

matrix
object

兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。

lines
object[]

各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補淨額(恆正 > 0)。

components
object[]

組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。

label
string

組成項標籤(如某費用類型 / 代墊來源)。

amountTwd
number

簽名金額(相對 debtor→creditor 視角)。

unclassified
object

未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。

byAccount
object[]

landing 帳戶 → 未分類本金合計。

accountId
string | null

收款帳戶 ID;未歸戶為 null。

principalTwd
number

該帳戶未分類收款本金合計(TWD 整數)。

totalTwd
number

未分類收款本金總額(TWD 整數)。

obligations
object[]

本期相關掛帳(period_settlement + adjustment,含結清進度)。

id
string

帳戶間掛帳 ID。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補目標總額(TWD 整數,恆正)。

settledAmountTwd
number

已結清金額(TWD 整數,0 ≤ settled ≤ amount)。

outstandingTwd
number

待結餘額(派生 = amount − settled,>= 0)。

reason
"adjustment" | "advance_repayment" | "period_settlement" | "refund_advance"

掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。

originPeriod
string

產生月份(YYYY-MM,Asia/Taipei)。

status
"outstanding" | "partially_settled" | "settled"

結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。

note
string | null

備註;無則為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

carriedForward
object

跨期掛帳結轉基數(上期未結 period_settlement 殘額,已種入 matrix 淨額;此處供顯示明細 + 小計)。

lines
object[]

上期未結 period_settlement 殘額逐筆明細(已種入本期互抵基數)。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

outstandingTwd
number

殘額 = amount_twd − settled_amount_twd(恆正 > 0)。

originPeriod
string

原始產生月份(YYYY-MM,供顯示「來源期」)。

totalTwd
number

結轉殘額小計(TWD 整數)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/settlement-overview?period=2026-10" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
    }
  }
}

跑當期月結互抵派生 + upsert

POST/api/v1/reconciliation/settlement/compute
account_settlement.read模組:accounting

參數

period必填
string· 格式限定

要計算月結互抵的結算期(YYYY-MM),可重跑且冪等(不回退已結額)

回應欄位 · data

period
string

結算月份(YYYY-MM,Asia/Taipei)。

matrix
object

兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。

lines
object[]

各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

amountTwd
number

應補淨額(恆正 > 0)。

components
object[]

組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。

label
string

組成項標籤(如某費用類型 / 代墊來源)。

amountTwd
number

簽名金額(相對 debtor→creditor 視角)。

unclassified
object

未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。

byAccount
object[]

landing 帳戶 → 未分類本金合計。

accountId
string | null

收款帳戶 ID;未歸戶為 null。

principalTwd
number

該帳戶未分類收款本金合計(TWD 整數)。

totalTwd
number

未分類收款本金總額(TWD 整數)。

upserts
object[]

本次 run 對每條互抵列 upsert 的結果(含冪等護欄調整)。

debtorAccountId
string

欠款方(債務人)收款帳戶 ID。

creditorAccountId
string

收款方(債權人)收款帳戶 ID。

derivedAmountTwd
number

本次派生的目標淨額。

appliedAmountTwd
number

實際落地的掛帳 amount_twd(受冪等護欄約束,不低於已 settled)。

obligationId
string

對應的帳戶間掛帳 ID(本次 upsert 的目標列)。

action
"created" | "floored_to_settled" | "updated"

本次動作:created 新建 / updated 更新 / floored_to_settled 派生低於已結被護欄下限鎖住。

adjustmentTwd
number

派生與基準(原 amount + 已動帳 adjustment 簽名和)的差額絕對值(> 0 表示有缺口)。

adjustmentObligationId
string | null

缺口對應的引擎 adjustment 掛帳 id(新開或重跑沿用 / 改額的同一條;action='floored_to_settled' 時非 null)。

deletedObligationIds
string[]

本次 run 刪除的失效派生掛帳 id(settled=0 且不在新派生的 period_settlement + 被替換 / 失效的未結引擎 adjustment)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/settlement/compute" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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": [
      "…"
    ]
  }
}
GET/api/v1/reconciliation/statement-imports
bank_statement.read模組:accounting

參數

account必填
string· min 1

收款帳戶 ID,回傳該帳戶的對帳單批次 / 行 / 進度彙總

回應欄位 · data

imports
object[]

該帳戶的對帳單批次清單(新到舊)。

id
string

對帳單批次 ID。

periodStart
string

批次期間起日('YYYY-MM-DD',含當日)。

periodEnd
string

批次期間迄日('YYYY-MM-DD',含當日)。

filename
string

匯入的檔名。

createdAt
string

匯入時間。

lineCount
number

批內總行數。

autoCount
number

自動配對的行數。

manualCount
number

人工配對的行數。

unmatchedCount
number

尚未配對的行數。

ignoredCount
number

已略過(ignored)的行數。

excludedCount
number

已解除配對(excluded)的行數。

lines
object[]

該帳戶所有對帳單行(跨批次)。

id
string

對帳單行 ID。

importId
string

所屬對帳單批次 ID。

lineNo
number

檔案內行號(1 起算)。

txnDate
string

交易日期('YYYY-MM-DD')。

direction
"in" | "out"

現金流向:in 存入 / out 支出。

amountTwd
number

金額(TWD 整數)。

memo
string

摘要 / 備註文字。

status
string

配對狀態:unmatched 未配 / auto 自動 / manual 人工 / ignored 略過 / excluded 已解除。

matchedSourceType
string | null

已配對來源種類(payment_transaction / payable / account_transfer);未配為 null。

matchedSourceId
string | null

已配對來源 ID;未配為 null。

ignoredReason
string | null

略過原因;非 ignored 為 null。

progress
object

配對進度彙總。

total
number

總行數。

matched
number

已配對行數(auto + manual)。

unmatched
number

未配對行數。

ignored
number

已略過行數。

excluded
number

已解除配對行數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/statement-imports?account=example-account" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
    }
  }
}
POST/api/v1/reconciliation/statement-imports
bank_statement.manage模組:accounting

參數

receivingAccountId必填
string· min 1

收款帳戶 ID(僅支援 TWD 的 bank / cash 帳戶)

periodStart必填
string· 格式限定

對帳單期間起日(含當日)

periodEnd必填
string· 格式限定

對帳單期間迄日(含當日)

filename必填
string· min 1

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

contentBase64必填
string· min 1

對帳單檔案內容的 base64 編碼字串(固定範本填好後另存)

回應欄位 · data

importId
string

新建立的對帳單批次 ID。

autoMatched
number

匯入後即自動配對成功的行數。

unmatched
number

匯入後仍未配對的行數。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/statement-imports" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "receivingAccountId": "example-receivingAccountId",
  "periodStart": "2026-10-13",
  "periodEnd": "2026-10-13",
  "filename": "example-filename",
  "contentBase64": "example-contentBase64"
}'
回應
{
  "ok": true,
  "data": {
    "importId": "…",
    "autoMatched": 0,
    "unmatched": 0
  }
}

刪整批

DELETE/api/v1/reconciliation/statement-imports/{importId}
bank_statement.manage模組:accounting

參數

importId路徑
string· min 1

對帳單批次 ID

回應欄位 · data

ok
boolean

是否刪除整批成功(批內無人工痕跡才可刪)。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/reconciliation/statement-imports/<importId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

對該批

POST/api/v1/reconciliation/statement-imports/{importId}/auto-match
bank_statement.manage模組:accounting

參數

importId路徑
string· min 1

對帳單批次 ID

回應欄位 · data

matched
number

本輪新增自動配對的行數。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/statement-imports/<importId>/auto-match" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "matched": 0
  }
}

某帳戶內、未被

GET/api/v1/reconciliation/statement-imports/candidates
bank_statement.read模組:accounting

參數

account必填
string· min 1

收款帳戶 ID,回傳該帳戶未配對的 ERP 現金流水候選

回應欄位 · data[]

sourceType
"account_transfer" | "payable" | "payment_transaction"

ERP 來源種類:payment_transaction 收款交易 / payable 出款 / account_transfer 帳戶移轉。

sourceId
string

ERP 來源紀錄 ID。

date
string

'YYYY-MM-DD'(Asia/Taipei 牆鐘日)。

direction
"in" | "out"

現金流向:in 進帳 / out 出帳。

amountTwd
number

金額(TWD 整數)。

label
string

顯示標籤(來源摘要,供人工配對時辨識)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/statement-imports/candidates?account=example-account" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "sourceType": "account_transfer",
      "sourceId": "…",
      "date": "…",
      "direction": "in",
      "amountTwd": 0,
      "label": "…"
    }
  ]
}

銀行對帳單匯入固定範本下載

GET/api/v1/reconciliation/statement-imports/template
bank_statement.read模組:accounting

回應欄位 · data

filename
string

建議另存的檔名(.xlsx,含日期戳)。

contentBase64
string

範本 .xlsx 內容的 base64 編碼字串(CLI 端解碼另存)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/statement-imports/template" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "filename": "…",
    "contentBase64": "…"
  }
}

兩階段匯入的第一階段 dry-run

POST/api/v1/reconciliation/statement-imports/validate
bank_statement.manage模組:accounting

參數

receivingAccountId必填
string· min 1

收款帳戶 ID(僅支援 TWD 的 bank / cash 帳戶)

periodStart必填
string· 格式限定

對帳單期間起日(含當日)

periodEnd必填
string· 格式限定

對帳單期間迄日(含當日)

filename必填
string· min 1

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

contentBase64必填
string· min 1

對帳單檔案內容的 base64 編碼字串

回應欄位 · data

accountId
string

對帳的收款帳戶 ID。

periodStart
string

對帳單期間起日('YYYY-MM-DD',含當日)。

periodEnd
string

對帳單期間迄日('YYYY-MM-DD',含當日)。

filename
string

上傳檔名。

lines
object[]

解析後的各行預覽(含「若 commit 是否會被自動配對」)。

lineNo
number

檔案內行號(1 起算)。

txnDate
string

交易日期('YYYY-MM-DD')。

direction
"in" | "out"

現金流向:in 存入 / out 支出。

amountTwd
number

金額(TWD 整數)。

memo
string

摘要 / 備註文字。

willAuto
boolean

依本批行與目前候選估算的配對結果;不保證未來 commit 結果。

parseErrors
object[]

解析錯誤 + 期間外的行(依行號排序;commit 端會 fail-closed 拒)。

lineNo
number

出錯的對帳單行號(原始列,從 1 起算)。

message
string

錯誤說明(解析失敗原因或期間外提示)。

willAutoCount
number

若現在 commit,預計會被自動配對的行數。

willUnmatchedCount
number

若現在 commit,預計仍未配對的行數。

periodOverlap
boolean

宣告期間是否與既有批次重疊(commit 會被擋)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/statement-imports/validate" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "receivingAccountId": "example-receivingAccountId",
  "periodStart": "2026-10-13",
  "periodEnd": "2026-10-13",
  "filename": "example-filename",
  "contentBase64": "example-contentBase64"
}'
回應
{
  "ok": true,
  "data": {
    "accountId": "…",
    "periodStart": "…",
    "periodEnd": "…",
    "filename": "…",
    "lines": [
      {
        "lineNo": 0,
        "txnDate": "…",
        "direction": "in",
        "amountTwd": 0,
        "memo": "…",
        "willAuto": true
      }
    ],
    "parseErrors": [
      {
        "lineNo": 0,
        "message": "…"
      }
    ],
    "willAutoCount": 0,
    "willUnmatchedCount": 0,
    "periodOverlap": true
  }
}

略過一條對帳單行 →

POST/api/v1/reconciliation/statement-lines/{lineId}/ignore
bank_statement.manage模組:accounting

參數

lineId路徑
string· min 1

對帳單行 ID

reason必填
string· min 1

略過原因(必填;如「手續費」「利息」)

回應欄位 · data

ok
boolean

是否標記略過成功(狀態轉為 ignored)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/statement-lines/<lineId>/ignore" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

人工配對一條對帳單行到指定

POST/api/v1/reconciliation/statement-lines/{lineId}/match
bank_statement.manage模組:accounting

參數

lineId路徑
string· min 1

對帳單行 ID

sourceType必填
enum
payment_transactionpayableaccount_transfer

配對來源種類:payment_transaction / payable / account_transfer

sourceId必填
string· min 1

配對來源 ID(該帳戶內未被配對的 ERP 候選)

回應欄位 · data

ok
boolean

是否人工配對成功(同帳戶 / 同金額 / 同方向)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/statement-lines/<lineId>/match" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceType": "payment_transaction",
  "sourceId": "example-sourceId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

解除配對 → 'excluded'

POST/api/v1/reconciliation/statement-lines/{lineId}/unmatch
bank_statement.manage模組:accounting

參數

lineId路徑
string· min 1

對帳單行 ID

回應欄位 · data

ok
boolean

是否解除配對成功(狀態轉為 excluded)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/statement-lines/<lineId>/unmatch" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

帳戶間移轉統一分類帳查詢

GET/api/v1/reconciliation/transfers
account_settlement.read

參數

kind選填
string

移轉類型篩選(fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 外幣期初 / reversal 沖正 / payout_batch 出款批次匯出 / gateway_payout 金流商撥款);省略則含全部

account選填
string

帳戶 ID 篩選,回傳該帳戶為出帳或進帳方的移轉;省略則不限帳戶

dateFrom選填
string

移轉日期起日(YYYY-MM-DD,含當日);省略則不設下界

dateTo選填
string

移轉日期迄日(YYYY-MM-DD,含當日);省略則不設上界

settlementPeriod選填
string

對應月結期間(YYYY-MM)篩選;省略則不限月結

obligation選填
string

掛帳 ID 篩選,回傳沖減該筆掛帳的移轉;省略則不限掛帳

回應欄位 · data[]

id
string

帳戶間移轉 ID。

kind
"advance" | "backfill" | "fx_conversion" | "gateway_payout" | "opening" | "payout_batch" | "refund_payout" | "replenishment" | "reversal"

移轉類型:fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 期初 / reversal 沖正 / payout_batch 出款批次匯出(系統落帳)/ gateway_payout 金流商撥款。

fromAccountId
string | null

出帳帳戶 ID;期初等單邊移轉為 null。

toAccountId
string | null

進帳帳戶 ID;單邊移轉為 null。

amountTwd
number

移轉金額(TWD 整數)。

feeTwd
number

手續費(TWD 整數)。

currency
string | null

外幣幣別(ISO 4217;純台幣移轉為 null)。

foreignAmount
number | null

外幣金額(整數;非外幣移轉為 null)。

feeForeign
number | null

外幣手續費(整數;無則為 null)。

grossRate
string | null

換匯牌價(numeric → 字串原值保精度;顯示/溯源用)。

settlementPeriod
string | null

對應月結期間(YYYY-MM);未歸屬月結為 null。

obligationId
string | null

沖減的帳戶間掛帳 ID;未沖減掛帳為 null。

reversesTransferId
string | null

被本筆沖正的原移轉 ID(kind='reversal' 時非 null)。

occurredAt
string

移轉日期('YYYY-MM-DD',date 欄)。

note
string | null

備註;無則為 null。

createdByUserId
string

登錄人 user ID。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/transfers" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}
POST/api/v1/reconciliation/transfers
account_transfer.manage模組:accounting

參數

kind選填
enum· 前處理正規化(省略則補預設 / null)
fx_conversionreplenishmentadvancebackfillgateway_payoutreversal

移轉類型:fx_conversion 換匯、replenishment 補款、advance 代墊、backfill 回填、gateway_payout 金流商撥款、reversal 沖正(退款匯出 / 出款批次由退款 / 出款模組落帳,不由此登錄)

fromAccountId選填
string· min 1 · 前處理正規化

出帳(轉出)帳戶 ID;與進帳帳戶至少填一個,null 表示無出帳方

toAccountId選填
string· min 1 · 前處理正規化

進帳(轉入)帳戶 ID;與出帳帳戶至少填一個,null 表示無進帳方

amountTwd選填
integer· 前處理正規化(省略則補預設 / null)

移轉台幣淨額(整數,不可為負);沖減掛帳時須大於 0。金流商撥款填銀行實際入帳的撥款額

feeTwd選填
integer· 前處理正規化(省略則補預設 / null)

此筆移轉產生的手續費(台幣整數,不可為負)。金流商撥款填金流商從撥款內扣的手續費

occurredAt選填
string· 格式限定 · 前處理正規化

移轉發生日期(YYYY-MM-DD)

settlementPeriod選填
string· 格式限定 · 前處理正規化

對應月結期間(YYYY-MM),標記此移轉沖減哪一期互抵;換匯不掛單一月結,傳 null

currency選填
string· 格式限定 · 前處理正規化

換匯外幣幣別(ISO 4217 三碼);非換匯傳 null

foreignAmount選填
integer· 前處理正規化(省略則補預設 / null)

換匯外幣金額(整數最小單位,須大於 0);非換匯傳 null

grossRate選填
string· 格式限定 · 前處理正規化

換匯牌價(正數,最多 6 位小數,以字串表達避免精度遺失);非換匯傳 null

obligationId選填
string· 格式限定 · 前處理正規化

選填沖減的掛帳 ID(aob_ 開頭);換匯不沖減掛帳須傳 null

reversesTransferId選填
string· 格式限定 · 前處理正規化

沖正指向的原移轉 ID(atr_ 開頭);kind=reversal 必填,其餘傳 null

paymentTransactionIds選填
array· 前處理正規化(省略則補預設 / null)

金流商撥款包含的現金列 ID(ptxn_ 開頭):收款為加項、同帳戶的刷退為扣項;kind=gateway_payout 必填且至少一筆收款,須滿足「收款合計 − 刷退合計 − 手續費 = 撥款額」,其餘傳 null

回應欄位 · data

ok
boolean

是否登錄成功(移轉 + 沖減掛帳的原子交易皆完成)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/reconciliation/transfers" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "fx_conversion",
  "fromAccountId": "example-fromAccountId",
  "toAccountId": "example-toAccountId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

某金流商帳戶上

GET/api/v1/reconciliation/transfers/gateway-payout-candidates
account_transfer.read模組:accounting

參數

account必填
string· min 1

金流商(gateway)帳戶 ID,回傳該帳戶還沒被撥出的收款與刷退

回應欄位 · data[]

paymentTransactionId
string

現金列 ID。

direction
"in" | "out"

in = 收款(加項)/ out = 刷退(撥款內扣的扣項)。

orderId
string

訂單 ID。

orderNumber
string

訂單編號。

date
string

發生日('YYYY-MM-DD',Asia/Taipei 牆鐘)。

amountTwd
number

金額(TWD 整數,正數;刷退的正負看 direction)。

feeTwd
number

現金列記的金流手續費(TWD 整數;多為付款回呼宣告的估計值)。

providerTradeNo
string | null

金流訂單編號(金流商交易序號,或登記收款時填的編號;沒有為 null)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reconciliation/transfers/gateway-payout-candidates?account=example-account" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "paymentTransactionId": "…",
      "direction": "in",
      "orderId": "…",
      "orderNumber": "…",
      "date": "…",
      "amountTwd": 0,
      "feeTwd": 0,
      "providerTradeNo": "…"
    }
  ]
}

/accrual-ledger

掛帳台帳

GET/api/v1/accrual-ledger
ledger.read

參數

period必填
string· 格式限定

出團月(格式 YYYY-MM,Asia/Taipei 時區)

回應欄位 · data

period
string

結算期間(YYYY-MM,Asia/Taipei 出團月)。

departureSummary
object[]

梯次彙總(區塊 1):出團月落於 period 的各梯次收入 / 成本 / 毛利。

departureId
string

梯次 ID。

tripTitle
string

團名。

departureDate
string

出團日期(YYYY-MM-DD)。

pax
number

出團人數(該梯次確認人數)。

revenueTwd
number

總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。

cancellationFeeTwd
number

已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。

realCostTwd
number

真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。

grossProfitTwd
number

毛利毛估 = revenue − realCost(含房費)。

costLines
object[]

成本掛帳逐筆(區塊 2):該期梯次上所有 departure_costs 成本列。

id
string

成本列 ID。

tripTitle
string

團名。

departureDate
string

所屬梯次出團日期(YYYY-MM-DD)。

category
string

成本分類(如 交通 / 餐費 / 保險 / 嚮導)。

vendor
string | null

廠商:已建檔廠商名優先,否則用成本列上填寫的廠商名;null = 未填。

amountTwd
number

代墊額(真實成本,TWD 整數)。

invoiceAmountTwd
number

憑證額(外帳可申報金額,TWD 整數)。

isDeclarable
boolean

有無發票憑證。

reviewStatus
string

覆核狀態:掛了支出證明單則用其 status(pending/approved),否則由有無憑證派生。

payables
object[]

應付清單(區塊 3):該期歸屬的請款單(payables)。

payableNumber
string

請款單號(人類可讀)。

tripTitle
string

團名(未綁定梯次的手動請款顯示「未綁定梯次」)。

payeeName
string

受款對象(供應商 / 嚮導 / 派車人等)。

amountTwd
number

請款金額(整數 TWD)。

status
string

draft | submitted | approved | paid | cancelled | rejected。

receivables
object[]

應收清單(區塊 4):該期梯次上的 tour 訂單應收 / 實收 / 待收。

orderId
string

訂單 ID(後台訂單頁連結用)。

orderNumber
string

訂單編號。

tripTitle
string

團名(該訂單在期間內任一梯次的團名)。

departureDate
string

出團日(YYYY-MM-DD)。同一行程同月常有多個梯次(例:10/15、10/16、10/22 三梯), 只看團名分不出是哪一梯,追尾款時得靠這欄(issue 600)。 ⚠️ 與 `tripTitle` 同一列取出(兩欄必定同梯),但口徑同樣是「該訂單在期間內**任一** 梯次」:跨梯次訂單只顯示最早那一梯,而 `receivableTwd` 是整張單未攤提的應收。真正 逐梯辨識要把來源改成 per (order, departure) 並接上 `orders/allocation.ts` 的攤提, 屬系統級 follow-up,不在本欄範圍。

primaryTravelerName
string | null

主要旅客姓名:有標記 `is_primary` 取該列,沒標記就取最早建立的旅客(與 departure-prep / agreements / traveler-validation 同一套取法——匯入的歷史單 可能整單都沒標主要旅客)。訂單完全沒有旅客列時為 null。 刻意不取下單會員名:一張訂單的下單者與旅客常常不是同一人(CONTEXT.md「旅客」)。

receivableTwd
number

應收金額(TWD 整數)。

receivedTwd
number

實收金額(收款減退款,TWD 整數)。

outstandingTwd
number

待收 = receivable − received。

請求
curl -X GET "https://your-tenant.example.com/api/v1/accrual-ledger?period=2026-10" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
      }
    ]
  }
}

掛帳台帳的「梯次彙總」

GET/api/v1/accrual-ledger/departure-summary
ledger.read

參數

period必填
string· 格式限定

出團月(格式 YYYY-MM,Asia/Taipei 時區)

回應欄位 · data

period
string

結算期間(YYYY-MM,Asia/Taipei 出團月),回聲請求參數。

departureSummary
object[]

梯次彙總:出團月落於 period 的各梯次收入 / 真實成本 / 毛估毛利。

departureId
string

梯次 ID。

tripTitle
string

團名。

departureDate
string

出團日期(YYYY-MM-DD)。

pax
number

出團人數(該梯次確認人數)。

revenueTwd
number

總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。

cancellationFeeTwd
number

已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。

realCostTwd
number

真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。

grossProfitTwd
number

毛利毛估 = revenue − realCost(含房費)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/accrual-ledger/departure-summary?period=2026-10" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "period": "…",
    "departureSummary": [
      {
        "departureId": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "pax": 0,
        "revenueTwd": 0,
        "cancellationFeeTwd": 0,
        "realCostTwd": 0,
        "grossProfitTwd": 0
      }
    ]
  }
}

/cost-templates

list reusable series-tour cost templates

GET/api/v1/cost-templates
cost_template.read模組:tour

參數

status選填
enum
activearchived

依狀態篩選:active 啟用、archived 已封存

active選填
boolean

啟用時只回傳輕量的 { id, name } 綁定挑選清單(行程設定的成本範本下拉用)

回應欄位 · data[]

id
string

成本範本 id(ct_ 前綴)。

name
string

成本範本名稱。

請求
curl -X GET "https://your-tenant.example.com/api/v1/cost-templates" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…"
    }
  ]
}
POST/api/v1/cost-templates
cost_template.manage模組:tour

參數

name必填
string· max 120 · min 1

成本範本名稱

description選填
string· max 500

成本範本說明

status選填
enum
activearchived

範本狀態:active 啟用、archived 已封存

回應欄位 · data

id
string

新建成本範本 ID(ct_ 前綴)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/cost-templates" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

full cost-template detail

GET/api/v1/cost-templates/{id}
cost_template.read模組:tour

參數

id路徑
string· min 1

成本範本 ID

回應欄位 · data

lines
object[]

成本行明細(品項 × 單價 × 數量模型)。

id
string

成本行 ID。

templateId
string

所屬成本範本 ID。

category
string

成本分類(如 交通 / 餐費 / 保險)。

vendorName
string | null

供應商 / 廠商名(選填)。

description
string | null

摘要說明(選填)。

unitPriceTwd
number | null

TWD 行的單價;外幣行 null。

currency
string

幣別('TWD' = 台幣行)。

unitPriceForeign
number | null

外幣行的外幣單價;TWD 行 null。

internalRateSource
TemplateRateSource | null

外幣行的內帳匯率來源;TWD 行 null。

fxAccountId
string | null

internalRateSource='fx_account' 時的外幣帳戶 id。

quantityMode
"fixed" | "headcount"

數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。

quantityFixed
number | null

fixed 模式的固定數量;headcount 模式為 null。

headcountComponents
HeadcountComponent[] | null

headcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。

groupDivisor
number | null

headcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。

isDeclarable
boolean

是否預設有合法憑證(帶入成本列的 is_declarable 初值)。

sortOrder
number

顯示排序。

id
string

成本範本 ID。

name
string

範本名稱。

description
string | null

範本說明(選填)。

status
"active" | "archived"

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

lineCount
number

成本行數(派生)。

boundTripCount
number

綁定行程數(派生)。

appliedDepartureCount
number

套用過本範本的梯次數(派生:departure_costs 經 template_line_id 追溯)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/cost-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
  }
}
PATCH/api/v1/cost-templates/{id}
cost_template.manage模組:tour

參數

name必填
string· max 120 · min 1

成本範本名稱

description選填
string· max 500

成本範本說明

status選填
enum
activearchived

範本狀態:active 啟用、archived 已封存

id路徑
string· min 1

成本範本 ID

回應欄位 · data

ok
boolean

是否更新成功。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/cost-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

add a cost line to a template.

POST/api/v1/cost-templates/{id}/lines
cost_template.manage模組:tour

參數

id路徑
string· min 1

成本範本 ID

line必填
object

成本明細列:含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式(fixed 固定/headcount 人數)與對應數量/人數組成、isDeclarable 是否可報帳等欄位

回應欄位 · data

rateNotice
string | null

新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 null。

id
string

新建成本明細行 ID。

請求
curl -X POST "https://your-tenant.example.com/api/v1/cost-templates/<id>/lines" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "line": {
    "category": "Transport",
    "quantityMode": "fixed",
    "quantityFixed": 1,
    "unitPriceTwd": 100
  }
}'
回應
{
  "ok": true,
  "data": {
    "rateNotice": "…",
    "id": "…"
  }
}

update or delete a

PATCH/api/v1/cost-templates/lines/{lineId}
cost_template.manage模組:tour

參數

lineId路徑
string· min 1

成本範本明細行 ID

line必填
object

成本明細列更新內容:含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式(fixed 固定/headcount 人數)與對應數量/人數組成、isDeclarable 是否可報帳等欄位

回應欄位 · data

ok
boolean

是否更新成功。

rateNotice
string | null

新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 null。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/cost-templates/lines/<lineId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "line": {
    "category": "example-category",
    "quantityMode": "fixed"
  }
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "rateNotice": "…"
  }
}
DELETE/api/v1/cost-templates/lines/{lineId}
cost_template.manage模組:tour

參數

lineId路徑
string· min 1

成本範本明細行 ID

回應欄位 · data

ok
boolean

是否刪除成功。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/cost-templates/lines/<lineId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

/internal-external-ledger

取消梯次待結轉列表

GET/api/v1/internal-external-ledger/cancelled-departures
ledger.read模組:accounting

回應欄位 · data[]

departureId
string

取消梯次 ID。

tripTitle
string

團名。

tripSlug
string

行程 slug(URL 識別)。

departureDate
string

原出團日期(YYYY-MM-DD)。

returnDate
string

原回程日期(YYYY-MM-DD)。

groupCode
string | null

團號(group-code),未產生為 null。

residualCostTwd
number

殘餘成本(TWD 整數):已核准的逐筆成本合計 + 房費底價成本合計。

approvedCostCount
number

已核准成本筆數。

pendingCostCount
number

待覆核成本筆數(UI 提示「還有待覆核成本」)。

roomCostTwd
number

房費殘餘成本(房費底價成本合計,整數 TWD)。

conversion
{ expenseId: string; amountTwd: number; period: string; description: string; } | null

結轉狀態:已結轉為特殊損益時的費用列資訊(expenseId / 金額 / 歸屬月 / 摘要);未結轉為 null。

expenseId
string
amountTwd
number
period
string
description
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/internal-external-ledger/cancelled-departures" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "departureId": "…",
      "tripTitle": "…",
      "tripSlug": "…",
      "departureDate": "…",
      "returnDate": "…",
      "groupCode": "…",
      "residualCostTwd": 0,
      "approvedCostCount": 0,
      "pendingCostCount": 0,
      "roomCostTwd": 0,
      "conversion": "…"
    }
  ]
}

結轉取消

POST/api/v1/internal-external-ledger/cancelled-departures/convert
operating_expense.manage模組:accounting

參數

departureId必填
string· min 1

梯次 ID

categoryId必填
string· min 1

特殊損益費用科目 ID(kind=special)

period必填
string· 格式限定

歸屬月(取消月,格式 YYYY-MM)

amountTwd必填
integer

結轉金額(整數 TWD,預設殘餘成本)

description必填
string· min 1

摘要

note選填
string

備註(選填)

回應欄位 · data

id
string

新建立的殘餘成本營業費用列 ID(opx_ 前綴)。

residualCostTwd
number

結轉的殘餘成本金額(TWD 整數)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/internal-external-ledger/cancelled-departures/convert" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureId": "example-departureId",
  "categoryId": "example-categoryId",
  "period": "2026-10",
  "amountTwd": 1,
  "description": "example-description"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "residualCostTwd": 0
  }
}

撤銷取消

POST/api/v1/internal-external-ledger/cancelled-departures/revert
operating_expense.manage模組:accounting

參數

departureId必填
string· min 1

梯次 ID

回應欄位 · data

ok
boolean

固定為 true:已還原取消梯次的轉列,回到未轉列狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/internal-external-ledger/cancelled-departures/revert" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "departureId": "example-departureId"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
PATCH/api/v1/internal-external-ledger/costs/{costId}
departure_cost.manage模組:tour

參數

category必填
string

成本類別代碼(須為有效的成本分類)

vendorName選填
string

廠商/供應商名稱

description選填
string

成本摘要說明

amountTwd選填
integer

真實成本(台幣整數)。台幣路徑必填;外幣路徑忽略,改由外幣金額乘匯率換算

currency選填
string

幣別;TWD 或留空走台幣路徑,其他幣別走外幣路徑

foreignAmount選填
integer

外幣金額(最小單位整數,ISO 4217 minor units:JPY 以「円」、USD 以「cent」計);僅外幣路徑使用

internalRateSource選填
enum
fx_accountpublishedmanual

內帳匯率來源:fx_account 外幣帳戶加權成本、published 台銀牌告、manual 手填成交率

fxAccountId選填
string

外幣帳戶 ID;內帳匯率來源為 fx_account 時使用

manualRate選填
string

手填成交匯率(字串保精度);內帳匯率來源為 manual 時使用

hasReceipt選填
boolean

是否有發票憑證;預設 true,false 表示無發票並強制可申報額為 0、改填支出證明單欄位

invoiceAmountTwd選填
integer

外帳可申報額覆寫(台幣整數,須大於等於 0、無上限)

payeeName選填
string

受款人姓名;無發票時的支出證明單欄位

reasonNoReceipt選填
string

無發票原因;無發票時的支出證明單欄位

proofSummary選填
string

支出證明摘要;無發票時的支出證明單欄位

quantityMode選填
enum
fixedheadcount

計價方式;未給=一次性總額,fixed=單價×固定數量,headcount=單價×ceil(Σ人頭/組距)

headcountComponents選填
array

依人頭計價的人頭組合(passenger/leader/assistant/driver,至少一項)

groupDivisor選填
integer

依人頭計價的組距(≥ 1;空=直接加總)

quantityFixed選填
integer

固定數量計價的數量(≥ 0)

unitPriceTwd選填
integer

單價(台幣整數);計價方式給值時必填

costId路徑
string· min 1

成本列 ID

回應欄位 · data

ok
boolean

固定為 true:成本列已更新。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/internal-external-ledger/costs/<costId>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "example-category"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
DELETE/api/v1/internal-external-ledger/costs/{costId}
departure_cost.manage模組:tour

參數

costId路徑
string· min 1

成本列 ID

回應欄位 · data

ok
boolean

固定為 true:成本列已刪除。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/internal-external-ledger/costs/<costId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
POST/api/v1/internal-external-ledger/costs/{costId}/approve-declaration
ledger.approve模組:accounting

參數

costId路徑
string· min 1

成本列 ID

回應欄位 · data

ok
boolean

固定為 true:成本自主申報已核准。

請求
curl -X POST "https://your-tenant.example.com/api/v1/internal-external-ledger/costs/<costId>/approve-declaration" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

待覆核的嚮導申報

GET/api/v1/internal-external-ledger/declarations/pending
ledger.read模組:accounting

回應欄位 · data[]

id
string

成本列 ID。

departureId
string

所屬梯次 ID。

tripTitle
string

團名。

departureDate
string

出團日期(YYYY-MM-DD)。

category
string

成本分類。

vendorName
string | null

供應商 / 廠商名(選填)。

amountTwd
number

代墊 / 實付額(內帳真實成本,整數 TWD)。

invoiceAmountTwd
number

憑證 / 發票額(外帳可申報,整數 TWD)。

isDeclarable
boolean

是否取得合法憑證。

createdByName
string | null

登記者(經手人)姓名。

createdAt
string

建立時間(嚮導送出時間)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/internal-external-ledger/declarations/pending" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "departureId": "…",
      "tripTitle": "…",
      "departureDate": "…",
      "category": "…",
      "vendorName": "…",
      "amountTwd": 0,
      "invoiceAmountTwd": 0,
      "isDeclarable": true,
      "createdByName": "…",
      "createdAt": "…"
    }
  ]
}

per-departure 內外帳列表

GET/api/v1/internal-external-ledger/departures
ledger.read模組:accounting

參數

windowDays選填
integer

回看天數;只列出近 N 天內的梯次

tripId選填
string

行程 ID;只列出該行程的梯次

period選填
string· 格式限定

出團月(格式 YYYY-MM);只列出該月的梯次

回應欄位 · data[]

tripTitle
string

梯次標題(trip title)。

tripSlug
string

行程 slug(URL 識別)。

departureDate
string

出團日期(YYYY-MM-DD)。

returnDate
string

回程日期(YYYY-MM-DD)。

groupCode
string | null

團號(group-code),未產生為 null。

pax
number

報名人數(非取消單 party_size 合計)。

departureStatus
string

梯次狀態。`'cancelled'` 的列在毛利視圖裡只帶已認列退改費(訂單應收與成本都是 0), 呈現面必須標出來,否則會被當成一個真的有出團的梯次(issue 601)。

departureId
string

梯次 ID。

revenueTwd
number

本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。

orderRevenueTwd
number

訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。

cancellationFeeTwd
number

已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。

realCostTwd
number

內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。

declarableCostTwd
number

外帳可申報成本(各成本列憑證額合計,TWD 整數)。

nonDeclarableCostTwd
number

不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。

costBilledTwd
number

已轉請款成本。

costUnbilledTwd
number

未轉請款成本;不含即付(當下已付、不轉請款)。

grossProfitTwd
number

**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。

feeEcpayTwd
number

預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。

feeFongshouTwd
number

預估豐收款手續費(**參考預估**,非權威)。

taxEstTwd
number

預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。

estimatedNetProfitTwd
number

**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。

marginPct
number | null

毛利率(grossProfit / revenue),revenue=0 時為 null。

pendingProofCount
number

待核(pending)支出證明單數。

feeRates
object

套用的費率(呈現用)。

ecpayFeeBps
number

預估綠界手續費率(basis points,270 = 2.70%)。

fongshouFeeBps
number

預估豐收款手續費率(basis points,50 = 0.50%)。

profitTaxBps
number

預估發票 / 營所稅率(basis points,500 = 5.00%)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/internal-external-ledger/departures" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
      }
    }
  ]
}

single

GET/api/v1/internal-external-ledger/departures/{departureId}
ledger.read模組:accounting

參數

departureId路徑
string· min 1

梯次 ID

回應欄位 · data

departureId
string

梯次 ID。

revenueTwd
number

本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。

orderRevenueTwd
number

訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。

cancellationFeeTwd
number

已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。

realCostTwd
number

內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。

declarableCostTwd
number

外帳可申報成本(各成本列憑證額合計,TWD 整數)。

nonDeclarableCostTwd
number

不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。

costBilledTwd
number

已轉請款成本。

costUnbilledTwd
number

未轉請款成本;不含即付(當下已付、不轉請款)。

grossProfitTwd
number

**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。

feeEcpayTwd
number

預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。

feeFongshouTwd
number

預估豐收款手續費(**參考預估**,非權威)。

taxEstTwd
number

預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。

estimatedNetProfitTwd
number

**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。

marginPct
number | null

毛利率(grossProfit / revenue),revenue=0 時為 null。

pendingProofCount
number

待核(pending)支出證明單數。

feeRates
object

套用的費率(呈現用)。

ecpayFeeBps
number

預估綠界手續費率(basis points,270 = 2.70%)。

fongshouFeeBps
number

預估豐收款手續費率(basis points,50 = 0.50%)。

profitTaxBps
number

預估發票 / 營所稅率(basis points,500 = 5.00%)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/internal-external-ledger/departures/<departureId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
    }
  }
}
POST/api/v1/internal-external-ledger/departures/{departureId}/convert-to-payable
departure_cost.manage模組:tour

參數

departureId路徑
string· min 1

梯次 ID

costIds必填
array· min 1

要轉成請款核簽的成本列 ID 陣列(至少一筆,須為尚未轉請款者)

payeeType選填
enum
supplierguidestaff_commissionother

受款對象類型:supplier 供應商、guide 嚮導、staff_commission 員工佣金、other 其他

payeeName必填
string· min 1

受款對象名稱

payeeBankAccount選填
string

受款銀行帳號

payeeBankName選填
string

受款銀行名稱

payeeBankBranch選填
string

受款銀行分行

payeeTaxId選填
string

受款對象統一編號/稅籍編號

taxAmountTwd選填
integer

代扣稅額(台幣整數)

submitImmediately選填
boolean

是否建立後立即送出核簽(true 直接送審)

回應欄位 · data

payableId
string

新建立應付單的 ID(pay_ 前綴)。

payableNumber
string

應付單編號(租戶內流水序號,出款核簽用)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/internal-external-ledger/departures/<departureId>/convert-to-payable" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "costIds": [
    "example-costIds"
  ],
  "payeeName": "example-payeeName"
}'
回應
{
  "ok": true,
  "data": {
    "payableId": "…",
    "payableNumber": "…"
  }
}
GET/api/v1/internal-external-ledger/departures/{departureId}/costs
ledger.read模組:tour

參數

departureId路徑
string· min 1

梯次 ID

createdBy選填
string

登記者使用者 ID;只列出該人登記的成本列

回應欄位 · data[]

id
string

成本列 ID。

departureId
string

所屬梯次 ID。

category
string

成本分類(如 交通 / 餐費 / 保險 / 嚮導)。

vendorName
string | null

供應商 / 廠商名(選填)。

description
string | null

摘要說明(選填)。

receiptImageUrl
string | null

憑證照片 URL(G3-2);未附照片 null。app-route 私有 URL,讀取經 route 權限閘。

amountTwd
number

代墊 / 實付額(內帳真實成本,整數 TWD)。

invoiceAmountTwd
number

外帳可申報額(internal-external-ledger §2.1)。

isDeclarable
boolean

是否取得合法憑證。

reviewStatus
string

覆核狀態 'pending' | 'approved'(L'):pending 不計入毛利 / 可申報(UI 須標示、停用轉請款)。

currency
string

成本幣別(ISO 4217);'TWD' = 台幣列。

foreignAmount
number | null

外幣金額(最小單位整數);TWD 列 null。

internalRateSource
string | null

內帳匯率來源;TWD 列 null。

fxAccountId
string | null

internalRateSource='fx_account' 時的外幣帳戶 id。

internalRate
string | null

內帳匯率快照(numeric 字串);TWD 列 null。

externalRate
string | null

外帳匯率快照(numeric 字串,台銀牌告);TWD 列 null。

feeCategory
string | null

費用類型 tag(account-settlement §3.4,成本側類別→領域帳戶映射;null = 未 tag)。

quantityMode
QuantityMode | null

計價方式 'fixed' / 'headcount';一次性總額列 null。

headcountComponents
HeadcountComponent[] | null

headcount 人頭組合;非 headcount 列 null。

groupDivisor
number | null

headcount 組距;非 headcount 列 null。

quantity
number | null

解析後(headcount)或自訂(fixed)的數量;一次性總額列 null。

unitPriceTwd
number | null

單價(台幣整數);一次性總額列 null。

expenseProofId
string | null

無發票支出掛的支出證明單 id(null = 有憑證)。

proofNumber
string | null

支出證明單單號(join expense_proofs,null = 無)。

proofStatus
string | null

支出證明單狀態 'pending' | 'approved'(null = 無)。

payableId
string | null

已轉請款時連結的請款單 ID(null = 未轉請款)。

payableNumber
string | null

連結請款單的人類可讀單號(null = 未轉請款)。

payableStatus
string | null

連結請款單的狀態(draft / submitted / approved / paid…;null = 未轉請款)。

paymentMethod
"paid_on_spot" | "request"

付款方式:'request' 走請款核簽;'paid_on_spot' 即付,算已付、不轉請款。

paidOn
string | null

即付的付款日('YYYY-MM-DD');請款列 null。

paidAccountId
string | null

即付的付款帳戶 ID;未指定或請款列 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/internal-external-ledger/departures/<departureId>/costs" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
POST/api/v1/internal-external-ledger/departures/{departureId}/costs
departure_cost.manage模組:tour

參數

category必填
string

成本類別代碼(須為有效的成本分類)

vendorName選填
string

廠商/供應商名稱

description選填
string

成本摘要說明

amountTwd選填
integer

真實成本(台幣整數)。台幣路徑必填;外幣路徑忽略,改由外幣金額乘匯率換算

currency選填
string

幣別;TWD 或留空走台幣路徑,其他幣別走外幣路徑

foreignAmount選填
integer

外幣金額(最小單位整數,ISO 4217 minor units:JPY 以「円」、USD 以「cent」計);僅外幣路徑使用

internalRateSource選填
enum
fx_accountpublishedmanual

內帳匯率來源:fx_account 外幣帳戶加權成本、published 台銀牌告、manual 手填成交率

fxAccountId選填
string

外幣帳戶 ID;內帳匯率來源為 fx_account 時使用

manualRate選填
string

手填成交匯率(字串保精度);內帳匯率來源為 manual 時使用

hasReceipt選填
boolean

是否有發票憑證;預設 true,false 表示無發票並強制可申報額為 0、改填支出證明單欄位

invoiceAmountTwd選填
integer

外帳可申報額覆寫(台幣整數,須大於等於 0、無上限)

payeeName選填
string

受款人姓名;無發票時的支出證明單欄位

reasonNoReceipt選填
string

無發票原因;無發票時的支出證明單欄位

proofSummary選填
string

支出證明摘要;無發票時的支出證明單欄位

quantityMode選填
enum
fixedheadcount

計價方式;未給=一次性總額,fixed=單價×固定數量,headcount=單價×ceil(Σ人頭/組距)

headcountComponents選填
array

依人頭計價的人頭組合(passenger/leader/assistant/driver,至少一項)

groupDivisor選填
integer

依人頭計價的組距(≥ 1;空=直接加總)

quantityFixed選填
integer

固定數量計價的數量(≥ 0)

unitPriceTwd選填
integer

單價(台幣整數);計價方式給值時必填

departureId路徑
string· min 1

梯次 ID

回應欄位 · data

id
string

新建立成本列的 ID(dc_ 前綴)。

expenseProofId
string | null

隨附憑證的 ID(若本次一併登記),無則為 null。

請求
curl -X POST "https://your-tenant.example.com/api/v1/internal-external-ledger/departures/<departureId>/costs" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "example-category"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "expenseProofId": "…"
  }
}

支出

GET/api/v1/internal-external-ledger/departures/{departureId}/proofs
ledger.read模組:accounting

參數

departureId路徑
string· min 1

梯次 ID

回應欄位 · data[]

id
string

支出證明單 ID。

proofNumber
string

人類可讀單號(EP-YYMMDD-NNN)。

departureId
string

所屬梯次 ID。

payeeName
string

受款對象(自然人 / 廠商)。

amountTwd
number

金額(整數 TWD,對應所掛成本列的 amount_twd)。

reasonNoReceipt
string

無法取得單據的原因(如「自然人」)。

summary
string | null

支出內容及摘要(選填)。

handlerUserId
string

經手人(建單者)user ID。

approverUserId
string | null

核准人 user ID(強制 ≠ 經手人);未核准為 null。

status
"approved" | "pending"

狀態:pending 待核准 / approved 已核准(核准後 append-only)。

approvedAt
string | null

核准時間;未核准為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/internal-external-ledger/departures/<departureId>/proofs" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "proofNumber": "…",
      "departureId": "…",
      "payeeName": "…",
      "amountTwd": 0,
      "reasonNoReceipt": "…",
      "summary": "…",
      "handlerUserId": "…",
      "approverUserId": "…",
      "status": "approved",
      "approvedAt": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
GET/api/v1/internal-external-ledger/departures/{departureId}/proofs/{proofId}
ledger.read模組:accounting

參數

departureId路徑
string· min 1

梯次 ID

proofId路徑
string· min 1

支出證明單 ID

回應欄位 · data

id
string

支出證明單 ID。

proofNumber
string

人類可讀單號(EP-YYMMDD-NNN)。

departureId
string

所屬梯次 ID。

payeeName
string

受款對象(自然人 / 廠商)。

amountTwd
number

金額(整數 TWD,對應所掛成本列的 amount_twd)。

reasonNoReceipt
string

無法取得單據的原因(如「自然人」)。

summary
string | null

支出內容及摘要(選填)。

handlerUserId
string

經手人(建單者)user ID。

approverUserId
string | null

核准人 user ID(強制 ≠ 經手人);未核准為 null。

status
"approved" | "pending"

狀態:pending 待核准 / approved 已核准(核准後 append-only)。

approvedAt
string | null

核准時間;未核准為 null。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/internal-external-ledger/departures/<departureId>/proofs/<proofId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "proofNumber": "…",
    "departureId": "…",
    "payeeName": "…",
    "amountTwd": 0,
    "reasonNoReceipt": "…",
    "summary": "…",
    "handlerUserId": "…",
    "approverUserId": "…",
    "status": "approved",
    "approvedAt": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
POST/api/v1/internal-external-ledger/proofs/{proofId}/approve
ledger.approve模組:accounting

參數

proofId路徑
string· min 1

支出證明單 ID

回應欄位 · data

ok
boolean

固定為 true:憑證已核准。

請求
curl -X POST "https://your-tenant.example.com/api/v1/internal-external-ledger/proofs/<proofId>/approve" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

/payouts

派生當月

GET/api/v1/payouts/aggregate
supplier.read模組:accounting

參數

period必填
string· 格式限定

出款月份(YYYY-MM),彙整該月已核准未付的應付

scope必填
enum
guidesupplierstaff

收款對象範圍(guide 領隊嚮導 / supplier 供應商 / staff 員工)

回應欄位 · data[]

payeeType
"guide" | "staff" | "supplier"

收款對象類型:guide 領隊嚮導 / supplier 供應商 / staff 員工。

payeeRefId
string

收款對象識別 key:供應商為其 ID,領隊 / 員工為收款人姓名。

payeeName
string

收款對象名稱。

payeeAccountName
string | null

收款人戶名(supplier 取 suppliers / guide 取 guides;staff 暫無主檔 → null)。

payeeBankCode
string | null

收款銀行代號(同上來源;無主檔為 null)。

payeeAccountNumber
string | null

收款帳號(同上來源;無主檔為 null,遮罩回傳)。

grossTwd
number

當月已核准未付的請款單淨額合計(TWD 整數)。

items
object[]

彙整明細(日期 + 團名 + 金額,唯讀派生,不另存)。

payableId
string

請款單 ID。

payableNumber
string

請款單人類可讀單號。

date
string | null

梯次出發日('YYYY-MM-DD');無連梯次時 null。

tripLabel
string | null

團名;無連梯次時 null。

amountTwd
number

該請款單的應付淨額(TWD 整數)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payouts/aggregate?period=2026-10&scope=guide" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "payeeType": "guide",
      "payeeRefId": "…",
      "payeeName": "…",
      "payeeAccountName": "…",
      "payeeBankCode": "…",
      "payeeAccountNumber": "…",
      "grossTwd": 0,
      "items": [
        {
          "payableId": "…",
          "payableNumber": "…",
          "date": "…",
          "tripLabel": "…",
          "amountTwd": 0
        }
      ]
    }
  ]
}

建立出款批次草稿

POST/api/v1/payouts/batches
supplier.read模組:accounting

參數

period必填
string· 格式限定

出款月份(YYYY-MM)

payeeScope必填
enum
guidesupplierstaff

收款對象範圍(guide 領隊嚮導 / supplier 供應商 / staff 員工)

paidFromAccountId選填
string· min 1

出帳帳戶 id(從哪個收款帳戶付出);可留空待確認時指定

lines必填
array· min 1

納入批次的出款列(至少一列)

回應欄位 · data

id
string

新建立出款批次的 ID(pob_ 前綴)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payouts/batches" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "2026-10",
  "payeeScope": "guide",
  "lines": [
    {
      "payeeType": "guide",
      "payeeRefId": "example-payeeRefId",
      "grossTwd": 1
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

確認出款批次

POST/api/v1/payouts/batches/{id}/confirm
payable.mark_paid模組:accounting

參數

id路徑
string· 格式限定

出款批次 id(路徑參數,格式 pob_…)

bankReference選填
string· max 64

網銀交易序號 / 轉帳憑證號(可選)

回應欄位 · data

ok
boolean

固定為 true:出款批次已確認送出。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payouts/batches/<id>/confirm" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "bankReference": "example-bankReference"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

出款批次的標準四欄批次轉帳檔

GET/api/v1/payouts/batches/{id}/transfer-file
payable.mark_paid模組:accounting

參數

id路徑
string· min 1

出款批次 id(路徑參數)

format選填
enum
csvjson

輸出格式:json 完整匯出(預設)或 csv 僅回傳轉帳檔字串

請求
curl -X GET "https://your-tenant.example.com/api/v1/payouts/batches/<id>/transfer-file" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": "…"
}

為某出款批次列簽發廠商自助確認

POST/api/v1/payouts/lines/{lineId}/confirm-token
supplier.read模組:accounting

參數

lineId路徑
string· 格式限定

出款批次列 id(路徑參數,格式 pobl_…)

回應欄位 · data

token
string

廠商自助確認 token(拼成對外確認頁網址;未過期重複簽發回原 token)。

expiresAt
string

token 失效時點(簽發起 14 天;重簽發會展延)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/payouts/lines/<lineId>/confirm-token" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "token": "…",
    "expiresAt": "…"
  }
}

出款批次的「出帳帳戶」選項

GET/api/v1/payouts/remit-accounts
supplier.read模組:accounting

回應欄位 · data[]

id
string

收款帳戶 ID。

code
string

帳戶代碼(租戶內唯一穩定識別)。

displayName
string

帳戶顯示名。

kind
"bank" | "cash" | "gateway"

帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。

gatewayProvider
string | null

綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `payment/gateway-providers.ts`。

bankName
string | null

銀行名稱;現金/閘道帳戶為 null。

accountNo
string | null

銀行帳號;現金/閘道帳戶為 null。

bankCode
string | null
bankBranch
string | null
accountHolder
string | null
canReceive
boolean

可收款(幾乎都 true)。

canRemit
boolean

可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。

canChargeback
boolean

可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。

canPaySupplier
boolean

付款渠道:出團準備的付款登記區可選它付供應商(#1375)。

isDeprecated
boolean

廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。

isSettlementMaster
boolean

主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。

payoutAccountId
string | null

撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。

currency
string

帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。

isActive
boolean

此帳戶是否啟用。

displayOrder
number

後台清單排序序位(小者在前)。

usedCount
number

被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。

currencyLocked
boolean

幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/payouts/remit-accounts" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}

/pnl

list the company expense-category

GET/api/v1/pnl/expense-categories
operating_expense.read

參數

activeOnly選填
boolean

是否只回傳啟用中的費用類別;預設含停用列

回應欄位 · data[]

id
string

費用類別 ID。

code
string

科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。

displayName
string

顯示名(如 房租 / 行政薪資 / 營業稅)。

kind
"opex" | "platform_fee" | "special" | "tax"

費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。

isActive
boolean

是否啟用(停用不刪,既有費用列仍引用得到)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/pnl/expense-categories" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "kind": "opex",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

list company operating-expense ledger rows

GET/api/v1/pnl/expenses
operating_expense.read

參數

period選填
string

歸屬月(格式 YYYY-MM);只列出該月的費用

category選填
string

費用類別 ID;只列出該類別的費用

kind選填
enum
opextaxplatform_feespecial

費用大類:opex 營業費用、tax 稅、platform_fee 平台手續費、special 特殊損益

回應欄位 · data[]

id
string

費用列 ID。

categoryId
string

費用科目 ID。

categoryCode
string | null

費用科目代碼(如 rent / salary_admin)。

categoryDisplayName
string | null

費用科目顯示名。

categoryKind
string | null

費用科目大類(opex / tax / platform_fee / special)。

period
string

歸屬月(YYYY-MM,損益表據此彙整;可與支付日不同月)。

incurredOn
string | null

發生 / 支付日期(YYYY-MM-DD);金流商內扣 / 攤提無單一發生日者為 null。

amountTwd
number

金額(整數 TWD,恆正;損 / 益由 direction 表達)。

direction
"expense" | "income"

損益方向:'expense' 費用(預設)| 'income' 特殊收入(僅 kind='special' 科目)。

description
string

摘要(廠商 / 品名,如 台中房租 / 委外廣告投放)。

paidFromAccountId
string | null

出帳帳戶 ID;金流商內扣者為 null。

paidFromAccountName
string | null

出帳帳戶顯示名。

frontedByUserId
string | null

代墊者 user ID;非空代表由此人代墊待回補(走請款回補代墊者)。

frontedByName
string | null

代墊者姓名。

payableId
string | null

若走出款核簽,連結的請款單 ID;否則 null。

payableNumber
string | null

連結請款單的人類可讀單號。

recurring
boolean

月固定標記(人工登記時備註「月固定」;自動生成走範本表,非此欄)。

status
"confirmed" | "draft"

'draft'(月固定範本自動生成、待確認,不入損益)| 'confirmed'(計入損益)。

origin
"departure_conversion" | "manual" | "recurring"

'manual'(手動登記)| 'recurring'(月固定範本自動生成)| 'departure_conversion'(取消梯次結轉,§3.4)。

sourceTemplateId
string | null

生成來源範本(origin='recurring');手動登記為 null。

note
string | null

備註。

createdByUserId
string

經手人 user ID(建立此費用列者)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/pnl/expenses" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}
POST/api/v1/pnl/expenses
operating_expense.manage模組:accounting

參數

categoryId必填
string· min 1

費用類別 ID(對應公司費用類別目錄)

period必填
string· 格式限定

歸屬月(格式 YYYY-MM),供月損益表彙整

description必填
string· min 1

費用摘要

amountTwd必填
integer

費用金額(台幣非負整數;損 / 益由 direction 表達,金額恆正)

direction選填
enum
expenseincome

損益方向:expense 費用(預設)/ income 特殊收入(保險理賠、政府補助等;僅 kind='special' 科目可用)

incurredOn選填
string

費用發生日期(格式 YYYY-MM-DD)

paidFromAccountId選填
string

支付來源帳戶 ID

frontedByUserId選填
string

代墊人使用者 ID(由員工先行墊付時填寫)

note選填
string

備註

recurring選填
boolean

是否為週期性費用

回應欄位 · data

ok
boolean

固定為 true:營業費用列已新增。

id
string

新建立營業費用列的 ID(opx_ 前綴)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/pnl/expenses" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "categoryId": "example-categoryId",
  "period": "2026-10",
  "description": "example-description",
  "amountTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

更正一筆公司營業費用

PATCH/api/v1/pnl/expenses/{id}
operating_expense.manage模組:accounting

參數

categoryId必填
string· min 1

費用類別 ID(對應公司費用類別目錄)

period必填
string· 格式限定

歸屬月(格式 YYYY-MM),供月損益表彙整

description必填
string· min 1

費用摘要

amountTwd必填
integer

費用金額(台幣非負整數;損 / 益由 direction 表達,金額恆正)

direction選填
enum
expenseincome

損益方向:expense 費用(預設)/ income 特殊收入(保險理賠、政府補助等;僅 kind='special' 科目可用)

incurredOn選填
string

費用發生日期(格式 YYYY-MM-DD)

paidFromAccountId選填
string

支付來源帳戶 ID

frontedByUserId選填
string

代墊人使用者 ID(由員工先行墊付時填寫)

note選填
string

備註

recurring選填
boolean

是否為週期性費用

id路徑
string· min 1

營業費用列 ID

payableId選填
string

關聯的請款核簽 ID;整列覆寫時須原樣帶回,省略則清為 null

回應欄位 · data

ok
boolean

固定為 true:營業費用列已更新。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/pnl/expenses/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "categoryId": "example-categoryId",
  "period": "2026-10",
  "description": "example-description",
  "amountTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

the company monthly P&L statement

GET/api/v1/pnl/statement
operating_expense.read

參數

period必填
string· 格式限定

損益表結算月(格式 YYYY-MM)

回應欄位 · data

period
string

結算期間(YYYY-MM)。

regions
object[]

各區毛利明細(出團月落 period 的梯次按區 roll-up)。

region
string

派生 region key(穩定,由 trip 屬性派生)。

label
string

顯示標籤(destination 原文 / 衍生)。

revenueTwd
number

本區收入(出團月落 period 的梯次合計 = 訂單收入 + 已認列退改費,TWD 整數)。

cancellationFeeTwd
number

本區已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 拆出來呈現,會計才對得出「這區的收入有多少不是出團賺的」。

directCostTwd
number

本區真實直接成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。

marginTwd
number

本區毛利 = revenue − directCost。

departures
number

本區梯次數(出團月落 period)。

grossMarginTwd
number

各區毛利加總(整數 TWD)。

revenueTotalTwd
number

各區營收加總(整數 TWD)。

adminFeeIncomeTwd
number

行政手續費收入(退款收取的行政手續費,只計未出團 / 取消單,TWD 整數)。

otherIncomeTwd
number

其他收入合計 = adminFeeIncome(整數 TWD)。GS「額外收入總計」改由 special income 列 承載(specialIncomeTwd,於特殊損益帶號區認列),**不在此重複加總**(防雙計)。

expensesByKind
object[]

公司營業費用按 kind roll-up(opex / tax / platform_fee,只計已確認)。

kind
string

'opex' / 'tax' / 'platform_fee'。

amountTwd
number

該 kind 本期費用合計(整數 TWD)。

count
number

該 kind 本期費用筆數。

operatingExpenseTotalTwd
number

公司營業費用合計 = Σ opex / tax / platform_fee(整數 TWD)。

special
object[]

特殊損益逐筆(kind='special',一次性、獨立列、損 / 益雙向,只計已確認)。

id
string

費用列 ID。

categoryId
string

費用科目 ID(特殊損益科目)。

categoryDisplayName
string | null

費用科目顯示名。

description
string

摘要(如 取消神山床位沒收訂金 / 保險理賠)。

amountTwd
number

金額(整數 TWD ≥ 0,DB CHECK operating_expenses_amount_nonneg)。恆正;損 / 益由 `direction` 表達(0055 特殊損益雙向)。

direction
"expense" | "income"

'expense' 損(扣減淨利)| 'income' 益(增益淨利;GS「額外收入」的載體)。

specialExpenseTwd
number

特殊損合計(direction='expense',整數 TWD ≥ 0)。

specialIncomeTwd
number

特殊益合計(direction='income',整數 TWD ≥ 0)= GS「額外收入總計」的載體。

specialTotalTwd
number

特殊損益淨額(**帶號**)= specialExpense − specialIncome(整數 TWD;淨益時為負)。 淨利計算從淨利扣減此值——income 為正貢獻(損 1000 + 益 300 → specialTotal 700 → 淨利 −700)。

netProfitTwd
number

公司淨利 = grossMargin + otherIncome − operatingExpenseTotal − specialTotal(帶號)。

netMarginPct
number | null

淨利率(netProfit / revenueTotal),revenue=0 時 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/pnl/statement?period=2026-10" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
  }
}

/reports

tenant monthly

GET/api/v1/reports/monthly
order.read

參數

year必填
integer· max 2100 · min 2000

報表年份(西元四位數),月界以台北時區計

month必填
integer· max 12 · min 1

報表月份,1 至 12

回應欄位 · data

year
number

報表年份(西元四位數)。

month
number

報表月份(1-12,月界以 Asia/Taipei 計)。

totalOrders
number

本月建立的 tour 訂單數(依 created_at 計)。

paidOrders
number

本月有實收現金的 tour 訂單數(月內有 inbound 交易)。

cancelledOrders
number

本月取消的 tour 訂單數(依 `orders.cancelled_at` 計,Asia/Taipei 月界)。 取消時刻不明的單(`cancelled_at IS NULL`)任何月份都不計 —— 見 repo 內註解。

cancelledOrdersUnknownDate
number

取消時刻不明的 tour 訂單數(`cancelled_at IS NULL`)。**不分月份** —— 它們 不屬於任何一個月,所以每個月的報表都回報同一個值。> 0 時畫面要講出來: 否則這批單在每個月的報表裡都不出現,逐月讀完也看不出它們存在 —— 而它們確實 被取消了。(不要拿它跟訂單清單的取消總數對:報表側是 tour line 口徑、清單側是 `o.kind`,兩者本來就不相等,見 #20。)

totalRevenue
number

本月實際收到的現金。

refundedAmount
number

本月退還客人的現金,含退款與信用卡爭議退款(chargeback)。

netCash
number

本月淨現金:實收減退還現金,再扣手續費。

newCustomers
number

本月新註冊會員數(排除 staff 角色)。

byTrip
object[]

依行程銷售排行(前 10 名,按本月實收現金的攤提份額)。跨出團/跨行程訂單 的現金按 orders/allocation 份額分(#12),Σ revenue = totalRevenue 守恆。

tripId
string

行程 ID。

tripTitle
string

團名。

orderCount
number

該行程本月有實收現金份額的訂單數。

revenue
number

collected_cash by trip:本月實收現金攤提份額(tour-scoped)。

byProvider
object[]

依金流商分組的本月實收現金。

provider
string

金流商代碼(如 ecpay / test)。

orderCount
number

該金流商本月有實收現金的訂單數。

amount
number

collected_cash by provider:本月實收現金(tour-scoped)。

dailyRevenue
object[]

collected_cash by day:本月逐日實收現金(tour-scoped,Asia/Taipei 日界), 整月零填滿(無入帳的日子 amount=0)。Σ amount === totalRevenue,與 KPI 對帳。

day
string

日期(YYYY-MM-DD,Asia/Taipei 日界)。

amount
number

當日實收現金(tour-scoped,整數 TWD)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/reports/monthly?year=2000&month=1" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…",
        "orderCount": 0,
        "amount": 0
      }
    ],
    "dailyRevenue": [
      {
        "day": "…",
        "amount": 0
      }
    ]
  }
}

/suppliers

廠商目錄列表

GET/api/v1/suppliers
supplier.read

參數

status選填
enum
activeinactiveall

依狀態篩選(active 啟用 / inactive 停用 / all 全部,預設 active)

q選填
string

關鍵字搜尋(廠商名稱或類別)

回應欄位 · data[]

id
string

廠商 ID。

name
string

廠商名稱。

categoryHint
string | null

慣用類別提示(租戶自定,非硬枚舉)。

payeeAccountName
string | null

收款人戶名(批次轉帳檔欄 (1))。

payeeBankCode
string | null

收款銀行代號(批次轉帳檔欄 (3))。

payeeAccountNumber
string | null

收款帳號(批次轉帳檔欄 (2),遮罩回傳)。

status
"active" | "inactive"

狀態:active 啟用 / inactive 停用(停用不刪)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/suppliers" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "categoryHint": "…",
      "payeeAccountName": "…",
      "payeeBankCode": "…",
      "payeeAccountNumber": "…",
      "status": "active",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
POST/api/v1/suppliers
supplier.manage模組:accounting

參數

name必填
string· max 120 · min 1

廠商名稱(出款對象顯示名)

categoryHint選填
string· max 60

類別提示(如住宿、交通、餐飲),供分類與搜尋

payeeAccountName選填
string· max 65

收款戶名(須與銀行帳戶登記名一致)

payeeBankCode選填
string· 格式限定

銀行代號(3~7 碼數字,台銀通用四欄轉帳檔用)

payeeAccountNumber選填
string· 格式限定 · max 20

收款銀行帳號(純數字,write-only 寫入後僅回遮罩)

回應欄位 · data

ok
boolean

固定為 true:廠商已新增。

id
string

新建立廠商的 ID(sup_ 前綴)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/suppliers" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "id": "…"
  }
}

單一廠商主檔

GET/api/v1/suppliers/{id}
supplier.read

參數

id路徑
string· min 1

廠商 id(路徑參數)

回應欄位 · data

id
string

廠商 ID。

name
string

廠商名稱。

categoryHint
string | null

慣用類別提示(租戶自定,非硬枚舉)。

payeeAccountName
string | null

收款人戶名(批次轉帳檔欄 (1))。

payeeBankCode
string | null

收款銀行代號(批次轉帳檔欄 (3))。

payeeAccountNumber
string | null

收款帳號(批次轉帳檔欄 (2),遮罩回傳)。

status
"active" | "inactive"

狀態:active 啟用 / inactive 停用(停用不刪)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/suppliers/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "categoryHint": "…",
    "payeeAccountName": "…",
    "payeeBankCode": "…",
    "payeeAccountNumber": "…",
    "status": "active",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
PATCH/api/v1/suppliers/{id}
supplier.manage模組:accounting

參數

name選填
string· max 120 · min 1

廠商名稱(出款對象顯示名)

categoryHint選填
string· max 60

類別提示(如住宿、交通、餐飲),供分類與搜尋

payeeAccountName選填
string· max 65

收款戶名(須與銀行帳戶登記名一致)

payeeBankCode選填
string· 格式限定

銀行代號(3~7 碼數字,台銀通用四欄轉帳檔用)

payeeAccountNumber選填
string· 格式限定 · max 20

收款銀行帳號(純數字,write-only 寫入後僅回遮罩)

id路徑
string· min 1

廠商 id(路徑參數)

回應欄位 · data

ok
boolean

固定為 true:廠商資料已更新。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/suppliers/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "categoryHint": "example-categoryHint",
  "payeeAccountName": "example-payeeAccountName"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

/audit

list/filter the append-only tenant audit trail

GET/api/v1/audit/log
audit.read

參數

action選填
string

動作代碼篩選,例如 order.update(比對稽核事件的動作)

actor選填
string

操作者篩選,比對執行該動作的使用者 ID

entity選填
string

目標實體篩選,比對被操作對象的類型或 ID

from選填
string

起始時間(ISO 8601),僅回傳此時間之後的事件

to選填
string

結束時間(ISO 8601),僅回傳此時間之前的事件

before選填
string

往更舊翻頁的游標:直接帶前一批最後一列的 cursor 欄位(勿用 createdAt 重組)

after選填
string

往更新翻頁的游標:帶前一批第一列的 cursor 欄位。與 before 併用時以 before 為準

limit選填
integer· max 1000

回傳筆數上限,最多 1000 筆

回應欄位 · data[]

id
string

稽核事件 ID。

actorUserId
string | null

操作者的使用者 ID;系統事件(webhook/排程等非人為列)為 null。

actorEmail
string | null

操作者 Email;系統事件或帳號已刪時為 null。

actorName
string | null

操作者顯示名;系統事件或帳號已刪時為 null。

action
string

動作代碼,例如 order.create、traveler.decrypt。

targetType
string

被操作對象的類型,例如 order、member。

targetId
string

被操作對象的 ID。

metadata
unknown

該事件的附帶內容(欄位隨動作而異的自由結構 JSON)。

ipAddress
string | null

發起請求的來源 IP;無法取得時為 null。

createdAt
string

事件發生時間。**只用來顯示** —— 它到毫秒為止(JSON 序列化也是),翻頁請用 `cursor`。

cursor
string

這一列的 keyset 游標(`<ISO 微秒時間>|<id>`)。要往這一列的前後翻頁就直接把它 餵回 `before` / `after`,**不要拿 `createdAt` 重組**:那是 JS `Date`,只到毫秒, 而 `audit_log.created_at` 是微秒。JSON 序列化之後只剩 3 位小數,同一毫秒內更舊 的列會被整批跳過(`/api/v1` 與 CLI 走的正是這條路)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/audit/log" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "actorUserId": "…",
      "actorEmail": "…",
      "actorName": "…",
      "action": "…",
      "targetType": "…",
      "targetId": "…",
      "metadata": "…",
      "ipAddress": "…",
      "createdAt": "…",
      "cursor": "…"
    }
  ]
}

audit KPI counts

GET/api/v1/audit/stats
audit.read

參數

actor選填
string

操作者使用者 ID,指定時將統計數據限縮至該操作者

回應欄位 · data

eventsThisMonth
number

本月(Asia/Taipei)稽核事件總數。

eventsToday
number

今日(Asia/Taipei)稽核事件總數。

writesThisMonth
number

本月寫入類事件數(排除 *.read 讀取事件)。

distinctActorsThisMonth
number

本月有動作紀錄的不重複操作者人數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/audit/stats" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "eventsThisMonth": 0,
    "eventsToday": 0,
    "writesThisMonth": 0,
    "distinctActorsThisMonth": 0
  }
}

/leaderboard

全公司業務業績排行

GET/api/v1/leaderboard
leaderboard.read

參數

period選填
enum
monthquarteryearall

業績統計區間:當月、當季、當年或全部,預設 month

回應欄位 · data[]

userId
string

業務的使用者 ID。

name
string

業務顯示姓名。

email
string

業務登入 Email。

role
string

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

orderCount
number

承作訂單總數(歸屬此業務、含各狀態的旅遊團訂單)。

paidCount
number

成交訂單數(未取消,且已付清或已完成)。

cancelledCount
number

已取消訂單數。

revenue
number

業績額(TWD 整數):歸屬於該業務、未取消訂單的應收合計。

commissionTwd
number

估算佣金 = round(revenue × sales_commission_bps / 10000)(tenant_settings 費率)。

bonusTwd
number

月度第一名加碼 = round(revenue × monthly_top_bonus_bps / 10000),僅當期 rank 1 且 revenue > 0;其餘為 0。與 isMonthlyTop 同步。

isMonthlyTop
boolean

當期 rank 1(revenue > 0)=月度第一,享 bonus。

avgOrderTwd
number

客單均價 = round(revenue / orderCount);0 單為 0。

請求
curl -X GET "https://your-tenant.example.com/api/v1/leaderboard" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "name": "…",
      "email": "…",
      "role": "…",
      "orderCount": 0,
      "paidCount": 0,
      "cancelledCount": 0,
      "revenue": 0,
      "commissionTwd": 0,
      "bonusTwd": 0,
      "isMonthlyTop": true,
      "avgOrderTwd": 0
    }
  ]
}

待派發訂單 KPI

GET/api/v1/leaderboard/review-stats
leaderboard.read

回應欄位 · data

pendingCount
number

待派發(pending_review)訂單筆數。

pendingTotalTwd
number

待派發訂單的應收金額合計(新台幣)。

longestWaitHours
number

目前待派發訂單中,最長已等待的時數。

thisMonthAssigned
number

本月(Asia/Taipei)已完成派發的訂單數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/leaderboard/review-stats" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "pendingCount": 0,
    "pendingTotalTwd": 0,
    "longestWaitHours": 0,
    "thisMonthAssigned": 0
  }
}

/message-templates

list canned message templates

GET/api/v1/message-templates
message_template.read

參數

channel選填
enum
lineemail

依發送管道篩選範本(line 或 email)

回應欄位 · data[]

id
string

範本 ID。

key
string | null

穩定識別碼(NULL = 未指定)。

stage
string

SOP 階段(受理 → 出團完成)。

channel
"email" | "line"

發送管道:line 或 email。

title
string

範本標題。

bodySingle
string

單人版內文(含 {{...}} 合併變數)。

bodyMulti
string | null

多人版變體;NULL = 只有單人版。

isActive
boolean

是否為該階段目前啟用的範本。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

updatedBy
string | null

最後更新者姓名;未知或帳號已刪除時為 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/message-templates" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "key": "…",
      "stage": "…",
      "channel": "email",
      "title": "…",
      "bodySingle": "…",
      "bodyMulti": "…",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…",
      "updatedBy": "…"
    }
  ]
}
POST/api/v1/message-templates
message_template.manage

參數

key選填
string

範本識別碼,2–64 碼大寫英數 / _ / -(用於程式化引用,選填,自動轉大寫)

stage必填
string· max 100 · min 1

訊息對應的 SOP 階段(合法值 = 租戶階段目錄中的階段名)

channel必填
enum
lineemail

發送管道(line 或 email)

title必填
string· max 200 · min 1

範本標題(供後台辨識)

bodySingle必填
string· max 5000 · min 1

單人版訊息內文

bodyMulti選填
string· max 5000

多人版訊息內文(留空表示沿用單人版;選填)

isActive選填
boolean

是否啟用(停用後不出現在可選範本中)

回應欄位 · data

id
string

新建立的訊息範本 ID。

請求
curl -X POST "https://your-tenant.example.com/api/v1/message-templates" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "stage": "example-stage",
  "channel": "line",
  "title": "example-title",
  "bodySingle": "example-bodySingle"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

single canned message template detail.

GET/api/v1/message-templates/{id}
message_template.read

參數

id路徑
string· min 1

訊息範本 ID

回應欄位 · data

id
string

範本 ID。

key
string | null

穩定識別碼(NULL = 未指定)。

stage
string

SOP 階段(受理 → 出團完成)。

channel
"email" | "line"

發送管道:line 或 email。

title
string

範本標題。

bodySingle
string

單人版內文(含 {{...}} 合併變數)。

bodyMulti
string | null

多人版變體;NULL = 只有單人版。

isActive
boolean

是否為該階段目前啟用的範本。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

updatedBy
string | null

最後更新者姓名;未知或帳號已刪除時為 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/message-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "key": "…",
    "stage": "…",
    "channel": "email",
    "title": "…",
    "bodySingle": "…",
    "bodyMulti": "…",
    "isActive": true,
    "createdAt": "…",
    "updatedAt": "…",
    "updatedBy": "…"
  }
}
PATCH/api/v1/message-templates/{id}
message_template.manage

參數

id路徑
string· min 1

要更新的訊息範本 ID

key選填
string

範本識別碼,2–64 碼大寫英數 / _ / -(用於程式化引用,選填,自動轉大寫)

stage必填
string· max 100 · min 1

訊息對應的 SOP 階段(合法值 = 租戶階段目錄中的階段名)

channel必填
enum
lineemail

發送管道(line 或 email)

title必填
string· max 200 · min 1

範本標題(供後台辨識)

bodySingle必填
string· max 5000 · min 1

單人版訊息內文

bodyMulti選填
string· max 5000

多人版訊息內文(留空表示沿用單人版;選填)

isActive選填
boolean

是否啟用(停用後不出現在可選範本中)

回應欄位 · data

ok
boolean

是否成功更新訊息範本。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/message-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "stage": "example-stage",
  "channel": "line",
  "title": "example-title",
  "bodySingle": "example-bodySingle"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
DELETE/api/v1/message-templates/{id}
message_template.manage

參數

id路徑
string· min 1

訊息範本 ID

回應欄位 · data

ok
boolean

是否成功刪除訊息範本。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/message-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

enable / disable

POST/api/v1/message-templates/{id}/active
message_template.manage

參數

id路徑
string· min 1

要啟用 / 停用的訊息範本 ID

isActive必填
boolean

true 啟用、false 停用(軟刪除)此範本

回應欄位 · data

ok
boolean

是否成功切換訊息範本的啟用狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/message-templates/<id>/active" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

/roles

list all roles

GET/api/v1/roles
role.manage

參數

system選填
enum
truefalse

是否只列內建角色:true 僅內建、false 僅自訂,省略則全部

回應欄位 · data[]

id
string

角色 ID(內建角色為其代碼)。

name
string

角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。

label
string

角色顯示名稱。

isSystem
boolean

是否為系統內建角色(內建角色不可修改或刪除)。

permissionCount
number

該角色目前擁有的 (resource, action) 數量。

memberCount
number

持有此角色的使用者人數。

請求
curl -X GET "https://your-tenant.example.com/api/v1/roles" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "label": "…",
      "isSystem": true,
      "permissionCount": 0,
      "memberCount": 0
    }
  ]
}
POST/api/v1/roles
role.manage

參數

name必填
string

角色代碼,小寫英數與底線、2–32 字且須以字母開頭,建立後不可改

label必填
string

角色顯示名稱,呈現於後台角色清單

permissions選填
array

此角色授予的權限清單,每筆為一組資源與動作

orderScope選填
enum
ownall

訂單資料範圍:own 只看自己名下訂單(預設)、all 全租戶(含旅客證件解密)

回應欄位 · data

id
string

新建立的角色 ID。

請求
curl -X POST "https://your-tenant.example.com/api/v1/roles" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "label": "example-label"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

one role + its full

GET/api/v1/roles/{id}
role.manage

參數

id路徑
string· min 1

角色 ID(內建角色為其代碼)

回應欄位 · data

id
string

角色 ID(內建角色為其代碼)。

name
string

角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。

label
string

角色顯示名稱。

isSystem
boolean

是否為系統內建角色(內建角色不可修改或刪除)。

orderScope
"all" | "own"

訂單資料範圍:'own' 只看名下訂單、'all' 全租戶(含旅客證件解密)。

permissions
object[]

此角色授予的完整 (resource, action) 權限清單。

resource
string

權限資源代碼,例如 order、member。

action
string

權限動作代碼,例如 read、update。

請求
curl -X GET "https://your-tenant.example.com/api/v1/roles/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "name": "…",
    "label": "…",
    "isSystem": true,
    "orderScope": "all",
    "permissions": [
      {
        "resource": "…",
        "action": "…"
      }
    ]
  }
}
PATCH/api/v1/roles/{id}
role.manage

參數

id路徑
string· min 1

欲更新的角色 ID

label必填
string

角色顯示名稱,呈現於後台角色清單

permissions選填
array

完整取代後的權限清單,會整批覆寫此角色現有權限

orderScope選填
enum
ownall

訂單資料範圍:own 只看自己名下訂單、all 全租戶(含旅客證件解密);省略則不變

回應欄位 · data

ok
boolean

是否成功更新角色。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/roles/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "example-label"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
DELETE/api/v1/roles/{id}
role.manage

參數

id路徑
string· min 1

角色 ID(內建角色為其代碼)

回應欄位 · data

ok
boolean

是否成功刪除角色。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/roles/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

the code-defined permission catalog: every legal

GET/api/v1/roles/catalog
role.manage

回應欄位 · data[]

resource
string

權限資源代碼,例如 order、member。

label
string

中文名。

actions
object[]
action
string

動作代碼,例如 read、set-role。

label
string

中文說明;指派權限的人看的是這個。

risk選填
string | undefined

有值表示高風險,內容是授出去會發生什麼事。

請求
curl -X GET "https://your-tenant.example.com/api/v1/roles/catalog" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "resource": "…",
      "label": "…",
      "actions": [
        {
          "action": "…",
          "label": "…",
          "risk": "…"
        }
      ]
    }
  ]
}

/settings

the tenant_settings singleton

GET/api/v1/settings
role.manage

回應欄位 · data

id
string

設定列 ID(單例,恆為 'singleton')。

companyName
string

公司全名,顯示於發票、合約與對外信件抬頭。**必填**(#87,DB NOT NULL + 非空白 CHECK)。

companyPhone
string | null

公司聯絡電話,顯示於對外文件;null = 未設定。

companyEmail
string | null

公司對外聯絡信箱,自建前台的站台資訊輸出它;null = 未設定。

taxId
string | null

公司統一編號(8 位數字),用於開立發票;null = 未設定。

companyAddress
string | null

公司登記地址,顯示於對外文件;null = 未設定。

logoUrl
string | null

公司 Logo 圖片網址,用於後台與對外頁面品牌呈現;null = 未設定。

siteTagline
string | null

公開站標語(SEO/首頁);null = 未設定。

seoDefaultDescription
string | null

公開站預設 SEO meta description;null = 未設定。

ogImageUrl
string | null

社群分享預設 Open Graph 圖片網址;null = 未設定。

emailReplyTo
string | null

系統寄信時的回覆收件信箱;null = 未設定。

lineOfficialUrl
string | null

官方 LINE 加好友連結(issue 748);null = 未設定。

facebookUrl
string | null

Facebook 粉專網址;null = 未設定。

instagramUrl
string | null

Instagram 網址;null = 未設定。

youtubeUrl
string | null

YouTube 頻道網址;null = 未設定。

assignmentMode
string

S5: 'auto_round_robin' | 'auto_customer_choice' | 'manual_review'

defaultAssigneeUserId
string | null

S5: fallback assignee when round-robin finds no active sales, etc.

allowSalesClaim
boolean

order-assignment §6:業務自派搶單開關(per-tenant opt-in,預設 false)。

passportExpiryWarningDays
number

護照效期提醒天數(document-expiry §4.1;NOT NULL DEFAULT 180)。

guideCertExpiryWarningDays
number

嚮導證照到期提醒天數(#563;NOT NULL DEFAULT 60)。回程日 + 此天數 > 到期日即警示。

guideDispatchNearGap
number

派嚮導清單的「快成團」門檻人數(#1377;NOT NULL DEFAULT 2)。

groupCodePattern
string | null

團號 token 樣板(如 '{YY}{region}{airline?}{MMDD}{seq}')。NULL = 內建預設。

groupCodeSeqStyle
string

序號樣式:'alpha' | 'alpha_no_io' | 'numeric'(NOT NULL DEFAULT 'alpha')。

groupCodeSeqWidth
number

numeric 序號補零寬度(NOT NULL DEFAULT 2;alpha 樣式忽略)。

ecpayFeeBps
number

預估綠界手續費率(270 = 2.70%)。NOT NULL DEFAULT 270。

fongshouFeeBps
number

預估豐收款手續費率(50 = 0.50%)。NOT NULL DEFAULT 50。

profitTaxBps
number

預估發票 / 營所稅率(500 = 5.00%)。NOT NULL DEFAULT 500。

salesCommissionBps
number

業務抽成率(1000 = 10.00%)。NOT NULL DEFAULT 1000。

monthlyTopBonusBps
number

月度第一名加碼率(500 = 5.00%)。NOT NULL DEFAULT 500。

senderLocalPart
string | null

寄件人 local-part,未填視為 'info'。

storefrontTemplate
string

前台店面模板 key(storefront-templates §3)。可能對不上 registry(打錯、模板 改名/下架)—— 前台渲染一律經 resolveStorefrontTemplate() fallback `minimal`。

customStorefrontUrl
string | null
websiteMode
"platform" | "headless" | null
activeCustomStorefrontUrl
string | null
customStorefrontTripPath
string | null
ga4MeasurementId
string | null

轉換追蹤 ID(specs/conversion-tracking.md)。NULL = 不載入該追蹤碼。

metaPixelId
string | null
googleAdsId
string | null
customerCancelUnpaidEnabled
boolean

未付款單可否由客人自行線上取消。

customerCancelPaidEnabled
boolean

已付款(含只付訂金)單可否由客人自行線上取消。

customerCancelPaidMinDaysBefore
number

已付款單的出發日門檻:距出發 < 此天數即不可線上取消。

customerRescheduleMinDaysBefore
number | null

自助換梯門檻(customer-cancellation §8.1):null = 不開放,N = 來源與目標距出發 ≥ N 天。

customerRescheduleSurplus
"keep_overpaid" | "refund_draft"

自助換梯後新梯較便宜時的差額處理(§8.5)。

cancellationFeeTiers
object[]

租戶預設退改費階梯(已正規化、降序)。`[]` = 不收退改費。

daysBefore
number

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

feePercent選填
number | undefined

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

feeFixedTwd選填
number | undefined

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

refundRemitFeeTwd
number

退款轉帳費(customer-cancellation §3.4,按單一次)。走匯出的退款才收,刷退恆 0。

refundApprovalPolicy
object

退款核准權限(#1405)。見 `refunds/approval-policy`。

approverRoles
string[] | null

可核准退款的角色名單。null = 不另外限縮,持有 `refund.approve` 的角色都可核准。

accountantCanCreate
boolean

內建會計角色可開退款單並送審(`refund.create`)。

selfApprovalEnabled
boolean

建單人可以核准自己的退款單。關 = 維持現狀的責任分離:只擋建單人 (`CREATOR_CANNOT_APPROVE`),送審人不受限。

customerCancelReminder
string | null

客人自助取消提醒文字(customer-cancellation §5.1);null = 不顯示。

lotteryFilingFeeTiers
object[]

送件行政費的次數階梯(customer-cancellation §3.6,**每人**,已正規化、升序)。 `[]` = 不收。計次範圍是該訂單所屬的備案鏈。

fromCount
number

累計未中籤 ≥ 此次數時適用本列(最小 1)。

totalTwd
number

到 `fromCount` 次為止的**累計總額**(整數 TWD,每位旅客各自計)。

tourAgreementEnabled
boolean

契約流程總開關(預設關)。

tourAgreementTravelForm
"group" | "individual"

舊 API 的單一旅遊型態;只供相容使用。

tourAgreementDomesticTravelForm
"group" | "individual"
tourAgreementOverseasTravelForm
"group" | "individual"
companyRepresentative
string | null

乙方負責人;null = 未設定 → 契約 fail-closed。

travelAgencyRegistrationNo
string | null

旅行業註冊編號;null = 未設定 → 契約 fail-closed。

courtJurisdiction
string | null

合意管轄法院;null = 未設定 → 契約 fail-closed。

tourAgreementChangeDaysDefault
number

可變更第三人期限:免抽籤梯次預設(NOT NULL DEFAULT 35)。

tourAgreementChangeBufferDays
number

可變更第三人期限:抽籤日前的緩衝天數(NOT NULL DEFAULT 5)。

tourAgreementLotteryDeadlineTypeKey選填
string | null | undefined
tourAgreementReviewHardBlock
boolean

審閱期硬擋 24 小時(預設關,只記錄提供 / 簽署時間)。

tourAgreementGuardianSigning
boolean

未成年由法定代理人代簽(預設開)。

tourAgreementSoftBlock
boolean

出團軟擋:未簽列入出團前待辦(預設關;系統永不硬擋)。

escortLeadLabel
string

隨團人員職稱:`leader` 的顯示文字(issue 587;NOT NULL DEFAULT '主要隨團人員')。

escortAssistantLabel
string

隨團人員職稱:`assistant` 的顯示文字(NOT NULL DEFAULT '協同')。

updatedAt
string

設定最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "companyName": "…",
    "companyPhone": "…",
    "companyEmail": "…",
    "taxId": "…",
    "companyAddress": "…",
    "logoUrl": "…",
    "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": "platform",
    "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": "…"
  }
}
PATCH/api/v1/settings
role.manage

參數

companyName選填
string· max 200 · min 1

公司全名,顯示於發票、合約與對外信件抬頭。必填欄,不可清除(省略=不修改)

companyPhone選填
string· max 40

公司聯絡電話,顯示於對外文件;傳 null 或空字串清除

taxId選填
string· 格式限定

公司統一編號(8 位數字),用於開立發票;傳 null 或空字串清除

companyAddress選填
string· max 500

公司登記地址,顯示於對外文件;傳 null 或空字串清除

logoUrl選填
string· max 2000

公司 Logo 圖片網址(http/https 或本站圖庫資產路徑),用於後台與對外頁面品牌呈現;傳 null 或空字串清除

emailReplyTo選填
string · email· max 120

系統寄信時的回覆收件信箱,客戶回信會寄到此處;傳 null 或空字串清除

senderLocalPart選填
string· 格式限定 · max 64

寄件人信箱的帳號部分(@ 前段),與寄件網域組成完整寄件地址;傳 null 或空字串清除

passportExpiryWarningDays選填
integer· max 3650 · min 1

護照到期前提早幾天提醒(1 至 3650 天),用於行前護照效期預警

guideCertExpiryWarningDays選填
integer· max 3650 · min 1

嚮導證照到期提醒天數(1 至 3650 天):梯次回程日加上此天數晚於到期日即警示

guideDispatchNearGap選填
integer· max 99 · min 0

派嚮導清單的快成團門檻(0 至 99 人):還沒成團、但離成團門檻在此人數以內的梯次預設列進清單

escortLeadLabel選填
string· max 20 · min 1

主要隨團人員(leader)在畫面與信件上的職稱,例:領隊、嚮導(1 至 20 字,不可清空)

escortAssistantLabel選填
string· max 20 · min 1

協同(assistant)在畫面與信件上的職稱,例:導遊、協作嚮導(1 至 20 字,不可清空)

回應欄位 · data

ok
boolean

是否成功更新租戶設定。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "companyName": "example-companyName",
  "companyPhone": "example-companyPhone",
  "taxId": "12345678"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

the staff pool eligible to be an

GET/api/v1/settings/assignable-staff
role.manage

回應欄位 · data[]

userId
string

員工的使用者 ID(作為指派對象)。

name
string

員工顯示姓名。

email
string

員工登入 Email。

role
string

員工角色代碼(sales/admin 等可指派角色)。

thisMonthAssigned
number

本月(Asia/Taipei)已指派給此員工的訂單數(供輪派負載參考)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/assignable-staff" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "name": "…",
      "email": "…",
      "role": "…",
      "thisMonthAssigned": 0
    }
  ]
}

S5 order-assignment mode + default

PATCH/api/v1/settings/assignment
role.manage模組:tour

參數

assignmentMode必填
enum
auto_round_robinauto_customer_choiceauto_by_destinationmanual_review

訂單指派模式:auto_round_robin 輪流自動指派、auto_customer_choice 依客戶選擇指派、auto_by_destination 依目的地地區碼對應規則指派、manual_review 進待審由人工指派

defaultAssigneeUserId選填
string

預設承辦人員的使用者 ID,自動指派找不到對象時的兜底承辦人;空字串表示不設預設

allowSalesClaim選填
boolean

是否開放業務自派搶單(從待派發池自行搶單);未提供則不變更

回應欄位 · data

ok
boolean

是否成功更新訂單指派模式設定。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/assignment" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "assignmentMode": "auto_round_robin"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

PUT/api/v1/settings/cancellation-policy
role.manage

參數

unpaidEnabled必填
boolean

Enable unpaid customer cancellation

paidEnabled必填
boolean

Enable paid customer cancellation

paidMinDaysBefore必填
integer· max 365 · min 0

Minimum days before departure

refundRemitFeeTwd必填
integer· max 10000 · min 0

Refund remittance fee

feeTiers必填
array

Cancellation tiers; exactly one fee per row

lotteryFilingFeeTiers必填
array

Cumulative filing fee tiers

customerCancelReminder選填
string

Plain-text reminder shown before a customer confirms self-cancellation; null or blank clears it, omit to keep it

customerRescheduleMinDaysBefore選填
integer· max 365 · min 0

Customer self-service departure change: source and target must be at least this many days away; null turns it off, omit to keep it

customerRescheduleSurplus選填
enum
refund_draftkeep_overpaid

When the new departure is cheaper: refund_draft opens a refund draft, keep_overpaid keeps the surplus on the order; omit to keep it

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/cancellation-policy" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "unpaidEnabled": true,
  "paidEnabled": true,
  "paidMinDaysBefore": 1,
  "refundRemitFeeTwd": 1,
  "feeTiers": [
    {
      "daysBefore": 0,
      "feePercent": 100
    }
  ],
  "lotteryFilingFeeTiers": [
    {
      "fromCount": 1,
      "totalTwd": 1
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Read the domestic and overseas departure

GET/api/v1/settings/departure-owner-rotation
role.manage模組:tour

回應欄位 · data

domestic
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

overseas
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/departure-owner-rotation" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "domestic": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    },
    "overseas": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    }
  }
}
PUT/api/v1/settings/departure-owner-rotation
role.manage模組:tour

參數

region必填
enum
domesticoverseas

Which list to replace: domestic (國內線) or overseas (海外線)

userIds必填
array· max 100

Staff user IDs in rotation order. Each must be an op or admin account that is not banned. An empty array clears the list

回應欄位 · data

domestic
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

overseas
object
members
object[]
userId
string
name
string
assignable
boolean

false = 目前不可指派(角色改了或封鎖中),輪到時會跳過。

nextUserId
string | null

下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。

請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/departure-owner-rotation" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "region": "domestic",
  "userIds": [
    "example-userIds"
  ]
}'
回應
{
  "ok": true,
  "data": {
    "domestic": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    },
    "overseas": {
      "members": [
        {
          "userId": "…",
          "name": "…",
          "assignable": true
        }
      ],
      "nextUserId": "…"
    }
  }
}

Use the canonical tenant operation.

GET/api/v1/settings/destination-rules
role.manage模組:tour

回應欄位 · data[]

id
string
regionCode
string
regionName
string | null

地區中文名稱。

assigneeUserId
string | null

受派業務 userId;null = assignee 離職/刪帳號後被 SET NULL(規則退化為未命中)。

assigneeName
string | null

受派業務姓名;未指派或帳號已刪除時為 null。

assigneeRole
string | null
createdAt
string
updatedAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/destination-rules" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "regionCode": "…",
      "regionName": "…",
      "assigneeUserId": "…",
      "assigneeName": "…",
      "assigneeRole": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
PUT/api/v1/settings/destination-rules
role.manage模組:tour

參數

regionCode必填
string· min 1

Region code

assigneeUserId必填
string· min 1

Staff user ID

回應欄位 · data

id
string
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/destination-rules" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "regionCode": "example-regionCode",
  "assigneeUserId": "example-assigneeUserId"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

Use the canonical tenant operation.

DELETE/api/v1/settings/destination-rules/{id}
role.manage模組:tour

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
boolean
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/settings/destination-rules/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
PUT/api/v1/settings/ecpay-credentials
role.manage

參數

merchantId必填
string· max 20 · min 1

綠界 ECPay 特店編號(MerchantID),用於金流請款與簽章

hashKey必填
string· max 100 · min 1

綠界 ECPay HashKey,CheckMacValue 簽章用密鑰;寫入後即 KMS 加密儲存且永不回傳

hashIv必填
string· max 100 · min 1

綠界 ECPay HashIV,CheckMacValue 簽章用初始向量;寫入後即 KMS 加密儲存且永不回傳

回應欄位 · data

ok
boolean

是否成功儲存 ECPay 憑證(HashKey/HashIV 已 KMS 加密,永不回傳)。

請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/ecpay-credentials" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "example-merchantId",
  "hashKey": "example-hashKey",
  "hashIv": "example-hashIv"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
DELETE/api/v1/settings/ecpay-credentials
role.manage

回應欄位 · data

ok
boolean

是否成功清除 ECPay 憑證。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/settings/ecpay-credentials" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

公司營業費用類別目錄

GET/api/v1/settings/expense-categories
operating_expense.read模組:accounting

參數

activeOnly選填
boolean

是否只回傳啟用中的費用類別(true/false);省略則含停用

回應欄位 · data[]

id
string

費用類別 ID。

code
string

科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。

displayName
string

顯示名(如 房租 / 行政薪資 / 營業稅)。

kind
"opex" | "platform_fee" | "special" | "tax"

費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。

isActive
boolean

是否啟用(停用不刪,既有費用列仍引用得到)。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/expense-categories" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "kind": "opex",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
POST/api/v1/settings/expense-categories
operating_expense.manage模組:accounting

參數

code必填
string· 格式限定 · max 40 · min 1

費用類別代碼(小寫英數與底線),建立後不可變更,作為類別的穩定識別

displayName必填
string· max 100 · min 1

費用類別顯示名稱,呈現於後台費用登錄與報表

kind必填
enum
opextaxplatform_feespecial

費用類別種類:opex 營業費用、tax 稅務、platform_fee 平台手續費、special 特殊,影響損益表歸類

回應欄位 · data

id
string

新建立的費用類別 ID。

請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/expense-categories" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "undefined_example",
  "displayName": "example-displayName",
  "kind": "opex"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

更新費用類別的顯示名 / kind +

PATCH/api/v1/settings/expense-categories/{id}
operating_expense.manage模組:accounting

參數

id路徑
string· min 1

費用類別 ID(路徑參數),指定要更新的類別

displayName必填
string· max 100 · min 1

費用類別顯示名稱,呈現於後台費用登錄與報表

kind必填
enum
opextaxplatform_feespecial

費用類別種類:opex 營業費用、tax 稅務、platform_fee 平台手續費、special 特殊,影響損益表歸類

isActive必填
boolean

是否啟用此費用類別;false 為停用(停用而非刪除)

回應欄位 · data

ok
boolean

是否成功更新費用類別。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/expense-categories/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "example-displayName",
  "kind": "opex",
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

toggle a費用類別

PATCH/api/v1/settings/expense-categories/{id}/active
operating_expense.manage模組:accounting

參數

id路徑
string· min 1

費用類別 ID(路徑參數),指定要切換啟用狀態的類別

isActive必填
boolean

目標啟用狀態:true 啟用、false 停用(停用而非刪除)

回應欄位 · data

ok
boolean

是否成功切換費用類別的啟用狀態。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/expense-categories/<id>/active" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

fee-category → final receiving

GET/api/v1/settings/fee-category-routes
receiving_account.manage模組:accounting

回應欄位 · data[]

id
string

路由設定 ID。

feeCategory
string

費用類型代碼(租戶自定唯一鍵,如 tour_fee/lodging/equipment)。

displayName
string

費用類型顯示名。

finalAccountId
string

此費用類型最終結算進的收款帳戶 ID。

finalAccountName
string | null

最終收款帳戶名稱;無對應帳戶時為 null。

finalAccountCode
string | null

final 帳戶代號。

isActive
boolean

此路由是否啟用。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/fee-category-routes" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "feeCategory": "…",
      "displayName": "…",
      "finalAccountId": "…",
      "finalAccountName": "…",
      "finalAccountCode": "…",
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
PUT/api/v1/settings/fee-category-routes
receiving_account.manage模組:accounting

參數

feeCategory必填
string· 格式限定 · max 40 · min 1

費用類型代碼(小寫英數與底線),此 upsert 的唯一鍵;決定該手續費類型最終結算到哪個帳戶

displayName必填
string· max 100 · min 1

費用類型路由的顯示名稱,呈現於對帳設定

finalAccountId必填
string· min 1

此費用類型最終結算進的收款帳戶 ID

isActive選填
boolean

是否啟用此費用類型路由;省略則維持預設啟用

回應欄位 · data

id
string

新建立或更新的費用類型路由 ID。

請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/fee-category-routes" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "feeCategory": "undefined_example",
  "displayName": "example-displayName",
  "finalAccountId": "example-finalAccountId"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

toggle a fee-category

PATCH/api/v1/settings/fee-category-routes/{id}/active
receiving_account.manage模組:accounting

參數

id路徑
string· min 1

費用類型路由 ID(路徑參數,非 feeCategory 代碼),指定要切換啟用狀態的路由

isActive必填
boolean

目標啟用狀態:true 啟用、false 停用(停用而非刪除)

回應欄位 · data

ok
boolean

是否成功切換費用類型路由的啟用狀態。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/fee-category-routes/<id>/active" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

GET/api/v1/settings/fee-item-presets
role.manage

回應欄位 · data[]

id
string
text
string

項目文字(租戶內唯一)。

included
boolean

預設歸「含」(true)或「不含」(false)。

displayOrder
number
createdAt
string
updatedAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/fee-item-presets" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "text": "…",
      "included": true,
      "displayOrder": 0,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
POST/api/v1/settings/fee-item-presets
role.manage

參數

text必填
string· max 100 · min 1

Fee text

included必填
boolean

Included in trip price

displayOrder選填
integer

Display order

回應欄位 · data

id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/fee-item-presets" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "example-text",
  "included": true
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

Use the canonical tenant operation.

PUT/api/v1/settings/fee-item-presets/{id}
role.manage

參數

id路徑
string· min 1

Resource ID

text必填
string· max 100 · min 1

Fee text

included必填
boolean

Included in trip price

displayOrder選填
integer

Display order

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/fee-item-presets/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "example-text",
  "included": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/settings/fee-item-presets/{id}/delete
role.manage

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/fee-item-presets/<id>/delete" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

PUT/api/v1/settings/group-code-pattern
group_code.manage模組:tour

參數

pattern必填
string· max 120

Pattern; null restores default

seqStyle必填
enum
alphaalpha_no_ionumeric

Sequence style

seqWidth必填
integer· max 6 · min 1

Sequence width

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/group-code-pattern" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "pattern": "{region}{YY}{MMDD}-{seq}",
  "seqStyle": "alpha",
  "seqWidth": 2
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

PUT/api/v1/settings/guide-portal-policy
role.manage模組:tour

參數

loginMode必填
enum
password_totppassword_only

Guide login mode

dossierWindowDays必填
integer· max 365 · min 0

Roster access days after return

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/guide-portal-policy" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "loginMode": "password_totp",
  "dossierWindowDays": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

各家整合的憑證綁定狀態

GET/api/v1/settings/integration-credentials
role.manage

回應欄位 · data[]

provider
string

整合代號(`ecpay` / `travelinvoice`… / 轉換追蹤的 `ga4`、`meta`)。列不存在=該家未綁定。

merchantId
string

金鑰綁定的帳號 ID(明文,顯示 / 診斷用):金流是特店 ID,`ga4` 是 Measurement ID,`meta` 是 Pixel ID。

secretsMask
string | null

金鑰的遮罩碼(`****` + 末 4):金流是 HashKey,`ga4`/`meta` 是後端補送的金鑰。金鑰本身永不回傳。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/integration-credentials" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "provider": "…",
      "merchantId": "…",
      "secretsMask": "…"
    }
  ]
}

internal/external-ledger profit estimate

PATCH/api/v1/settings/ledger-fees
role.manage模組:accounting

參數

ecpayFeeBps選填
integer· max 10000 · min 0

綠界 ECPay 金流手續費率,單位 basis points(0..10000,10000=100%),用於內外帳參考預估淨利;留空不變更

fongshouFeeBps選填
integer· max 10000 · min 0

豐收金流手續費率,單位 basis points(0..10000,10000=100%),用於內外帳參考預估淨利;留空不變更

profitTaxBps選填
integer· max 10000 · min 0

淨利稅率,單位 basis points(0..10000,10000=100%),用於內外帳參考預估淨利;留空不變更

回應欄位 · data

ok
boolean

是否成功更新內外帳參考預估淨利費率。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/ledger-fees" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ecpayFeeBps": "",
  "fongshouFeeBps": "",
  "profitTaxBps": ""
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Read the tenant's plan module flags.

GET/api/v1/settings/modules
role.manage

回應欄位 · data

tour
boolean
climbing
boolean
lodging
boolean
accounting
boolean
lottery
boolean
api_access
boolean
headless_storefront
boolean
custom_domain
boolean
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/modules" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "tour": true,
    "climbing": true,
    "lodging": true,
    "accounting": true,
    "lottery": true,
    "api_access": true,
    "headless_storefront": true,
    "custom_domain": true
  }
}
GET/api/v1/settings/payment-provider
role.manage

回應欄位 · data

selected
"ecpay" | "manual" | "newebpay" | "paynow" | "payuni" | "sinopac" | "test"
switchingAllowed
boolean
testAllowed
boolean
providers
{ credential: { merchantId: string; mask: string | null; } | null; versions: { id: string; merchantAccount: string; environment: string; mask: string | null; createdAt: string; current: boolean; }[]; ... 11 more ...; requiresFeePolicy: false; } | { ...; } | { ...; } | { ...; } | { ...; }[]
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/payment-provider" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "selected": "ecpay",
    "switchingAllowed": true,
    "testAllowed": true,
    "providers": [
      "…"
    ]
  }
}
PUT/api/v1/settings/payment-provider
role.manage

參數

operation必填
enum
switchconfigurechange_merchantrotate_keyunlinkfee_policy
provider必填
enum
manualtestecpaypayuninewebpaypaynowsinopac
merchantId選填
string· max 25 · min 1

Required for credential configuration, merchant changes, and key rotation.

environment選填
enum
sandboxproduction

Required for credential operations.

hashKey選填
string· max 100 · min 1

Required with HashIV for ECPay and PAYUNi. This secret is never returned.

hashIv選填
string· max 100 · min 1

Required with HashKey for credential operations. This secret is never returned.

transactionPassword選填
string· max 200 · min 1

Required for PayNow credential operations. This secret is never returned.

hashA1選填
string· 格式限定

Required for SinoPac credential operations. This secret is never returned.

hashA2選填
string· 格式限定

Required for SinoPac credential operations. This secret is never returned.

hashB1選填
string· 格式限定

Required for SinoPac credential operations. This secret is never returned.

hashB2選填
string· 格式限定

Required for SinoPac credential operations. This secret is never returned.

xKey選填
string· max 1000 · min 1

Required for SinoPac credential operations. This secret is never returned.

notificationFeeBps選填
integer· max 10000 · min 0

Required for fee_policy. New PAYUNi, NewebPay, and PayNow attempts retain this fee estimate.

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/payment-provider" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "switch",
  "provider": "manual"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

GET/api/v1/settings/pnl-regions
operating_expense.manage模組:accounting

回應欄位 · data[]

id
string
code
string
displayName
string
displayOrder
number
isActive
boolean
createdAt
string
updatedAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/pnl-regions" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "code": "…",
      "displayName": "…",
      "displayOrder": 0,
      "isActive": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
POST/api/v1/settings/pnl-regions
operating_expense.manage模組:accounting

參數

code必填
string· max 40 · min 1

Region code

displayName必填
string· min 1

Region name

displayOrder選填
integer

Display order

回應欄位 · data

id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/pnl-regions" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "displayName": "example-displayName"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

Use the canonical tenant operation.

PUT/api/v1/settings/pnl-regions/{id}
operating_expense.manage模組:accounting

參數

id路徑
string· min 1

Resource ID

displayName必填
string· min 1

Region name

displayOrder選填
integer

Display order

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/pnl-regions/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "example-displayName"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/settings/pnl-regions/{id}/active
operating_expense.manage模組:accounting

參數

id路徑
string· min 1

Resource ID

isActive必填
boolean

Enabled status

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/pnl-regions/<id>/active" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

the收款帳戶目錄

GET/api/v1/settings/receiving-accounts
receiving_account.manage

參數

activeOnly選填
boolean

是否只回傳啟用中的收款帳戶(true/false);省略則含停用

回應欄位 · data[]

id
string

收款帳戶 ID。

code
string

帳戶代碼(租戶內唯一穩定識別)。

displayName
string

帳戶顯示名。

kind
"bank" | "cash" | "gateway"

帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。

gatewayProvider
string | null

綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `payment/gateway-providers.ts`。

bankName
string | null

銀行名稱;現金/閘道帳戶為 null。

accountNo
string | null

銀行帳號;現金/閘道帳戶為 null。

bankCode
string | null
bankBranch
string | null
accountHolder
string | null
canReceive
boolean

可收款(幾乎都 true)。

canRemit
boolean

可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。

canChargeback
boolean

可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。

canPaySupplier
boolean

付款渠道:出團準備的付款登記區可選它付供應商(#1375)。

isDeprecated
boolean

廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。

isSettlementMaster
boolean

主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。

payoutAccountId
string | null

撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。

currency
string

帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。

isActive
boolean

此帳戶是否啟用。

displayOrder
number

後台清單排序序位(小者在前)。

usedCount
number

被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。

currencyLocked
boolean

幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/receiving-accounts" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
    }
  ]
}
POST/api/v1/settings/receiving-accounts
receiving_account.manage

參數

code必填
string· max 40 · min 1

收款帳戶代號,建立後不可變更,作為帳戶的穩定識別

displayName必填
string· max 100 · min 1

收款帳戶顯示名稱,呈現於收款與對帳介面

kind必填
enum
bankcashgateway

帳戶種類:bank 銀行帳戶、cash 現金、gateway 金流閘道

gatewayProvider選填
enum

綁定的金流商代號(如 ecpay),限 gateway 帳戶;該金流商的收款會自動歸入此帳戶。空字串或省略 = 不綁定

payoutAccountId選填
string· min 1

撥款帳戶 ID,限 gateway 帳戶:金流商把收款撥進的台幣銀行帳戶(須啟用中)。設定後月結把此帳戶的收款落地改算成撥款帳戶。空字串或省略 = 不設

bankName選填
string· max 100

銀行名稱(bank 類別適用);空字串清除

bankCode選填
string· max 3

銀行代碼;匯款用途須填完整

bankBranch選填
string· max 100

分行;匯款用途須填完整

accountHolder選填
string· max 100

戶名;匯款用途須填完整

accountNo選填
string· max 50

銀行帳號(bank 類別適用);空字串清除

currency選填
string· 格式限定

帳戶幣別,ISO 4217 三碼(如 TWD / JPY / IDR);空字串預設 TWD,非 TWD 即為外幣池

displayOrder選填
integer· max 9999 · min 0

排序權重(0..9999),數字越小越前面;預設 0

isActive選填
boolean

是否啟用此帳戶;省略維持預設

canReceive選填
boolean

是否可作為收款(進帳)帳戶

canRemit選填
boolean

是否可作為出款(匯出)帳戶

canPaySupplier選填
boolean

是否可作為出團準備付款登記的付款渠道(例:小編機)

isDeprecated選填
boolean

是否標記為已淘汰(保留歷史紀錄但不再新用)

isSettlementMaster選填
boolean

是否為主結算帳戶;每租戶僅能有一個,月結互抵以此為彙整中心

回應欄位 · data

id
string

新建立的收款帳戶 ID。

請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/receiving-accounts" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "example-code",
  "displayName": "example-displayName",
  "kind": "bank"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

update a收款帳戶

PATCH/api/v1/settings/receiving-accounts/{id}
receiving_account.manage

參數

id路徑
string· min 1

收款帳戶 ID(路徑參數),指定要更新的帳戶

displayName必填
string· max 100 · min 1

收款帳戶顯示名稱,呈現於收款與對帳介面

kind必填
enum
bankcashgateway

帳戶種類:bank 銀行帳戶、cash 現金、gateway 金流閘道

gatewayProvider選填
enum

綁定的金流商代號(如 ecpay),限 gateway 帳戶;省略維持原值,空字串解除綁定

payoutAccountId選填
string· min 1

撥款帳戶 ID,限 gateway 帳戶:金流商把收款撥進的台幣銀行帳戶(須啟用中)。省略維持原值,空字串或 null 清除

bankName選填
string· max 100

銀行名稱(bank 類別適用);空字串清除

bankCode選填
string· max 3

銀行代碼;匯款用途須填完整

bankBranch選填
string· max 100

分行;匯款用途須填完整

accountHolder選填
string· max 100

戶名;匯款用途須填完整

accountNo選填
string· max 50

銀行帳號(bank 類別適用);空字串清除

currency選填
string· 格式限定

帳戶幣別,ISO 4217 三碼(如 TWD / JPY / IDR);省略維持原值,非 TWD 即為外幣池

displayOrder必填
integer· max 9999 · min 0

排序權重(0..9999),數字越小越前面

isActive選填
boolean

是否啟用此帳戶;省略維持原值

canReceive選填
boolean

是否可作為收款(進帳)帳戶

canRemit選填
boolean

是否可作為出款(匯出)帳戶

canPaySupplier選填
boolean

是否可作為出團準備付款登記的付款渠道(例:小編機)

isDeprecated選填
boolean

是否標記為已淘汰(保留歷史紀錄但不再新用)

isSettlementMaster選填
boolean

是否為主結算帳戶;每租戶僅能有一個,月結互抵以此為彙整中心

回應欄位 · data

ok
boolean

是否成功更新收款帳戶。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/receiving-accounts/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "example-displayName",
  "kind": "bank",
  "displayOrder": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

GET/api/v1/settings/recurring-expenses
operating_expense.manage模組:accounting

回應欄位 · data[]

id
string
categoryId
string
categoryCode
string | null
categoryDisplayName
string | null
categoryKind
string | null
amountTwd
number
description
string
paidFromAccountId
string | null
paidFromAccountName
string | null
isActive
boolean
createdByUserId
string
createdAt
string
updatedAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/recurring-expenses" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "categoryId": "…",
      "categoryCode": "…",
      "categoryDisplayName": "…",
      "categoryKind": "…",
      "amountTwd": 0,
      "description": "…",
      "paidFromAccountId": "…",
      "paidFromAccountName": "…",
      "isActive": true,
      "createdByUserId": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
POST/api/v1/settings/recurring-expenses
operating_expense.manage模組:accounting

參數

categoryId必填
string· min 1

Expense category ID

amountTwd必填
integer

Default amount TWD

description必填
string· min 1

Description

paidFromAccountId選填
string· min 1

Payer account ID

回應欄位 · data

id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/recurring-expenses" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "categoryId": "example-categoryId",
  "amountTwd": 1,
  "description": "example-description"
}'
回應
{
  "ok": true,
  "data": {
    "id": "…"
  }
}

Use the canonical tenant operation.

PUT/api/v1/settings/recurring-expenses/{id}
operating_expense.manage模組:accounting

參數

id路徑
string· min 1

Resource ID

categoryId必填
string· min 1

Expense category ID

amountTwd必填
integer

Default amount TWD

description必填
string· min 1

Description

paidFromAccountId選填
string· min 1

Payer account ID

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/recurring-expenses/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "categoryId": "example-categoryId",
  "amountTwd": 1,
  "description": "example-description"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/settings/recurring-expenses/{id}/active
operating_expense.manage模組:accounting

參數

id路徑
string· min 1

Resource ID

isActive必填
boolean

Enabled status

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/recurring-expenses/<id>/active" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

the tenant's custom email sending-domain

GET/api/v1/settings/sending-domain
role.manage

回應欄位 · data

sendingDomain
string | null

自有寄件網域;未設定時為 null。

resendDomainId
string | null

寄件服務商(Resend)的網域識別碼;未設定時為 null。

sendingDomainStatus
string | null

網域驗證狀態(如 pending/verified);未設定時為 null。

senderLocalPart
string | null

寄件人信箱的帳號部分(@ 前段);未填視為 info。

records
object[]

待設定的 DNS 記錄清單(SPF/DKIM 等);Resend 不可達或未設定時為空陣列。

record
string

DNS 記錄用途分類(如 DKIM/SPF 等,來自 Resend)。

name
string

記錄主機名(需在網域 DNS 新增的 host)。

type
string

記錄類型(如 TXT/MX/CNAME)。

value
string

記錄值(需填入 DNS 的內容)。

ttl選填
string | undefined

存活時間(TTL);未指定時省略。

status選填
string | undefined

此筆記錄的驗證狀態(如 pending/verified);未指定時省略。

priority選填
number | undefined

MX 記錄優先權;非 MX 記錄省略。

請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/sending-domain" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "sendingDomain": "…",
    "resendDomainId": "…",
    "sendingDomainStatus": "…",
    "senderLocalPart": "…",
    "records": [
      {
        "record": "…",
        "name": "…",
        "type": "…",
        "value": "…",
        "ttl": "…",
        "status": "…",
        "priority": 0
      }
    ]
  }
}

tear down the tenant's custom

POST/api/v1/settings/sending-domain/disable
role.manage

回應欄位 · data

ok
boolean

是否成功停用自有寄件網域。

請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/sending-domain/disable" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

provision the tenant's custom

POST/api/v1/settings/sending-domain/enable
role.manage

回應欄位 · data

ok
boolean

是否成功啟用自有寄件網域。

domain
string

啟用的寄件網域(由綁定的站台網域派生)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/sending-domain/enable" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "domain": "…"
  }
}

re-sync DNS verification status

POST/api/v1/settings/sending-domain/verify
role.manage

回應欄位 · data

ok
boolean

是否成功觸發驗證狀態同步。

status
string

從 Resend 同步回來的最新網域驗證狀態(如 pending/verified)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/settings/sending-domain/verify" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "status": "…"
  }
}

SEO defaults subset of tenant_settings

PATCH/api/v1/settings/seo
website.edit

參數

siteTagline選填
string· max 120

網站標語,顯示於公開站標題與品牌呈現;空字串清除

seoDefaultDescription選填
string· max 300

SEO 預設頁面描述(meta description),未個別設定的頁面套用此值;空字串清除

ogImageUrl選填
string· max 2000

社群分享預設縮圖(Open Graph image)網址(http/https 或本站圖庫資產路徑);空字串清除

回應欄位 · data

ok
boolean

是否成功更新公開站 SEO 設定。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/seo" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "siteTagline": "example-siteTagline",
  "seoDefaultDescription": "example-seoDefaultDescription",
  "ogImageUrl": "https://example.com"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
GET/api/v1/settings/storefront
website.read | website.edit | website.manage

回應欄位 · data

banners
object[]
imageUrl
string
alt
string
linkUrl
string | null
name
string | null
faqs
object[]
question
string
answer
string
categories
object[]
name
string
tag
string
imageUrl
string | null
websiteMode
"headless" | "platform"
activeCustomStorefrontUrl
string | null
template
string
customStorefrontUrl
string | null
customStorefrontTripPath
string | null
slots
object
aboutContentMdx
string | null
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/storefront" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "banners": [
      {
        "imageUrl": "…",
        "alt": "…",
        "linkUrl": "…",
        "name": "…"
      }
    ],
    "faqs": [
      {
        "question": "…",
        "answer": "…"
      }
    ],
    "categories": [
      {
        "name": "…",
        "tag": "…",
        "imageUrl": "…"
      }
    ],
    "websiteMode": "headless",
    "activeCustomStorefrontUrl": "…",
    "template": "…",
    "customStorefrontUrl": "…",
    "customStorefrontTripPath": "…",
    "slots": "…",
    "aboutContentMdx": "…"
  }
}
PATCH/api/v1/settings/storefront
website.edit | website.manage

參數

websiteMode選填
enum
platformheadless

Explicitly activate the saved website address or restore the platform website

template選填
enum
outdoorresortminimalvoyage

Apply a platform template without changing the website mode

customStorefrontUrl選填
string· max 1000

Prepared HTTPS website address; saving does not activate it

customStorefrontTripPath選填
string· max 500

Trip page path on the headless storefront, with one {slug}, such as /shop/{slug}; null keeps trip links on the platform trip page

slots選填
object

Partial content overrides; null restores the template default

aboutContentMdx選填
string· max 100000

About page content; null clears it

banners選填
array· max 5

Home page banner carousel in display order; replaces the whole list

faqs選填
array· max 20

Home page FAQ in display order; replaces the whole list

categories選填
array· max 8

Home page trip categories in display order; replaces the whole list

回應欄位 · data

ok
boolean
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/settings/storefront" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "websiteMode": "platform",
  "template": "outdoor",
  "customStorefrontUrl": "https://example.com",
  "slots": {
    "hero_title": "Example trips"
  },
  "aboutContentMdx": "Example company"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Set both regional travel forms.

PUT/api/v1/settings/tour-agreement
role.manage模組:tour

參數

enabled必填
boolean

Enable agreements

domesticTravelForm選填
enum
individualgroup

Domestic travel form

overseasTravelForm選填
enum
individualgroup

Overseas travel form

travelForm選填
enum
individualgroup

Legacy travel form for both regions

companyRepresentative必填
string· max 100

Company representative

travelAgencyRegistrationNo必填
string· max 50

Agency registration number

courtJurisdiction必填
string· max 100

Court jurisdiction

changeDaysDefault必填
integer· max 365 · min 0

Default change days

lotteryDeadlineTypeKey選填
string· max 100

Deadline type for the lottery date

changeBufferDays必填
integer· max 365 · min 0

Change buffer days

reviewHardBlock必填
boolean

Enforce review period

guardianSigning必填
boolean

Allow guardian signing

softBlock必填
boolean

Enable soft block

回應欄位 · data

ok
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/tour-agreement" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}
GET/api/v1/settings/workflow-controls
role.manage

回應欄位 · data

newPaymentsPaused
boolean
newAgreementsPaused
boolean
請求
curl -X GET "https://your-tenant.example.com/api/v1/settings/workflow-controls" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "newPaymentsPaused": true,
    "newAgreementsPaused": true
  }
}
PUT/api/v1/settings/workflow-controls
role.manage

參數

newPaymentsPaused必填
boolean

Pause new payment forms

newAgreementsPaused必填
boolean

Pause new agreements

回應欄位 · data

newPaymentsPaused
boolean
newAgreementsPaused
boolean
請求
curl -X PUT "https://your-tenant.example.com/api/v1/settings/workflow-controls" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "newPaymentsPaused": true,
  "newAgreementsPaused": true
}'
回應
{
  "ok": true,
  "data": {
    "newPaymentsPaused": true,
    "newAgreementsPaused": true
  }
}

/staff

list every staffer in the tenant DB

GET/api/v1/staff
role.manage

回應欄位 · data[]

userId
string

員工的使用者 ID。

email
string

員工登入 Email(帳號識別)。

name
string

員工顯示姓名。

role
string

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

createdAt
string

帳號建立時間。

banned
boolean

Account frozen via ban (離職 / 停權). False after a temporary ban ends, also before the next sign-in clears it.

twoFactorEnabled
boolean

是否已完成 TOTP 兩步驟驗證註冊。

emailVerified
boolean

Email 是否已驗證。**不是**啟用判準:員工邀請流程不寄信(一次性密碼當場交付), 所以受邀者走完整條流程這個旗標也不會變 true。啟用看 `activated`。

lastLoginAt
string | null

最後一次登入時間;`null` = 從來沒有人登入過這個帳號。代理登入不計。

activated
boolean

派生的「已啟用」狀態:至少成功登入過一次,代表發出去的一次性密碼有人在用。

請求
curl -X GET "https://your-tenant.example.com/api/v1/staff" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "userId": "…",
      "email": "…",
      "name": "…",
      "role": "…",
      "createdAt": "…",
      "banned": true,
      "twoFactorEnabled": true,
      "emailVerified": true,
      "lastLoginAt": "…",
      "activated": true
    }
  ]
}

remove a staffer

DELETE/api/v1/staff/{userId}
role.manage

參數

userId路徑
string· min 1

欲移除員工身分的使用者 ID(將降為一般顧客)

回應欄位 · data

ok
boolean

是否成功移除員工身分(降為一般顧客)。

請求
curl -X DELETE "https://your-tenant.example.com/api/v1/staff/<userId>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/staff/{userId}/ban
role.manage

參數

userId路徑
string· min 1

Resource ID

reason選填
string

Ban reason

回應欄位 · data

ok
true
請求
curl -X POST "https://your-tenant.example.com/api/v1/staff/<userId>/ban" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}

change a staffer's role

PATCH/api/v1/staff/{userId}/role
role.manage

參數

userId路徑
string· min 1

欲變更角色的員工使用者 ID

role必填
string· min 1

變更後的員工角色(內建 admin/sales/op/accountant,或本租戶自訂角色),決定權限範圍

回應欄位 · data

ok
boolean

是否成功變更員工角色。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/staff/<userId>/role" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "example-role"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

Use the canonical tenant operation.

POST/api/v1/staff/{userId}/unban
role.manage

參數

userId路徑
string· min 1

Resource ID

回應欄位 · data

ok
true
請求
curl -X POST "https://your-tenant.example.com/api/v1/staff/<userId>/unban" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}

建立一個新員工帳號

POST/api/v1/staff/invite
role.manage

參數

email必填
string · email· max 120

受邀員工的登入 Email,作為帳號識別

name必填
string· max 100 · min 1

員工顯示姓名

role必填
string· min 1

指派的員工角色(內建 admin/sales/op/accountant,或本租戶自訂角色),決定權限範圍

回應欄位 · data

userId
string

新建立員工的使用者 ID。

tempPassword
string

一次性明文暫時密碼,僅此次回傳(請立即轉交並要求員工首次登入改密)。

email
string

新員工的登入 Email。

role
string

指派的員工角色(admin/sales/op/accountant)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/staff/invite" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "name": "example-name",
  "role": "example-role"
}'
回應
{
  "ok": true,
  "data": {
    "userId": "…",
    "tempPassword": "…",
    "email": "…",
    "role": "…"
  }
}

/departure-op-assignments

Use the canonical tenant operation.

DELETE/api/v1/departure-op-assignments/{id}
departure_prep.manage模組:tour

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
true
departureId
string
userId
string
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/departure-op-assignments/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "departureId": "…",
    "userId": "…"
  }
}

/departure-prep

跨梯次到期待辦

GET/api/v1/departure-prep/deadlines
departure_prep.read模組:tour

參數

range選填
enum
todayall

today = 只列逾期、超級緊急、可以開始三級;all(預設)= 再加注意準備

horizon選填
integer· max 30 · min 1
scope選填
enum
allunassigned

all(預設)= 全公司;unassigned = 只看尚未指派承辦的梯次

anomalies選填
boolean

設為 true 時一併回傳日期設定異常(規則適用卻沒有日期列);預設 false

回應欄位 · data

today
string
horizon
number
range
"all" | "today"
rows
object[]
softDate
string | null
hardDate
string
source
"generated" | "manual"
dayMode
"calendar" | "month_same_day" | "workday"

梯次期限列存的 day_mode(產生或人工寫入當下解析出的有效規則)。距離單位:`workday` 算工作天, 其他模式(含 `month_same_day`)算日曆天。

hardDistance
number
softDistance
number | null
urgency
"critical" | "overdue" | "start" | "upcoming"
lotteryDraw
LotteryDrawInfo | null

期限日取自抽籤時程表時的時段與原抽籤日(lottery-schedule spec §3.5)。

slotStart
string | null
slotEnd
string | null
firstDrawDate
string | null
label
string
departureId
string
tripId
string
tripTitle
string
tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

groupCode
string | null
departureDate
string
opNames
string[]

承辦小編姓名(依姓名排序);空陣列 = 未指派。

typeKey
string
anomalies
object[]

`anomalies: false` 時恆為空陣列。

label
string
departureId
string
tripId
string
tripTitle
string
tripShortName
string | null

行程內部簡稱(issue 1414);未填為 null。

groupCode
string | null
departureDate
string
opNames
string[]

承辦小編姓名(依姓名排序);空陣列 = 未指派。

typeKey
string
counts
object
overdue
number
critical
number
start
number
upcoming
number
missingHolidayYears
number[]

未逾期的工作天事項「今天 → 硬 deadline」之間假日表未維護年度的聯集。

請求
curl -X GET "https://your-tenant.example.com/api/v1/departure-prep/deadlines" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
    ]
  }
}

/email-history

GET/api/v1/email-history
email_history.read

參數

startDate選填
string· 前處理正規化(省略則補預設 / null)
endDate選填
string· 前處理正規化(省略則補預設 / null)
status選填
enum· 前處理正規化(省略則補預設 / null)
queuedsendingsentfailed
category選填
enum· 前處理正規化(省略則補預設 / null)
authorderpaymentguidecontractmessagesystem
recipient選填
string· max 254 · 前處理正規化
departureId選填
string· max 100 · 前處理正規化
orderId選填
string· max 100 · 前處理正規化
guideId選填
string· max 100 · 前處理正規化
asOf選填
string· 前處理正規化(省略則補預設 / null)
page選填
integer· max 10000 · min 1 · 前處理正規化
pageSize選填
integer· max 100 · min 1 · 前處理正規化

回應欄位 · data

items
object[]
id
string
toEmail
string
subject
string
templateKey
string
category
"auth" | "contract" | "guide" | "message" | "order" | "payment" | "system"
status
string
error
string | null
attempts
number
orderId
string | null
departureId
string | null
guideId
string | null
createdAt
string
sentAt
string | null
canRetry
boolean
retryRecipient
string | null
retryUnavailableReason
"unsupported" | "auth_requires_new_request" | "not_failed" | "intent_changed" | null
total
number
page
number
pageSize
number
asOf
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/email-history" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
  }
}
GET/api/v1/email-history/{id}
email_history.read

參數

id路徑
string· max 100 · min 1

回應欄位 · data

html
string | null
text
string | null
contentState
"available" | "masked" | "unavailable"
id
string
toEmail
string
subject
string
templateKey
string
category
"auth" | "contract" | "guide" | "message" | "order" | "payment" | "system"
status
string
error
string | null
attempts
number
orderId
string | null
departureId
string | null
guideId
string | null
createdAt
string
sentAt
string | null
canRetry
boolean
retryRecipient
string | null
retryUnavailableReason
"unsupported" | "auth_requires_new_request" | "not_failed" | "intent_changed" | null
請求
curl -X GET "https://your-tenant.example.com/api/v1/email-history/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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"
  }
}
POST/api/v1/email-history/{id}/retry
email_history.retry

參數

id路徑
string· max 100 · min 1
expectedRecipient選填
string · email

回應欄位 · data

retried
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/email-history/<id>/retry" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedRecipient": "customer@example.com"
}'
回應
{
  "ok": true,
  "data": {
    "retried": true
  }
}

/guide-categories

List guide categories with guide counts

GET/api/v1/guide-categories
guide.read模組:tour

回應欄位 · data[]

id
string
name
string
sortOrder
number
isActive
boolean

停用 = 不供新選用(既有嚮導照舊顯示這個分類)。

guideCount
number

引用此分類的嚮導數(>0 時不可刪,只可停用)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guide-categories" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "sortOrder": 0,
      "isActive": true,
      "guideCount": 0
    }
  ]
}
POST/api/v1/guide-categories
guide.manage模組:tour

參數

name必填
string· max 100 · min 1

Guide category name

sortOrder選填
integer

Display order; also the default guide sort order

回應欄位 · data

ok
true
id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/guide-categories" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}

Rename, reorder, or deactivate a guide category

PATCH/api/v1/guide-categories/{id}
guide.manage模組:tour

參數

id路徑
string· min 1

Resource ID

name選填
string· max 100 · min 1

Guide category name

sortOrder選填
integer

Display order; also the default guide sort order

isActive選填
boolean

Category enabled; inactive categories stay on existing guides but are not offered for new ones

回應欄位 · data

ok
true
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/guide-categories/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "sortOrder": 1,
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
DELETE/api/v1/guide-categories/{id}
guide.manage模組:tour

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
true
removed
object
name
string
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/guide-categories/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "removed": {
      "name": "…"
    }
  }
}

/guide-certificate-types

Use the canonical tenant operation.

GET/api/v1/guide-certificate-types
guide.read模組:tour

回應欄位 · data[]

id
string
name
string
sortOrder
number
isActive
boolean

停用 = 不供新證照選用(既有證照不受影響)。

certificateCount
number

引用此類別的證照數(>0 時不可刪,只可停用)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/guide-certificate-types" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "sortOrder": 0,
      "isActive": true,
      "certificateCount": 0
    }
  ]
}
POST/api/v1/guide-certificate-types
guide.manage模組:tour

參數

name必填
string· max 100 · min 1

Certificate type name

sortOrder選填
integer

Display order

回應欄位 · data

ok
true
id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/guide-certificate-types" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}

Use the canonical tenant operation.

PATCH/api/v1/guide-certificate-types/{id}
guide.manage模組:tour

參數

id路徑
string· min 1

Resource ID

name選填
string· max 100 · min 1

Type name

sortOrder選填
integer

Display order

isActive選填
boolean

Type enabled

回應欄位 · data

ok
true
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/guide-certificate-types/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "sortOrder": 1,
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
DELETE/api/v1/guide-certificate-types/{id}
guide.manage模組:tour

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
true
removed
object
name
string
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/guide-certificate-types/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "removed": {
      "name": "…"
    }
  }
}

/guide-portal

嚮導顯示自己帶梯次旅客的證號

POST/api/v1/guide-portal/travelers/{travelerId}/reveal
guide_portal.read模組:tour

參數

travelerId路徑
string· min 1

旅客 ID

field必填
enum
idNumberpassportNo

欲顯示全碼的個資欄位:idNumber 身分證字號、passportNo 護照號碼

請求
curl -X POST "https://your-tenant.example.com/api/v1/guide-portal/travelers/<travelerId>/reveal" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "field": "idNumber"
}'
回應
{
  "ok": true,
  "data": "idNumber"
}

/lottery-filings

Use the canonical tenant operation.

POST/api/v1/lottery-filings/adjustments
lottery.manage模組:lottery

參數

personId必填
string· min 1

Person ID

orderId必填
string· min 1

Order ID

delta必填
integer· max 20

Signed adjustment

reason必填
string· max 500 · min 1

Adjustment reason

回應欄位 · data

personId
string
chains
object[]

依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。

headOrderId
string

鏈首訂單(分組鍵)。

headOrderNumber
string
filingCount
number

送件紀錄筆數(這條鏈上)。

adjustmentTotal
number

調整差額加總(這條鏈上,可負)。

count
number

目前送件次數加上調整差額,下限為 0。

nextSeq
number

下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。

filings
object[]
id
string
orderId
string
orderNumber
string
travelerName
string | null

送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。

createdAt
string
adjustments
object[]
id
string
orderId
string

這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。

orderNumber
string
delta
number
reason
string
actorName
string

下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。

createdAt
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/lottery-filings/adjustments" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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": "…"
          }
        ]
      }
    ]
  }
}

Use the canonical tenant operation.

GET/api/v1/lottery-filings/count
lottery.read模組:lottery

參數

personId必填
string· min 1

Person ID

orderId必填
string· min 1

Order ID

回應欄位 · data

personId
string
chains
object[]

依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。

headOrderId
string

鏈首訂單(分組鍵)。

headOrderNumber
string
filingCount
number

送件紀錄筆數(這條鏈上)。

adjustmentTotal
number

調整差額加總(這條鏈上,可負)。

count
number

目前送件次數加上調整差額,下限為 0。

nextSeq
number

下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。

filings
object[]
id
string
orderId
string
orderNumber
string
travelerName
string | null

送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。

createdAt
string
adjustments
object[]
id
string
orderId
string

這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。

orderNumber
string
delta
number
reason
string
actorName
string

下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。

createdAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/lottery-filings/count?personId=example-personId&orderId=example-orderId" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
          }
        ]
      }
    ]
  }
}

Use the canonical tenant operation.

POST/api/v1/lottery-filings/lookup
lottery.read模組:lottery

參數

docType必填
enum
id_numberpassport

Document type

docNumber必填
string· min 1

Document number

請求
curl -X POST "https://your-tenant.example.com/api/v1/lottery-filings/lookup" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "docType": "id_number",
  "docNumber": "example-docNumber"
}'
回應
{
  "ok": true,
  "data": "…"
}

/lottery-notice-templates

GET/api/v1/lottery-notice-templates
trip.manage模組:climbing

回應欄位 · data[]

id
object
length
number

Returns the length of a String object.

name
string
contentMdx
string
createdAt
string
updatedAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/lottery-notice-templates" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": {
        "length": 0
      },
      "name": "…",
      "contentMdx": "…",
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}
POST/api/v1/lottery-notice-templates
trip.manage模組:climbing

參數

name必填
string· max 100 · min 1

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

contentMdx必填
string· max 50000 · min 1

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

回應欄位 · data

id
object
length
number

Returns the length of a String object.

請求
curl -X POST "https://your-tenant.example.com/api/v1/lottery-notice-templates" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "contentMdx": "example-contentMdx"
}'
回應
{
  "ok": true,
  "data": {
    "id": {
      "length": 0
    }
  }
}
GET/api/v1/lottery-notice-templates/{id}
trip.manage模組:climbing

參數

id路徑
string· min 1

抽籤須知範本 ID

回應欄位 · data

id
object
length
number

Returns the length of a String object.

name
string
contentMdx
string
createdAt
string
updatedAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/lottery-notice-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": {
      "length": 0
    },
    "name": "…",
    "contentMdx": "…",
    "createdAt": "…",
    "updatedAt": "…"
  }
}
PATCH/api/v1/lottery-notice-templates/{id}
trip.manage模組:climbing

參數

name必填
string· max 100 · min 1

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

contentMdx必填
string· max 50000 · min 1

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

id路徑
string· min 1

抽籤須知範本 ID

回應欄位 · data

ok
boolean
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/lottery-notice-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "contentMdx": "example-contentMdx"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}
DELETE/api/v1/lottery-notice-templates/{id}
trip.manage模組:climbing

參數

id路徑
string· min 1

抽籤須知範本 ID

回應欄位 · data

ok
boolean
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/lottery-notice-templates/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

/lottery-schedules

List lottery schedules with their sync status.

GET/api/v1/lottery-schedules
lottery.read模組:lottery

回應欄位 · data

schedules
object[]
id
string
name
string
source
"manual" | "yushan_official"
lastSyncAttemptedAt
string | null
lastSyncedAt
string | null
lastSyncError
string | null
entryCount
number
warning
LotteryScheduleWarning | null
請求
curl -X GET "https://your-tenant.example.com/api/v1/lottery-schedules" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "schedules": [
      {
        "id": "…",
        "name": "…",
        "source": "manual",
        "lastSyncAttemptedAt": "…",
        "lastSyncedAt": "…",
        "lastSyncError": "…",
        "entryCount": 0,
        "warning": null
      }
    ]
  }
}

Write a batch of draw dates.

POST/api/v1/lottery-schedules/{id}/entries/batch
lottery.manage模組:lottery

參數

id路徑
string· min 1

Lottery schedule ID

rows必填
array· max 1000 · min 1

Rows to write. A stay date that is already on the table is updated.

回應欄位 · data

changedStayDates
string[]
writtenCount
number
recomputedDepartureCount
number
請求
curl -X POST "https://your-tenant.example.com/api/v1/lottery-schedules/<id>/entries/batch" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "stayDate": "2026-10-13",
      "drawDate": "2026-10-13",
      "slotStart": "example-slotStart",
      "slotEnd": "example-slotEnd"
    }
  ]
}'
回應
{
  "ok": true,
  "data": {
    "changedStayDates": [
      "…"
    ],
    "writtenCount": 0,
    "recomputedDepartureCount": 0
  }
}

/message-template-stages

Use the canonical tenant operation.

GET/api/v1/message-template-stages
message_template.read

回應欄位 · data[]

id
string

階段 ID('mts_<ulid>')。

name
string

階段顯示名(FK 錨點;改名 ON UPDATE CASCADE 連動範本列)。

sortOrder
number
isActive
boolean

停用 = 不供新範本選用(既有綁此階段的範本不受影響)。

templateCount
number

綁此階段的範本數(>0 時不可刪,只可停用)。

請求
curl -X GET "https://your-tenant.example.com/api/v1/message-template-stages" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": [
    {
      "id": "…",
      "name": "…",
      "sortOrder": 0,
      "isActive": true,
      "templateCount": 0
    }
  ]
}
POST/api/v1/message-template-stages
message_template.manage

參數

name必填
string· max 100 · min 1

Stage name

sortOrder選填
integer

Display order

回應欄位 · data

ok
true
id
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/message-template-stages" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name"
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "id": "…"
  }
}

Use the canonical tenant operation.

PATCH/api/v1/message-template-stages/{id}
message_template.manage

參數

id路徑
string· min 1

Resource ID

name選填
string· max 100 · min 1

Stage name

sortOrder選填
integer

Display order

isActive選填
boolean

Stage enabled

回應欄位 · data

ok
true
請求
curl -X PATCH "https://your-tenant.example.com/api/v1/message-template-stages/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example-name",
  "sortOrder": 1,
  "isActive": true
}'
回應
{
  "ok": true,
  "data": {
    "ok": "…"
  }
}
DELETE/api/v1/message-template-stages/{id}
message_template.manage

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
true
removed
object
name
string
sortOrder
number
isActive
boolean
請求
curl -X DELETE "https://your-tenant.example.com/api/v1/message-template-stages/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": "…",
    "removed": {
      "name": "…",
      "sortOrder": 0,
      "isActive": true
    }
  }
}

/operating-expenses

Use the canonical tenant operation.

POST/api/v1/operating-expenses/{id}/confirm
operating_expense.manage模組:accounting

參數

id路徑
string· min 1

Resource ID

amountTwd選填
integer

Actual amount TWD; omit to retain draft amount

回應欄位 · data

ok
boolean
請求
curl -X POST "https://your-tenant.example.com/api/v1/operating-expenses/<id>/confirm" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amountTwd": 1
}'
回應
{
  "ok": true,
  "data": {
    "ok": true
  }
}

/order-conversations

待回覆的訂單對話

GET/api/v1/order-conversations/awaiting-reply
order_conversation.read

參數

olderThanHours必填
integer· max 720 · min 1

最後一則訂購人留言距今至少幾小時(含),整數 1–720,必填

page選填
integer

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

pageSize選填
integer· max 200

每頁筆數,上限 200

回應欄位 · data

rows
object[]
orderId
string
orderNumber
string
customerName
string
lastCustomerMessageAt
string
total
number
page
number
pageSize
number
請求
curl -X GET "https://your-tenant.example.com/api/v1/order-conversations/awaiting-reply?olderThanHours=1" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "rows": [
      {
        "orderId": "…",
        "orderNumber": "…",
        "customerName": "…",
        "lastCustomerMessageAt": "…"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0
  }
}

/permit-applications

GET/api/v1/permit-applications/{id}
departure_prep.read模組:climbing

參數

id路徑
string· min 1

申請單 ID(pmt_ 前綴)

回應欄位 · data

application
object

申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

files
object[]

證件檔清單。檔案本身只能從後台下載。

id
string

證件檔 ID(pmf_ 前綴)。

kind
"bed_permit" | "entry_permit" | "mountain_permit" | "other" | "site_snapshot"

檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。

contentType
string

檔案類型:application/pdf、image/png 或 image/jpeg。

sizeBytes
number

檔案大小(位元組)。

sha256
string

檔案的 sha256(hex)。

originalName
string | null

原始檔名。

uploadedAt
string

上傳時間。

uploadedByUserId
string | null

上傳者的使用者 ID。

source
"api" | "staff"

來源:staff(後台)或 api(送籤台)。

events
object[]

歷程,新的在前。身分證只有遮罩值。

id
string

歷程 ID(pme_ 前綴)。

kind
"cancel_reported" | "created" | "file_added" | "file_removed" | "leader_changed" | "pii_revealed" | "renumbered" | "status_changed" | "status_forced" | "status_ignored" | "superseded" | "updated"

歷程種類,例:created、status_changed、status_ignored、renumbered。

source
"api" | "staff"

來源:staff(後台)或 api(送籤台)。

actorUserId
string | null

寫入者的使用者 ID。

actorName
string | null

寫入者的姓名。

apiKeyId
string | null

送籤台寫入時的 API 金鑰 ID。

apiKeyName
string | null

寫入的 API 金鑰名稱;金鑰已刪為 null。

changes
object

改了什麼:{ 欄位: { from, to } }。身分證只有遮罩值。 領隊是嚮導或旅客時,歷程只存來源 id;讀取時補上來源目前的姓名與遮罩。 補的欄是 `name`、`idNumber`;建單歷程是 `leaderName`、`leaderIdNumber`。 去識別化的旅客顯示去識別化後的名字。

reason
string | null

原因(強制覆蓋、作廢)。

createdAt
string

寫入時間。

請求
curl -X GET "https://your-tenant.example.com/api/v1/permit-applications/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
      }
    ]
  }
}
PATCH/api/v1/permit-applications/{id}
departure_prep.manage模組:climbing

參數

office選填
enum
one_stoppoliceforestryother

申請處:one_stop(國家公園一站式)/ police(警政署入山)/ forestry(林務局山屋/營地)/ other(其他)。建單時必填

officeLabel選填
string· max 100

申請處名稱;office = other 時必填,例:一葉蘭許可

route選填
string· max 200

路線(站方表單上的路線名)

groupLabel選填
string· max 50

組別,例:A 組。分組送件時用來分辨同一梯的多張單

partySize選填
integer· max 99 · min 1

申請人數(1–99)

entryDate選填
string

入園日(YYYY-MM-DD)

exitDate選填
string

離園日(YYYY-MM-DD),不得早於入園日

teamName選填
string· max 100

隊名(站方表單上的隊伍名稱)

applicantName選填
string· max 100

申請人姓名

applicantIdNumber選填
string· max 30

申請人身分證明碼(加密存放);需要 permit_pii.read,沒有時回 403

applicantAccount選填
string· max 200

申請用的帳號或信箱

leaderKind選填
enum
same_as_applicantguidetravelerother

領隊來源:same_as_applicant(同申請人)/ guide(嚮導,帶 leaderGuideId)/ traveler(本團旅客,帶 leaderTravelerId)/ other(手填 leaderName 與 leaderIdNumber)

leaderGuideId選填
string

leaderKind = guide 時的嚮導 ID。伺服器端從嚮導資料取姓名與身分證快照

leaderTravelerId選填
string

leaderKind = traveler 時的旅客 ID(須在本梯)。伺服器端取姓名與身分證快照

leaderName選填
string· max 100

領隊姓名;只在 leaderKind = other 時使用

leaderIdNumber選填
string· max 30

領隊身分證明碼;只在 leaderKind = other 時使用。需要 permit_pii.read,沒有時回 403

applicationNo選填
string· max 20

申請編號(英數與連字號,6–20 字)。改號時直接給新號,舊號留在歷程

oneStopSerial選填
string· max 50

一站式序號

caseNo選填
string· max 50

項目案件編號

submittedAt選填
string

申請(送出)時間(ISO 8601,含時區)

status選填
enum
draftsubmitted_no_numbersubmittedin_reviewwaitlistedlost_to_waitlistwon_pending_paymentwon_needs_documentsapprovedlostrejecteddeniedwaitlist_failedcancelled

狀態。弱的狀態不蓋強的:較弱時不套用,回應 applied.status.reason = weaker_status。voided 只能由重送產生

statusNote選填
string· max 1000

狀態說明

checkedAt選填
string

最近一次查籤的時間(ISO 8601,含時區)

siteDetail選填
string· max 5000

站方明細原文(查詢頁的文字摘要)

waitlistRank選填
integer· min 1

備取順位

eligibility選填
enum
pendinggrantednot_granted

入園資格:pending(待定)/ granted(取得)/ not_granted(未取得)

eligibilityNote選填
string· max 1000

資格說明

bedNumbers選填
string· max 500

床位/營位編號,原文照存

paymentDueAt選填
string

繳費期限(ISO 8601,含時區;林務局中籤後繳費)

latestMailSummary選填
string· max 2000

最近來信摘要。不要放身分證

orderIds選填
array· max 50

對應的訂單 ID(整組取代,須在本梯)。空陣列 = 整梯的單

idempotencyKey選填
string· 格式限定

冪等鍵(8–64 字英數或連字號)。同一把 key 再送一次不重複寫入,回傳第一次的結果;內容不同回 409 idempotency_conflict

expectedVersion選填
integer· min 1

目前的 version。和伺服器上的不同時回 409 stale_version

id路徑
string· min 1

申請單 ID(pmt_ 前綴)

回應欄位 · data

application
object

更新後的申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

applied
object

每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。

created
boolean

PATCH 恆為 false。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

請求
curl -X PATCH "https://your-tenant.example.com/api/v1/permit-applications/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}

上傳一份證件檔

POST/api/v1/permit-applications/{id}/files
departure_prep.manage模組:climbing

參數

id路徑
string· min 1

申請單 ID(pmt_ 前綴)

kind必填
enum
entry_permitmountain_permitbed_permitsite_snapshotother

檔案種類:entry_permit(入園證)/ mountain_permit(入山證)/ bed_permit(床位證)/ site_snapshot(查詢頁快照)/ other

contentBase64必填
string· min 1

檔案內容的 base64 編碼字串(PDF / PNG / JPEG,上限 8MB)

originalName選填
string· max 200

原始檔名,只顯示用

回應欄位 · data

file
object

證件檔資訊。

id
string

證件檔 ID(pmf_ 前綴)。

kind
"bed_permit" | "entry_permit" | "mountain_permit" | "other" | "site_snapshot"

檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。

contentType
string

檔案類型:application/pdf、image/png 或 image/jpeg。

sizeBytes
number

檔案大小(位元組)。

sha256
string

檔案的 sha256(hex)。

originalName
string | null

原始檔名。

uploadedAt
string

上傳時間。

uploadedByUserId
string | null

上傳者的使用者 ID。

source
"api" | "staff"

來源:staff(後台)或 api(送籤台)。

created
boolean

false = 這張單已有同一個檔案,沒有再存一份。

請求
curl -X POST "https://your-tenant.example.com/api/v1/permit-applications/<id>/files" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}

顯示申請人或領隊的身分證全碼

POST/api/v1/permit-applications/{id}/reveal
permit_pii.read模組:climbing

參數

id路徑
string· min 1

申請單 ID(pmt_ 前綴)

field必填
enum
applicantIdNumberleaderIdNumber

要顯示的欄位:applicantIdNumber 申請人身分證、leaderIdNumber 領隊身分證

回應欄位 · data

field
"applicantIdNumber" | "leaderIdNumber"

本次顯示的欄位。

value
string | null

身分證全碼;null = 這一欄沒有值。每次呼叫都會寫入解密稽核紀錄。

請求
curl -X POST "https://your-tenant.example.com/api/v1/permit-applications/<id>/reveal" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "field": "applicantIdNumber"
}'
回應
{
  "ok": true,
  "data": {
    "field": "applicantIdNumber",
    "value": "…"
  }
}

用找單規則找一張申請單

GET/api/v1/permit-applications/lookup
departure_prep.read模組:climbing

參數

applicationId選填
string

申請單 ID;有帶時直接用它

applicationNo選填
string

申請編號,配 office。找不到有效單時,再從歷程的改號紀錄找舊號

office選填
enum
one_stoppoliceforestryother

申請處,配 applicationNo 或 departureId

departureId選填
string

梯次 ID,配 office 與 groupLabel。跳過草稿與已作廢的單

groupLabel選填
string

組別,配 departureId 與 office;不帶或 null = 沒有組別的單

entryDate選填
string

入園日(YYYY-MM-DD),配 departureId 時可再收斂

回應欄位 · data

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

請求
curl -X GET "https://your-tenant.example.com/api/v1/permit-applications/lookup" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
  }
}

送籤台寫回申請單的主要入口

POST/api/v1/permit-applications/sync
departure_prep.manage模組:climbing

參數

office選填
enum
one_stoppoliceforestryother

申請處:one_stop(國家公園一站式)/ police(警政署入山)/ forestry(林務局山屋/營地)/ other(其他)。建單時必填

officeLabel選填
string· max 100

申請處名稱;office = other 時必填,例:一葉蘭許可

route選填
string· max 200

路線(站方表單上的路線名)

groupLabel選填
string· max 50

組別,例:A 組。分組送件時用來分辨同一梯的多張單

partySize選填
integer· max 99 · min 1

申請人數(1–99)

entryDate選填
string

入園日(YYYY-MM-DD)

exitDate選填
string

離園日(YYYY-MM-DD),不得早於入園日

teamName選填
string· max 100

隊名(站方表單上的隊伍名稱)

applicantName選填
string· max 100

申請人姓名

applicantIdNumber選填
string· max 30

申請人身分證明碼(加密存放);需要 permit_pii.read,沒有時回 403

applicantAccount選填
string· max 200

申請用的帳號或信箱

leaderKind選填
enum
same_as_applicantguidetravelerother

領隊來源:same_as_applicant(同申請人)/ guide(嚮導,帶 leaderGuideId)/ traveler(本團旅客,帶 leaderTravelerId)/ other(手填 leaderName 與 leaderIdNumber)

leaderGuideId選填
string

leaderKind = guide 時的嚮導 ID。伺服器端從嚮導資料取姓名與身分證快照

leaderTravelerId選填
string

leaderKind = traveler 時的旅客 ID(須在本梯)。伺服器端取姓名與身分證快照

leaderName選填
string· max 100

領隊姓名;只在 leaderKind = other 時使用

leaderIdNumber選填
string· max 30

領隊身分證明碼;只在 leaderKind = other 時使用。需要 permit_pii.read,沒有時回 403

applicationNo選填
string· max 20

申請編號(英數與連字號,6–20 字)。改號時直接給新號,舊號留在歷程

oneStopSerial選填
string· max 50

一站式序號

caseNo選填
string· max 50

項目案件編號

submittedAt選填
string

申請(送出)時間(ISO 8601,含時區)

status選填
enum
draftsubmitted_no_numbersubmittedin_reviewwaitlistedlost_to_waitlistwon_pending_paymentwon_needs_documentsapprovedlostrejecteddeniedwaitlist_failedcancelled

狀態。弱的狀態不蓋強的:較弱時不套用,回應 applied.status.reason = weaker_status。voided 只能由重送產生

statusNote選填
string· max 1000

狀態說明

checkedAt選填
string

最近一次查籤的時間(ISO 8601,含時區)

siteDetail選填
string· max 5000

站方明細原文(查詢頁的文字摘要)

waitlistRank選填
integer· min 1

備取順位

eligibility選填
enum
pendinggrantednot_granted

入園資格:pending(待定)/ granted(取得)/ not_granted(未取得)

eligibilityNote選填
string· max 1000

資格說明

bedNumbers選填
string· max 500

床位/營位編號,原文照存

paymentDueAt選填
string

繳費期限(ISO 8601,含時區;林務局中籤後繳費)

latestMailSummary選填
string· max 2000

最近來信摘要。不要放身分證

orderIds選填
array· max 50

對應的訂單 ID(整組取代,須在本梯)。空陣列 = 整梯的單

idempotencyKey選填
string· 格式限定

冪等鍵(8–64 字英數或連字號)。同一把 key 再送一次不重複寫入,回傳第一次的結果;內容不同回 409 idempotency_conflict

match必填
object

找單條件(§6.3)

departureId選填
string

找不到單時要建在哪一梯;match 帶了 departureId 時可省略

replacesId選填
string

重送:被取代的舊單 ID

replacesApplicationNo選填
string

重送:被取代的舊單申請編號(同 match.office 或 office)

回應欄位 · data

application
object

更新或新建後的申請單(身分證遮罩)。

id
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

office
"forestry" | "one_stop" | "other" | "police"

申請處:one_stop / police / forestry / other。

officeLabel
string | null

申請處名稱(office = other 時有值)。

route
string | null

路線。

groupLabel
string | null

組別。

partySize
number | null

申請人數。

entryDate
string | null

入園日(YYYY-MM-DD)。

exitDate
string | null

離園日(YYYY-MM-DD)。

teamName
string | null

隊名。

applicantName
string | null

申請人姓名。

applicantIdNumberMask
string | null

申請人身分證遮罩(末 3 碼)。

applicantAccount
string | null

申請用的帳號或信箱。

leaderKind
"traveler" | "other" | "guide" | "same_as_applicant" | null

領隊來源:same_as_applicant / guide / traveler / other。

leaderGuideId
string | null

領隊是嚮導時的嚮導 ID。

leaderTravelerId
string | null

領隊是本團旅客時的旅客 ID。

leaderName
string | null

有效的領隊姓名。`same_as_applicant` 時是申請人姓名。

leaderIdNumberMask
string | null

有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。

leaderChangedAt
string | null

最近一次換領的時間。

applicationNo
string | null

申請編號(大寫)。

oneStopSerial
string | null

一站式序號。

caseNo
string | null

項目案件編號。

submittedAt
string | null

申請(送出)時間。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

狀態(見 specs/permit-applications.md §4.1)。

statusNote
string | null

狀態說明。

checkedAt
string | null

最近一次查籤的時間。

siteDetail
string | null

站方明細原文。

waitlistRank
number | null

備取順位。

eligibility
"granted" | "not_granted" | "pending"

入園資格:pending / granted / not_granted。

eligibilityNote
string | null

資格說明。

bedNumbers
string | null

床位/營位編號。

paymentDueAt
string | null

繳費期限。

latestMailSummary
string | null

最近來信摘要。

replacesId
string | null

重送時被這張單取代的舊單 ID。

replacedById
string | null

取代這張單的新單;沒有被取代為 null。

orderIds
string[]

對應的訂單 ID;空陣列 = 整梯的單。

fileCount
number

證件檔數。

version
number

版本,每次寫入加 1。PATCH 的 expectedVersion 用它。

createdAt
string

建立時間。

updatedAt
string

最後更新時間。

createdByUserId
string | null

建單的使用者 ID。

applied
object

每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。

created
boolean

這次是否建了新單。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

請求
curl -X POST "https://your-tenant.example.com/api/v1/permit-applications/sync" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}

/permit-cancel-requests

列出還沒完成的申請單取消請求

GET/api/v1/permit-cancel-requests
departure_prep.read模組:climbing

參數

status選填
enum
pendingclaimed

只列這個狀態:pending(待處理)或 claimed(已取走)。不帶時兩種都列

limit選填
integer· max 100 · min 1

最多列幾筆(1–100,預設 50)

回應欄位 · data

requests
object[]

還沒完成的請求,依截止時間排序。

id
string

取消請求 ID(pcr_ 前綴)。

applicationId
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

kind
"cancel_application" | "remove_travelers"

cancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。

trigger
"departure_changed" | "order_cancelled" | "traveler_removed"

觸發點:order_cancelled / departure_changed / traveler_removed。

orderId
string | null

觸發的訂單 ID。

orderNumber
string | null

觸發的訂單編號。

travelers
object[]

離開的旅客:只有 id、姓名與身分證遮罩。

id
string
name
string
idNumberMask
string | null
status
"claimed" | "done" | "pending"

pending(待處理)/ claimed(送籤台已取走)/ done(已完成)。

attempts
number

送籤台回報失敗的次數。

claimedAt
string | null

送籤台取走的時間。

resultNote
string | null

最近一次回報的說明。

dueAt
string

最晚要完成的時間:入園日前一天的台北時間 12:00。

createdAt
string

建立時間。

completedAt
string | null

完成時間。

application
object

申請單摘要,送籤台到站方找單用。

office
"forestry" | "one_stop" | "other" | "police"

申請處。

officeLabel
string | null

申請處名稱(office = other 時有值)。

applicationNo
string | null

申請編號。

groupLabel
string | null

組別。

entryDate
string | null

入園日(YYYY-MM-DD)。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

申請單目前的狀態。

請求
curl -X GET "https://your-tenant.example.com/api/v1/permit-cancel-requests" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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"
        }
      }
    ]
  }
}

送籤台回報一筆取消請求的結果

POST/api/v1/permit-cancel-requests/{id}/result
departure_prep.manage模組:climbing

參數

id路徑
string· min 1

取消請求 ID(pcr_ 前綴)

result必填
enum
donefailed

done(已在站方完成)或 failed(這次沒有完成)

note選填
string· max 1000

說明,例:站方回覆的取消編號,或失敗的原因

idempotencyKey選填
string· 格式限定

冪等鍵(8–64 字英數或連字號)。同一把 key 重送回傳目前的請求

回應欄位 · data

request
object

回報後的請求。

id
string

取消請求 ID(pcr_ 前綴)。

applicationId
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

kind
"cancel_application" | "remove_travelers"

cancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。

trigger
"departure_changed" | "order_cancelled" | "traveler_removed"

觸發點:order_cancelled / departure_changed / traveler_removed。

orderId
string | null

觸發的訂單 ID。

orderNumber
string | null

觸發的訂單編號。

travelers
object[]

離開的旅客:只有 id、姓名與身分證遮罩。

id
string
name
string
idNumberMask
string | null
status
"claimed" | "done" | "pending"

pending(待處理)/ claimed(送籤台已取走)/ done(已完成)。

attempts
number

送籤台回報失敗的次數。

claimedAt
string | null

送籤台取走的時間。

resultNote
string | null

最近一次回報的說明。

dueAt
string

最晚要完成的時間:入園日前一天的台北時間 12:00。

createdAt
string

建立時間。

completedAt
string | null

完成時間。

application
object

申請單摘要,送籤台到站方找單用。

office
"forestry" | "one_stop" | "other" | "police"

申請處。

officeLabel
string | null

申請處名稱(office = other 時有值)。

applicationNo
string | null

申請編號。

groupLabel
string | null

組別。

entryDate
string | null

入園日(YYYY-MM-DD)。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

申請單目前的狀態。

replayed
boolean

這次是同一個 idempotencyKey 的重送,沒有再寫入。

請求
curl -X POST "https://your-tenant.example.com/api/v1/permit-cancel-requests/<id>/result" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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
  }
}

送籤台取走待處理的申請單取消請求

POST/api/v1/permit-cancel-requests/claim
departure_prep.manage模組:climbing

參數

limit選填
integer· max 100 · min 1

一次最多取幾筆(1–100,預設 50)

回應欄位 · data

requests
object[]

這次取走的請求,已標成 claimed。

id
string

取消請求 ID(pcr_ 前綴)。

applicationId
string

申請單 ID(pmt_ 前綴)。

departureId
string

梯次 ID。

kind
"cancel_application" | "remove_travelers"

cancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。

trigger
"departure_changed" | "order_cancelled" | "traveler_removed"

觸發點:order_cancelled / departure_changed / traveler_removed。

orderId
string | null

觸發的訂單 ID。

orderNumber
string | null

觸發的訂單編號。

travelers
object[]

離開的旅客:只有 id、姓名與身分證遮罩。

id
string
name
string
idNumberMask
string | null
status
"claimed" | "done" | "pending"

pending(待處理)/ claimed(送籤台已取走)/ done(已完成)。

attempts
number

送籤台回報失敗的次數。

claimedAt
string | null

送籤台取走的時間。

resultNote
string | null

最近一次回報的說明。

dueAt
string

最晚要完成的時間:入園日前一天的台北時間 12:00。

createdAt
string

建立時間。

completedAt
string | null

完成時間。

application
object

申請單摘要,送籤台到站方找單用。

office
"forestry" | "one_stop" | "other" | "police"

申請處。

officeLabel
string | null

申請處名稱(office = other 時有值)。

applicationNo
string | null

申請編號。

groupLabel
string | null

組別。

entryDate
string | null

入園日(YYYY-MM-DD)。

status
"approved" | "cancelled" | "denied" | "draft" | "in_review" | "lost" | "lost_to_waitlist" | "rejected" | "submitted" | "submitted_no_number" | "voided" | "waitlist_failed" | "waitlisted" | "won_needs_documents" | "won_pending_payment"

申請單目前的狀態。

請求
curl -X POST "https://your-tenant.example.com/api/v1/permit-cancel-requests/claim" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 50
}'
回應
{
  "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"
        }
      }
    ]
  }
}

/supplier-payments

依付款日期區間查全部梯次的付款登記

GET/api/v1/supplier-payments
payment.read模組:tour

參數

from必填
string· min 1

付款日期起日(YYYY-MM-DD,含)

to必填
string· min 1

付款日期迄日(YYYY-MM-DD,含);區間最多 366 天

回應欄位 · data

from
string
to
string
payments
object[]
id
string
departureId
string
groupCode
string | null

團號;未產生為 null。

tripTitle
string
departureDate
string

出發日(YYYY-MM-DD)。

paidOn
string

付款日期(YYYY-MM-DD)。

handlerUserId
string
handlerName
string

經手人姓名。

receivingAccountId
string

付款渠道(收款帳戶 ID)。

channelName
string

付款帳戶名稱(例:小編機)。

payee
string

付給誰/項目。

note
string | null

說明;未填為 null。

amountTwd
number

金額(TWD 整數);退費為負數。

createdAt
string

登記時間(ISO 8601,UTC)。

updatedAt
string

最後修改時間(ISO 8601,UTC)。

totalTwd
number
請求
curl -X GET "https://your-tenant.example.com/api/v1/supplier-payments?from=example-from&to=example-to" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "from": "…",
    "to": "…",
    "payments": [
      {
        "id": "…",
        "departureId": "…",
        "groupCode": "…",
        "tripTitle": "…",
        "departureDate": "…",
        "paidOn": "…",
        "handlerUserId": "…",
        "handlerName": "…",
        "receivingAccountId": "…",
        "channelName": "…",
        "payee": "…",
        "note": "…",
        "amountTwd": 0,
        "createdAt": "…",
        "updatedAt": "…"
      }
    ],
    "totalTwd": 0
  }
}

/travelinvoice

GET/api/v1/travelinvoice
invoice.read

回應欄位 · data

rows
object[]
id
string
orderId
string
orderNumber
string | null
merchantOrderNo
string
provider
string
category
"B2B" | "B2C"
buyerName
string
buyerUbn
string | null
totalAmtTwd
number
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
declaredStatus
"declared" | "undeclared"
invoiceNumber
string | null
invoiceTransNo
string | null

平台開立流水號;pending 列有值代表平台已受理預約開立。

displayUrl
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
lastError
string | null
lastSyncedAt
string | null
createdAt
string
total
number
page
number
pageSize
number
請求
curl -X GET "https://your-tenant.example.com/api/v1/travelinvoice" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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
  }
}

Use the canonical tenant operation.

POST/api/v1/travelinvoice
invoice.issue

參數

orderId必填
string· min 1

Paid order ID; one active receipt per order

buyer必填
object

Buyer details

mode選填
enum
immediatehold

Issue mode

回應欄位 · data

id
string
merchantOrderNo
string
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
invoiceNumber
string | null
lastError
string | null

落缺件(pending + last_error)時填,供 UI 顯示缺件原因。

請求
curl -X POST "https://your-tenant.example.com/api/v1/travelinvoice" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "example-orderId",
  "buyer": {
    "category": "B2B",
    "name": "example-name",
    "email": "customer@example.com"
  }
}'
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "merchantOrderNo": "…",
    "status": "allowance",
    "invoiceNumber": "…",
    "lastError": "…"
  }
}

Use the canonical tenant operation.

GET/api/v1/travelinvoice/{id}
invoice.read

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

id
string
orderId
string
orderNumber
string | null
merchantOrderNo
string
provider
string
category
"B2B" | "B2C"
buyerName
string
buyerUbn
string | null
totalAmtTwd
number
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
declaredStatus
"declared" | "undeclared"
invoiceNumber
string | null
invoiceTransNo
string | null

平台開立流水號;pending 列有值代表平台已受理預約開立。

displayUrl
string | null
tourName
string | null
tourNo
string | null
tourDate
string | null
lastError
string | null
lastSyncedAt
string | null
createdAt
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/travelinvoice/<id>" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "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": "…"
  }
}

Use the canonical tenant operation.

POST/api/v1/travelinvoice/{id}/abandon
invoice.invalid

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
boolean
result
object
id
string
status
"cancelled"
請求
curl -X POST "https://your-tenant.example.com/api/v1/travelinvoice/<id>/abandon" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "id": "…",
      "status": "cancelled"
    }
  }
}

Use the canonical tenant operation.

POST/api/v1/travelinvoice/{id}/allowance
invoice.allowance

參數

id路徑
string· min 1

Resource ID

amountTwd必填
integer

Allowance TWD

reason必填
string· min 1

Allowance reason

回應欄位 · data

ok
boolean
result
object
allowanceId
string
allowanceNo
string | null
請求
curl -X POST "https://your-tenant.example.com/api/v1/travelinvoice/<id>/allowance" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amountTwd": 1,
  "reason": "example-reason"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "allowanceId": "…",
      "allowanceNo": "…"
    }
  }
}

Use the canonical tenant operation.

POST/api/v1/travelinvoice/{id}/cancel-scheduled
invoice.invalid

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
boolean
result
object
id
string
status
"cancelled"
請求
curl -X POST "https://your-tenant.example.com/api/v1/travelinvoice/<id>/cancel-scheduled" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "id": "…",
      "status": "cancelled"
    }
  }
}

Use the canonical tenant operation.

POST/api/v1/travelinvoice/{id}/invalidate
invoice.invalid

參數

id路徑
string· min 1

Resource ID

reason必填
string· max 10 · min 1

回應欄位 · data

ok
boolean
result
object
invalidationId
string
請求
curl -X POST "https://your-tenant.example.com/api/v1/travelinvoice/<id>/invalidate" \
  -H "Authorization: Bearer $TOKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "example-re"
}'
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "invalidationId": "…"
    }
  }
}

Use the canonical tenant operation.

POST/api/v1/travelinvoice/{id}/sync
invoice.issue

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
boolean
result
object
declaredStatus
TaxReceiptDeclaredStatus | null
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"

查回後的本地收據狀態(預約收據回補後可能轉 issued / cancelled)。

請求
curl -X POST "https://your-tenant.example.com/api/v1/travelinvoice/<id>/sync" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "declaredStatus": null,
      "status": "allowance"
    }
  }
}

Use the canonical tenant operation.

POST/api/v1/travelinvoice/{id}/touch-issue
invoice.issue

參數

id路徑
string· min 1

Resource ID

回應欄位 · data

ok
boolean
result
object
id
string
merchantOrderNo
string
status
"allowance" | "cancelled" | "invalid" | "issued" | "pending"
invoiceNumber
string | null
lastError
string | null

落缺件(pending + last_error)時填,供 UI 顯示缺件原因。

請求
curl -X POST "https://your-tenant.example.com/api/v1/travelinvoice/<id>/touch-issue" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "ok": true,
    "result": {
      "id": "…",
      "merchantOrderNo": "…",
      "status": "allowance",
      "invoiceNumber": "…",
      "lastError": "…"
    }
  }
}

/whoami

identity of the bearer-authenticated user

GET/api/v1/whoami
無權限閘

回應欄位 · data

id
string
email
string
name
string
role
string
請求
curl -X GET "https://your-tenant.example.com/api/v1/whoami" \
  -H "Authorization: Bearer $TOKO_TOKEN"
回應
{
  "ok": true,
  "data": {
    "id": "…",
    "email": "…",
    "name": "…",
    "role": "…"
  }
}

Command Palette

Search for a command to run...