API 參考 2026-11-03
進階套組/departures
設定梯次分配模式
/api/v1/departures/{depId}/allocation-mode參數
depId路徑梯次 ID
mode必填fcfslottery分配模式:fcfs(先到先得)或 lottery(抽籤)
回應欄位 · data
ok更新成功旗標,恆為 true。
departureId被更新的梯次 id。
mode更新後的佔位模式: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.
/api/v1/departures/{depId}/backup-candidates參數
depId路徑Departure ID
回應欄位 · data
mainidtripIddepartureDatereturnDatepriceTwd牌價 `departures.price_twd`(備案同價的基準)。
agencyPriceTwd同業通路有效單價(見 `effectiveAgencyUnitPrice`)。
capacitybookedCountallocationModelabel梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。
isPrivate不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。
candidatesidtripIddepartureDatereturnDatepriceTwd牌價 `departures.price_twd`(備案同價的基準)。
agencyPriceTwd同業通路有效單價(見 `effectiveAgencyUnitPrice`)。
capacitybookedCountallocationModelabel梯次標籤 / 副標(issue 509 ①):同日兩梯的候選下拉靠它分辨。
isPrivate不對外販售:候選下拉標「不對外」,承辦才知道正把客人放進包團梯。
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.
/api/v1/departures/{depId}/cancel-group-not-confirmed參數
depId路徑Departure ID
回應欄位 · data
cancelled本次真的翻成 cancelled 的訂單數。
alreadyCancelled已經是未成團取消狀態、本次不重複取消的訂單數(重跑時的正常值)。
emailed本次寄出(信進了佇列)的通知數。
emailSkippedAlreadySent已寄過通知、本次略過的訂單數。
emailSkippedNoTemplate取消成立但沒寄成,因為租戶沒有啟用中的「未成團通知」範本。**不留 claim** —— 設好範本後重按同一顆按鈕會補寄。
emailSkippedNoRecipient取消成立但沒寄成,因為訂購人沒有 email。**與缺範本分開數**:缺範本的後續動作是 去設範本再按一次,這種按幾次都沒用,要改走電話或其他管道。混成一個數字等於叫 承辦對這張單做一件永遠不會生效的事。
unprocessedDepartureIneligible因**梯次**中途失格(被標記成團 / 已結團)而未處理的訂單數 —— 含發現當下那張與 其後全部未跑到的單。>0 = 這批提早中止。刻意**不併進其他數字**:那些的後續動作是 去看那張單,這種是去看梯次。
crossDepartureSkipped**跨梯訂單**:同時掛在本梯與別梯的單,一律不碰(見批次說明)。清單而不是計數 —— 這些單要承辦逐張人工處理,沒有訂單號等於沒有回報。
orderIdorderNumberfailed**取消**沒成立的訂單數(其餘訂單不受影響)。**只數 `phase='cancel'`** —— 取消已經 commit、只是通知寄不出去的單不算,那張單真的取消了,把它報成失敗等於對線控謊稱 「這張還沒取消」,而他會去做一件已經做完的事。
failures失敗清單(辨識到訂單號)。`phase` 分「取消沒成立」與「取消成立但通知炸了」—— 後續動作完全不同。**不帶例外訊息**:DB 例外會帶表名 / 約束名 / 衝突鍵的值(可能 含 email),那些留 server log,不經 server action 回瀏覽器。
orderIdorderNumberphaseselectedNotEligible**只有選單版會有值**:選了、但不在本梯名單上的單(不掛在本梯、已出團、或已被其他 事由取消)—— 一張都沒動。清單而不是計數,理由同 `crossDepartureSkipped`。整梯版恆為空。
orderIdorderNumbercurl -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.
/api/v1/departures/{depId}/complete參數
depId路徑Departure ID
回應欄位 · data
okcurl -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.
/api/v1/departures/{depId}/confirmation參數
depId路徑Departure ID
confirmed必填Confirm or withdraw group confirmation
回應欄位 · data
okcurl -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
}
}登錄梯次成本
/api/v1/departures/{depId}/costs參數
depId路徑梯次 ID
category必填成本科目類別,決定歸入哪個分類帳
vendorName選填供應商/受款對象名稱
description選填成本說明備註
amountTwd必填成本金額(台幣,整數)
回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的梯次成本列 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": "…"
}
}/api/v1/departures/{depId}/costs/{costId}參數
costId路徑成本列 ID
category必填成本科目類別,決定歸入哪個分類帳
vendorName選填供應商/受款對象名稱
description選填成本說明備註
amountTwd必填成本金額(台幣,整數)
回應欄位 · data
ok更新成功旗標,恆為 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
}
}/api/v1/departures/{depId}/costs/{costId}參數
costId路徑成本列 ID
回應欄位 · data
ok刪除成功旗標,恆為 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.
/api/v1/departures/{depId}/delete參數
depId路徑Departure ID
回應欄位 · data
okcurl -X POST "https://your-tenant.example.com/api/v1/departures/<depId>/delete" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": true
}
}該梯次財務摘要
/api/v1/departures/{depId}/finance-summary參數
depId路徑梯次 ID
回應欄位 · data
header梯次表頭(團號/行程名/出發日等基本資訊)。
id梯次 id(dep_ 前綴)。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日(ISO 'YYYY-MM-DD')。
returnDate回程日(ISO 'YYYY-MM-DD')。
finance應收/已收金額彙整(TWD)。
receivableTwd梯次應收:tour 訂單的攤提份額(orders/allocation;排除已取消單)。 **含代收暫收款**(裝備押金等)—— 客人確實欠這筆錢,收款計畫與待收都照它走。 要「本團收入」請用 revenueTwd,不要拿這個當收入(issue #578)。
custodialTwd應收之中的代收暫收款份額(裝備押金等;要退還,不是收入)。
revenueTwd本團收入 = 應收 − 代收暫收款。毛利、損益、月報表一律用這個。
collectedTwd實收:tour 訂單 payment_transactions(direction='in') 的攤提份額。
cashReturnedTwd客戶現金退回(refund/chargeback/reversal)的攤提份額。
netCollectedTwd已收淨額 = 實收 − 退回。
outstandingTwd待收 = 應收 − (實收 − 退回),floor 0。
costTwd成本:departure_costs 真實額(房費另計,見成本登記簿)。
costBilledTwd已轉請款成本。
costUnbilledTwd未轉請款成本;不含即付(當下已付、不轉請款)。
anomalyOrderCount異常單數:overpaid / partially_refunded / refund pending 的 tour 訂單。
cost成本彙整(各類直接成本合計,TWD)。
totalTwd內帳真實成本合計(TWD 整數,各成本列金額加總)。
billedTwd已轉請款的成本合計(TWD 整數)。
paidOnSpotTwd即付的成本合計(TWD 整數):當下已付,不轉請款。
unbilledTwd尚未轉請款的成本合計(TWD 整數);不含即付列。
declarableTwd外帳可申報金額合計(TWD 整數,各列憑證金額加總)。
nonDeclarableTwd無憑證的不可申報成本合計(TWD 整數,逐列取 金額−憑證 的正值,不可跨列抵減)。
count成本列筆數。
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
}
}
}該梯次抽籤訂單清單
/api/v1/departures/{depId}/lottery-orders參數
depId路徑梯次 ID
回應欄位 · data[]
orderId訂單 id。
orderNumber訂單編號。
customerName訂購人姓名。
partySize佔位人數。
lotteryState抽籤狀態:applied 已應募/won 中籤/lost 未中籤。null = 落在受管制抽籤梯次但沒標 應募的單(後台 K 單、事後改成抽籤的梯次)——只因抽籤實名制占用而被列出(§3.7)。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。 只有 `lotteryState='applied'` 時可能為 true。
applicationKeyCurrent application (`lotteryApplicationKey`). A decision sends it back to reject an old page.
undoDecisionId選填Latest reversible decision. The write entry checks later work under the order lock.
backupChoiceCount客人自選的有序備案筆數(order_backup_choices;0 = 無備案)。
collectedTwd已收現金(payment_transactions direction='in');抽籤未中安置時的訂金結轉基準。
failoverFromOrderId落腳譜系:本單若是由某主單 force-place / cascade 落腳而成立的備案單,指向原主單 id。 null = 本單即主單(非備案落腳單)。供線控從備案列回溯主單。
awaitingPlacementtrue when lottery_state='lost' and still active (not cancelled). Means backup cascade exhausted — awaiting manual placement or explicit cancel.
identityHoldPending是否仍占用抽籤實名資格。為 true 時可顯示「解除實名占用」動作。
identityHoldReleased抽籤實名占用是否已由線控手動解除。
failover最近一次未中籤自動轉備案:`placed` 落腳、`reapplied` 重新應募、`stopped` 停止並待人工安置。 `blocker` 為停止原因,null=清單走完。`skipped` 列被跳過的順位與原因。null=未曾自動轉備案。
outcomeplaced = a general backup took the order; reapplied = a new application; stopped = awaits placement.
blockerWhy the failover stopped. null = every backup choice was tried. Only for `stopped`.
skippedBackup choices that the failover skipped, in rank order.
rankdepartureIdreasoncurl -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
}
]
}該梯次旅客名單
/api/v1/departures/{depId}/manifest參數
depId路徑梯次 ID
includeCancelled選填是否也列出已取消訂單的旅客(true/false);省略則不列
回應欄位 · data[]
travelerId旅客 id。外部系統用它對人,不靠姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
travelerName旅客姓名。
phone聯絡電話。
email聯絡 Email。
isPrimary是否為該訂單的主要聯絡人(訂購人)。
gender性別(明文 enum-like):'male'|'female'|'other'|null(未填)。
birthDate生日 ISO `YYYY-MM-DD`;null = 未填。
diet飲食需求(葷素)明文;null = 未填。
medicalNotes醫療 / 過敏 / 病史備註明文;null = 未填。
specialNeeds「飲食 · 特殊需求」欄的合併顯示字串(diet + medical_notes,以 ` · ` 併接)。 結構化欄落地後改吃 diet / medical_notes(不再湊 roommate_pref —— 分房需求回歸分房面板)。 兩者皆空 → null。
staffNote該訂單的承辦備註(issue 1659,`orders.staff_note`)。同一張單的每位旅客列帶同一份; null = 沒有備註。與 `specialNeeds` 分開,不併進飲食 / 過敏字串。
emergencyContactName緊急聯絡人姓名;null = 未填。
emergencyContactPhone緊急聯絡人電話;null = 未填。
consentPending該訂單是否仍缺最新版 PDPA 同意書(per-order,同訂單所有旅客共享此旗標)。 true = 未簽 / 只簽過舊版;與 dashboard KPI、催簽 badge 同一述詞。
orderStatusSingle display status (派生自三軸,與 deriveOrderDisplayStatus 同 precedence)。
amount每人分攤的應收(整單應收 ÷ 人數,四捨五入,TWD)。加總可能差幾元;對帳用 `orderReceivableTwd`。
orderReceivableTwd**整單**會計應收(TWD,不是每人分攤)。同一張單的每一列都帶同一個數字。 未取消=訂單應收。已取消=`cancellationFeeTwd`+`refundFeesTwd`:取消時訂單應收 歸零,公司留下的是這兩筆錢。退款執行完後,「應收 −(收款 − 退款)= 0」。 null=退改費尚未核算(見 `cancellationFeePending`)。
cancellationFeePendingtrue=已取消、退改費尚未核算、手上還有可退現金:整單應收還定不下來。
cancellationFeeTwd已取消單留下的退改費(整單)。未取消=null;尚未核算=null。
refundFeesTwd已取消單已執行退款的行政手續費+匯款手續費(整單)。未取消=null。
companionGroupId本梯次的同行組 id(departure-prep §2.11);null = 不屬任何組。
companionGroupCode同行組代號(A、B…);null = 不屬任何組。
companionGroupColor同行組顏色序號(0 起);null = 不屬任何組。
climbingExperience登山經歷(新到舊)。登山模組未啟用時恆為空陣列。
label行程 / 山岳名稱(自填為自由文字;order 來源 = 行程名稱快照)。
climbedOn約略完成日 `YYYY-MM-DD`;null = 未填。
source來源:order = 完團後系統沉澱;self = 會員自填或承辦代填。
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"
}
]
}
]
}成本轉請款:以選定的未轉成本列建立一張
/api/v1/departures/{depId}/payables參數
depId路徑梯次 ID
costIds必填要轉成請款單的成本列 ID 清單,至少一筆
payeeType必填supplierguidestaff_commissionother受款人類型:supplier(供應商)/ guide(領隊)/ staff_commission(員工佣金)/ other(其他)
payeeName必填受款人姓名/戶名(必填)
payeeBankAccount選填受款人銀行帳號
payeeBankName選填受款人銀行名稱
payeeTaxId選填受款人統一編號/稅籍編號
submitImmediately選填設為 true 時建立後立即送出核簽,否則僅存為草稿
回應欄位 · data
ok轉請款成功旗標,恆為 true。
payableId新建立的出款單(payable)id。
payableNumber出款單編號。
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
/api/v1/departures/{depId}/payments-export參數
depId路徑梯次 ID
回應欄位 · data
filenamecsvcurl -X GET "https://your-tenant.example.com/api/v1/departures/<depId>/payments-export" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"filename": "…",
"csv": "…"
}
}/api/v1/departures/{depId}/permit-applications參數
depId路徑梯次 ID
回應欄位 · data[]
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
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": "…"
}
]
}/api/v1/departures/{depId}/permit-applications參數
office選填one_stoppoliceforestryother申請處:one_stop(國家公園一站式)/ police(警政署入山)/ forestry(林務局山屋/營地)/ other(其他)。建單時必填
officeLabel選填申請處名稱;office = other 時必填,例:一葉蘭許可
route選填路線(站方表單上的路線名)
groupLabel選填組別,例:A 組。分組送件時用來分辨同一梯的多張單
partySize選填申請人數(1–99)
entryDate選填入園日(YYYY-MM-DD)
exitDate選填離園日(YYYY-MM-DD),不得早於入園日
teamName選填隊名(站方表單上的隊伍名稱)
applicantName選填申請人姓名
applicantIdNumber選填申請人身分證明碼(加密存放);需要 permit_pii.read,沒有時回 403
applicantAccount選填申請用的帳號或信箱
leaderKind選填same_as_applicantguidetravelerother領隊來源:same_as_applicant(同申請人)/ guide(嚮導,帶 leaderGuideId)/ traveler(本團旅客,帶 leaderTravelerId)/ other(手填 leaderName 與 leaderIdNumber)
leaderGuideId選填leaderKind = guide 時的嚮導 ID。伺服器端從嚮導資料取姓名與身分證快照
leaderTravelerId選填leaderKind = traveler 時的旅客 ID(須在本梯)。伺服器端取姓名與身分證快照
leaderName選填領隊姓名;只在 leaderKind = other 時使用
leaderIdNumber選填領隊身分證明碼;只在 leaderKind = other 時使用。需要 permit_pii.read,沒有時回 403
applicationNo選填申請編號(英數與連字號,6–20 字)。改號時直接給新號,舊號留在歷程
oneStopSerial選填一站式序號
caseNo選填項目案件編號
submittedAt選填申請(送出)時間(ISO 8601,含時區)
status選填draftsubmitted_no_numbersubmittedin_reviewwaitlistedlost_to_waitlistwon_pending_paymentwon_needs_documentsapprovedlostrejecteddeniedwaitlist_failedcancelled狀態。弱的狀態不蓋強的:較弱時不套用,回應 applied.status.reason = weaker_status。voided 只能由重送產生
statusNote選填狀態說明
checkedAt選填最近一次查籤的時間(ISO 8601,含時區)
siteDetail選填站方明細原文(查詢頁的文字摘要)
waitlistRank選填備取順位
eligibility選填pendinggrantednot_granted入園資格:pending(待定)/ granted(取得)/ not_granted(未取得)
eligibilityNote選填資格說明
bedNumbers選填床位/營位編號,原文照存
paymentDueAt選填繳費期限(ISO 8601,含時區;林務局中籤後繳費)
latestMailSummary選填最近來信摘要。不要放身分證
orderIds選填對應的訂單 ID(整組取代,須在本梯)。空陣列 = 整梯的單
idempotencyKey選填冪等鍵(8–64 字英數或連字號)。同一把 key 再送一次不重複寫入,回傳第一次的結果;內容不同回 409 idempotency_conflict
replacesId選填重送時被取代的舊單 ID。舊單會在同一個交易改成 voided(已作廢(重送))
depId路徑梯次 ID
回應欄位 · data
application建立後的申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
applied每個有帶的欄位是否套用。
created是否建了新單;冪等重送時沿用第一次的值。
replayed這次是同一個 idempotencyKey 的重送,沒有再寫入。
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
}
}出團準備整包讀取
/api/v1/departures/{depId}/prep參數
depId路徑梯次 ID
回應欄位 · data
departureId梯次 id。
guides隨團人員指派(leader 在前),含指派狀態。
id指派紀錄 id。
guideId被指派的嚮導 id。
guideName被指派的嚮導姓名。
role指派角色:leader 主要隨團人員/assistant 協同。
status指派狀態:tentative 預塞暫定/confirmed 正式確認。
guideStartDateguideEndDateeffectiveStartDateeffectiveEndDateisNameBoundpermitSwappedAt勾「已換領」的時間(ISO);null = 未勾(issue 1731)。
permitSwappedByName勾「已換領」的人的名稱;帳號已刪或未勾時為 null。
transport派車紀錄。
iddescriptiondriverNamevehicleInfofareNotestatuscatering餐食紀錄。
idsuppliermealPlanheadcountNotestatuspretripStay出發前夜住宿:宣告 + 全部登記(含已釋回列,看 releaseReason)。人數與性別彙總由 呼叫端從登記列算。訂房模組未啟用或行程沒指定據點時為 null。
declarationid實體列 id;**尚未實體化時為 null**(ADR 0022)。分頁的顯示條件是行程設定,不是這一列, 所以「有分頁但還沒有列」是正常狀態,第一筆登記或第一次發名單連結才會把它建出來。
departureIddepartureDatepropertyIdpropertyNameroomTypeIdroomTypeNametripRoomTypeId行程當下指定的床位池;null = 行程已改回旅客自理。**與 `roomTypeId` 不同時,這個出團 走的是實體化當下那一份**(ADR 0022 的 Consequence:畫面要說得出這件事)。
stayNight住宿夜 = 出發日前一晚(由 departure_date 現算,非讀 `check_in` 欄)。
rosterLinkExpiresAt只讓後台判斷是否已有有效連結;token 本體不進 server render。
rosterLinkActivedepartureConfirmed成團(`departures.confirmed_at` 有值)。旅客自助登記連結只在成團後可產生(issue 463)。
registrationsidtravelerIdfullName活動登記現讀 travelers;旅客退團刪除後顯示不含 PII 的佔位文字。
genderphoneorderNumberorderCancelled訂單是否已取消;T8 後對應登記應同時帶 releaseReason。
arrivalTimenightcleaningFeeCollectedAtcleaningFeeCollectedByNamereleaseReasonreleasedAtrentals本梯裝備租借單(含明細)。登山未對此梯生效時為空陣列。
orderOnDepartureWhether the order currently includes this rental departure.
deliveredAt選填depositClearedAt選填id租借單 id(equipmentRental_ 前綴)。
rentalCode人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。
orderId掛載的訂單 id。
orderNumber訂單編號;無對應訂單時為 null。
departureId綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。
departureLabel梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。
renterName租借人姓名(可空)。
rentStartDate租期起日(YYYY-MM-DD;可空)。
rentEndDate租期迄日(YYYY-MM-DD;可空)。
returnedAt歸還驗收時間(尚未歸還為 null)。
returnState歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。
inspectedAt驗收時間(尚未驗收為 null)。
damageCostTwd破損/遺失賠償金額(TWD;無為 null)。
reconState對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。
cancelledAt取消時間(未取消為 null)。
cancelReason取消原因(未取消為 null)。
notes備註(可空)。
createdAt建單時間。
updatedAt最後更新時間。
lines租借明細(借出的品項清單)。
id租借明細 id(equipmentRentalLine_ 前綴)。
equipmentItemId借出的裝備主檔品項 id。
itemName裝備品項目前的名稱。
quantity借出數量。
rentPriceTwdSnapshot成交單位總價快照(每日單價 × 計價日數;TWD)。
depositTwdSnapshot成交每件押金快照(TWD,不乘天數)。
returnedQuantity已歸還數量(尚未歸還為 null)。
rentTotalTwd成交租金合計(Σ rent snapshot × qty)。
depositTotalTwd成交押金合計(Σ deposit snapshot × qty)。
documents證件追蹤(只回既有列)。登山未對此梯生效時為空陣列。
iddocType證件種類 key(`departure_document_types.key`)。
applyStatusfileReadyuploadedToCloudfileUriappliedAtapprovedAtnotenotApplicableAt標「本團不需要」的時間;null = 沒標。
notApplicableByUserIdnotApplicableReason不需要的原因;有標記才有值。
checklist團層級出團待辦(出團前在前,含已勾或有狀態文字但事後停用的項目),每項帶狀態文字。
id勾稽列 id;null = 目錄有此項但本梯次還沒有勾稽列。
itemKeylabelphase目錄階段。UI 依此分「出團前」「出團後」兩區;完成分母只計 'pre'。
isActive目錄啟用狀態。false 只可能出現在「已勾但事後停用」的列(見 listChecklist)。
required這一梯要做:項目啟用中,而且行程沒設定或有勾選(issue 1369)。false 的列只因為本梯已勾、 寫過字或標過不適用才列出,不計入進度。
checkedAtcheckedByUserIdcheckedByName勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。
note狀態文字(issue 1245);null = 沒有字。與勾選彼此獨立。
noteUpdatedAt最後寫字的時間;沒有字時為 null。
noteUpdatedByUserId最後寫字的人;沒有字或帳號刪除後為 null。
noteUpdatedByName最後寫字的人的顯示名(同 `checkedByName`,帳號刪除後為 null)。
notApplicableAt標「本團不適用」的時間;null = 沒標(issue 1369)。
notApplicableByName標記者的顯示名;帳號刪除後為 null。
notApplicableReason不適用的原因;有標記才有值。
travelerChecks旅客層級出團待辦:欄(items)+ 已勾的格(checks)+ 有狀態文字的格(notes),都以 travelerId 對人。勾選與狀態文字彼此獨立,所以分兩份稀疏清單。
itemsitemKeylabelisActivefalse 只可能出現在「已勾或寫過字但事後停用」的項目。
checkstravelerIditemKeycheckedAtcheckedByUserIdcheckedByName勾選者顯示名(LEFT JOIN `user`;帳號刪除後 FK set null → 這裡也是 null)。
notestravelerIditemKeynotenoteUpdatedAtnoteUpdatedByUserIdnoteUpdatedByName最後寫字的人的顯示名(帳號刪除後為 null)。
insurance投保(旅責險 / 登山險兩軸,依 kind 分)。
idkindinsurerpolicyNostatusscheduledDate排定日 'YYYY-MM-DD'(可以開始辦的日,不是死線);null = 未排定。
insuredCount投保人數;null = 未填。
notecurl -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": "…"
}
]
}
}新增餐食紀錄
/api/v1/departures/{depId}/prep/catering參數
depId路徑梯次 ID
supplier選填餐食供應商名稱
mealPlan選填餐食安排說明(如餐數、菜色)
headcountNote選填人數備註(如素食、特殊餐需求)
status選填餐食安排狀態,預設 pending
回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的餐食紀錄 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": "…"
}
}更新餐食紀錄
/api/v1/departures/{depId}/prep/catering/{id}參數
depId路徑梯次 ID
id路徑餐食紀錄 ID
supplier選填餐食供應商名稱;省略不動,給 null 清空
mealPlan選填餐食安排說明(如餐數、菜色);省略不動,給 null 清空
headcountNote選填人數備註(如素食、特殊餐需求);省略不動,給 null 清空
status選填餐食安排狀態(pending / arranged);省略不動
回應欄位 · data
ok更新成功旗標,恆為 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
}
}刪除餐食紀錄
/api/v1/departures/{depId}/prep/catering/{id}參數
depId路徑梯次 ID
id路徑餐食紀錄 ID
回應欄位 · data
ok刪除成功旗標,恆為 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
}
}設定出團待辦某項勾選狀態
/api/v1/departures/{depId}/prep/checklist參數
depId路徑梯次 ID
itemKey必填出團待辦項目的代碼
checked必填該檢查項目是否已完成勾選
回應欄位 · data
ok設定成功旗標,恆為 true。
id出團待辦勾稽紀錄 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": "…"
}
}設定梯次期限警戒
/api/v1/departures/{depId}/prep/deadlines參數
depId路徑梯次 ID
deadlines必填softDates選填期限種類 key → 軟日期(建議開始,ISO 日期);空字串清空;未列的 key 保留既有軟日期
回應欄位 · data
ok設定成功旗標,恆為 true。
departureId被設定期限的梯次 id。
deadlines本次套用的硬 deadline 異動(key → 日期;null = 已清除)。寫入的列來源為 manual。
softDates本次套用的軟日期異動(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.
/api/v1/departures/{depId}/prep/deadlines/done參數
depId路徑Departure ID
typeKey必填Deadline type key
done必填Target status
回應欄位 · data
changedcurl -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.
/api/v1/departures/{depId}/prep/deadlines/not-applicable參數
depId路徑Departure ID
typeKey必填Deadline type key
notApplicable必填Target status
reason選填Required when marking not applicable
回應欄位 · data
changedreasoncurl -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": "…"
}
}依關鍵日期回推規則重算梯次期限
/api/v1/departures/{depId}/prep/deadlines/recompute參數
depId路徑梯次 ID
keys選填只重算這些期限種類 key(至少一個);省略 = 全部啟用中的事項
includeManual選填true = 把指定事項的人工覆寫改回公式值(還原);必須搭配 keys,不得整梯次一次還原。預設 false 只覆寫公式列
回應欄位 · data
departureId被重算的梯次 id。
rows各事項的公式結果;written=false 表示該列是人工覆寫、本次未動。
keylabelsoftDatedeadlineDatewrittenfalse = 該列是人工覆寫、本次未動(includeManual=false)。
missingHolidayYearsskipped規則無法套用而略過的事項(key / label / 原因)。
keylabelmessagemissingHolidayYears假日表未維護、但工作天回推觸及的年度;非空即「假日資料不完整」。
removed被清掉的事項 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 一種證件追蹤狀態
/api/v1/departures/{depId}/prep/documents參數
depId路徑梯次 ID
docType必填證件/文件種類代碼(如入山申請、保險名冊)
applyStatus選填todoapplyingapproved申辦狀態:todo(待辦)/ applying(申請中)/ approved(已核准)
fileReady選填文件檔案是否已備妥
uploadedToCloud選填文件是否已上傳雲端
fileUri選填文件檔案連結;給 null 清空
note選填備註;給 null 清空
回應欄位 · data
okupsert 成功旗標,恆為 true。
id證件追蹤紀錄 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 某裝備品項的需求數
/api/v1/departures/{depId}/prep/equipment-needs參數
depId路徑梯次 ID
equipmentItemId必填裝備品項 ID
quantity必填該品項的需求數量
note選填需求備註;給 null 清空
回應欄位 · data
okupsert 成功旗標,恆為 true。
id裝備需求紀錄 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": "…"
}
}刪除裝備需求列
/api/v1/departures/{depId}/prep/equipment-needs/{id}參數
depId路徑梯次 ID
id路徑裝備需求列 ID
回應欄位 · data
ok刪除成功旗標,恆為 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
}
}指派 / 重派嚮導到梯次
/api/v1/departures/{depId}/prep/guides參數
guideStartDate選填帶團開始日期;與結束日期成對,null 回復行程預設
guideEndDate選填帶團結束日期;與開始日期成對
isNameBound選填是否為綁名指派
nameBoundChangeReason選填解除綁名或變更綁名角色的原因
depId路徑梯次 ID
guideId必填嚮導 ID
role必填leaderassistant指派角色:leader(主要隨團人員)或 assistant(協同)
status選填tentativeconfirmed指派狀態:tentative(暫定)或 confirmed(已確認)
回應欄位 · data
ok指派成功旗標,恆為 true。
id指派紀錄 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": "…"
}
}新增投保紀錄
/api/v1/departures/{depId}/prep/insurance參數
depId路徑梯次 ID
kind必填保險種類:liability(旅責險)/ climbing(登山險)
insurer選填保險公司名稱
policyNo選填保單號碼
status選填投保狀態,預設 pending
scheduledDate選填排定日 YYYY-MM-DD(旅責:排定辦理日;登山:排定送出日)。可以開始辦的日,不是死線;省略 = 未填
insuredCount選填投保人數;省略 = 未填
note選填備註;給 null 清空
回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的投保紀錄 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": "…"
}
}更新投保紀錄
/api/v1/departures/{depId}/prep/insurance/{id}參數
depId路徑梯次 ID
id路徑投保紀錄 ID
insurer選填保險公司名稱;省略不動,給 null 清空
policyNo選填保單號碼;省略不動,給 null 清空
status選填投保狀態(pending / done);省略不動
scheduledDate選填排定日 YYYY-MM-DD(旅責:排定辦理日;登山:排定送出日)。可以開始辦的日,不是死線;省略不動,給 null 清空
insuredCount選填投保人數;省略不動,給 null 清空
note選填備註;省略不動,給 null 清空
回應欄位 · data
ok更新成功旗標,恆為 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
}
}刪除投保紀錄
/api/v1/departures/{depId}/prep/insurance/{id}參數
depId路徑梯次 ID
id路徑投保紀錄 ID
回應欄位 · data
ok刪除成功旗標,恆為 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
}
}/api/v1/departures/{depId}/prep/ops參數
depId路徑Departure ID
回應欄位 · data
assignmentsiduserIduserNamecandidatesidnamecurl -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": "…"
}
]
}
}/api/v1/departures/{depId}/prep/ops參數
depId路徑Departure ID
userId必填Staff user ID
回應欄位 · data
okidcreatedtrue = 這次真的新增;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.
/api/v1/departures/{depId}/prep/ops-defaults/apply參數
depId路徑Departure ID
回應欄位 · data
transportcateringinsurancecurl -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.
/api/v1/departures/{depId}/prep/pretrip-stays參數
depId路徑Departure ID
travelerId必填Traveler ID
arrivalTime選填Arrival time HH:MM
回應欄位 · data
okregistrationIdcurl -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.
/api/v1/departures/{depId}/prep/pretrip-stays/{registrationId}/arrival參數
depId路徑Departure ID
registrationId路徑Pretrip stay registration ID
arrivalTime選填Arrival time HH:MM
回應欄位 · data
okcurl -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.
/api/v1/departures/{depId}/prep/pretrip-stays/{registrationId}/cancel參數
depId路徑Departure ID
registrationId路徑Pretrip stay registration ID
回應欄位 · data
okcurl -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.
/api/v1/departures/{depId}/prep/pretrip-stays/{registrationId}/cleaning-fee參數
depId路徑Departure ID
registrationId路徑Pretrip stay registration ID
collected必填Cleaning fee collected
回應欄位 · data
okcurl -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.
/api/v1/departures/{depId}/prep/pretrip-stays/roster-link參數
depId路徑Departure ID
回應欄位 · data
tokenexpiresAturlcurl -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.
/api/v1/departures/{depId}/prep/pretrip-stays/self-links參數
depId路徑Departure ID
orderId選填Limit to one order
mode必填ensurerotateKeep or rotate the link
回應欄位 · data
linksorderIdorderNumberurlexpiresAtrotatedcurl -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
}
]
}
}從裝備需求開租借單
/api/v1/departures/{depId}/prep/rentals參數
depId路徑梯次 ID
orderId必填要掛這筆租借費用的訂單 ID
renterName選填租借人姓名;給 null 清空
rentStartDate選填Rental start date
rentEndDate選填Rental end date
lines必填租借品項明細(品項 + 數量),數量需大於 0 才計入
回應欄位 · data
ok開單成功旗標,恆為 true。
rentalId新開立的裝備租借單 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": "…"
}
}新增派車紀錄
/api/v1/departures/{depId}/prep/transport參數
depId路徑梯次 ID
description選填派車說明(如路線、接送地點)
driverName選填司機姓名
vehicleInfo選填車輛資訊(如車型、車牌)
fareNote選填車資備註
status選填派車狀態,預設 pending
回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的派車紀錄 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": "…"
}
}更新派車紀錄
/api/v1/departures/{depId}/prep/transport/{id}參數
depId路徑梯次 ID
id路徑派車紀錄 ID
description選填派車說明(如路線、接送地點);省略不動,給 null 清空
driverName選填司機姓名;省略不動,給 null 清空
vehicleInfo選填車輛資訊(如車型、車牌);省略不動,給 null 清空
fareNote選填車資備註;省略不動,給 null 清空
status選填派車狀態(pending / arranged);省略不動
回應欄位 · data
ok更新成功旗標,恆為 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
}
}刪除派車紀錄
/api/v1/departures/{depId}/prep/transport/{id}參數
depId路徑梯次 ID
id路徑派車紀錄 ID
回應欄位 · data
ok刪除成功旗標,恆為 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
}
}分房表匯出資料列
/api/v1/departures/{depId}/rooming-export參數
depId路徑梯次 ID
回應欄位 · data[]
travelerId旅客 id。外部系統用它對人,不靠姓名。
fullName旅客姓名。
gender性別(中文標籤:男/女/其他)。
roomLabel房號/房間標籤(未排房為「未分房」)。
bedInfo床位資訊(房型中文標籤 + 床位)。
roommates同房其他旅客姓名(依房號分組派生)。
specialRequest特殊需求(房友偏好等自由文字)。
contactSummary聯絡摘要(電話已遮罩,只露末 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": "…"
}
]
}該梯次分房檢視
/api/v1/departures/{depId}/rooms參數
depId路徑梯次 ID
回應欄位 · data
departure梯次表頭(id/起訖日/行程名/容量等)。
id梯次 id(dep_ 前綴)。
departureDate出發日(ISO 'YYYY-MM-DD')。
returnDate回程日(ISO 'YYYY-MM-DD')。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
capacity名額上限(人數)。
bookedCount已成團佔用名額(人數)。
rooms此梯次的所有房間(含入住旅客)。
id房間 id。
roomLabel房號/房間標籤。
roomType房型(如 single 單人/double 雙人/dorm 通舖)。
bedCount床位數。
bedConfig床位配置說明(可空)。
accommodationName住宿名稱(梯次配套派生房才有;可空)。
accommodationDate住宿日期(YYYY-MM-DD;可空)。
baseCostTwd房間底價成本(TWD)。
upgradeFeeTwd房型升等補款(TWD)。
notes備註(可空)。
departureLodgingIdnull = 手動建立的房;non-null = 梯次配套自動派生房的來源 ID。
assignedTravelers已入住此房的旅客。
id旅客 id。
fullName旅客姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
isPrimary是否為該訂單的主要聯絡人(訂購人)。
gender性別(分房 gender 衝突偵測用):'male'|'female'|'other'|null。
roomPreference下單登記的房型偏好(chip 上顯示配房意向 badge)。
roommatePref指定房友 id / 特殊需求自由文字。
companionGroup本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。
groupIdcode代號(A、B…,第 27 組起 AA)。
colorIndex顏色序號(0 起,循環)。UI 用它挑色票。
unassignedTravelers尚未分房的旅客清單。
assignedElsewhere選填True when the traveler has a room in another departure.
id旅客 id。
fullName旅客姓名。
orderId所屬訂單 id。
orderNumber所屬訂單編號。
isPrimary是否為該訂單的主要聯絡人(訂購人)。
gender性別:'male'|'female'|'other'|null。
birthDate選填出生日期(YYYY-MM-DD;可空)。
roomPreference下單登記的房型偏好(auto-pair 起點提示)。
roommatePref指定房友 id / 特殊需求自由文字。
companionGroup本梯次的同行組(departure-prep §2.11);null = 不屬任何組。分房頁唯讀顯示,auto-pair 用它湊房。
groupIdcode代號(A、B…,第 27 組起 AA)。
colorIndex顏色序號(0 起,循環)。UI 用它挑色票。
stats分房統計彙總(總人數/已分房數/房間數/升等補款合計)。
totalTravelers此梯次旅客總人數。
assignedCount已分配房間的旅客數。
roomCount房間數。
totalUpgradeFee升等補款合計(TWD 整數)。
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
}
}
}建立一間梯次房間
/api/v1/departures/{depId}/rooms參數
depId路徑梯次 ID
roomLabel必填房間代號/標籤(如 101、A 房)
roomType必填房型(如 雙人房、四人房)
bedCount必填床位數,必須大於 0
bedConfig選填床型配置說明(如 2 大床、1 大 2 小)
accommodationName選填住宿地點/旅宿名稱
accommodationDate選填入住日期,須為 YYYY-MM-DD 且為真實存在的曆日;形狀不合回 409 conflict
baseCostTwd選填房間基本成本(台幣),預設 0
upgradeFeeTwd選填房型升等補款金額(台幣),預設 0
notes選填房間備註
回應欄位 · data
ok建立成功旗標,恆為 true。
id新建立的房間 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": "…"
}
}編輯房間
/api/v1/departures/{depId}/rooms/{roomId}參數
roomId路徑房間 ID
roomLabel選填房間代號/標籤;未給則不變
roomType選填房型;未給則不變
bedCount選填床位數;未給則不變
bedConfig選填床型配置說明;給 null 清空、未給則不變
accommodationName選填住宿地點名稱;給 null 清空、未給則不變
accommodationDate選填入住日期,須為 YYYY-MM-DD 且為真實存在的曆日(形狀不合回 409 conflict);給 null 清空、未給則不變
baseCostTwd選填房間基本成本(台幣);未給則不變
upgradeFeeTwd選填房型升等補款金額(台幣);未給則不變
notes選填房間備註;給 null 清空、未給則不變
回應欄位 · data
ok更新成功旗標,恆為 true。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
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
}
}刪除房間
/api/v1/departures/{depId}/rooms/{roomId}參數
roomId路徑房間 ID
回應欄位 · data
ok刪除成功旗標,恆為 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 建議分組:
/api/v1/departures/{depId}/rooms/auto-pair-apply參數
depId路徑梯次 ID
travelerIds必填要編入同一房的旅客 ID 清單,至少一人
roomType選填建立房間的房型,預設 shared(合住)
回應欄位 · data
ok套用成功旗標,恆為 true。
roomId建議分組寫入後所在的房間 id。
travelerIds被排入該房的旅客 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": [
"…"
]
}
}對某梯次「尚未排房」的旅客
/api/v1/departures/{depId}/rooms/auto-pair-preview參數
depId路徑梯次 ID
回應欄位 · data
suggestionauto-pair 引擎產出的分房建議(未寫入,供線控確認)。
groups建議的分房組合(每組一間房,含旅客與需確認註記)。
kindtravelerIdsneedsConfirmation選填需線控人工確認(跨性別指定房友 / gender='other')。
note選填給線控看的提示(特殊需求原文、超過床數、單人房卻又指名房友…)。
unmatched無法安全自動配對、待人工處理的旅客。
travelerIdreasonnamestravelerId → 顯示名(建議分組渲染用)。
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.
/api/v1/departures/{depId}/send-balance-slips參數
depId路徑Departure ID
回應欄位 · data
sent真的寄出(信進了佇列)的訂單數。
excludedAgencyOrders同業單不寄信、不建連結,請經同業收款。
skipped逐單略過數 = `skippedAlreadySent` + `skippedNoTemplate` + `skippedNoRecipient` + `skippedNotEligible`。 **不含**因梯次失格而中止未跑到的單(那些在 `unsentDepartureIneligible`)。
skippedAlreadySent略過細分:已寄過(claim 命中)。重跑仍會略過,正常。
skippedNoTemplate略過細分:連結已建但租戶沒有啟用中的「收尾款」範本而沒寄成。這種略過**不留 claim** —— 補設範本後重跑同一批次會補寄。
skippedNoRecipient略過細分:連結已建但沒有收件人而沒寄成。訂購人沒有 email。補設範本不會補寄,承辦要另行聯繫。
skippedNotEligible略過細分:撈出來之後才發現不符資格(尾款已結清 / 期間被取消)。
unsentDepartureIneligible因**梯次**中途失格(被取消 / 被退回成團)而未寄的訂單數 —— 含發現當下那張與其後 全部未跑到的單。>0 = 這批提早中止。刻意**不併進 `skipped`**:那三種略過的後續動作 是去看那張單,這種是去看梯次。
failed例外中斷的訂單數(其餘訂單不受影響)。
failures失敗清單(辨識到訂單號)。`reason` 只給分類字串 —— DB 例外訊息會帶表名 / 約束名 / 衝突鍵的值(可能含 email),那些留 server log,不經 server action 回瀏覽器。
orderIdorderNumberreasonnoCandidates本梯沒有任何符合條件的單時,各張單為什麼不符(#1456);有符合的單時 null。 結果全是 0 時,承辦要看得出是「沒有符合的單」,不是「按了沒反應」。
total本梯的訂單數(含已取消)。
cancelledwaitlisted候補中(還沒有席位)。
lotteryNotWon抽籤梯次未中籤。
unpaidpartiallyPaid已付款但未付足訂金。
paid已付清(含溢收)。
othercurl -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.
/api/v1/departures/{depId}/send-consent-reminders參數
depId路徑Departure ID
回應欄位 · data
sentskippedNoPending沒有待簽的自訂同意書(已簽齊或不適用)。
skippedNoRecipient訂購人帳號沒有 email,系統寄不出去。
failedfailuresorderNumbercurl -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.
/api/v1/departures/{depId}/submission-export參數
depId路徑Departure ID
assignments必填Order group assignments; null skips an order
acknowledgedIssueCount必填Acknowledged traveler issue count from preview
回應欄位 · data
kindvexportedAt匯出時間(ISO 8601,UTC)。承辦貼上後用來核對不是上一梯的資料。
tripcodenamedeparturegroupCode團號;還沒產生時為 null。
entryDate入園日 = 出發日 + 入園日偏移。
startDate出發日 YYYY-MM-DD。
endDate回程日 YYYY-MM-DD。
groupsnotravelersnamegenderbirthDateidNumberphoneemailaddressemergencyNameemergencyPhonevalidationorderNumberpassportNonationalitynationalityNamepassportFile護照影本的下載網址(passport-ocr §0.5)。沒有影本時為 null。網址 30 分鐘到期, 兌換時另要登入身分與 `departure.submission_export`。
urlcontentTypeexpiresAt網址到期時間(ISO 8601,UTC)。
staff加帶的隨團人員,不屬於任何一組(issue 1416)。沒勾任何人為空陣列。
kindguideIdroleleader 主要/assistant 協同。
statustentative 預塞/confirmed 正式。
englishName英文姓名(與護照一致);未填為空字串。
namephoneemailaddressgenderbirthDateidNumberemergencyNameemergencyPhonevalidationpassportNonationalitynationalityNamecounts送件人數:客人(各組合計)+隨團。
travelersstafftotalsourcetoolcurl -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.
/api/v1/departures/{depId}/submission-preview參數
depId路徑Departure ID
回應欄位 · data
departuredepartureIdgroupCode團號;還沒產生時為 null。
tripCode行程的中性代碼(slug)。
tripTitlestartDate出發日 YYYY-MM-DD。
endDate回程日 YYYY-MM-DD。
entryDate入園日 = 出發日 + 入園日偏移。
entryDateOffsetDaysordersorderIdorderNumberleadName主要聯絡人(訂單第一位旅客)姓名,讓承辦認得是哪一張單。
travelerCounttravelers這張單的全部旅客,順序同匯出。`companionGroup` 是旅客在本梯次的同行組(§2.11), 給承辦當「誰跟誰一夥」的提示,跨訂單也對得上(issue 1171)。
namecompanionGroupgroupIdcode代號(A、B…,第 27 組起 AA)。
colorIndex顏色序號(0 起,循環)。UI 用它挑色票。
lastGroup上一次匯出時這張單的組別(已重編)。`null` = 沒有可沿用的紀錄:沒匯出過、這張單 當時不在梯次上、或人數變了。
groupissues有驗證問題的旅客;沒有問題的旅客不列。
travelerNamemessagesstaff這一梯的全部已派隨團人員,`included` = 已勾加帶進送籤名單(issue 1416)。
assignmentId指派紀錄 id。
guideIdnickname暱稱(後台顯示名)。
legalName正式姓名;未填為 null(送籤檢查會列「姓名未填」)。
roleleader 主要/assistant 協同。
statustentative 預塞/confirmed 正式。
included已勾「加帶進送籤名單」。
issues送籤檢查問題(資料待補);沒有問題為空陣列。
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.
/api/v1/departures/{depId}/submission-staff參數
depId路徑Departure ID
guideIds必填Assigned guide IDs to include in the submission list; omitted guides are removed
回應欄位 · data
guideIdscurl -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": [
"…"
]
}
}梯次的付款登記
/api/v1/departures/{depId}/supplier-payments參數
depId路徑梯次 ID
回應欄位 · data
departureIdpaymentsiddepartureIdgroupCode團號;未產生為 null。
tripTitledepartureDate出發日(YYYY-MM-DD)。
paidOn付款日期(YYYY-MM-DD)。
handlerUserIdhandlerName經手人姓名。
receivingAccountId付款渠道(收款帳戶 ID)。
channelName付款帳戶名稱(例:小編機)。
payee付給誰/項目。
note說明;未填為 null。
amountTwd金額(TWD 整數);退費為負數。
createdAt登記時間(ISO 8601,UTC)。
updatedAt最後修改時間(ISO 8601,UTC)。
totalTwdcurl -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
}
}該梯次的有效報名調查項
/api/v1/departures/{depId}/survey參數
depId路徑梯次 ID
回應欄位 · data[]
idkindlabeldescriptionrequiredoptionsidlabeldisabled本梯次停用(新答案不可選;既有答案保留並標示)。
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.
/api/v1/departures/{depId}/survey-options/{optionId}參數
depId路徑Departure ID
optionId路徑Survey option ID
disabled必填Disable option for this departure
回應欄位 · data
okcurl -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": "…"
}
}該梯次套用的成本範本列
/api/v1/departures/{depId}/template-costs參數
depId路徑梯次 ID
回應欄位 · data[]
id梯次成本列 ID。
category成本分類(如 交通 / 餐費 / 保險)。
vendorName供應商 / 廠商名(可空)。
description摘要說明(可空)。
amountTwd內帳成本金額(TWD;數量 × 單價派生)。
invoiceAmountTwd報帳/發票金額(TWD;is_declarable=true 時同步 amount,否則 0)。
isDeclarable是否有合法憑證可報帳(開發票)。
quantityMode數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。
headcountComponentsheadcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。
groupDivisorheadcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。
quantity實際套用的數量(依 quantityMode 派生)。
unitPriceTwd內帳單價(TWD;外幣列可為 null)。
currency幣別('TWD' = 台幣列)。
unitPriceForeign外幣單價;TWD 列 null。
foreignAmount外幣金額快照 = unit_price_foreign × quantity;TWD 列 null。
internalRate內帳匯率快照(numeric 字串);TWD 列 null。
externalRate外帳匯率快照(numeric 字串);TWD 列 null。
isManualOverride是否為線控手動改寫(true 時重算會跳過此列,不覆蓋手改值)。
payableId已轉請款 → 鎖定(不可手改 / 重算)。
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": "…"
}
]
}重設為範本算法
/api/v1/departures/{depId}/template-costs/{id}/clear-override參數
id路徑範本成本列 ID
回應欄位 · data
ok清除手改鎖並重算成功旗標,恆為 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
}
}線控手改某範本成本列
/api/v1/departures/{depId}/template-costs/{id}/override參數
id路徑範本成本列 ID
amountTwd必填手動指定的成本金額(台幣),設定後停止自動重算
回應欄位 · data
ok手改金額成功旗標,恆為 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
}
}套用行程綁定範本到本梯次
/api/v1/departures/{depId}/template-costs/apply參數
depId路徑梯次 ID
回應欄位 · data
ok套用成功旗標,恆為 true。
inserted本次新補插入的範本成本行數(冪等,已存在的不重複插)。
skippedForeign因匯率未備妥而跳過的外幣行數。補齊匯率後再套用,會自動補上這些行。
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
}
}該梯次各訂單旅客資料完整度
/api/v1/departures/{depId}/validation-summary參數
depId路徑梯次 ID
回應欄位 · data[]
orderId訂單 id。
orderNumber訂單編號。
errorCount該訂單的 error(必補缺漏)項目數。
warningCount該訂單的 warning(建議補齊)項目數。
incompleteTravelerCount至少有一項 error 或 warning 的旅客數(資料待補人數)。
errorTravelerCount含 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/付款/同意書
/api/v1/departures/control參數
range選填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選填自訂區間起日 YYYY-MM-DD(含),range=custom 時必填
to選填自訂區間迄日 YYYY-MM-DD(含),range=custom 時必填;from ≤ to,最長 731 天,超過回 400
trip選填行程 ID,只看該行程的梯次
status選填梯次狀態篩選(如 open / closed)
attention選填設為 true 時只回傳需要關注的梯次:有人未結清、有訂單未簽同意書,或有缺件(已成團未派主要隨團人員、未派承辦、隨團人員不足(已成團、需要數已填且確認人數少於需要數)、期限逾期或將到期、資料待補或資格待審、未分房)。已結束的梯次預設不列;同時指定 status 時,那些梯次只看付款與同意書
mine選填設為 true 時只回傳我是承辦小編的梯次;只對 op / admin 生效,其他角色忽略
回應欄位 · data[]
id梯次 id。
tripId所屬行程 id。
tripTitle行程名稱。
tripShortName行程內部簡稱(issue 1414);未填為 null。
hasPreTripNight行程有行前集合夜:出發日前一晚集合(trips.md §3)。
tripSlug行程公開頁網址代稱(slug)。
groupCode團號(可空)。
label梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);null = 無。
isPrivate不對外販售(issue 509 ①):前台藏、後台照建。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(YYYY-MM-DD)。
capacity團位容量(總名額)。
bookedCount已佔位人數。
status梯次狀態(如 open 開放/closed 關閉)。
salesOpenAt排定的開賣時間 ISO 字串;null = 沒排程(trips.md §2.2a,issue 1643)。
salesOpenFailedReason自動開賣被擋下的原因;null = 沒失敗。
confirmedAt成團時間 ISO 字串;null = 尚未成團(group-confirmation §2,與 status 正交)。
minGroupSize行程層最低成團人數門檻;null = 未設門檻(不提示達標)。
allocationMode佔位模式:fcfs 先到先得/lottery 抽籤。
leaderNames已排主要隨團人員姓名(confirmed + tentative 皆列;空 = 未指派)。
assistantNames已排協作 / 助教姓名(空 = 未指派協作)。
nameBoundGuideNamesNames on assignments that require a reason for replacement or removal.
confirmedLeaderCount已確認(status='confirmed')的主要隨團人員人數;0 = 沒有確認的主要隨團人員(tentative 不算)。
confirmedGuideCount已確認(status='confirmed')的主要+協同人數合計(issue 1117 的「已派」)。
permitSwappedCount已確認指派中勾了「已換領」的人數(issue 1731)。
requiredGuideCount需要的隨團人員數;null = 未填(issue 1117)。
notes梯次備註(集合上下車點、代收註記…;null = 無)。
opNames承辦小編姓名;空陣列不代表本梯不需承辦。
opNotRequiredReason選填明確標記本梯不需承辦的原因;null = 未標記。
priceTwd定價(TWD)。
agencyPriceTwd同業/旅行社報價(TWD;未設為 null)。
promoActive是否有進行中的促銷價。
promoPriceTwd促銷價(TWD;無促銷為 null)。
promoAgencyPriceTwd同業促銷價(TWD;無促銷為 null)。
daysUntilDeparture距出發天數(負值表示已出發)。
salesClosePassed選填有效停止售票時間已過(同 `updateDepartureStatus` 的守衛)。true 時改回售票中一定被拒, 梯次總覽的「恢復售票」改成停用並寫原因(issue 1654)。省略視同 false。
travelerCount旅客總人數(未取消訂單的 party_size 加總)。
paidCount已付款人數(party_size 加總;不含取消)。
pendingCount未結清人數(未付/部分付/已付訂金;不含取消)= unpaidCount + balanceDueCount。
unpaidCount完全未付人數(payment_state = unpaid;不含取消)。
balanceDueCount待收尾款人數(已付部分或訂金、還沒付清:partially_paid / deposit_paid;不含取消)。
cancelledCount已取消人數(僅供參考,不計入總數)。
ordersWithoutConsent尚未簽署同意書(PDPA)的訂單數。
codedRevenueTwd有折扣訂單的應收營收合計(TWD;排除取消/退款)。
discountTotalTwd折扣金額合計(TWD)。
profitShareTotalTwd利潤分潤金額合計(TWD)。
lottery梯次層抽籤結果:`result` 為 none(未送件)/pending(待抽籤)/waitlisted(備取中)/ won(已中籤)/lost(未中籤),`waitlistedCount` 為同梯還在備取的張數。先到先得梯次為 null。
resultwaitlistedCountlotteryWaitlistEnabled行程開了「抽籤結果含備取」(issue 1691):抽籤梯次才出現「備取」標記鍵。
stage生命週期階段。
metThreshold已達最低成團人數;門檻未設時為 false。
rooming分房進度;null = 這一梯不用分房(通鋪團或沒有房)。
roomCountassignedCounttotalTravelerscurl -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
}
]
}多梯次的分房進度統計
/api/v1/departures/room-stats參數
ids必填要查詢的梯次 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
/api/v1/discount-codes回應欄位 · data[]
id折扣碼 id(disc_ 前綴)。
code折扣碼字串(客戶結帳輸入用,租戶內唯一)。
label折扣碼顯示名稱(後台辨識用)。
discountType折扣型別:fixed 定額折抵 / percentage 比例折抵。
discountValue折扣值:fixed 為 TWD 整數,percentage 為百分比數字。
discountBasis計算方式:per_order 整張訂單折一次 / per_travelers 每 N 位旅客折一次 / per_amount 每滿 N 元折一次。
discountStepN:每幾位旅客 / 每滿幾元(TWD);per_order 時為 null。
profitShareType分潤型別:fixed 定額 / percentage 比例;null = 無分潤。
profitShareValue分潤值:fixed 為 TWD 整數,percentage 為百分比;null = 無分潤。
profitSharePayee分潤受款對象(如合作夥伴名稱);null = 無。
isActive是否啟用(停用後不可再兌換)。
validFrom生效起始時間;null = 無下限。
validUntil生效截止時間;null = 無上限。
maxRedemptions總兌換次數上限;null = 不限。
redemptionCount已兌換次數(不含已取消訂單)。
minOrderTwd最低訂單金額門檻(TWD 整數);null = 無門檻。
minTravelerCount最低旅客人數門檻;null = 無門檻。
appliesToAll是否適用所有行程(true = 全站,false = 僅限 tripIds 名單)。
maxRedemptionsPerCustomer每位客戶兌換次數上限;null = 不限。
allowedPriceChannels限用的價格通路清單(如 direct / agency);null = 不限。
allowedCustomerTypes限用的客戶類型清單;null = 不限。
stackable保留的旗標,結帳不讀:一張訂單只能套一個折扣碼。
notes內部備註;null = 無。
createdAt建立時間。
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
/api/v1/discount-codes參數
code必填折扣碼字串(前台結帳輸入,不分大小寫須唯一)
label必填折扣碼顯示名稱(後台與報表辨識用)
discountType必填fixedpercentage折抵方式:fixed 固定金額(TWD)或 percentage 百分比
discountValue必填折抵數值;fixed 為折抵金額(TWD),percentage 為百分比(1–100)
discountBasis選填per_orderper_travelersper_amount計算方式:per_order 整張訂單折一次(預設)、per_travelers 每 N 位旅客折一次、per_amount 每滿 N 元(折前金額)折一次;後兩者只限 fixed,折扣 = discountValue × 倍數,總額不超過訂單金額
discountStep選填N:每幾位旅客或每滿幾元(TWD);per_order 時須為 null,其餘必填
profitShareType選填fixedpercentage分潤方式:fixed 固定金額或 percentage 百分比;null 為不分潤
profitShareValue選填分潤數值;搭配 profitShareType,percentage 須 1–100,null 為不分潤
profitSharePayee選填分潤對象名稱(如合作推廣者),供出款對帳辨識
isActive選填是否啟用;停用後前台無法套用
validFrom選填生效起日(YYYY-MM-DD);留空為不限起日
validUntil選填生效迄日(YYYY-MM-DD);留空為不限迄日
maxRedemptions選填全碼可使用總次數上限;null 為不限
minOrderTwd選填最低訂單金額門檻(TWD),未達門檻不可套用;null 為不限
minTravelerCount選填最低旅客人數門檻(行程以旅客數、住宿以入住人數計),未達門檻不可套用;null 為不限
appliesToAll選填是否適用全部行程;true 時忽略 tripIds
tripIds選填指定可套用的行程 id 清單(appliesToAll=false 時生效)
maxRedemptionsPerCustomer選填每位客戶可使用次數上限;null 為不限
allowedPriceChannels選填可套用的價格渠道(direct 直客 / agency 同業);空陣列為不限。促銷價不是渠道:促銷價的直客單仍算 direct
allowedCustomerTypes選填可套用的客戶類型(direct 直客 / agency_contact 同業聯絡人);空陣列為不限
stackable選填保留的旗標,結帳不讀:一張訂單只能套一個折扣碼
notes選填內部備註(不對外顯示)
回應欄位 · data
id新建立折扣碼的 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
/api/v1/discount-codes/{id}參數
id路徑折扣碼 id(路徑參數)
回應欄位 · data
id折扣碼 id(disc_ 前綴)。
code折扣碼字串(客戶結帳輸入用,租戶內唯一)。
label折扣碼顯示名稱(後台辨識用)。
discountType折扣型別:fixed 定額折抵 / percentage 比例折抵。
discountValue折扣值:fixed 為 TWD 整數,percentage 為百分比數字。
discountBasis計算方式:per_order 整張訂單折一次 / per_travelers 每 N 位旅客折一次 / per_amount 每滿 N 元折一次。
discountStepN:每幾位旅客 / 每滿幾元(TWD);per_order 時為 null。
profitShareType分潤型別:fixed 定額 / percentage 比例;null = 無分潤。
profitShareValue分潤值:fixed 為 TWD 整數,percentage 為百分比;null = 無分潤。
profitSharePayee分潤受款對象(如合作夥伴名稱);null = 無。
isActive是否啟用(停用後不可再兌換)。
validFrom生效起始時間;null = 無下限。
validUntil生效截止時間;null = 無上限。
maxRedemptions總兌換次數上限;null = 不限。
redemptionCount已兌換次數(不含已取消訂單)。
minOrderTwd最低訂單金額門檻(TWD 整數);null = 無門檻。
minTravelerCount最低旅客人數門檻;null = 無門檻。
appliesToAll是否適用所有行程(true = 全站,false = 僅限 tripIds 名單)。
maxRedemptionsPerCustomer每位客戶兌換次數上限;null = 不限。
allowedPriceChannels限用的價格通路清單(如 direct / agency);null = 不限。
allowedCustomerTypes限用的客戶類型清單;null = 不限。
stackable保留的旗標,結帳不讀:一張訂單只能套一個折扣碼。
notes內部備註;null = 無。
createdAt建立時間。
tripIds限定適用的行程 id 清單(appliesToAll=false 時生效)。
redemptions逐筆兌換紀錄。
orderId兌換該折扣碼的訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
codeSnapshot兌換當下的折扣碼字串快照。
originalTotalTwd套用折扣前的原始應收總額(TWD 整數);跨行程換梯後為目標團費。
discountTwd現行折抵金額(TWD 整數);跨行程換梯退出優惠後為 0。
profitShareTwd現行分潤金額(TWD 整數);跨行程換梯退出優惠後為 0。
orderStatus訂單當前狀態。
createdAt兌換(下單)時間。
totalDiscountTwd累計折抵金額合計(TWD 整數)。
totalProfitShareTwd累計分潤金額合計(TWD 整數)。
totalPaidTwd兌換訂單累計已收金額合計(TWD 整數)。
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
/api/v1/discount-codes/{id}參數
id路徑折扣碼 id(路徑參數)
code必填折扣碼字串(前台結帳輸入,不分大小寫須唯一)
label必填折扣碼顯示名稱(後台與報表辨識用)
discountType必填fixedpercentage折抵方式:fixed 固定金額(TWD)或 percentage 百分比
discountValue必填折抵數值;fixed 為折抵金額(TWD),percentage 為百分比(1–100)
discountBasis選填per_orderper_travelersper_amount計算方式:per_order 整張訂單折一次、per_travelers 每 N 位旅客折一次、per_amount 每滿 N 元(折前金額)折一次;後兩者只限 fixed,折扣 = discountValue × 倍數,總額不超過訂單金額。省略時沿用現值;改成 percentage 而省略時退回 per_order
discountStep選填N:每幾位旅客或每滿幾元(TWD);per_order 時須為 null。省略時沿用現值
profitShareType選填fixedpercentage分潤方式:fixed 固定金額或 percentage 百分比;null 為不分潤
profitShareValue選填分潤數值;搭配 profitShareType,percentage 須 1–100,null 為不分潤
profitSharePayee選填分潤對象名稱(如合作推廣者),供出款對帳辨識
isActive選填是否啟用;停用後前台無法套用
validFrom選填生效起日(YYYY-MM-DD);留空為不限起日
validUntil選填生效迄日(YYYY-MM-DD);留空為不限迄日
maxRedemptions選填全碼可使用總次數上限;null 為不限
minOrderTwd選填最低訂單金額門檻(TWD),未達門檻不可套用;null 為不限
minTravelerCount選填最低旅客人數門檻(行程以旅客數、住宿以入住人數計),未達門檻不可套用;null 為不限
appliesToAll選填是否適用全部行程;true 時忽略 tripIds
tripIds選填指定可套用的行程 id 清單(appliesToAll=false 時生效)
maxRedemptionsPerCustomer選填每位客戶可使用次數上限;null 為不限
allowedPriceChannels選填可套用的價格渠道(direct 直客 / agency 同業);空陣列為不限。促銷價不是渠道:促銷價的直客單仍算 direct
allowedCustomerTypes選填可套用的客戶類型(direct 直客 / agency_contact 同業聯絡人);空陣列為不限
stackable選填保留的旗標,結帳不讀:一張訂單只能套一個折扣碼
notes選填內部備註(不對外顯示)
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/discount-codes/{id}/redemptions參數
id路徑折扣碼 id(路徑參數)
回應欄位 · data
id折扣碼 id(disc_ 前綴)。
code折扣碼字串。
label折扣碼顯示名稱。
redemptionCount已兌換次數(不含已取消訂單)。
totalDiscountTwd累計折抵金額合計(TWD 整數)。
totalProfitShareTwd累計分潤金額合計(TWD 整數)。
totalPaidTwd兌換訂單累計已收金額合計(TWD 整數)。
redemptions逐筆兌換紀錄。
orderId兌換該折扣碼的訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
codeSnapshot兌換當下的折扣碼字串快照。
originalTotalTwd套用折扣前的原始應收總額(TWD 整數);跨行程換梯後為目標團費。
discountTwd現行折抵金額(TWD 整數);跨行程換梯退出優惠後為 0。
profitShareTwd現行分潤金額(TWD 整數);跨行程換梯退出優惠後為 0。
orderStatus訂單當前狀態。
createdAt兌換(下單)時間。
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
/api/v1/discount-codes/{id}/set-active參數
id路徑折扣碼 id(路徑參數)
isActive必填目標啟用狀態:true 啟用、false 停用
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/discount-codes/preview參數
code必填欲試算的折扣碼字串
kind必填tourlodging產品種類:tour 行程或 lodging 住宿
tripId選填行程 id(kind=tour 時必填)
total必填試算用原始金額(TWD,未折扣前)
priceChannel選填價格渠道(direct / agency),用於折扣碼資格判定
customerType選填客戶類型(direct / agency_contact),用於折扣碼資格判定
userId選填客戶 user id,用於每客戶使用次數限制判定
travelerCount選填訂單旅客數(行程為旅客數、住宿為入住人數);設有最低人數門檻的碼未帶此值一律拒絕
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
}/group-codes
航空碼對照表
/api/v1/group-codes/airlines參數
activeOnly選填truefalse10傳 true 或 1 時只列出啟用中的航空碼
回應欄位 · data[]
code航空公司代碼(團號組成,通常大寫縮寫,如 EG)。
name航空公司名稱。
isActive是否啟用(停用後不可再指派給新梯次)。
displayOrder顯示排序(由小到大)。
usedCount被多少梯次引用。
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
}
]
}/api/v1/group-codes/airlines參數
code必填對照表碼,2–8 碼大寫英數,最後一碼是字母(自動轉大寫)
name必填碼的顯示名稱(如地區或航空公司全名)
isActive選填是否啟用(停用後不再供新團號選用)
displayOrder選填排序權重,數字越小越前面
回應欄位 · data
ok操作成功旗標,恆為 true。
code新增或更新的航空公司代碼。
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": "…"
}
}/api/v1/group-codes/airlines參數
code必填要更新的對照表碼(不可變更碼本身)
name必填碼的顯示名稱(如地區或航空公司全名)
isActive選填是否啟用(停用後不再供新團號選用)
displayOrder選填排序權重,數字越小越前面
回應欄位 · data
ok操作成功旗標,恆為 true。
code新增或更新的航空公司代碼。
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": "…"
}
}/api/v1/group-codes/airlines參數
code必填要刪除的對照表碼。有梯次引用的碼不能刪,只能改名稱或停用
回應欄位 · data
ok操作成功旗標,恆為 true。
code刪除的航空碼。
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": "…"
}
}前綴團號反查多梯次
/api/v1/group-codes/departures參數
prefix必填團號前綴,反查同地區同航空的所有梯次(如 26EGTK)
回應欄位 · data[]
id梯次 id(dep_ 前綴)。
tripId所屬行程 id(trip_ 前綴)。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日(ISO 'YYYY-MM-DD')。
groupCode完整團號。
regionCode地區代碼;null = 未設。
airlineCode航空公司代碼;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": "…"
}
]
}精確團號反查單一梯次
/api/v1/group-codes/departures/{id}參數
id路徑完整團號,反查單一梯次(大小寫不敏感)
回應欄位 · data
id梯次 id(dep_ 前綴)。
tripId所屬行程 id(trip_ 前綴)。
tripTitle所屬行程標題。
tripSlug所屬行程網址 slug。
departureDate出發日(ISO 'YYYY-MM-DD')。
groupCode完整團號。
regionCode地區代碼;null = 未設。
airlineCode航空公司代碼;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": "…"
}
}地區碼對照表
/api/v1/group-codes/regions參數
activeOnly選填truefalse10傳 true 或 1 時只列出啟用中的地區碼
回應欄位 · data[]
code地區代碼(團號組成,通常大寫縮寫,如 YS)。
name地區名稱(如「玉山」)。
isActive是否啟用(停用後不可再指派給新梯次)。
displayOrder顯示排序(由小到大)。
usedCount被多少梯次引用 —— 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
}
]
}/api/v1/group-codes/regions參數
code必填對照表碼,2–8 碼大寫英數,最後一碼是字母(自動轉大寫)
name必填碼的顯示名稱(如地區或航空公司全名)
isActive選填是否啟用(停用後不再供新團號選用)
displayOrder選填排序權重,數字越小越前面
回應欄位 · data
ok操作成功旗標,恆為 true。
code新增或更新的地區代碼。
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": "…"
}
}/api/v1/group-codes/regions參數
code必填要更新的對照表碼(不可變更碼本身)
name必填碼的顯示名稱(如地區或航空公司全名)
isActive選填是否啟用(停用後不再供新團號選用)
displayOrder選填排序權重,數字越小越前面
回應欄位 · data
ok操作成功旗標,恆為 true。
code新增或更新的地區代碼。
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": "…"
}
}/api/v1/group-codes/regions參數
code必填要刪除的對照表碼。有梯次引用的碼不能刪,只能改名稱或停用
回應欄位 · data
ok操作成功旗標,恆為 true。
code刪除的地區碼。
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
/api/v1/holidays參數
year選填篩選的西元年份(1000..9999);省略則回傳所有年份
回應欄位 · data
rows假日列(依日期排序)。
date日期(ISO 'YYYY-MM-DD')。
name名稱(如「國慶日」「補班」)。
isWorkday是否為補班日(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
/api/v1/holidays/{date}參數
date路徑假日 / 補班日的日期(YYYY-MM-DD,路徑參數),作為該筆紀錄的自然鍵
name必填假日 / 補班日名稱(如「春節」「補行上班」)
isWorkday選填是否為補班日:true 表示原假日改上班、false 表示國定假日;影響行前作業工作日倒數
回應欄位 · data
ok操作成功旗標,恆為 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
}
}/api/v1/holidays/{date}參數
date路徑要刪除的假日 / 補班日日期(YYYY-MM-DD,路徑參數)
回應欄位 · data
ok操作成功旗標,恆為 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.
/api/v1/holidays/batch參數
rows必填Holiday rows; atomic upsert
回應欄位 · data
importedcurl -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.
/api/v1/holidays/stats參數
year必填要統計的西元年份(1000..9999,必填)
回應欄位 · data
holidayCount該年度放假日數。
makeupCount該年度補班日數。
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
/api/v1/images參數
tripId選填行程 ID 篩選,僅回傳掛在該行程的圖片
q選填關鍵字,模糊比對行程標題、slug、圖說或網址
page選填分頁頁碼,從 1 起算,預設第 1 頁
pageSize選填每頁筆數,上限 200,預設由後端決定
回應欄位 · data
rows當頁圖片列。
id圖片資源 id(timg_ 前綴)。
tripId所屬行程 id(trip_ 前綴);null = 未歸屬。
tripTitle所屬行程標題;null = 未歸屬。
tripSlug所屬行程網址 slug;null = 未歸屬。
url圖片公開 URL。
caption圖說文字;null = 無。
displayOrder在行程相簿中的排序(由小到大)。
createdAt上傳建立時間。
total符合條件的總筆數(跨頁)。
page目前頁碼(1 起算)。
pageSize每頁筆數。
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
}
}/api/v1/images參數
tripId必填要掛上此圖片的行程 ID
url必填圖片網址(http 或 https),以引用方式掛載,非檔案上傳
caption選填圖片說明文字,選填
displayOrder選填排序權重,數字越小越前面,預設 0
回應欄位 · data
id新建立圖片的 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
/api/v1/images/{id}參數
id路徑欲刪除的行程圖片 ID
回應欄位 · data
ok操作成功旗標,恆為 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 +
/api/v1/images/trips回應欄位 · data[]
id行程 id(trip_ 前綴)。
title行程標題。
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
/api/v1/images/upload參數
contentBase64必填圖片檔案內容的 base64 編碼字串(JPEG / PNG / WebP,上限 8MB)
tripId選填要掛上此圖片的行程 ID,選填;不帶即為未歸屬圖片
caption選填圖片說明文字,選填
回應欄位 · data
id新建立圖片的 id(timg_ 前綴)。
url圖片網址,可直接填進輪播或封面欄位。
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
/api/v1/lodging/bookings參數
status選填依顯示狀態篩選(省略則回全部):pending_payment / paid / completed / cancelled / refunded。與列表 badge 同口徑——取消、退款、完成的優先序高於付款軸,所以取消或退款過的單不會出現在付款類的值裡
q選填自由文字關鍵字(訂房人、旅宿等)
回應欄位 · data[]
orderId訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
status顯示狀態(派生自三軸,沿用舊欄名供 UI badge / canCancel 相容)。
bookingState訂位軸狀態(如 confirmed / cancelled)。
paymentState付款軸狀態(如 unpaid / partial / paid)。
refundState退款軸狀態。
totalTwd應收總額(TWD 整數,訂單各應收明細加總)。
createdAt訂單建立時間。
bookerName訂購人姓名。
bookerEmail訂購人 email。
propertyId住宿館 id(prop_ 前綴)。
propertyName住宿館名稱。
roomTypeId房型 id(rt_ 前綴)。
roomTypeName房型名稱。
checkIn入住日(ISO 'YYYY-MM-DD')。
checkOut退房日(ISO 'YYYY-MM-DD')。
units訂購房間數。
guestCount入住總人數。
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
}
]
}/api/v1/lodging/bookings參數
propertyId必填旅宿物件 ID
roomTypeId必填房型 ID(須屬於該旅宿物件)
checkIn必填入住日(YYYY-MM-DD,含此晚)
checkOut必填退房日(YYYY-MM-DD,不含此晚,須晚於入住日)
units必填預訂單元數(房數或床位數,1-50)
guestCount必填入住人數(1-100,不得超過房型總容納人數)
bookerEmail必填訂房人 Email(須為已註冊會員)
paymentMethod必填cashatmmanual付款方式:cash 現金/atm 轉帳/manual 其他人工
receivingAccountId選填收款帳戶 ID(搭配付款方式記帳,可省略)
notes選填代訂備註
回應欄位 · data
orderId新建立住宿訂單的 id(ord_ 前綴)。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;建單與入帳本身已完成。
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.
/api/v1/lodging/bookings/{orderId}參數
orderId路徑旅宿訂單 ID
回應欄位 · data
orderId訂單 id(ord_ 前綴)。
orderNumber訂單編號(人類可讀流水號)。
status顯示狀態(派生自三軸,沿用舊欄名供 UI badge / canCancel 相容)。
bookingState訂位軸狀態(如 confirmed / cancelled)。
paymentState付款軸狀態(如 unpaid / partial / paid)。
refundState退款軸狀態。
totalTwd應收總額(TWD 整數,訂單各應收明細加總)。
createdAt訂單建立時間。
bookerName訂購人姓名。
bookerEmail訂購人 email。
propertyId住宿館 id(prop_ 前綴)。
propertyName住宿館名稱。
roomTypeId房型 id(rt_ 前綴)。
roomTypeName房型名稱。
checkIn入住日(ISO 'YYYY-MM-DD')。
checkOut退房日(ISO 'YYYY-MM-DD')。
units訂購房間數。
guestCount入住總人數。
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
/api/v1/lodging/bookings/{orderId}/cancel參數
orderId路徑旅宿訂單 ID
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/lodging/images/{id}參數
id路徑圖片 ID
kind必填propertyroom-type圖片所屬相簿:property 旅宿相簿/room-type 房型相簿
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/lodging/properties回應欄位 · data[]
id住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
slug網址 slug(公開站路徑,租戶內唯一)。
name住宿館名稱。
kind類型:hotel 旅館 / camp 營地。
isOverseas是否為海外住宿。
location地點描述;null = 未設。
description簡介文字;null = 未設。
contentMdx內文(MDX 原始碼);null = 未設。
facilities設施清單(JSON);null = 未設。
coverImageUrl封面圖 URL;null = 未設。
usageHint用途:direct 散客直訂 / package 梯次配套 / both 兩者皆可 / internal 不販售(內部據點)。
checkInTime入住時間文字(如「15:00」);null = 未設。
checkOutTime退房時間文字(如「11:00」);null = 未設。
checkInInfo入住須知;null = 未設。
houseRules館內規範;null = 未設。
cancellationPolicy取消政策;null = 未設。
addressRegion地址:縣市/區域;null = 未設。
addressLocality地址:鄉鎮/地區;null = 未設。
streetAddress街道地址;null = 未設。
postalCode郵遞區號;null = 未設。
latitude緯度;null = 未設。
longitude經度;null = 未設。
phone聯絡電話;null = 未設。
petsAllowed是否允許攜帶寵物;null = 未設。
smokingAllowed是否允許吸菸;null = 未設。
status狀態:active 啟用 / inactive 停用。
seoTitleSEO 標題覆寫;null = 沿用內容欄。
seoDescriptionSEO 描述;null = 未設。
ogImageUrlOpen Graph 分享圖 URL;null = 未設。
createdAt建立時間。
updatedAt最後更新時間。
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
/api/v1/lodging/properties參數
slug選填旅宿代稱(英數與連字號 2-63 字,租戶內唯一,用於網址;大寫自動轉小寫。只有 usageHint=internal 的內部據點可省略,省略時由名稱產生)
name必填旅宿名稱(對外顯示)
kind選填camphotel旅宿類型:camp 營地/hotel 旅館,預設 hotel
isOverseas選填是否為海外旅宿,預設否
location選填所在地點概述(如縣市、區域)
description選填旅宿介紹文字
usageHint選填directpackagebothinternal銷售用途:direct 僅直接訂房/package 僅併入套裝行程/both 兩者皆可/internal 不販售(內部據點,退出所有對客與販售路徑),預設 both
coverImageUrl選填封面圖網址(http/https 或本站圖庫資產路徑),用於公開旅宿頁與列表卡片
回應欄位 · data
id新建立住宿館的 id(prop_ 前綴)。
slug實際寫入的網址 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
/api/v1/lodging/properties/{id}參數
id路徑旅宿物件 ID
回應欄位 · data
id住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
slug網址 slug(公開站路徑,租戶內唯一)。
name住宿館名稱。
kind類型:hotel 旅館 / camp 營地。
isOverseas是否為海外住宿。
location地點描述;null = 未設。
description簡介文字;null = 未設。
contentMdx內文(MDX 原始碼);null = 未設。
facilities設施清單(JSON);null = 未設。
coverImageUrl封面圖 URL;null = 未設。
usageHint用途:direct 散客直訂 / package 梯次配套 / both 兩者皆可 / internal 不販售(內部據點)。
checkInTime入住時間文字(如「15:00」);null = 未設。
checkOutTime退房時間文字(如「11:00」);null = 未設。
checkInInfo入住須知;null = 未設。
houseRules館內規範;null = 未設。
cancellationPolicy取消政策;null = 未設。
addressRegion地址:縣市/區域;null = 未設。
addressLocality地址:鄉鎮/地區;null = 未設。
streetAddress街道地址;null = 未設。
postalCode郵遞區號;null = 未設。
latitude緯度;null = 未設。
longitude經度;null = 未設。
phone聯絡電話;null = 未設。
petsAllowed是否允許攜帶寵物;null = 未設。
smokingAllowed是否允許吸菸;null = 未設。
status狀態:active 啟用 / inactive 停用。
seoTitleSEO 標題覆寫;null = 沿用內容欄。
seoDescriptionSEO 描述;null = 未設。
ogImageUrlOpen Graph 分享圖 URL;null = 未設。
createdAt建立時間。
updatedAt最後更新時間。
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
/api/v1/lodging/properties/{id}參數
id路徑旅宿物件 ID
name選填旅宿名稱(對外顯示)
slug選填旅宿代稱(大寫自動轉小寫)。只有 usageHint=internal 的內部據點改得動,其餘已有公開頁、建立後不可修改
location選填所在地點概述(如縣市、區域)
description選填旅宿介紹文字
usageHint選填directpackagebothinternal銷售用途:direct 僅直接訂房/package 僅併入套裝行程/both 兩者皆可/internal 不販售(內部據點,退出所有對客與販售路徑)
checkInTime選填入住時間(如 15:00)
checkOutTime選填退房時間(如 11:00)
checkInInfo選填入住須知與報到說明
houseRules選填住宿規範
cancellationPolicy選填取消政策說明
addressRegion選填地址行政區(縣市層級)
addressLocality選填地址鄉鎮市區
streetAddress選填街道地址
postalCode選填郵遞區號
latitude選填緯度(-90 至 90)
longitude選填經度(-180 至 180)
phone選填聯絡電話
petsAllowed選填allowdisallowunset是否允許攜帶寵物:allow 允許/disallow 不允許/unset 清除設定,省略則不變更
smokingAllowed選填allowdisallowunset是否允許吸菸:allow 允許/disallow 不允許/unset 清除設定,省略則不變更
facilities選填設施代碼陣列(須為合法 amenity key;送空陣列代表清空)
seoTitle選填SEO 標題(送空字串代表清空,退回預設)
seoDescription選填SEO 描述(送空字串代表清空,退回預設)
ogImageUrl選填社群分享圖 URL(http/https 或本站圖庫資產路徑,送空字串代表清空)
coverImageUrl選填封面圖網址(http/https 或本站圖庫資產路徑),用於公開旅宿頁與列表卡片;傳 null 或空字串清除
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/lodging/properties/{id}/archive參數
id路徑旅宿物件 ID
回應欄位 · data
ok操作成功旗標,恆為 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.
/api/v1/lodging/properties/{id}/images參數
id路徑旅宿物件 ID
回應欄位 · data[]
id圖片資源 id(pimg_ / rtimg_ 前綴)。
url圖片公開 URL。
caption圖說文字;null = 無。
displayOrder相簿中的排序(由小到大)。
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
/api/v1/lodging/properties/{id}/images參數
id路徑旅宿物件 ID
url必填圖片網址
caption選填圖片說明文字(可省略)
displayOrder選填在相簿中的排序序號,數字越小越前面,預設 0
回應欄位 · data
id新建立住宿館圖片的 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
/api/v1/lodging/properties/{id}/room-types參數
id路徑旅宿物件 ID
回應欄位 · data[]
id房型 id(rt_ 前綴)。
lengthReturns the length of a String object.
propertyId所屬住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
name房型名稱。
inventoryUnit庫存單位:room 以房計 / bed 以床位計。
unitsTotal總庫存量(房間數或床位數)。
capacityPerUnit每單位可住人數。
lowAvailabilityThreshold低水位提示門檻;null = 不提示。
basePriceTwd底價(TWD 整數,每晚每單位;可被逐晚覆寫)。
description房型描述;null = 未設。
facilities設施清單(JSON);null = 未設。
bedConfig床型配置(JSON);null = 未設。
floorSizeSqm房間坪數(平方公尺);null = 未設。
status狀態:active 啟用 / inactive 停用。
createdAt建立時間。
updatedAt最後更新時間。
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
/api/v1/lodging/properties/{id}/room-types參數
id路徑所屬旅宿物件 ID
name必填房型名稱(如標準雙人房)
inventoryUnit選填roombed庫存單位:room 以房計/bed 以床位計,預設 room
unitsTotal必填此房型可售總單元數(房數或床位數)
capacityPerUnit選填每單元可容納人數,預設 1
lowAvailabilityThreshold選填剩餘單元數低水位門檻;null 表示不提示
basePriceTwd必填每晚每單元基準售價(新台幣)
description選填房型介紹文字
floorSizeSqm選填房間坪數(平方公尺)
bedType選填床型代碼(須為合法 bed type,搭配 bedCount 才生效)
bedCount選填該床型數量(須大於 0 才生效)
facilities選填房型設施代碼陣列(須為合法 amenity key)
回應欄位 · data
id新建立房型的 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
/api/v1/lodging/room-types/{id}參數
id路徑房型 ID
回應欄位 · data
id房型 id(rt_ 前綴)。
lengthReturns the length of a String object.
propertyId所屬住宿館 id(prop_ 前綴)。
lengthReturns the length of a String object.
name房型名稱。
inventoryUnit庫存單位:room 以房計 / bed 以床位計。
unitsTotal總庫存量(房間數或床位數)。
capacityPerUnit每單位可住人數。
lowAvailabilityThreshold低水位提示門檻;null = 不提示。
basePriceTwd底價(TWD 整數,每晚每單位;可被逐晚覆寫)。
description房型描述;null = 未設。
facilities設施清單(JSON);null = 未設。
bedConfig床型配置(JSON);null = 未設。
floorSizeSqm房間坪數(平方公尺);null = 未設。
status狀態:active 啟用 / inactive 停用。
createdAt建立時間。
updatedAt最後更新時間。
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
/api/v1/lodging/room-types/{id}參數
id路徑房型 ID
name選填房型名稱(如標準雙人房)
inventoryUnit選填roombed庫存單位:room 以房計/bed 以床位計
unitsTotal選填此房型可售總單元數(房數或床位數)
capacityPerUnit選填每單元可容納人數
lowAvailabilityThreshold選填剩餘單元數低水位門檻;null 表示清除提示
basePriceTwd選填每晚每單元基準售價(新台幣)
description選填房型介紹文字
floorSizeSqm選填房間坪數(平方公尺)
bedType選填床型代碼(須為合法 bed type,搭配 bedCount 才生效)
bedCount選填該床型數量(須大於 0 才生效)
facilities選填房型設施代碼陣列(須為合法 amenity key;送空陣列代表清空)
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/lodging/room-types/{id}/archive參數
id路徑房型 ID
回應欄位 · data
ok操作成功旗標,恆為 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 +
/api/v1/lodging/room-types/{id}/availability參數
id路徑房型 ID
checkIn必填入住日(YYYY-MM-DD,含此晚)
checkOut必填退房日(YYYY-MM-DD,不含此晚,區間最多 60 晚)
回應欄位 · data
available整段住宿期間可訂房間數(各晚剩餘取最小;任一晚關閉則為 0)。
nights住宿晚數。
totalPriceTwd整段期間房價合計(TWD 整數,逐晚牌價加總)。
perNight逐晚可售明細。
night該晚日期(ISO 'YYYY-MM-DD')。
capacity該晚可售容量(房間數;有覆寫則用覆寫值,否則房型總數)。
booked該晚已訂數。
remaining該晚剩餘可訂數(capacity − booked,不小於 0)。
priceTwd該晚房價(TWD 整數;有逐晚覆寫則用覆寫值,否則房型底價)。
status該晚販售狀態: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
/api/v1/lodging/room-types/{id}/availability/breakdown參數
id路徑房型 ID
from必填起始日(YYYY-MM-DD,含此晚)
to必填結束日(YYYY-MM-DD,不含此晚)
回應欄位 · data[]
night該晚日期(ISO 'YYYY-MM-DD')。
directBooked該晚散客直訂的已訂數。
packageBooked該晚梯次配套佔用的已訂數。
pretripBooked該晚出發前夜住宿(非販售佔用)的已訂數。
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.
/api/v1/lodging/room-types/{id}/images參數
id路徑房型 ID
回應欄位 · data[]
id圖片資源 id(pimg_ / rtimg_ 前綴)。
url圖片公開 URL。
caption圖說文字;null = 無。
displayOrder相簿中的排序(由小到大)。
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
/api/v1/lodging/room-types/{id}/images參數
id路徑房型 ID
url必填圖片網址
caption選填圖片說明文字(可省略)
displayOrder選填在相簿中的排序序號,數字越小越前面,預設 0
回應欄位 · data
id新建立房型圖片的 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
/api/v1/lodging/room-types/{id}/nights/override參數
id路徑房型 ID
from必填套用起始日(YYYY-MM-DD,含此日)
to必填套用結束日(YYYY-MM-DD,含此日;須不早於起始日,且區間最長 366 天)
priceTwd選填覆寫的每晚售價(新台幣),省略則不調整價格
capacity選填覆寫的每晚可售單元數,若低於已訂數量會回 409 衝突
status選填openclosed每晚開關房狀態:open 開放/closed 封房
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/lodging/stats回應欄位 · data
tonightCheckInUnits今晚入住房間數(Asia/Taipei)。
tonightCheckInGuests今晚入住總人數(Asia/Taipei)。
weekOccupancyPct未來 7 晚住房率(已訂 / 可售,0–100)。
next7AvailableUnits未來 7 晚仍可售的房晚數。
pendingPaymentCount待收款訂單筆數。
pendingPaymentTwd待收款金額合計(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
/api/v1/trips參數
status選填依行程狀態篩選(draft 草稿/published 上架/archived 封存)
q選填自由文字搜尋(行程標題/代稱/目的地)
groupCode選填依團號篩選,列出含該團號梯次的行程
回應欄位 · data[]
id行程 id(trip_ 前綴)。
slug行程網址 slug。
title行程標題。
destination目的地名稱。
durationDays天數。
guideStartDay選填guideEndDay選填priceFromTwd「NT$ X 起」起價(TWD 整數)。
status上架狀態:draft 草稿 / published 已上架 / archived 封存。
isHidden不對外顯示(#1435)。
isLinkOnly僅限連結:不進任何列表,行程頁不給搜尋引擎收錄,拿到網址可報名。與 `isHidden` 互斥。
foreignTravelersOnly限外籍旅客(issue 1519)。
updatedAt最後更新時間。
isClimbing是否登山團(行程層模組旗標)。
isOverseas是否海外團(行程層模組旗標)。
hasPreTripNight是否有行前集合夜(trips.md §3)。
activeDepartureCountCount of departures with status='selling'.
nextDepartureDateEarliest selling departure_date, ISO date string, or null.
representativeGroupCode代表團號(group-code §8.2):最新一筆有團號的梯次;無則 null(UI 顯示 —)。
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
/api/v1/trips參數
tags選填自由行程標籤;最多 20 個,每個最多 50 字。省略不變,空陣列清空
slug必填行程網址代稱(slug),用於前台路徑與後台識別,英數與連字號 2-63 字,大寫自動轉小寫
title必填行程標題,顯示於前台與訂單
shortName選填內部簡稱(例:嘉明湖三日),只用於後台與 API;null 或空字串清空,省略不變
summary選填行程摘要,前台列表卡片用的一句話簡介
contentMdx選填行程詳細內容(MDX 格式),前台行程頁主文
lotteryNoticeMdx選填登山行程的抽籤須知(MDX);null 清空,省略不變,不改抽籤或付款規則
destination必填目的地名稱
durationDays必填行程天數
guideStartDay選填帶團開始日,D1 起算;起訖成對設定,null 清除
guideEndDay選填帶團結束日,含當日;不得超過行程天數,null 清除
difficultyLevel選填對客難度(1 輕鬆、2 入門、3 中等、4 進階、5 挑戰);null 表示未分級,不影響內部資格審核
priceFromTwd必填起價(新台幣),前台「OOO 元起」顯示用
directPriceTwd選填直客定價(新台幣),留空(null)則退回起價繼承
agencyPriceTwd選填同業定價(新台幣),留空(null)則退回直客/起價繼承
depositMode選填nonefixedpercent訂金計算方式(none 不收/fixed 固定金額/percent 百分比)
depositAmountTwd選填訂金固定金額(新台幣),depositMode 為 fixed 時生效。按人或按單由 depositBasis 決定
depositBasis選填per_personper_order固定金額訂金的計算單位(per_person 每人,應付訂金=金額 × 人數/per_order 每張訂單一筆)。新行程預設 per_person;梯次覆寫的固定金額也照這個單位
depositPercent選填訂金百分比(1–100),depositMode 為 percent 時生效
balanceDueDaysBeforeDeparture選填尾款應繳截止日(出發前幾天)
feeInclusions選填費用包含項目清單,每項含勾選狀態(ok)與說明文字(text)
notices選填注意事項清單;最多 30 項,每項最多 200 字。省略不變,空陣列清空
cancellationFeeTiers選填退改費階梯覆寫:距出發 ≥ daysBefore 天扣 feePercent%(佔成交總額)或 feeFixedTwd 元/人,二選一;null = 繼承租戶預設
isClimbing選填是否為登山團(啟用登山相關模組欄位)
isOverseas選填是否為海外團
isHidden選填不對外顯示:官網、站內搜尋與搜尋引擎都看不到,梯次不對外販售;後台照常可建單
isLinkOnly選填僅限連結:不出現在官網列表、搜尋、sitemap 與前台 API 的行程列表,行程頁不給搜尋引擎收錄;拿到行程網址的人照常報名。與 isHidden 互斥;只送其中一個 true 時,另一個自動改成 false
manualCancellationRefund選填取消後先由承辦核算扣除額,再開退款單
equipmentRentalEnabled選填是否可租借裝備(需同時為登山團;開後此行程的梯次才能開租借單 / 登記裝備需求)
hasPreTripNight選填是否有行前集合夜(出發日前一晚集合夜宿;集合日恆為出發日 −1)
meetingDay選填第幾天集合(1 = 出發日,2 = 出發日隔天)。契約第 4 條的集合日照此計算;有行前集合夜時只能是 1,且不能超過行程天數
pretripStayRoomTypeId選填出發前夜住宿據點的床位池 id;null 表示不住公司據點
pretripStayExternalArranged選填出發前夜住宿是否由公司安排外部住宿(民宿等);與據點床位池互斥
gradeScore選填登山難度評分(0–100),null 表示未評級
requiresAlpineExperience選填是否需具備高山經驗
gradeLabel選填難度等級標籤文字
minGroupSize選填最低成團人數門檻,null 表示不設門檻
defaultCapacity選填新增梯次時席次欄的預設值,null 表示沒設(表單用固定預設)
salesCloseDaysBefore選填停止售票預設:出發日前 N 天的 00:00 自動把售票中的梯次改為已關閉;null 表示不自動關。梯次未自訂停止售票時間時繼承此值
meetingTime選填集合時間預設(HH:mm,台北牆鐘),null 表示清空;梯次未填時繼承
meetingPlace選填集合地點預設,null 表示清空;梯次未填時繼承
pretripBriefingUrl選填行前說明網址(http/https),所有梯次共用,null 表示清空。首次收款通知以 {{行前說明網址}} 代入;未填時通知刪掉含這個變數的整行
paymentReceivedBody選填收款後通知內文,所有梯次共用,null 表示清空。有值時首次收款通知(PAYMENT_RECEIVED)的內文改用它,主旨與啟用開關仍沿用範本;可用範本的 merge 變數
waitlistEnabled選填是否開放候補
foreignTravelersOnly選填限外籍旅客。true 時前台結帳擋下國籍空白或台灣的旅客;建單 API 與 K 單同樣擋,要送 allowDomesticTravelers 才放行
lotteryIdentityGuardEnabled選填是否啟用抽籤實名制:同一證件在任一受管制抽籤梯次同時只能有一筆待決申請
lotteryWaitlistEnabled選填抽籤結果含備取:主管機關會把申請排進備取的路線(例:排雲山莊)。true 時團控出現「備取」標記鍵。與 waitlistEnabled(一般梯次滿席候補)無關
defaultAllocationMode選填fcfslottery預設分配模式(fcfs 先到先得/lottery 抽籤):新增梯次未指定時繼承此值,梯次可逐梯覆寫;改動不回寫既有梯次。lottery 需抽籤模組
travelersPerGuide選填每幾位旅客配一位隨團人員(1–99),null 表示不自動算。成團時以已佔位人數算 ceil(人數 / 此值),帶入仍未填的梯次 requiredGuideCount
defaultGuideCount選填預設需要幾位嚮導(0–99;0 = 不需嚮導),null 表示沒設。新增梯次沒指定 requiredGuideCount 時帶入;改動不回寫既有梯次
lotteryLeadDays選填抽籤日在出發日前幾天(1–365),null 表示未設。退改費階梯首列門檻須為此值 + 1;抽籤梯次的可變更第三人期限 = 此值 + 緩衝天數;租戶抽籤日期來源的期限日 = 出發日前此天數
lotteryDrawTime選填抽籤時刻預設(HH:MM,台北時間),null 表示未設。抽籤梯次到抽籤日的這個時刻,前台停收新單;後台建單不受影響。抽籤時程表的時段開始與梯次覆寫優先;都沒設時抽籤日 00:00 停收
agreementChangeBufferDays選填抽籤梯次緩衝天數的行程覆寫(0–365),null 表示沿用公司設定。抽籤梯次的可變更第三人期限 = 抽籤前幾天 + 此值
agreementTravelForm選填individualgroup本行程契約的旅遊型態(individual 個別/group 團體),null 表示沿用公司設定。國內/國外仍由 isOverseas 決定
agreementExempt選填此行程不需旅遊契約。true 時這條行程的訂單不產生契約、不寄簽約邀請,並撤銷待簽契約;改回 false 後照一般規則補產生
coverImageUrl選填行程封面圖網址(http/https,或本站圖庫資產路徑);null 清空
seoTitle選填SEO 標題,覆寫前台頁面 title
seoDescription選填SEO 描述,覆寫前台 meta description
ogImageUrl選填Open Graph 社群分享圖網址(http/https,或本站圖庫資產路徑);null 清空
status選填draftpublishedarchived行程狀態(draft 草稿/published 上架/archived 封存)
pnlRegionId選填損益分區 id(pnl_regions),null 表示未指派、退回系統派生
回應欄位 · data
id新建立行程的 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
/api/v1/trips/{id}參數
id路徑行程 ID(路徑參數)
回應欄位 · data
id行程 id(trip_ 前綴)。
lengthReturns the length of a String object.
slug行程網址 slug(公開站路徑)。
title行程標題。
shortName選填內部簡稱(issue 1414);null = 未填。只有後台讀取帶,前台投影不帶。
summary一句話摘要;null = 未設。
contentMdx行程內文(MDX 原始碼);null = 未設。
lotteryNoticeMdx選填destination目的地名稱。
durationDays天數。
guideStartDay選填guideEndDay選填priceFromTwd「NT$ X 起」起價(TWD 整數)。
coverImageUrl封面圖 URL;null = 未設。
status上架狀態:draft 草稿 / published 已上架 / archived 封存。
isHidden不對外顯示(#1435):官網看不到、網址 404,後台照常可用。
isLinkOnly僅限連結(issue 1351):不進任何列表,行程頁 noindex、不出 JSON-LD,拿到網址可報名。
createdAt建立時間。
updatedAt最後更新時間。
isClimbing是否登山團(行程層模組旗標)。
isOverseas是否海外團(行程層模組旗標)。
equipmentRentalEnabled可租借裝備(equipment-inventory §3.1):與登山團旗標疊加,梯次不得覆寫。
hasPreTripNight是否有行前集合夜(trips.md §3)。集合日恆為 `departure_date − 1`,不落欄。
meetingDay第幾天集合(issue 1474):1 = 出發日。有行前集合夜時恆為 1。
minGroupSize最低成團人數(旅遊契約第 10 條揭露用);null = 不設門檻。
pretripStayRoomTypeId出發前夜住宿據點的床位池(ADR 0022 / 0029);null = 不住公司據點。出團不得覆寫。
pretripStayExternalArranged出發前夜住宿由公司安排外部住宿(民宿等);效力同旅客自理,僅顯示語意(#431)。
gradeScore難度評鑑分數(climbing-screening §3.1);null = 未評級。
difficultyLeveltagsrequiresAlpineExperience是否要求具備高山經驗(報名審核用)。
gradeLabel難度標籤(如「B+」);null = 未設。
waitlistEnabled候補開關(席滿後仍收候補,lottery-integration §3.5)。
defaultAllocationMode預設分配模式(lottery-integration §2.1):新增梯次時 copy-on-create,梯次可覆寫。
lotteryLeadDays選填抽籤日在出發日前幾天(issue 1095);null = 未設。梯次可覆寫;admin-only。
lotteryDrawTime選填抽籤時刻預設(`HH:MM`,issue 1656);null = 未設。梯次可覆寫;admin-only。
agreementChangeBufferDays選填抽籤梯次緩衝天數的行程覆寫(issue 1178);null = 沿用公司設定;admin-only。
agreementTravelForm選填本行程契約的旅遊型態(issue 1178);null = 沿用公司設定;admin-only。
agreementExempt選填此行程不需旅遊契約(issue 1524)。
foreignTravelersOnly限外籍旅客(issue 1519):本國旅客不能報名。行程頁對客揭露,所以公開投影也帶。
travelersPerGuide選填每幾位旅客配一位隨團人員(issue 1117);null = 不自動算;admin-only。
defaultGuideCount選填預設需要幾位嚮導(#1377);建梯次沒指定時帶入,0 = 不需嚮導;null = 沒設;admin-only。
defaultCapacity新增梯次的預設席次(trips.md §2.1);null = 沒設,表單用固定預設。
meetingTime集合時間的行程層預設(HH:mm,台北牆鐘;departure-prep §2.4.1);null = 未設。梯次未填時繼承。
meetingPlace集合地點的行程層預設;null = 未設。梯次未填時繼承。
pretripBriefingUrl選填行前說明網址(issue 1618);null = 未填。所有梯次共用;admin-only。
paymentReceivedBody選填收款後通知內文(issue 1743);null = 未填,用範本內文。所有梯次共用;admin-only。
salesCloseDaysBefore停止售票預設:出發前 N 天 00:00(trips.md §2.2);null = 行程層不設。
feeInclusions團費包含/不包含(前台費用區唯一來源);null = 未設。
notices注意事項(前台行程頁顯示);空陣列 = 未設。
cancellationFeeTiers逐行程退改費階梯覆寫(customer-cancellation §3);**null = 未覆寫**(用租戶預設), `[]` = 本行程不收退改費。兩者語意不同,不可折疊。
manualCancellationRefundseoTitleSEO 標題覆寫;null = 沿用 title。
seoDescriptionSEO 描述;null = 未設。
ogImageUrlOpen Graph 分享圖 URL;null = 未設。
images行程相簿圖片(依 displayOrder 排序)。
id圖片資源 id(timg_ 前綴)。
url圖片公開 URL。
caption圖說文字;null = 無。
displayOrder在行程相簿中的排序(由小到大)。
departuresActive (selling, future) departures only on the public side; all on admin.
id梯次 id(dep_ 前綴)。
tripId所屬行程 id(trip_ 前綴)。
departureDate出發日(ISO 'YYYY-MM-DD')。
returnDate回程日(ISO 'YYYY-MM-DD')。
priceTwd售價(TWD 整數,未稅牌價)。
capacity名額上限(人數)。
bookedCount已成團佔用名額(人數)。
status梯次狀態:selling 販售中 / closed 關閉 / cancelled 取消 / completed 已結團。
notes內部備註;null = 無。
allocationMode抽籤分配模式(lottery-integration §2.1):fcfs=先到先得 / lottery=抽籤制。
label選填梯次標籤 / 副標(例:「包」「包1」);null = 無;admin-only,公開站不映射。
isPrivate選填不對外販售(前台不顯示、不可自助報名;後台可建單);admin-only,公開站不映射。
agencyPriceTwd選填同業價(TWD 整數);admin-only,公開站不映射。
depositMode選填訂金規則模式:none 免訂金 / fixed 定額 / percent 比例;admin-only。
depositAmountTwd選填訂金定額(TWD 整數,depositMode=fixed 時適用);admin-only。
depositPercent選填訂金比例(百分比,depositMode=percent 時適用);admin-only。
groupCode選填團號(group-code §3.3);admin-only,公開站不映射。
regionCode選填地區代碼(團號組成);admin-only。
airlineCode選填航空公司代碼(團號組成);admin-only。
promoActive選填梯次促銷是否啟用(trip-pricing);admin-only。
promoPriceTwd選填促銷覆寫售價(TWD 整數);admin-only。
promoAgencyPriceTwd選填促銷覆寫同業價(TWD 整數);admin-only。
salesCloseAt選填逐梯停止售票時間(trips.md §2.2);null = 繼承行程層;admin-only。
effectiveSalesCloseAt選填有效停止售票時間:逐梯值,否則行程層「出發前 N 天 00:00」派生;兩者皆無為 null。 排程到點把 selling → closed 就是看這個值;admin-only。
salesAutoClosedAt選填排程自動關閉的時間;null = 人工關或未關。與 status='closed' 合看;admin-only。
salesClosePassed選填有效停止售票時間是否已到(DB 的 NOW() 判,與排程同一個時鐘);admin-only。
salesOpenAt選填開賣時間(trips.md §2.2a);null = 沒有排程;admin-only。
salesOpenFailedReason選填到點開賣被擋下的原因;null = 沒有失敗;admin-only。
meetingTime選填第 4 條集合時間(牆鐘字串);admin-only。
meetingPlace選填第 4 條集合地點;admin-only。
agreementChangeDays選填可變更第三人期限天數的逐梯覆寫;null = 退回租戶預設(團體契約的抽籤梯次必填);admin-only。
entryDateOffsetDays選填實際入園日相對出發日的偏移天數(departure-prep §2.6.1);admin-only。
lotteryLeadDays選填抽籤前幾天的逐梯覆寫(issue 1095);null = 繼承行程層;admin-only。
lotteryDrawTime選填抽籤時刻的逐梯覆寫(`HH:MM`,issue 1656);null = 繼承行程層;admin-only。
lotteryChangeDays選填抽籤梯次的自動可變更第三人期限(出發前幾天,issue 1178):抽籤前幾天+緩衝天數,或公司抽籤 日期來源推回的天數;算不出來是 null。不看逐梯手填值與分配模式;admin-only。
lotteryDrawDate選填抽籤日(`YYYY-MM-DD`,`lotteryDrawDateSql`,issue 1656);沒有抽籤日為 null。不看分配模式;admin-only。
effectiveLotteryDrawTime選填生效的抽籤時刻(`HH:MM`,`lotteryDrawTimeSql`:時程表時段開始 → 梯次覆寫 → 行程預設); 未設為 null,前台在抽籤日 00:00 截止;admin-only。
lotteryApplicationClosed選填抽籤梯次已截止申請(前台不收單,issue 1656);admin-only。
requiredGuideCount選填需要的隨團人員數(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
}
]
}
}/api/v1/trips/{id}參數
id路徑行程 ID(路徑參數)
tags選填自由行程標籤;最多 20 個,每個最多 50 字。省略不變,空陣列清空
slug選填行程網址代稱(slug),用於前台路徑與後台識別,英數與連字號 2-63 字,大寫自動轉小寫
title選填行程標題,顯示於前台與訂單
shortName選填內部簡稱(例:嘉明湖三日),只用於後台與 API;null 或空字串清空,省略不變
summary選填行程摘要,前台列表卡片用的一句話簡介
contentMdx選填行程詳細內容(MDX 格式),前台行程頁主文
lotteryNoticeMdx選填登山行程的抽籤須知(MDX);null 清空,省略不變,不改抽籤或付款規則
destination選填目的地名稱
durationDays選填行程天數
guideStartDay選填帶團開始日,D1 起算;起訖成對設定,null 清除
guideEndDay選填帶團結束日,含當日;不得超過行程天數,null 清除
difficultyLevel選填對客難度(1 輕鬆、2 入門、3 中等、4 進階、5 挑戰);null 表示未分級,不影響內部資格審核
priceFromTwd選填起價(新台幣),前台「OOO 元起」顯示用
directPriceTwd選填直客定價(新台幣),留空(null)則退回起價繼承
agencyPriceTwd選填同業定價(新台幣),留空(null)則退回直客/起價繼承
depositMode選填nonefixedpercent訂金計算方式(none 不收/fixed 固定金額/percent 百分比)
depositAmountTwd選填訂金固定金額(新台幣),depositMode 為 fixed 時生效。按人或按單由 depositBasis 決定
depositBasis選填per_personper_order固定金額訂金的計算單位(per_person 每人,應付訂金=金額 × 人數/per_order 每張訂單一筆)。新行程預設 per_person;梯次覆寫的固定金額也照這個單位
depositPercent選填訂金百分比(1–100),depositMode 為 percent 時生效
balanceDueDaysBeforeDeparture選填尾款應繳截止日(出發前幾天)
feeInclusions選填費用包含項目清單,每項含勾選狀態(ok)與說明文字(text)
notices選填注意事項清單;最多 30 項,每項最多 200 字。省略不變,空陣列清空
cancellationFeeTiers選填退改費階梯覆寫:距出發 ≥ daysBefore 天扣 feePercent%(佔成交總額)或 feeFixedTwd 元/人,二選一;null = 繼承租戶預設
isClimbing選填是否為登山團(啟用登山相關模組欄位)
isOverseas選填是否為海外團
isHidden選填不對外顯示:官網、站內搜尋與搜尋引擎都看不到,梯次不對外販售;後台照常可建單
isLinkOnly選填僅限連結:不出現在官網列表、搜尋、sitemap 與前台 API 的行程列表,行程頁不給搜尋引擎收錄;拿到行程網址的人照常報名。與 isHidden 互斥;只送其中一個 true 時,另一個自動改成 false
manualCancellationRefund選填取消後先由承辦核算扣除額,再開退款單
equipmentRentalEnabled選填是否可租借裝備(需同時為登山團;開後此行程的梯次才能開租借單 / 登記裝備需求)
hasPreTripNight選填是否有行前集合夜(出發日前一晚集合夜宿;集合日恆為出發日 −1)
meetingDay選填第幾天集合(1 = 出發日,2 = 出發日隔天)。契約第 4 條的集合日照此計算;有行前集合夜時只能是 1,且不能超過行程天數
pretripStayRoomTypeId選填出發前夜住宿據點的床位池 id;null 表示不住公司據點
pretripStayExternalArranged選填出發前夜住宿是否由公司安排外部住宿(民宿等);與據點床位池互斥
gradeScore選填登山難度評分(0–100),null 表示未評級
requiresAlpineExperience選填是否需具備高山經驗
gradeLabel選填難度等級標籤文字
minGroupSize選填最低成團人數門檻,null 表示不設門檻
defaultCapacity選填新增梯次時席次欄的預設值,null 表示沒設(表單用固定預設)
salesCloseDaysBefore選填停止售票預設:出發日前 N 天的 00:00 自動把售票中的梯次改為已關閉;null 表示不自動關。梯次未自訂停止售票時間時繼承此值
meetingTime選填集合時間預設(HH:mm,台北牆鐘),null 表示清空;梯次未填時繼承
meetingPlace選填集合地點預設,null 表示清空;梯次未填時繼承
pretripBriefingUrl選填行前說明網址(http/https),所有梯次共用,null 表示清空。首次收款通知以 {{行前說明網址}} 代入;未填時通知刪掉含這個變數的整行
paymentReceivedBody選填收款後通知內文,所有梯次共用,null 表示清空。有值時首次收款通知(PAYMENT_RECEIVED)的內文改用它,主旨與啟用開關仍沿用範本;可用範本的 merge 變數
waitlistEnabled選填是否開放候補
foreignTravelersOnly選填限外籍旅客。true 時前台結帳擋下國籍空白或台灣的旅客;建單 API 與 K 單同樣擋,要送 allowDomesticTravelers 才放行
lotteryIdentityGuardEnabled選填是否啟用抽籤實名制:同一證件在任一受管制抽籤梯次同時只能有一筆待決申請
lotteryWaitlistEnabled選填抽籤結果含備取:主管機關會把申請排進備取的路線(例:排雲山莊)。true 時團控出現「備取」標記鍵。與 waitlistEnabled(一般梯次滿席候補)無關
defaultAllocationMode選填fcfslottery預設分配模式(fcfs 先到先得/lottery 抽籤):新增梯次未指定時繼承此值,梯次可逐梯覆寫;改動不回寫既有梯次。lottery 需抽籤模組
travelersPerGuide選填每幾位旅客配一位隨團人員(1–99),null 表示不自動算。成團時以已佔位人數算 ceil(人數 / 此值),帶入仍未填的梯次 requiredGuideCount
defaultGuideCount選填預設需要幾位嚮導(0–99;0 = 不需嚮導),null 表示沒設。新增梯次沒指定 requiredGuideCount 時帶入;改動不回寫既有梯次
lotteryLeadDays選填抽籤日在出發日前幾天(1–365),null 表示未設。退改費階梯首列門檻須為此值 + 1;抽籤梯次的可變更第三人期限 = 此值 + 緩衝天數;租戶抽籤日期來源的期限日 = 出發日前此天數
lotteryDrawTime選填抽籤時刻預設(HH:MM,台北時間),null 表示未設。抽籤梯次到抽籤日的這個時刻,前台停收新單;後台建單不受影響。抽籤時程表的時段開始與梯次覆寫優先;都沒設時抽籤日 00:00 停收
agreementChangeBufferDays選填抽籤梯次緩衝天數的行程覆寫(0–365),null 表示沿用公司設定。抽籤梯次的可變更第三人期限 = 抽籤前幾天 + 此值
agreementTravelForm選填individualgroup本行程契約的旅遊型態(individual 個別/group 團體),null 表示沿用公司設定。國內/國外仍由 isOverseas 決定
agreementExempt選填此行程不需旅遊契約。true 時這條行程的訂單不產生契約、不寄簽約邀請,並撤銷待簽契約;改回 false 後照一般規則補產生
coverImageUrl選填行程封面圖網址(http/https,或本站圖庫資產路徑);null 清空
seoTitle選填SEO 標題,覆寫前台頁面 title
seoDescription選填SEO 描述,覆寫前台 meta description
ogImageUrl選填Open Graph 社群分享圖網址(http/https,或本站圖庫資產路徑);null 清空
pnlRegionId選填損益分區 id(pnl_regions),null 表示未指派、退回系統派生
status選填draftpublishedarchived行程狀態(draft 草稿/published 上架/archived 封存);省略 = 不動
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/trips/{id}/cost-template參數
id路徑行程 ID(路徑參數)
templateIds選填要綁定的成本範本 ID 陣列(依序疊加);[] 或省略表示解除全部綁定
templateId選填(向後相容,單一)要綁定的成本範本 ID;null 表示解綁
回應欄位 · data
ok操作成功旗標,恆為 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
/api/v1/trips/{id}/departures參數
id路徑行程 ID(路徑參數),新梯次所屬的行程
departureDate必填出發日期(YYYY-MM-DD)
returnDate必填回程日期(YYYY-MM-DD),須晚於出發日
priceTwd必填梯次直客售價(新台幣)
capacity必填梯次總名額(座位上限)
agencyPriceTwd選填梯次同業售價(新台幣)
depositMode選填nonefixedpercent訂金計算方式(none 不收/fixed 固定金額/percent 百分比)
depositAmountTwd選填梯次訂金固定金額(新台幣),depositMode 為 fixed 時生效。按人或按單照行程的 depositBasis
depositPercent選填訂金百分比(1–100),depositMode 為 percent 時生效
status選填sellingclosedcancelledcompleted梯次狀態(selling 銷售中/closed 關閉/cancelled 取消/completed 完成);省略 = selling,有 salesOpenAt 時 = closed
label選填梯次標籤/副標(最多 30 字,例:包、包1、外籍包),只顯示在後台;省略 = 無
isPrivate選填不對外販售:前台不顯示、客人不可自助報名,但後台 K 單看得到、建得了;省略 = false
allocationMode選填fcfslottery分配模式(fcfs 先到先得/lottery 抽籤);省略 = 繼承行程的 defaultAllocationMode。lottery 需抽籤模組
regionCode選填團號地區來源碼(2–8 碼大寫英數),用於產生團號,可不指定
airlineCode選填團號航空來源碼(2–8 碼大寫英數),用於產生團號,可不指定
salesCloseAt選填停止售票時間(YYYY-MM-DDTHH:MM,台北牆鐘),到點自動把售票中改為已關閉;省略則繼承行程的「出發前 N 天」預設
salesOpenAt選填開賣時間(YYYY-MM-DDTHH:MM,台北牆鐘)。梯次先建成已關閉,到點自動改為售票中;須晚於現在、早於停止售票時間。省略 = 照舊人工上架
meetingTime選填集合時間(HH:mm,台北牆鐘);省略 = 繼承行程層預設
meetingPlace選填集合地點;省略 = 繼承行程層預設
agreementChangeDays選填可變更第三人期限(出發前 N 日,對應契約「旅客之變更權」條);免抽籤梯次省略則用租戶預設,團體抽籤契約未設定有效日期來源時必填
entryDateOffsetDays選填實際入園日相對出發日的偏移天數(入園日 = 出發日 + N);省略 = 0。錨定入園日的關鍵日期由此回推
lotteryLeadDays選填抽籤日在出發日前幾天的逐梯覆寫(1–365);省略或 null = 繼承行程的 lotteryLeadDays。只影響期限與契約,不改退改費階梯
lotteryDrawTime選填抽籤時刻的逐梯覆寫(HH:MM,台北時間);省略或 null = 繼承行程的 lotteryDrawTime。抽籤時程表上有這梯的時段開始時,時段開始優先
requiredGuideCount選填需要的隨團人員數(主要+協同合計,0–99;0 = 不需嚮導);省略或 null = 帶入行程的 defaultGuideCount(沒設 = 未填);仍未填且行程有設 travelersPerGuide 時,成團以 ceil(已佔位人數 / 比例) 帶入
回應欄位 · data
id新建立梯次的 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": "…"
}
}為某梯次預留自家旅宿配套
/api/v1/trips/{id}/departures/{depId}/lodging參數
id路徑行程 ID(路徑參數),梯次所屬的行程
depId路徑梯次 ID(路徑參數),要預留旅宿的梯次
propertyId必填自家旅宿物件 ID
roomTypeId必填該旅宿的房型 ID
checkIn必填入住日(YYYY-MM-DD)
checkOut必填退房日(YYYY-MM-DD),須晚於入住日,且區間最多 60 晚
blockUnits必填整塊預留的房間間數
回應欄位 · data
ok操作成功旗標,恆為 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
}
}釋回某梯次的自家旅宿配套預留
/api/v1/trips/{id}/lodging/{dlId}參數
id路徑行程 ID(路徑參數),預留所屬的行程
dlId路徑梯次旅宿配套預留 ID(路徑參數),要釋回的預留
回應欄位 · data
ok操作成功旗標,恆為 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
}
}/api/v1/trips/{id}/ops-defaults參數
id路徑Resource ID
回應欄位 · data
transportkeydescriptionvehicleInfofareNotecateringkeysuppliermealPlanheadcountNoteinsurance逐 kind 一列:保險公司與排定辦理日的「出發前 N 個工作天」(issue 1373)。兩欄至少一欄有值; 缺 kind = 該類不預建。保單號永遠逐梯填。`workdaysBefore` 省略 = 不帶排定日。
kindinsurerworkdaysBefore選填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.
/api/v1/trips/{id}/ops-defaults參數
id路徑Resource ID
defaults必填Replace transport, catering, and insurance defaults; null clears defaults
回應欄位 · data
defaultstransportkeydescriptionvehicleInfofareNotecateringkeysuppliermealPlanheadcountNoteinsurance逐 kind 一列:保險公司與排定辦理日的「出發前 N 個工作天」(issue 1373)。兩欄至少一欄有值; 缺 kind = 該類不預建。保單號永遠逐梯填。`workdaysBefore` 省略 = 不帶排定日。
kindinsurerworkdaysBefore選填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.
/api/v1/trips/{id}/survey參數
id路徑Resource ID
回應欄位 · data[]
idtripIdkindlabeldescriptionrequireddisplayOrderisActiveoptionsidlabelequipmentItemId綁定的裝備主檔品項(issue 240;只有 multi / quantity 題可綁);null = 純文字選項。
displayOrderisActivecurl -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.
/api/v1/trips/{id}/survey/options/{optionId}參數
id路徑Resource ID
optionId路徑Option ID
label選填Option label
isActive選填Option enabled
equipmentItemId選填Equipment item; null to unlink
回應欄位 · data
foundcurl -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.
/api/v1/trips/{id}/survey/questions參數
id路徑Resource ID
kind必填textsinglemultiquantityQuestion kind
label必填Question label
description選填Question description
required選填Answer required
options選填Option labels
回應欄位 · data
idcurl -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.
/api/v1/trips/{id}/survey/questions/{questionId}參數
id路徑Resource ID
questionId路徑Question ID
label選填Question label
description選填Description
required選填Answer required
回應欄位 · data
foundcurl -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.
/api/v1/trips/{id}/survey/questions/{questionId}/active參數
id路徑Resource ID
questionId路徑Question ID
isActive必填Question enabled
回應欄位 · data
foundcurl -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.
/api/v1/trips/{id}/survey/questions/{questionId}/options參數
id路徑Resource ID
questionId路徑Question ID
label必填Option label
回應欄位 · data
idcurl -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
/api/v1/trips/batch-departures參數
rows必填回應欄位 · data
result建檔結果(建立筆數與逐列結果)。
importBatchId本次匯入批次 id(imp_ 前綴),供稽核追溯。
createdTripCount新建行程數。
createdDepartureCount新建梯次數。
skippedCount略過列數(重複/無需匯入)。
errorCount失敗列數。
results逐列匯入結果。
rowNumber試算表列號(含表頭列,資料第一列為 2)。
status該列匯入結果:new_trip / append_departure / skip / error。
messageerror / skip 的人話原因(繁中);成功列為空。
tripId選填建出的 trip id(new_trip 成功時)。
departureId選填建出的 departure id(new_trip / append_departure 成功時)。
groupCode選填產生的團號(有地區碼時;航空碼選填)。
incompleteTrips本批**新建**行程中,關鍵設定仍為空者(#461)。漏填的三組全是靜默失效(難度分留空 → 審核器不作用;階梯未覆寫 → 套租戶預設那組;訂金不收),結果頁列出並附編輯連結。 只列有缺的行程;補梯次的既有行程不列(匯入不動它的設定)。
tripIdslugtitlemissing仍為空的關鍵設定(至少一項)。
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
/api/v1/trips/batch-departures/validate參數
rows必填回應欄位 · data
result試算(dry-run)結果:逐列預覽 + 彙總,列號 = 第幾列(1 起)。
rowsrowNumber試算表列號(含表頭列,資料第一列為 2)。
status該列匯入判定:new_trip 新建行程 / append_departure 附加梯次 / skip 略過 / error 錯誤。
messageerror / skip 的人話原因(繁中);new_trip / append_departure 為空。
parsed解析後的欄位值。
slugtitlesummarydestinationdurationDaysisClimbingisOverseashasPreTripNight行前集合夜三態;null = 留空(繼承既有行程)。見 {@link ImportedCell}。
gradeScore登山難度評鑑分數(0–100,可小數)。
requiresAlpineExperience是否需具備高山經驗(是/否)。
lotteryLeadDays30 / 60 / 120 依租戶預設產生階梯;海外使用個別契約範本。
overseasIndividualCancellation選填明示套用海外個別契約範本;留空不套用。
depositMode訂金方式(不收 / 固定金額 / 比例)。
depositAmountTwd訂金金額(TWD 正整數;方式=固定金額時必填)。
depositPercent訂金比例(1–100;方式=比例時必填)。
departureDatereturnDatepriceTwdcapacity留空 = null(補梯次時沿用行程的預設名額);非整數 → 'invalid'。
noteslabel梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);留空 = null。
isPrivate不對外販售(issue 509 ①)。留空 = 否;填了無法辨識的值 → 'invalid'(dry-run error)。
allocationMode分配模式(issue 511)。留空 = 繼承母行程的預設分配模式(createDeparture copy-on-create); 填了無法辨識的值 → 'invalid'(dry-run error);抽籤但平台未啟用抽籤模組 → error。
regionCodeairlineCodeagencyPriceTwd同業價(TWD 整數 ≥ 0);留空 = 退回常規定價鏈。
departureDepositMode梯次訂金方式覆寫;留空 = 繼承行程的訂金設定。
departureDepositAmountTwd梯次訂金金額(方式=固定金額時必填)。
departureDepositPercent梯次訂金比例(方式=比例時必填,1–100)。
salesCloseAt逐梯停止售票時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘);只填日期 = 當天 00:00;留空 = 繼承行程層。
salesOpenAt開賣時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘,issue 1643);解析同停止售票日。有值時梯次建成 已關閉,排程到點開賣;留空 = 照舊。
meetingTime集合時間 `HH:mm`(台北牆鐘);留空 = 讀取時繼承行程層。
meetingPlace集合地點(≤ 200 字);留空 = 讀取時繼承行程層。
agreementChangeDays可變更第三人期限(出發前 N 日,0–365);留空 = 免抽籤梯次用租戶預設,團體契約的抽籤梯次缺值不產生契約,個別契約不適用。
entryDateOffsetDays實際入園日偏移(入園日 = 出發日 + N,0–行程天數−1);留空 = 0。
requiredGuideCount需要的隨團人員數(1–99,issue 1117);留空 = 未填,成團時再依行程比例帶入。
promoPriceTwd促銷直客價(TWD 正整數);有值 = 啟用梯次促銷;留空 = 不促銷。
promoAgencyPriceTwd促銷同業價(TWD 正整數);須搭配促銷直客價;留空 = 同業不參與促銷。
opAssignee承辦(issue 1102):後台帳號 Email,或唯一對到帳號的姓名;原樣保留,比對在 resolveRows。 留空 = 不掛承辦。補梯次列與「梯次已存在」的列也套用。
existingTripDefaultAllocationMode選填該 slug 在 DB 已有行程時,其 `default_allocation_mode`(issue 511):預覽對留空的補梯次列 印出「繼承後會落成什麼」用。slug 在 DB 不存在 → null。
warnings建完後擋開賣的缺項(#613 2026-10-20)。只提醒、不擋建檔;只有會建檔的列 (new_trip / append_departure)才有。判準見 {@link importRowWarnings}。
codemessagesummarytotalRows資料列總數。
newTripCount判定為「新建行程」的列數。
appendDepartureCount判定為「附加梯次到既有行程」的列數。
skipCount略過列數。
errorCount有錯誤的列數。
unsellableCount會建檔、但建完後開賣會被擋的梯次數(至少一則 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.
/api/v1/trips/cancellation-tiers/preview參數
tripIds必填Selected trip IDs
回應欄位 · data
changes`leadDays` 為 null:首列與租戶預設同門檻,直接重套成租戶預設。
tripIdtitleleadDaysskipped略過的行程(無效列、不收退改費、判斷不出前置天數、租戶預設產不出階梯)。
tripIdtitlereasonunchangedCount已經一致或未覆寫,不需要改的行程數。
tenantTiers判斷時用的租戶預設。確認寫入時原樣送回,交易內比對它有沒有被改過。
daysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
onSaleCount`changes` 裡已開賣的行程數:有後台可建單(販售中)、且尚未出發的梯次。
orderCount`changes` 掛著的未結訂單數(`pending_payment` / `confirmed`,一張單只算一次)。 PM 裁示一改全改(issue 538),這些單之後取消會套新階梯。
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.
/api/v1/trips/cancellation-tiers/reapply參數
tripIds必填Selected trip IDs
confirmedTripIds必填Confirmed affected trip IDs from preview
confirmedTenantTiers必填Tenant tiers from preview
回應欄位 · data
changes`leadDays` 為 null:首列與租戶預設同門檻,直接重套成租戶預設。
tripIdtitleleadDaysskipped略過的行程(無效列、不收退改費、判斷不出前置天數、租戶預設產不出階梯)。
tripIdtitlereasonunchangedCount已經一致或未覆寫,不需要改的行程數。
tenantTiers判斷時用的租戶預設。確認寫入時原樣送回,交易內比對它有沒有被改過。
daysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
onSaleCount`changes` 裡已開賣的行程數:有後台可建單(販售中)、且尚未出發的梯次。
orderCount`changes` 掛著的未結訂單數(`pending_payment` / `confirmed`,一張單只算一次)。 PM 裁示一改全改(issue 538),這些單之後取消會套新階梯。
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
/api/v1/trips/cost-templates參數
status選填成本範本狀態篩選;目前僅回傳啟用中(active)範本
回應欄位 · data[]
id成本範本 id(ct_ 前綴)。
name成本範本名稱。
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.
/api/v1/trips/departures參數
groupCode選填完整團號,精確比對單一梯次
groupCodePrefix選填團號前綴,前綴比對列出多個梯次
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
/api/v1/trips/departures/{departureId}參數
departureId路徑梯次 ID(路徑參數)
departureDate選填出發日期(YYYY-MM-DD),與回程日一起提供
returnDate選填回程日期(YYYY-MM-DD),不得早於出發日
capacity選填梯次總名額(座位上限),不得低於已報名人數
priceTwd選填梯次直客售價(新台幣)
agencyPriceTwd選填梯次同業售價(新台幣),null 表示清空、退回常規定價鏈
depositMode選填nonefixedpercent訂金計算方式(none 不收/fixed 固定金額/percent 百分比),null 表示退回繼承
depositAmountTwd選填梯次訂金固定金額(新台幣),depositMode 為 fixed 時生效,null 表示清空。按人或按單照行程的 depositBasis
depositPercent選填訂金百分比(1–100),depositMode 為 percent 時生效,null 表示清空
promoActive選填是否啟用梯次促銷覆寫價
promoPriceTwd選填直客促銷價(新台幣),啟用促銷時必填,null 表示清空
promoAgencyPriceTwd選填同業促銷價(新台幣),null 表示同業退回常規鏈
salesCloseAt選填停止售票時間(YYYY-MM-DDTHH:MM,台北牆鐘),到點自動把售票中改為已關閉;null 表示清空、退回繼承行程的「出發前 N 天」預設
salesOpenAt選填開賣時間(YYYY-MM-DDTHH:MM,台北牆鐘),到點自動把已關閉改為售票中;只有已關閉的梯次可設,須晚於現在、早於停止售票時間。null 表示取消排程
meetingTime選填集合時間(HH:mm,台北牆鐘),null 表示清空、退回繼承行程層預設
meetingPlace選填集合地點,null 表示清空、退回繼承行程層預設
agreementChangeDays選填可變更第三人期限(出發前 N 日,對應契約「旅客之變更權」條),null 表示退回租戶預設
entryDateOffsetDays選填實際入園日相對出發日的偏移天數(入園日 = 出發日 + N);改動會重算公式產生的關鍵日期
lotteryLeadDays選填抽籤日在出發日前幾天的逐梯覆寫(1–365),null 表示退回繼承行程的 lotteryLeadDays;改動會重算公式產生的關鍵日期
lotteryDrawTime選填抽籤時刻的逐梯覆寫(HH:MM,台北時間);省略或 null = 繼承行程的 lotteryDrawTime。抽籤時程表上有這梯的時段開始時,時段開始優先
requiredGuideCount選填需要的隨團人員數(主要+協同合計,0–99;0 = 不需嚮導),null 表示清空成未填。已確認指派數少於此值時,團控缺件列「隨團人員不足」
label選填梯次標籤/副標(最多 30 字),null 表示清空
isPrivate選填不對外販售:true 前台不顯示、客人不可自助報名(後台仍可建單);false 恢復對外
allocationMode選填fcfslottery分配模式(fcfs 先到先得/lottery 抽籤),null 表示退回繼承行程的 defaultAllocationMode。lottery 需抽籤模組
回應欄位 · data
ok操作成功旗標,恆為 true。
retentionDeferredtrue = 回訪來源尚未同步,每日排程會補做;梯次本身已更新。
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
/api/v1/trips/departures/{departureId}/group-code參數
departureId路徑要覆寫團號的梯次 ID
groupCode必填完整團號(自動轉大寫)。格式依租戶團號樣板驗證;未設樣板時為 YY+地區+[航空]+MMDD+序號(如 26EGTK1010A)
回應欄位 · data
ok操作成功旗標,恆為 true。
groupCode設定後的團號。
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
/api/v1/trips/departures/{departureId}/group-code/generate參數
departureId路徑要產生團號的梯次 ID
regionCode必填地區碼,2–8 碼大寫英數(自動轉大寫)
airlineCode選填航空碼(選填),2–8 碼大寫英數;國內團留空省略航空段
departureDate必填出發日期(ISO 格式 YYYY-MM-DD,取 MMDD 組成團號)
回應欄位 · data
groupCode自動產生的團號。
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
/api/v1/trips/departures/{departureId}/status參數
departureId路徑梯次 ID(路徑參數)
status必填sellingclosedcancelledcompleted目標梯次狀態(selling 銷售中/closed 關閉/cancelled 取消/completed 完成)
回應欄位 · data
ok操作成功旗標,恆為 true。
retentionDeferredtrue = 回訪來源尚未同步,每日排程會補做;梯次狀態本身已變更。
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
}
}匯出行程
/api/v1/trips/export參數
status選填依行程狀態篩選(draft 草稿/published 上架/archived 封存)
q選填自由文字搜尋(行程標題/代稱/目的地)
groupCode選填依團號篩選,匯出含該團號梯次的行程
回應欄位 · data
rows匯出的行程列(套用相同 filter,無分頁)。
id行程 id(trip_ 前綴)。
slug行程網址 slug。
title行程標題。
destination目的地名稱。
durationDays天數。
guideStartDay選填guideEndDay選填priceFromTwd「NT$ X 起」起價(TWD 整數)。
status上架狀態:draft 草稿 / published 已上架 / archived 封存。
isHidden不對外顯示(#1435)。
isLinkOnly僅限連結:不進任何列表,行程頁不給搜尋引擎收錄,拿到網址可報名。與 `isHidden` 互斥。
foreignTravelersOnly限外籍旅客(issue 1519)。
updatedAt最後更新時間。
isClimbing是否登山團(行程層模組旗標)。
isOverseas是否海外團(行程層模組旗標)。
hasPreTripNight是否有行前集合夜(trips.md §3)。
activeDepartureCountCount of departures with status='selling'.
nextDepartureDateEarliest selling departure_date, ISO date string, or null.
representativeGroupCode代表團號(group-code §8.2):最新一筆有團號的梯次;無則 null(UI 顯示 —)。
total匯出總筆數。
truncated是否因上限被截斷(此端點回全列,恆為 false)。
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:上傳檔
/api/v1/trips/import參數
filename必填上傳檔名,副檔名須為 .xlsx 或 .csv
contentBase64必填檔案內容的 base64 編碼字串(上限 5 MB)
回應欄位 · data
filename已匯入的檔名。
result匯入結果(建檔筆數與逐列結果)。
importBatchId本次匯入批次 id(imp_ 前綴),供稽核追溯。
createdTripCount新建行程數。
createdDepartureCount新建梯次數。
skippedCount略過列數(重複/無需匯入)。
errorCount失敗列數。
results逐列匯入結果。
rowNumber試算表列號(含表頭列,資料第一列為 2)。
status該列匯入結果:new_trip / append_departure / skip / error。
messageerror / skip 的人話原因(繁中);成功列為空。
tripId選填建出的 trip id(new_trip 成功時)。
departureId選填建出的 departure id(new_trip / append_departure 成功時)。
groupCode選填產生的團號(有地區碼時;航空碼選填)。
incompleteTrips本批**新建**行程中,關鍵設定仍為空者(#461)。漏填的三組全是靜默失效(難度分留空 → 審核器不作用;階梯未覆寫 → 套租戶預設那組;訂金不收),結果頁列出並附編輯連結。 只列有缺的行程;補梯次的既有行程不列(匯入不動它的設定)。
tripIdslugtitlemissing仍為空的關鍵設定(至少一項)。
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:上傳檔
/api/v1/trips/import/validate參數
filename必填上傳檔名,副檔名須為 .xlsx 或 .csv
contentBase64必填檔案內容的 base64 編碼字串(上限 5 MB)
回應欄位 · data
filename已驗證的檔名。
result試算(dry-run)結果(逐列預覽 + 彙總,不寫入)。
rows逐列預覽結果。
rowNumber試算表列號(含表頭列,資料第一列為 2)。
status該列匯入判定:new_trip 新建行程 / append_departure 附加梯次 / skip 略過 / error 錯誤。
messageerror / skip 的人話原因(繁中);new_trip / append_departure 為空。
parsed解析後的欄位值。
slugtitlesummarydestinationdurationDaysisClimbingisOverseashasPreTripNight行前集合夜三態;null = 留空(繼承既有行程)。見 {@link ImportedCell}。
gradeScore登山難度評鑑分數(0–100,可小數)。
requiresAlpineExperience是否需具備高山經驗(是/否)。
lotteryLeadDays30 / 60 / 120 依租戶預設產生階梯;海外使用個別契約範本。
overseasIndividualCancellation選填明示套用海外個別契約範本;留空不套用。
depositMode訂金方式(不收 / 固定金額 / 比例)。
depositAmountTwd訂金金額(TWD 正整數;方式=固定金額時必填)。
depositPercent訂金比例(1–100;方式=比例時必填)。
departureDatereturnDatepriceTwdcapacity留空 = null(補梯次時沿用行程的預設名額);非整數 → 'invalid'。
noteslabel梯次標籤 / 副標(issue 509 ①;例:「包」「包1」);留空 = null。
isPrivate不對外販售(issue 509 ①)。留空 = 否;填了無法辨識的值 → 'invalid'(dry-run error)。
allocationMode分配模式(issue 511)。留空 = 繼承母行程的預設分配模式(createDeparture copy-on-create); 填了無法辨識的值 → 'invalid'(dry-run error);抽籤但平台未啟用抽籤模組 → error。
regionCodeairlineCodeagencyPriceTwd同業價(TWD 整數 ≥ 0);留空 = 退回常規定價鏈。
departureDepositMode梯次訂金方式覆寫;留空 = 繼承行程的訂金設定。
departureDepositAmountTwd梯次訂金金額(方式=固定金額時必填)。
departureDepositPercent梯次訂金比例(方式=比例時必填,1–100)。
salesCloseAt逐梯停止售票時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘);只填日期 = 當天 00:00;留空 = 繼承行程層。
salesOpenAt開賣時間 `'YYYY-MM-DDTHH:MM'`(台北牆鐘,issue 1643);解析同停止售票日。有值時梯次建成 已關閉,排程到點開賣;留空 = 照舊。
meetingTime集合時間 `HH:mm`(台北牆鐘);留空 = 讀取時繼承行程層。
meetingPlace集合地點(≤ 200 字);留空 = 讀取時繼承行程層。
agreementChangeDays可變更第三人期限(出發前 N 日,0–365);留空 = 免抽籤梯次用租戶預設,團體契約的抽籤梯次缺值不產生契約,個別契約不適用。
entryDateOffsetDays實際入園日偏移(入園日 = 出發日 + N,0–行程天數−1);留空 = 0。
requiredGuideCount需要的隨團人員數(1–99,issue 1117);留空 = 未填,成團時再依行程比例帶入。
promoPriceTwd促銷直客價(TWD 正整數);有值 = 啟用梯次促銷;留空 = 不促銷。
promoAgencyPriceTwd促銷同業價(TWD 正整數);須搭配促銷直客價;留空 = 同業不參與促銷。
opAssignee承辦(issue 1102):後台帳號 Email,或唯一對到帳號的姓名;原樣保留,比對在 resolveRows。 留空 = 不掛承辦。補梯次列與「梯次已存在」的列也套用。
existingTripDefaultAllocationMode選填該 slug 在 DB 已有行程時,其 `default_allocation_mode`(issue 511):預覽對留空的補梯次列 印出「繼承後會落成什麼」用。slug 在 DB 不存在 → null。
warnings建完後擋開賣的缺項(#613 2026-10-20)。只提醒、不擋建檔;只有會建檔的列 (new_trip / append_departure)才有。判準見 {@link importRowWarnings}。
codemessagesummary各狀態列數彙總。
totalRows資料列總數。
newTripCount判定為「新建行程」的列數。
appendDepartureCount判定為「附加梯次到既有行程」的列數。
skipCount略過列數。
errorCount有錯誤的列數。
unsellableCount會建檔、但建完後開賣會被擋的梯次數(至少一則 warning 的列)。
fileError整檔層級的致命錯誤(如超列上限、空檔、無法解析),非空時 rows 為空。
columns表頭各欄的辨識結果(issue 613):認成哪個欄位、認不得的欄、重複或不匯入的欄。 預覽據此列出欄位對應,讓使用者用下拉指定。讀不到表頭列(壞檔、空檔)時為空陣列; 「找不到可辨識的表頭欄位」時仍帶回整列,使用者才能當場指定。
index在表頭列中的第幾格(0-based)。
header原始標題(trim 後)。
key洗過的標題(記憶對應的 key);空標題為 `''`(記不起來、沒有下拉)。
target辨識結果:欄位、`'ignore'`(不匯入),或 `null`(認不得)。
source`alias` = 別名表;`memory` = 租戶記憶對應;`null` = 認不得或空標題。
writes真正讀進哪個欄位;`null` = 這一欄不匯入(原因在 `note`)。
note選填不匯入的原因(預覽的欄位對應表顯示)。
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
同業
/api/v1/agencies參數
status選填activearchived同業狀態篩選(active 啟用中/archived 已封存;省略為全部)
owner選填負責業務篩選(傳明確使用者 ID;none=只列尚未指派負責業務者;all 或省略=全部)
hasTaxId選填yesno是否有統一編號篩選(yes 僅列有統編者/no 僅列無統編者)
回應欄位 · data[]
id同業 id(前綴 `agc_`)。
name同業公司名 / 個人團主名稱。
taxId統一編號(個人團主可留空)。
contactName主要聯絡人姓名(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
address公司地址(未填 → null)。
paymentTerm帳期 / 結算方式(自由文字,例:'月結 30 天')。
paymentDueRuleownerUserId負責業務 user id(NULL = 未指派)。
ownerName負責業務顯示名;未指派為 null。
status同業狀態:active 啟用中 / archived 已封存。
note內部備註(未填 → null)。
orderCount累計訂單數(COUNT orders WHERE agency_id = id)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/agencies參數
name必填同業公司名稱(B2B 旅行社或個人團主名稱)
taxId選填統一編號(選填)
contactName選填主要聯絡人姓名(選填)
phone選填聯絡電話(選填)
email選填聯絡 Email(選填;留空字串視為未填)
address選填公司地址(選填)
paymentTerm選填付款條件/帳期約定(選填,如月結 30 天)
ownerUserId選填指派的負責業務使用者 ID(選填)
status選填activearchived同業狀態(active 啟用中/archived 已封存;預設 active)
note選填內部備註(選填)
回應欄位 · data
id新建立同業的 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": "…"
}
}單一同業完整資料
/api/v1/agencies/{id}參數
id路徑同業 ID
回應欄位 · data
id同業 id(前綴 `agc_`)。
name同業公司名 / 個人團主名稱。
taxId統一編號(個人團主可留空)。
contactName主要聯絡人姓名(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
address公司地址(未填 → null)。
paymentTerm帳期 / 結算方式(自由文字,例:'月結 30 天')。
paymentDueRuleownerUserId負責業務 user id(NULL = 未指派)。
ownerName負責業務顯示名;未指派為 null。
status同業狀態:active 啟用中 / archived 已封存。
note內部備註(未填 → null)。
orderCount累計訂單數(COUNT orders WHERE agency_id = id)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
}/api/v1/agencies/{id}參數
id路徑要更新的同業 ID
name選填同業公司名稱(省略則不更動)
taxId選填統一編號(省略則不更動)
contactName選填主要聯絡人姓名(省略則不更動)
phone選填聯絡電話(省略則不更動)
email選填聯絡 Email(省略則不更動;空字串視為清空)
address選填公司地址(省略則不更動)
paymentTerm選填付款條件/帳期約定(省略則不更動)
ownerUserId選填指派的負責業務使用者 ID(省略則不更動)
status選填activearchived同業狀態(active 啟用中/archived 已封存;省略則不更動)
note選填內部備註(省略則不更動)
回應欄位 · data
ok固定為 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
}
}上下架同業
/api/v1/agencies/{id}/status參數
id路徑同業 ID
status必填activearchived目標狀態(active 上架啟用/archived 下架封存)
回應欄位 · data
ok固定為 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
}
}負責業務指派候選清單
/api/v1/agencies/assignable-staff回應欄位 · data[]
userId員工使用者 id(可作為負責業務指派的 ownerUserId)。
name員工顯示名。
role角色代碼(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": "…"
}
]
}同業名單匯出
/api/v1/agencies/export參數
status選填activearchived同業狀態篩選(active 啟用中/archived 已封存;省略為全部)
owner選填負責業務篩選(傳明確使用者 ID;none=只列尚未指派負責業務者;all 或省略=全部)
hasTaxId選填yesno是否有統一編號篩選(yes 僅列有統編者/no 僅列無統編者)
回應欄位 · data
rows同業匯出資料列(依 owner 篩選後的全表快照,供試算表匯出)。
id同業 id(前綴 `agc_`)。
name同業公司名 / 個人團主名稱。
taxId統一編號(個人團主可留空)。
contactName主要聯絡人姓名(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
address公司地址(未填 → null)。
paymentTerm帳期 / 結算方式(自由文字,例:'月結 30 天')。
paymentDueRuleownerUserId負責業務 user id(NULL = 未指派)。
ownerName負責業務顯示名;未指派為 null。
status同業狀態:active 啟用中 / archived 已封存。
note內部備註(未填 → null)。
orderCount累計訂單數(COUNT orders WHERE agency_id = id)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}
}/consent-templates
list every consent-document template version
/api/v1/consent-templates參數
kind選填同意書類別代碼,指定時僅列出該類別的範本版本
回應欄位 · data[]
id同意書範本 id(前綴 `ct_`)。同一 kind 每個版本各有一個 id。
kind同意書類型:系統種類 pdpa(個資)/ tour_agreement(旅遊契約)/ cancellation_policy / refund_policy,或自訂種類的 `consent_kinds.id`(`cnsk_…`)。
agreementType旅遊契約的種類(觀光署四種之一)。非旅遊契約恆 null;`tour_agreement` 為 null = #585 之前建的未分類舊範本,選範本時選不到。
version版本號,同一 kind(旅遊契約則是同一 kind + 種類)從 1 遞增;append-only,編輯即新增下一版。
contentMdx範本內容(MDX 原始碼),可含 {{...}} merge 變數。
effectiveFrom此版本生效起始時間。
createdAt此版本建立時間。
signatureCount引用此版本的已簽署份數(COUNT consent_signatures)。
retiredsigningFieldsbalancePaymentMethodrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
emergencyContactRelationrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article30Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article32Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
guardianrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
electronicSigningConsentrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
curl -X GET "https://your-tenant.example.com/api/v1/consent-templates" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": [
{
"id": "…",
"kind": "…",
"agreementType": "domestic_individual",
"version": 0,
"contentMdx": "…",
"effectiveFrom": "…",
"createdAt": "…",
"signatureCount": 0,
"retired": true,
"signingFields": {
"balancePaymentMethod": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"emergencyContactRelation": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"article30Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"article32Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"guardian": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"electronicSigningConsent": {
"required": true,
"options": [
"agree"
],
"hidden": true
}
}
}
]
}/api/v1/consent-templates參數
signingFields選填此版本的簽署欄位規則
kind必填同意書類別代碼:系統種類(pdpa / tour_agreement / cancellation_policy / refund_policy)或租戶自訂種類的 id(cnsk_ 開頭)
contentMdx必填同意書內文(MDX 格式),即此版本的條款全文
agreementType選填domestic_individualdomestic_groupoverseas_individualoverseas_group旅遊契約種類(國內/國外 × 個別/團體),kind 為 tour_agreement 時必填
回應欄位 · data
id新建立同意書範本的 ID。
version範本版本號(每次發布遞增,簽署時綁定當下版本)。
curl -X POST "https://your-tenant.example.com/api/v1/consent-templates" \
-H "Authorization: Bearer $TOKO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"kind": "example-kind",
"contentMdx": "example-contentMdx"
}'{
"ok": true,
"data": {
"id": "…",
"version": 0
}
}a single consent-template version
/api/v1/consent-templates/{id}參數
id路徑同意書範本版本的 ID
回應欄位 · data
id同意書範本 id(前綴 `ct_`)。同一 kind 每個版本各有一個 id。
kind同意書類型:系統種類 pdpa(個資)/ tour_agreement(旅遊契約)/ cancellation_policy / refund_policy,或自訂種類的 `consent_kinds.id`(`cnsk_…`)。
agreementType旅遊契約的種類(觀光署四種之一)。非旅遊契約恆 null;`tour_agreement` 為 null = #585 之前建的未分類舊範本,選範本時選不到。
version版本號,同一 kind(旅遊契約則是同一 kind + 種類)從 1 遞增;append-only,編輯即新增下一版。
contentMdx範本內容(MDX 原始碼),可含 {{...}} merge 變數。
effectiveFrom此版本生效起始時間。
createdAt此版本建立時間。
signatureCount引用此版本的已簽署份數(COUNT consent_signatures)。
retiredsigningFieldsbalancePaymentMethodrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
emergencyContactRelationrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article30Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
article32Agreedrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
guardianrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
electronicSigningConsentrequiredoptionshidden選填true = 簽署頁不顯示此欄,旅客也不能作答。舊版本沒有此欄,視同 false。
curl -X GET "https://your-tenant.example.com/api/v1/consent-templates/<id>" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"id": "…",
"kind": "…",
"agreementType": "domestic_individual",
"version": 0,
"contentMdx": "…",
"effectiveFrom": "…",
"createdAt": "…",
"signatureCount": 0,
"retired": true,
"signingFields": {
"balancePaymentMethod": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"emergencyContactRelation": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"article30Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"article32Agreed": {
"required": true,
"options": [
"agree"
],
"hidden": true
},
"guardian": {
"required": true,
"options": [
"…"
],
"hidden": true
},
"electronicSigningConsent": {
"required": true,
"options": [
"agree"
],
"hidden": true
}
}
}
}/api/v1/consent-templates/{id}參數
id路徑同意書範本版本的 ID
回應欄位 · data
retiredcurl -X DELETE "https://your-tenant.example.com/api/v1/consent-templates/<id>" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"retired": true
}
}/members
list/search the tenant customer
/api/v1/members參數
q選填關鍵字,模糊比對會員姓名、Email 或電話
county選填縣市篩選,僅回傳通訊地址在該縣市的會員
year選填加入年份(西元四位數),僅回傳該年註冊的會員
page選填分頁頁碼,從 1 起算,預設第 1 頁
pageSize選填每頁筆數,上限 200,預設由後端決定
回應欄位 · data
rows當前頁的會員列。
userId會員(顧客)的 user id。
email會員 Email(登入帳號)。
name會員姓名。
createdAt會員註冊時間。
phone聯絡電話(未填 → null)。
address通訊地址(未填 → null)。
birthDate生日 YYYY-MM-DD(未填 → null)。
orderCount累計訂單數(含所有狀態與 kind)。
paidOrderCount成交訂單數(未取消,且已付清或已完成)。
totalSpent累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。
lastOrderAt最後一筆訂單建立時間(無訂單 → null)。
pdpaSignedAt最新版 PDPA 同意書簽署時間(未簽 → null)。
anonymizedAtPDPA 匿名化時間;非空 = 已匿名化。
createdByUserId後台代建者 user id(member-admin-create);null = 客戶自助註冊。
createdByName代建者姓名(join `user`);自助註冊 → null。
total符合篩選的會員總數。
page當前頁碼(從 1 起算)。
pageSize每頁筆數。
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
}
}/api/v1/members參數
email必填會員登入 Email,也是啟用信的收件地址
name必填會員姓名
phone選填聯絡電話(選填)
回應欄位 · data
userId新建會員的使用者 ID。
email正規化(小寫)後的登入 Email。
name會員姓名。
activationSent啟用信是否已送出請求;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
/api/v1/members/{id}參數
id路徑會員(顧客)的使用者 ID
回應欄位 · data
profile會員基本資料 + 訂單彙整。
userId會員(顧客)的 user id。
email會員 Email(登入帳號)。
name會員姓名。
createdAt會員註冊時間。
phone聯絡電話(未填 → null)。
address通訊地址(未填 → null)。
birthDate生日 YYYY-MM-DD(未填 → null)。
orderCount累計訂單數(含所有狀態與 kind)。
paidOrderCount成交訂單數(未取消,且已付清或已完成)。
totalSpent累計消費(實收現金淨額 = 收款 − 已退款,含取消單留下的退改費,TWD 整數)。
lastOrderAt最後一筆訂單建立時間(無訂單 → null)。
pdpaSignedAt最新版 PDPA 同意書簽署時間(未簽 → null)。
anonymizedAtPDPA 匿名化時間;非空 = 已匿名化。
createdByUserId後台代建者 user id(member-admin-create);null = 客戶自助註冊。
createdByName代建者姓名(join `user`);自助註冊 → null。
orders近期訂單列表(上限 50 筆,含 lodging)。
id訂單 id。
orderNumber人類可讀訂單編號。
status金流模型 v2:deriveOrderDisplayStatus(booking/payment/refund) 派生的單一顯示狀態。
total該會員所有訂單的應收總額(TWD 整數)。
createdAt訂單建立時間。
tripTitle行程 / 產品標題。
consents已簽署的同意書紀錄(上限 50 筆)。
id簽署紀錄 id。
kind同意書類型:系統種類(pdpa / tour_agreement / cancellation_policy / refund_policy) 或租戶自訂種類的 id(`cnsk_…`)。
kindLabel自訂種類的名稱;系統種類為 null。
travelerName代簽時被代簽旅客的姓名(逐旅客的自訂同意書);本人簽署為 null。
version簽署當下的範本版本號。
signedAt簽署時間。
ipAddress簽署時來源 IP(未記錄 → null)。
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
/api/v1/members/{id}/anonymize參數
id路徑欲匿名化的會員(顧客)使用者 ID
reason選填匿名化原因,記入稽核紀錄備查
回應欄位 · data
ok固定為 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 綁到會員
/api/v1/members/{id}/line-user-id參數
id路徑會員(顧客)使用者 ID
lineUserId必填LINE userId:U 開頭加 32 碼小寫十六進位
回應欄位 · data
okcurl -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
}
}解除綁定
/api/v1/members/{id}/line-user-id參數
id路徑會員(顧客)使用者 ID
回應欄位 · data
okcurl -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 完整比對會員
/api/v1/members/by-line-user-id參數
lineUserId必填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
/api/v1/members/expiry-warnings參數
ids必填以逗號分隔的會員使用者 ID 批次,上限 200 個,回傳其中護照即將到期者
回應欄位 · data
userIds證件即將到期(或已過期)需提醒的會員 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 的完整比對
/api/v1/members/lookup參數
email必填訂購人 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": "…"
}K 單訂購人 typeahead:以 name / email ILIKE 找已註冊會員
/api/v1/members/search參數
q必填關鍵字,模糊比對會員姓名或 Email
回應欄位 · data[]
userIdnameemailphonelineIdlineDisplayNameorderCountcurl -X GET "https://your-tenant.example.com/api/v1/members/search?q=example-q" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": [
{
"userId": "…",
"name": "…",
"email": "…",
"phone": "…",
"lineId": "…",
"lineDisplayName": "…",
"orderCount": 0
}
]
}member directory KPI cards
/api/v1/members/stats回應欄位 · data
totalMembers會員(顧客)總數(排除員工帳號)。
newThisMonth本月新增會員數(自助 + 代建)。
newThisMonthStaffCreated本月新增中由後台代建的數量(member-admin-create §4)。
staffCreated累計由後台代建的會員數(`member_profiles.created_by_user_id IS NOT NULL`)。
withOrders有下過訂單的會員數。
averageOrders平均訂單數(只計有訂單者,避免零訂單稀釋)。
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
/api/v1/orders參數
status選填依訂單顯示狀態篩選(如 pending、paid、cancelled)
assignment選填依派發狀態篩選(如 unassigned、assigned)
rooming選填依分房狀態篩選
dateFrom選填出發日期區間起(格式 YYYY-MM-DD,含當日)
dateTo選填出發日期區間迄(格式 YYYY-MM-DD,含當日)
q選填關鍵字搜尋(訂單編號、訂購人姓名或 Email 等)
agencyId選填依合作旅行社 ID 篩選(同業單)
page選填頁碼,從 1 起算,預設第 1 頁
pageSize選填每頁筆數,上限 200
回應欄位 · data
rows當前頁的訂單列(每筆商品明細一列)。
kindid訂單 id(前綴 `ord_`)。
orderNumber人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。
bookingState預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。
paymentState付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。
refundState退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。
grossReceivableTwd應收(TWD 整數,派生自應收分類帳)。
collectedTwd收到現金(TWD 整數,派生)。
customerCashAppliedTwd客戶現金淨套用(收款減已退現金,TWD 整數,派生)。
refundableCashTwd可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。
outstandingTwd未收(應收減客戶現金淨套用,TWD 整數,派生)。
partySize參團人數(tour 訂單)。
createdAt訂單建立時間。
notes訂單備註(未填 → null)。
userId下單客戶的 user id(同庫 user 表)。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名(is_primary,未登記 → null)。
primaryTravelerPhone主要旅客電話(未登記 → null)。
tripId行程 id(tour 訂單經梯次反查;lodging 為空字串)。
tripTitle行程 / 產品標題。
tripShortName行程內部簡稱(issue 1414);未填或訂房訂單為 null。
tripSlug行程 slug。
departureId梯次 id(tour 訂單;lodging 為空字串)。
departureDate出發日 YYYY-MM-DD(lodging 為入住日)。
returnDate回程日 YYYY-MM-DD(lodging 為退房日)。
assignedToUserId派發給哪位業務的 user id(未派發 → null)。
assigneeName承辦業務顯示名(未派發 / 查無 → null)。
assignmentStatus派發狀態:unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間(未派發 → null)。
assignedByUserId執行派發者的 user id(未派發 → null)。
createdByUserIdS5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.
pendingConsent是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。
roomingStatus分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。
failoverFromOrderId備案訂單所對應的原訂單 ID。
isOverdue是否有已到期、尚未收齊的收款計畫。
total符合篩選的訂單總數(DISTINCT 訂單,非列數)。
page當前頁碼(從 1 起算)。
pageSize每頁筆數。
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 訂單
/api/v1/orders參數
tripId必填行程 ID
departureId必填梯次 ID,決定佔位的出發團
primaryEmail必填訂購人 Email,須對應已註冊會員
partySize必填報名人數,決定佔位數,須為 1 至 20 之間整數
travelers必填旅客名單,筆數須與報名人數一致。每筆至少要有 fullName,一般後台證件可後補;受管制抽籤需 idNumber 或 passportNo,受限名額需 idNumber;birthDate 若給值須為存在的 YYYY-MM-DD 日期;climbingRecords 可代填該旅客的登山經歷(label 必填、gradeScore 0–20 僅存參考且不計分、climbedOn YYYY-MM-DD、hasAlpineExperience;每位最多 20 筆),掛在該旅客本人身上、不掛帳號,須啟用登山模組,否則回 403
paymentMethod必填cashatmmanual收款方式:cash 現金、atm 轉帳、manual 人工
customerType選填directagency客戶類型:direct 直客、agency 同業,預設直客
agencyId選填同業 ID(agc_ 前綴),把這張單掛到該同業。只在 customerType=agency 時接受;須為啟用中的同業,否則回 422
paymentPlan選填fulldeposit付款方案:full 全額、deposit 訂金,預設全額
receivingAccountId選填收款帳戶 ID,指定本筆款項入帳的帳戶
discountCode選填優惠碼;由建單流程驗證並套用折扣,無效時拒絕建單
notes選填訂單備註
assigneeUserId選填指定業績歸屬業務的使用者 ID,省略或等於自己則歸屬建單者;指定他人需具備訂單指派權限
allowDomesticTravelers選填行程限外籍旅客時仍要建立:true 放行國籍空白或台灣的旅客,並留稽核紀錄。省略時這類旅客回 422
回應欄位 · data
orderId新建立訂單的 ID(ord_ 前綴)。
orderNumber訂單編號(租戶內流水序號,對外顯示用)。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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
/api/v1/orders/{id}參數
id路徑訂單 ID
回應欄位 · data
participationVersiondepartureChangesidparticipationVersionactorNamereasoncreatedAtsnapshotdocumentsagreementEnabledversioningReadyagreementCountagreementPendingagreementHistoryconsentslabelversionpendingretainedduepassportExpiryWarningsfingerprintcrossTrip選填sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdepartureprice_twdagency_price_twddeposit_modedeposit_amount_twddeposit_percentpromo_activepromo_price_twdpromo_agency_price_twdtripdirect_price_twdagency_price_twdprice_from_twddeposit_modedeposit_amount_twddeposit_percentdeposit_basisschema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。
unitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
basisstepN:每幾位旅客 / 每滿幾元。
unitTwd每次折多少(碼的折扣值)。
units折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valueselfService選填repricingThe target fare at its current price. Same shape as a cross-trip quote, without answers.
sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdeparturetripunitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valuefeetierdaysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
amountTwddescriptioncharge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。
surplusremitFeeTwdlottery選填sourceModetargetModestateBeforestateAfter`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.
placement選填failover選填Set when the backup failover made the change. A general target confirms the seat (`won`).
skippedBackup choices that the failover skipped before this one.
rankdepartureIdreasonhitRankRank of the backup choice that this step tries.
remainingDepartureIdsBackup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.
applicationKeyBeforeapplicationId選填Set on confirmation: the new application uses the departure change ID.
legacyChain選填effectiveCreditTwd選填policyTotalTwd選填refundDrafts選填participationVersionequipmentblockedrentalsrentalIdrentalCodedepartureIdrentStartDaterentEndDatereturnStatereconStatedeliveredAtdepositClearedAtrentTotalTwddepositTotalTwddepositBalanceTwddeprecated · 下一個版本移除replacesRentalIdreadyblockerlinesitemIdnamequantitycommittedQuantitypaymentWindowStartedAt選填sourceFingerprintrosterFingerprintsourceidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percenttargetidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percentarrangements選填roomFeeBeforeTwdroomFeeAfterTwdotherRoomOrderCountotherRoomFeeDeltaTwdotherRefundDraftTwdreleasedRoomCountreleasedPretripStayCounttaskstravelerIdkindlabelfingerprinttotalTwdunitPriceTwddiscountTwdchargeLinesidtypeamount_twddescriptiondepositTwdbalanceTwdbalanceDueAtreceiptsblockedreceiptsidmerchantOrderNostatusinvoiceNumberinvoiceTransNosubmittedoperationPendinglastErrortourNametourNotourDatetotalAmtTwdupdatedAtresolutiontargettourNametourNotourDatetotalAmtTwdcollectedTwdreturnedTwdpaidRefundFeesTwdcustomerCashAppliedTwdoutstandingTwdrefundHeadroomgrossReceivableTwd當前應收。
refundableCashTwd可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。
assessedCancellationFeeTwd此實收單保留的退改費;舊資料沿用人工核算基準。
openRefundGrossTwd同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。
openRefundCount同單其他未執行退款的張數。
openReceivableReductionTwd同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。
carriedToLiveBackupsTwd已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。
assessmentPending人工核算單、退改費尚未核算。
baseTwd額度基準 = 可退現金 − 上面三項扣減,下限 0。
overpaymentRefundTwddepositOutstandingTwdnextPaymentPurposenextPaymentTwdmoneyFingerprintrefundDraftId選填legacyChaincollectedTwdreturnedTwdpaidRefundFeesTwdeffectiveCreditTwdrefundableTwdopenRefundCountnodesorderIdorderNumbercollectedTwdreturnedTwdopenRefundCountarrangementsCurrent arrangement tasks after a departure change. Null means this order has no departure change.
departureIdtaskstravelerIdkindlabelactions訂單可行動作。每個動作是 `{ ok: true }`(部分動作另帶欄位,例:`cancel.path`、 `createRefund.headroom`)或 `{ ok: false, reason }`。`reason` 沿用對應寫入端點的 原因碼;`forbidden` 表示呼叫者沒有該動作的權限。
cancel`cancelOrder` / `cancelLodgingBooking` / `cancelFailoverChildOrder` / `cancelLotteryLostOrder`(依 `path`)。`lottery_lost` 的權限是 lottery.manage 加抽籤模組。
transferDepartureGeneral departure change with completed payment records. The selected target is checked during preview and confirmation.
adjust掛帳 / 折讓 / 沖正(`applyManualAdjustment` / `reverseChargeLine`)。
editTravelers旅客新增 / 編輯 / 移除(`addTraveler` / `updateTraveler` / `removeTraveler`)。名單凍結中 回 `EDIT_WINDOW_CLOSED` 加 `rosterFreezeUnlockable: true`(見 `TravelerEditAvailability`)。
editRooming分房需求登記(`updateRoomingPreference`)。
markPaid手動登記收款(`markOrderManuallyPaid`)。`settled`:寫入端回冪等成功、不入帳。
balancePayment補尾款連結 / 繳款單(`prepareBalancePayment`,可收分期的 `balance_link` 收款入口)。
balanceSlip寄尾款繳款單(`sendBalanceSlipInTx`,可收分期的 `balance_slip` 收款入口)。訂金制同 `balancePayment`,全額單收全額列的餘額(issue 1522)。
payLink自填金額付款連結(`issueOrderPayLink`,可收分期的 `pay_link` 收款入口,issue 1487)。已付訂金時同 `balancePayment`; 訂金未付時掛目前這一期,`remainingTwd` 是這一期的餘額。
createRefund建立退款。只看權限;金額上限與「為何是 0」在 `headroom`(`describeNoHeadroom`), 與建立 / 送審 / 標記已付三道 guard 讀同一份可退額度。
splitTraveler拆出旅客(`splitTraveler`)。`otherDepartures`:能不能拆到別梯;整單不能換梯時只能同梯另開單。 名單凍結時拆到別梯要帶 `acknowledgeRosterFreeze: true`(見 `editTravelers.rosterFreezeUnlockable`)。旅客、款項與目標梯次的資格在寫入端鎖內重驗。
heldCashTransfer用保留款折抵,本單是轉入目標(`transferHeldCash`)。來源單在寫入端鎖內重驗。
reduceReceivable直接減少應收:折讓、沖正原始應收、跨行程換梯的負數調整(`assertDirectAdjustmentAllowed`)。 「折讓必須經核准」開啟時,沒有核准權的人回 `APPROVAL_REQUIRED`。
requestDiscount手動少收申請(`requestManualDiscount`)。
decideDiscount核准或拒絕手動少收申請(`decideManualDiscount`)。核准權與 `canApproveAllowance` 同一條。
requestFeeWaiver申請減免退改費(`requestCancellationFeeWaiver`,#1621)。權限同建立退款單。
decideFeeWaiver核准或拒絕退改費減免。核准權同少收申請(`canApproveAllowance`+order.adjust)。
revokeReceipt撤銷或申請撤銷人工收款(`revokeManualReceipt` / `requestManualReceiptRevocation`)。只看權限, 不看這張單有沒有人工收款登記;逐筆的撤銷條件在寫入端。
submitRefund退款草稿送審(`submitRefund`)。退款單本身的狀態閘在寫入端。
cancelRefund退款草稿作廢(`cancelRefund`)。
approveRefund核准退款(`approveRefund`)。
rejectRefund駁回退款(`rejectRefund`)。
markRefundPaid標記退款已付與綠界刷退(`markRefundPaid`)。
assign派發:待審派發單走首次派發(`assignOrder`,order.assign),其他單走重派 (`reassignOrder`,order.reassign)。
updateOrder訂單層的其他更新(order.update):解除實名占用、代登登山紀錄、護照、同意書、 重寄信件、跨行程換梯報價。
reviewScreening審核登山資格(screening.review)。
manageAgreement管理旅遊契約(tour_agreement.manage)。
viewAgreementEvidence檢視旅遊契約簽署證據(tour_agreement.evidence)。
revealPii顯示證號全碼、檢視護照影本(order.reveal_pii)。
readConversation讀訂單對話(order_conversation.read)。
kind訂單種類(kind-agnostic 外殼)。'tour' 用既有 tour 區塊(梯次/分房/登山審核); 'lodging' 隱藏 tour-only 區、改顯示住宿 header(見 `lodging`)。共用的金流/旅客/ 派發/同意書區塊兩者皆 order-scoped 通用。
id訂單 id(前綴 `ord_`)。
orderNumber人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。
bookingState預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。
paymentState付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。
refundState退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。
grossReceivableTwd應收(TWD 整數,派生自應收分類帳)。
collectedTwd收到現金(TWD 整數,派生)。
customerCashAppliedTwd客戶現金淨套用(收款減已退現金,TWD 整數,派生)。
refundableCashTwd可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。
outstandingTwd未收(應收減客戶現金淨套用,TWD 整數,派生)。
partySize參團人數(tour 訂單)。
createdAt訂單建立時間。
notes訂單備註(未填 → null)。
userId下單客戶的 user id(同庫 user 表)。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名(is_primary,未登記 → null)。
primaryTravelerPhone主要旅客電話(未登記 → null)。
tripId行程 id(tour 訂單經梯次反查;lodging 為空字串)。
tripTitle行程 / 產品標題。
tripShortName行程內部簡稱(issue 1414);未填或訂房訂單為 null。
tripSlug行程 slug。
departureId梯次 id(tour 訂單;lodging 為空字串)。
departureDate出發日 YYYY-MM-DD(lodging 為入住日)。
returnDate回程日 YYYY-MM-DD(lodging 為退房日)。
assignedToUserId派發給哪位業務的 user id(未派發 → null)。
assigneeName承辦業務顯示名(未派發 / 查無 → null)。
assignmentStatus派發狀態:unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間(未派發 → null)。
assignedByUserId執行派發者的 user id(未派發 → null)。
createdByUserIdS5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.
pendingConsent是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。
roomingStatus分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。
failoverFromOrderId備案訂單所對應的原訂單 ID。
isOverdue是否有已到期、尚未收齊的收款計畫。
cancellationFeeTwd取消時公司留下的錢:退改費加上已付、不退的換梯手續費(customer-cancellation §8.9)。 NULL = 尚未核算,0 = 已核算且扣 0;兩者不可互換。
cancellationChangeFeeTwd`cancellationFeeTwd` 裡屬於已付換梯手續費、不退的部分(customer-cancellation §8.9)。 退改費 = `cancellationFeeTwd` − 這筆。null = 沒有。
cancellationFeeWaivedTwd已核准的退改費減免合計(#1621)。`cancellationFeeTwd` 已是減免後的數字。0 = 沒有減免。
staffNote承辦備註(issue 1659,`orders.staff_note`)。只給後台;null = 沒有備註。
cancellationRefundPendingcancellationMoney取消單現金與未執行退款摘要。
openRefundCount未執行退款單張數。
openRefundAmountTwd未執行退款單的實際退款金額合計。
openRefundAdminFeesTwd未執行退款單的**行政手續費**合計(`refunds.admin_fee_twd`)。與匯款手續費分成兩欄,顯示面 才叫得出名字 —— 合併成一個「手續費」會把這筆行政費講成匯款費。
openRefundRemitFeesTwd未執行退款單的**匯款手續費**合計(`refunds.remit_fee_twd`;spec 稱轉帳費,§3.4)。
retainedCashTwd可退現金扣退改費;無未執行退款單且退改費已核算時,與保留款帳同口徑。
tripIsOverseas行程是否出國(`trips.is_overseas`;lodging 為 false)。旅客編輯器據此顯示英文姓名 / 國籍欄(#459)。
tripCancellationFeeTiers行程自己的退改階梯(`trips.cancellation_fee_tiers` 解析後);null = 未覆寫,沿用租戶預設。 實際生效的階梯由呼叫端用 `resolveFeeTiers` 合成,與取消時同一個優先順序。
agencyPaymentDueDate客戶分類:同業單(`orders.agency_id`)帶同業名稱;直客單為 null。
agencyidnamecontactName同業主檔的聯絡窗口(#1782)。訂單頁顯示「聯絡窗口」,訂購人不變。
phoneconsentConfirmed「同業已代為取得旅客同意」的勾選(#1479)。沒有勾選時為 null。
atbyNamedepartureLabel梯次標籤 / 副標(issue 509 ①;lodging 為 null)。訂單頁的「梯次」欄接在日期後顯示。
lodginglodging 住宿 header(房型/住期/房數/人數);tour 為 null。
propertyNamepropertySlugroomTypeNamecheckIn入住日 YYYY-MM-DD。
checkOut退房日 YYYY-MM-DD(不含當晚)。
unitsguestCounttravelers旅客名單(含 PII 遮罩欄;主要旅客排前)。
id旅客 id(前綴 `trv_`)。
fullName旅客姓名。
idNumberMask遮罩碼(jsonb→mask,零解密);NULL = 未填。全碼走 reveal action(Task 7)。
passportNoMask護照號碼遮罩碼(零解密);NULL = 未填。全碼走 order-scoped reveal。
birthDate生日 YYYY-MM-DD(未填 → null)。
phone聯絡電話(未填 → null)。
email聯絡 Email(未填 → null)。
lineIdLINE ID(未填 → null)。明文。
lineDisplayNameenglishName英文姓名(#459,海外團;未填 → null)。明文,已 normalize 大寫。
nationality國籍(#459,海外團;未填 → null)。明文。
passportExpiryDate護照效期(#609,海外團;未填 → null)`YYYY-MM-DD`。明文 date 欄。
emergencyContactName緊急聯絡人姓名(未填 → null)。
emergencyContactPhone緊急聯絡人電話(未填 → null)。
isPrimary是否為主要旅客(訂單聯絡人)。
gender性別(分房硬約束 + 顯示):'male'|'female'|'other'|null。明文。
roomPreference分房房型偏好(下單登記)。
roommatePref指定房友 / 特殊需求自由文字。
diet飲食需求(葷素)明文;null = 未填。非 PII,不走 reveal。
medicalNotes醫療 / 過敏 / 病史備註明文;null = 未填。非 PII,不走 reveal。
address通訊地址(未填 → null)。
roomLabel團控已排房號的房間 label(null = 待團控分房)。
chargeLines應收分類帳(itemized)。
id應收明細列 id。
type應收類型:base(原始價)/ room_upgrade(房升補款)/ adjustment / failover_deposit_credit 等。
amountTwd金額(TWD 整數,signed;credit / 沖銷為負)。
description明細說明文字。
sourceType來源:system(系統派生)/ manual(人工登錄)等。
reversesChargeLineId若為沖銷列,指向被沖銷的應收明細列 id(否則 null)。
createdByUserId開立這筆費用列的使用者 id;系統派生或匯入列為 null。
createdAt建立時間。
transactions現金分類帳。
id現金交易列 id。
direction金流方向:in(收款)/ out(退款、扣款、沖銷)。
type交易類型:payment / refund / chargeback / reversal。
amountTwd交易金額(TWD 整數,正值)。
feeTwd金流商手續費(TWD 整數)。
netTwd淨額 = amount − fee(TWD 整數)。
provider金流商:manual / ecpay / test 等。
providerTradeNo金流商交易序號(manual 入帳可能為 null)。
merchantTradeNoThe merchant order reference of this transaction's payment attempt.
moneyReceiptIdPublic receipt ID for a proven money-core binding. Unbound historical rows retain null.
refundId若屬退款,指向 refunds 列 id(否則 null)。
bankReference銀行參考號:手動收款是客人的匯款後五碼,退款是匯款憑證號(未填為 null)。
remittanceId同源匯款關聯鍵:這列來自一筆拆到多張訂單的匯款時非 null,同一筆匯款的各列共用同一個值。
registrationId登記收款的批次鍵(#1411):撤銷人工收款時,原收款與反向紀錄共用同一個值。
bankCreditedOn入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填,其他為 null。
overTheCounter臨櫃存款(沒有末五碼)。
receivingAccountName收款帳戶顯示名稱(未歸戶為 null)。
transferCounterpartOrderId保留款轉移(`type='transfer'`,issue 1407)的對方訂單:轉出列指向目標單,轉入列指向 來源單。其他列為 null。
transferCounterpartOrderNumber對方訂單編號(同上)。
transferActorName執行這次保留款轉移的員工名稱(取自稽核紀錄;其他列為 null)。
occurredAt交易發生時間。
schedules收款計畫(current + historical)。
id收款計畫列 id。
purpose用途:full(全額)/ deposit(訂金)/ balance(尾款)/ adjustment(補款)。
targetAmountTwd應收目標金額(TWD 整數)。
status計畫狀態:open(未收齊)/ satisfied(已收齊)。
appliedTwd已套用到此列的現金(H3 唯一基準 `appliedCashForSchedule`;含 replaces 鏈)。
dueAt到期日(null = 未設)。
sequence排序序號(deposit → balance → adjustment)。
intents付款意圖(+ 最新 attempt)。
idpurposeamountTwdstatusscheduleIdinvalidationReasonReason for closing this checkout. departure_change permits a verified late payment.
invalidatedAmountTwdOriginal checkout amount in TWD when the intent became invalid.
attemptProviderattemptMethodattemptStatusbankCodevirtualAccountpayExpireAtrefunds退款工作流。
idrefundNumberstatusrefundKindamountTwdmethodreasoncreatedAtpaidAtexecutionMethod執行方式:chargeback 刷退 / remit 匯出;未定為 null(customer-cancellation §3.4)。
gatewayExecutionMode選填remitFeeTwd轉帳費(按單一次;remit 才有值)。承辦核放時可調降。
splitGroupId拆單組(#1406):同一筆退款拆成刷退+匯款時,各張共用。null = 沒有拆單。
gatewayLocked原路退刷 claim 已佔但無成功紀錄 = DoAction 結果不明,退款單被鎖住(mark-paid 一律 回 GATEWAY_IN_FLIGHT_OR_UNKNOWN)。判準取 clearRefundGatewayClaim 的 NOT_LOCKED 守衛 (別在 UI 端重刻)再加狀態閘:已 paid / cancelled 的殘留 claim 不該露出解鎖入口。
gatewayNeedsReview近 90 天已完成帳務且明確記錄自動退刷降級,供對帳辨識;不提供重試入口。
payee收款人四欄(匯款單才有值)。付款前承辦可改(issue 1698)。含完整帳號:`/api/v1` 對沒有 `refund.create` 權限的呼叫者回 null,和後台訂單頁的顯示條件相同。
accountNamebankCodebranchCodeaccountNumberconsentskindkindLabel自訂種類的名稱(#586);系統種類為 null,由畫面依 `kind` 查標籤。
versionsignedAtsignerName送出的帳號。逐旅客的自訂同意書是代簽人(訂購人)。
travelerName被代簽旅客的姓名;訂單層簽署為 null。旅客列移除後也是 null(紀錄本身仍在)。
travelerId被代簽旅客的 id(無 FK,旅客移除後仍保留作證據)。
ipAddressauditLogidactionactorUserIdactorUserNamemetadataipAddresscreatedAtorderDiscountcodeSnapshotoriginalTotalTwddiscountTwdprofitShareTwdprofitSharePayeeSnapshotcurl -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
/api/v1/orders/{id}/adjust參數
id路徑訂單 ID
kind必填surchargeallowance調整類型:surcharge 加收、allowance 減免
amountTwd必填調整金額(新台幣,正整數)
description必填調整事由說明
回應欄位 · data
ok固定為 true:訂單金額調整已套用。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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.
/api/v1/orders/{id}/agreements參數
id路徑Resource ID
回應欄位 · data[]
idorderIddepartureIddepartureDate梯次出發日(ISO date);一張單多梯時用來標示這份契約屬哪一梯。
participationVersion選填isCurrent選填travelerIdtravelerNamestatustemplateVersioncontractDateprovidedAttokenExpiresAtsignedAtsignerNamesignerIparticle32AgreedsigningPayloadevidenceSha256contentSha256hasPdfdeliveredAtdeliveryAddressrevokedAtrevokeReasonlastSyncedAtsync 最後檢視時間(排程漂移訊號的基準)。
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.
/api/v1/orders/{id}/agreements/{agreementId}/reissue參數
id路徑Resource ID
agreementId路徑Agreement ID
回應欄位 · data
okcurl -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.
/api/v1/orders/{id}/agreements/{agreementId}/resend-copy參數
id路徑Resource ID
agreementId路徑Agreement ID
回應欄位 · data
deliverycurl -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.
/api/v1/orders/{id}/agreements/{agreementId}/revoke參數
id路徑Resource ID
agreementId路徑Agreement ID
回應欄位 · data
okcurl -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.
/api/v1/orders/{id}/agreements/{agreementId}/sign-link參數
id路徑Resource ID
agreementId路徑Agreement ID
回應欄位 · data
okurlexpiresAtcurl -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.
/api/v1/orders/{id}/agreements/generate參數
id路徑Resource ID
回應欄位 · data
skipped整單層級略過原因;null = 有處理逐旅客。
issuedrevokedfailurestravelerIdtravelerNamereasonvarsmissingTemplateTypes這張單上「行程類型對得到種類、但該種類沒有範本」的契約種類(#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"
]
}
}首次派發訂單給承辦業務
/api/v1/orders/{id}/assign參數
requestId必填提交識別;重送同一提交時沿用此值
id路徑訂單 ID
assigneeUserId必填受派業務的使用者 ID
reason選填派發事由說明(上限 500 字)
回應欄位 · data
ok固定為 true:訂單已指派承辦。
idempotenttrue = 原提交已完成,或受派者相同,本次沒有再次派發。
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.
/api/v1/orders/{id}/backup-choices參數
id路徑Resource ID
departureIds必填Ordered backup departures
回應欄位 · data
okchosencurl -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": [
"…"
]
}
}產生/重用尾款
/api/v1/orders/{id}/balance-link參數
id路徑訂單 ID
回應欄位 · data
ok固定為 true:尾款付款連結已產生。
amountTwd本次尾款金額(TWD 整數)。
scheduleId對應的收款計畫 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
/api/v1/orders/{id}/cancel參數
id路徑訂單 ID
reason選填取消事由說明
cancellationReason選填admincustomer_requestno_showother取消政策事由;新單與舊鏈使用相同政策
disposition選填refundkeep可退款項的去向:refund 開退款草稿,keep 留在原單成為保留款。admin 不帶時為 keep(退改費記 0);customer_request 不帶時照舊退款;其他事由不可帶;舊鏈只能 refund
回應欄位 · data
ok固定為 true:訂單已取消(座位釋出、booking_state 轉 cancelled)。
refundsorderIdorderNumberrefundIdrefundNumberamountTwdremitFeeTwd選填retentionDeferredtrue = 回訪來源尚未同步,每日排程會補做;取消本身已完成。
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.
/api/v1/orders/{id}/cancel-failover參數
id路徑Resource ID
reason選填Cancellation reason
cancellationReason選填admincustomer_requestno_showother取消政策事由;不因舊子單身分免收退改費
回應欄位 · data
okheadOrderId鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。
refunds實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。
orderIdorderNumberrefundIdrefundError需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。
refundTotals本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。
amountTwdadminFeeTwdremitFeeTwdfilingFee逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。
totalTwd逐旅客費率的加總。
lines逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。
seqfeeTwd這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。
travelerName送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 null —— `traveler_id` 是不帶 FK 的快照 id,join 不到是合法狀態。
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.
/api/v1/orders/{id}/cancel-lottery-lost參數
id路徑Resource ID
回應欄位 · data
oknotifiedheadOrderId鏈首(`failover_from_order_id IS NULL`)。鏈長 1 時即 orderId 自己。
refunds實際建出來的 draft,一張有現金的單一張。空陣列 = 全鏈都沒有可退現金。
orderIdorderNumberrefundIdrefundError需要人工接手的彙總訊息(取消**不**回滾);沒有就是 null。兩種來源:建立失敗,以及 「轉帳費吃光可退現金、不開退款單」——後者現金仍留在單上,沒有退款單就沒有人會再看到它。
refundTotals本次開出的 draft 三筆金額的加總(沒開單就三項皆 0)。**通知信一律取這裡的值,不重算** ——行政費會被可退現金 clamp、轉帳費依原始收款方式推導,重算一定與客人實際入帳分岔。
amountTwdadminFeeTwdremitFeeTwdfilingFee逐旅客的送件行政費明細(只有 `chargeFilingFee` 那條路有值,其餘為 null)。退款通知 要把次數攤開(§3.6),而攤開的粒度是紀錄列不是人。
totalTwd逐旅客費率的加總。
lines逐筆明細,**同一個 person 的各次排在一起、其內依 `seq` 升序**(掛不上 person 的列 退回姓名分組)。**退款通知要把次數攤開**(§3.6):客人的認知是「我只報名了一次」。
seqfeeTwd這一列分攤到的金額 = 階梯的**邊際**(`總額(seq) − 總額(seq−1)`)。封頂之後是 0 —— 那一次確實算進去了,只是沒再加錢,行還是要列出來。
travelerName送件對象的姓名(退款通知逐旅客攤開用)。旅客列被刪 / 沒填姓名時為 null —— `traveler_id` 是不帶 FK 的快照 id,join 不到是合法狀態。
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
}
}業務自派搶單
/api/v1/orders/{id}/claim參數
id路徑訂單 ID
回應欄位 · data
ok固定為 true:訂單已由當前承辦認領。
curl -X POST "https://your-tenant.example.com/api/v1/orders/<id>/claim" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": true
}
}/api/v1/orders/{id}/cross-trip-quote參數
q選填搜尋行程名稱、日期、梯次標籤或 ID;最多回傳 50 筆
id路徑回應欄位 · data[]
departureIdlabelcurl -X GET "https://your-tenant.example.com/api/v1/orders/<id>/cross-trip-quote" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": [
{
"departureId": "…",
"label": "…"
}
]
}/api/v1/orders/{id}/cross-trip-quote參數
targetDepartureId必填adjustment選填id路徑回應欄位 · data
quoteorderIdparticipationVersionsourceVersionquoteFingerprintquotedAtexpiresAtconfirmationAvailableTrue when this order can continue to the departure change preview.
sourcedepartureIdtripIdtitledatetargetdepartureIdtripIdtitledatepriceChannelpriceSourcepartySizeoriginalFareTwdtargetFareTwdoriginalDiscountTwdtargetDiscountTwdoriginalProfitShareTwdtargetProfitShareTwddiscountcodestatusreasonexistingLinesidtypedescriptionamountTwdcategoryadjustmentkindamountTwdreasonoriginalReceivableTwdtargetReceivableTwddifferenceTwdcollectedTwdreturnedCashTwdpaidRefundFeesTwdeffectivePaidTwdoutstandingTwdrefundableTwdoverpaymentRefundTwddepositTargetTwddepositOutstandingTwdbalanceOutstandingTwddepositDueAtbalanceDueAtNull when the target is a lottery departure: the due date is set at the win.
tasksblockerscurl -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": [
"…"
]
}
}
}/api/v1/orders/{id}/departure-change-equipment參數
rentalId必填targetDepartureId必填participationVersion必填mode必填releaserebookreason必填rentStartDate選填rentEndDate選填lines選填id路徑Order ID
回應欄位 · data
replacementRentalId新建的替代租借單 ID;釋出時為 null。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
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.
/api/v1/orders/{id}/force-place參數
id路徑Resource ID
targetDepartureId必填Target departure ID
回應欄位 · data
retentionDeferredtrue = 回訪來源或期間尚未同步,每日排程會補做;安置本身已完成。
okorderIddepartureChangeIdbackupOrderIddeprecated · 下一個版本移除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
/api/v1/orders/{id}/lottery/resolve參數
id路徑訂單 ID
outcome必填wonlost抽籤裁決結果:won 中籤確認、lost 未中籤(啟動備案或取消)
applicationKey選填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固定為 true:抽籤結果已登錄。
outcome抽籤結果:won 中籤 / lost 未中籤。
balanceNotice中籤後的尾款通知(lost 為 null):sent 已寄出、already_sent 之前寄過、 not_eligible 沒有待收尾款、no_template 租戶沒有啟用中的收尾款範本、 no_recipient 沒有收件人(同業單或訂購人沒有 email)、failed 寄送失敗。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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
}
}/api/v1/orders/{id}/mark-paid參數
id路徑訂單 ID
amountTwd選填本次收款金額,TWD 正整數;省略則結清全部待收餘額
idempotencyKey選填收款冪等鍵,8 至 64 字英數或連字號;重送同鍵不重複入帳
bankReference選填匯款後五碼或銀行交易參考號,上限 40 字
providerTradeNo選填金流訂單編號;收款帳戶是第三方金流時必填
bankCreditedOn選填入帳日期 YYYY-MM-DD;收款帳戶是銀行時必填
overTheCounter選填臨櫃存款;銀行帳戶勾選後免填匯款後五碼
note選填對帳備註,記錄人工核款說明
receivingAccountId必填收款帳戶 ID,指定本筆款項入帳的帳戶
回應欄位 · data
idempotenttrue = 此請求已入帳或訂單已結清,本次未重複入帳。
collectedTwd本次入帳金額;冪等重送為 0。
customerCashAppliedTwd入帳後已收現金淨額。
outstandingTwd入帳後待收餘額。
paymentState入帳後付款狀態。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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
}
}某罐頭範本代入本訂單變數後的
/api/v1/orders/{id}/message-preview參數
id路徑訂單 ID
templateId必填訊息範本 ID(line 或 email 通道皆可)
回應欄位 · data
channel範本通道:line 或 email。
subject代入本訂單變數後的標題(email 為信件主旨)。
body代入本訂單變數後的內文。
missingVars範本引用但本訂單沒有值的變數名;成品裡仍是 `{{變數}}` 原樣,貼出前要手動處理。
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": [
"…"
]
}
}重新指派已派發訂單
/api/v1/orders/{id}/reassign參數
requestId必填提交識別;重送同一提交時沿用此值
id路徑訂單 ID
assigneeUserId必填重新指派的承接業務使用者 ID
reason選填重派事由說明(上限 500 字)
回應欄位 · data
ok固定為 true:訂單已改派承辦。
idempotenttrue = 原提交已完成,或受派者相同,本次沒有再次派發。
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
/api/v1/orders/{id}/refunds參數
creationSource選填manualheld_cashCreation source; held cash requires server verification
id路徑訂單 ID
refundKind必填receivable_reductionoverpayment_return退款種類:receivable_reduction 一般退款、overpayment_return 多付退回
reason必填退款事由說明
amountTwd必填退款總金額(新台幣,正整數)
executionMethod選填chargebackremit退款執行方式:chargeback 原路退刷、remit 銀行匯款
originAccountId選填出款來源帳戶 ID(匯款退款時指定)
adminFeeTwd選填手續費/行政費(新台幣,非負整數)
remitFeeTwd選填匯款轉帳費(新台幣,非負整數)
payeeAccountName選填受款人戶名(匯款退款時選填)
payeeBankCode選填受款銀行代碼(匯款退款時填寫)
payeeBranchCode選填受款分行代碼(匯款退款時選填,4 碼數字;須存在於銀行/分行對照表,否則回 409 查無此分行)
payeeAccountNumber選填受款銀行帳號(匯款退款時填寫)
lines選填退款明細列;省略時依退款總額處理
回應欄位 · data
id退款單 id(前綴 `rfnd_`)。
refundNumber人類可讀退款單號。
status退款工作流狀態: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
/api/v1/orders/{id}/refunds/{refundId}/approve參數
id路徑訂單 ID(path)
refundId路徑退款單 ID
回應欄位 · data
ok固定為 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
}
}取消待執行的退款單
/api/v1/orders/{id}/refunds/{refundId}/cancel參數
id路徑訂單 ID(path)
refundId路徑退款單 ID
reason必填取消原因(必填,寫進稽核日誌)
remitNotSentVerified選填已確認這筆匯款沒有送出銀行轉帳,或銀行已退件(取消已核准的匯款單時必填 true)
gatewayNoApplicationVerified選填已確認金流商沒有受理申請、處理中或已完成的退款(取消已核准的人工刷退時必填 true)
回應欄位 · data
ok固定為 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 鎖定
/api/v1/orders/{id}/refunds/{refundId}/clear-gateway-claim參數
id路徑訂單 ID(path)
refundId路徑退款單 ID
note必填查證依據(必填,寫進稽核日誌)
回應欄位 · data
ok固定為 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
}
}/api/v1/orders/{id}/refunds/{refundId}/mark-paid參數
id路徑訂單 ID(path)
refundId路徑退款單 ID
receiptId選填原路退刷必填:公開金流核心的原信用卡收款 ID
allocations選填首次送出時固定跨商卡款分配;總額必須等於退款金額
retryOf選填重試時填已確認安全失敗的前次執行 ID
bankReference選填出款的銀行交易參考號(匯款憑證)
receivingAccountId選填出款帳戶 ID;remit 退款須指定具匯款能力的帳戶
remitFeeTwd選填核放時調降的匯款手續費(只能調降;差額回到退款金額)
回應欄位 · data
ok指令已處理;pending 或 unknown 不代表已退款。
gatewaypending:已受理;unknown:結果不明;succeeded:已確認個別退款;not_applicable:非刷退或既有已付紀錄。
skipReason新執行不降級記帳;此相容欄位為 null。
providerRefundNo已確認的個別退款編號;未完成時為 null。
retentionDeferredtrue = 回訪來源尚未同步,每日排程會補做;退款帳務本身已完成。
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
/api/v1/orders/{id}/refunds/{refundId}/reject參數
id路徑訂單 ID(path)
refundId路徑退款單 ID
reason選填退件事由說明
回應欄位 · data
ok固定為 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.
/api/v1/orders/{id}/release-identity-hold參數
id路徑Resource ID
reason必填Required release reason
回應欄位 · data
okcurl -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": "…"
}
}/api/v1/orders/{id}/resolve-screening-follow-up參數
id路徑訂單 ID
回應欄位 · data
ok固定 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
/api/v1/orders/{id}/reverse參數
id路徑訂單 ID
chargeLineId必填欲沖正的應收項目(charge line)ID
description必填沖正事由說明
回應欄位 · data
ok固定為 true:訂單已沖銷(沖回應收與已認列項)。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;入帳或確認本身已完成。
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
}
}/api/v1/orders/{id}/review-screening參數
id路徑訂單 ID
decision必填approvereject登山資格審核裁決:approve 核可、reject 駁回
travelerId選填只裁決這一位旅客;省略 = 該單所有待審旅客一起裁決
disposition選填resupplementswitch_triprefund駁回必填:resupplement 補件、switch_trip 換團、refund 退費;不自動取消或退款
templateId選填駁回後寄送的訊息範本 ID;省略不寄信,寄信失敗不回滾駁回
note選填審核註記說明(上限 500 字)
redecide選填重新裁決一列正在漂移的已人工裁決紀錄(需指名 travelerId);預設 false
回應欄位 · data
ok固定為 true:名單複核結果已登錄。
followUpState處置後追蹤狀態;退費或核可為 null。
emailSent通知已加入寄送佇列;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.
/api/v1/orders/{id}/send-balance-slip參數
id路徑Resource ID
回應欄位 · data
okemailSentTrue when this call adds a queue entry. Delivery is still pending.
outcomeThe 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.
/api/v1/orders/{id}/send-message參數
id路徑Resource ID
templateId必填Email template ID
回應欄位 · data
okcurl -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": "…"
}
}/api/v1/orders/{id}/settle-cancellation參數
id路徑訂單 ID
deductionTwd必填人工核算扣除額(新台幣,非負整數)
reason必填實際損害核算依據
回應欄位 · data
refundIdrefundNumberdeductionTwdidempotentcurl -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
/api/v1/orders/{id}/split-traveler參數
id路徑Resource ID
travelerId必填Traveler to move to the new order
targetDepartureId選填Departure of the new order on the same trip. Omit to keep the same departure
transferTwd選填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選填previewconfirmPreview before confirmation
previewToken選填Token from the preview response
requestId選填Stable request ID for retries
reason選填Split reason
acknowledgeRosterFreeze選填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
okorderIdpreview選填Present after a preview. Send its previewToken on the confirmation.
previewTokensourceOrderIdtravelerIdtravelerNamesourceDepartureIdtargetDepartureIdsameDepartureunitPriceTwdmoneysourceReceivableBeforeTwdsourceReceivableAfterTwdnewReceivableTwdsuggestedTransferTwd系統建議值:依應收比例分配原單的有效已付款(§3.5)。
maxTransferTwdtransferTwdtransferOverriddensourceOverpaymentTwd拆出後原單多收、要開溢收退款草稿的金額。
keptOnSourceTwd留在原單、不分攤的折扣、人工調整與房型升等合計(§6 M2)。
discountTwdadjustmentTwdroomUpgradeTwdnewOrderSchedulesfirstPurposedepositTwdbalanceTwddepositOutstandingTwdnextPurposenextTwdnewOrderBalanceDueAtclears這位旅客目前在分房、同行組裡;拆出後清空。
roomcompanionGroupnewOrderId選填newOrderNumber選填splitId選填transferTwd選填refundDraftId選填Overpayment refund draft on the source order. null = no overpayment.
idempotent選填true = a retry of a completed request.
departureChange選填The departure change of the new order, for another target departure. On failure the split stays done and the new order stays on the source departure.
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.
/api/v1/orders/{id}/transfer-departure參數
id路徑Resource ID
targetDepartureId必填Target departure ID
mode選填previewconfirmPreview before confirmation
previewToken選填Token from the preview response
requestId選填Stable request ID for retries
reason選填Departure change reason
crossTrip選填Set true for a target on another trip. Without it, the target must be on the same trip
adjustment選填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
okorderIddepartureChangeId選填backupOrderId選填deprecated · 下一個版本移除preview選填Includes current document requirements, retained consents, and passport expiry warnings.
arrangementsroomFeeBeforeTwdroomFeeAfterTwdotherRoomOrderCountotherRoomFeeDeltaTwdotherRefundDraftTwdreleasedRoomCountreleasedPretripStayCounttaskstravelerIdkindlabelfingerprintpreviewTokenpaymentWindowHoursexpiresAtdocumentsagreementEnabledversioningReadyagreementCountagreementPendingagreementHistoryconsentslabelversionpendingretainedduepassportExpiryWarningsfingerprintcrossTrip選填sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdepartureprice_twdagency_price_twddeposit_modedeposit_amount_twddeposit_percentpromo_activepromo_price_twdpromo_agency_price_twdtripdirect_price_twdagency_price_twdprice_from_twddeposit_modedeposit_amount_twddeposit_percentdeposit_basisschema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。
unitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
basisstepN:每幾位旅客 / 每滿幾元。
unitTwd每次折多少(碼的折扣值)。
units折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valueselfService選填repricingThe target fare at its current price. Same shape as a cross-trip quote, without answers.
sourceTripIdsourceTitletargetTripIdtargetTitlepriceChannelpriceSourcepricingdepartureprice_twdagency_price_twddeposit_modedeposit_amount_twddeposit_percentpromo_activepromo_price_twdpromo_agency_price_twdtripdirect_price_twdagency_price_twdprice_from_twddeposit_modedeposit_amount_twddeposit_percentdeposit_basisschema 為 NOT NULL;LEFT JOIN 缺值時退回 per_person。
unitPriceTwdfareBeforeTwdfareAfterTwdadjustmentkindamountTwdreasondiscountThe current code checked again for the target. null = the order has no current code.
orderDiscountIddiscountCodeIdcodestatusapplied = the order keeps the code. released = the order leaves it.
reasonoriginalTotalTwdTarget fare that the discount is calculated from.
discountBeforeTwddiscountAfterTwdcalcAfter重算後的倍數折扣算式(discount-code §3);整張訂單折一次、百分比或退出優惠時為 null。
basisstepN:每幾位旅客 / 每滿幾元。
unitTwd每次折多少(碼的折扣值)。
units折幾次 = floor(旅客數 ÷ N) 或 floor(折前金額 ÷ N)。
profitShareBeforeTwdprofitShareAfterTwdprofitSharePayeeprofitSharePayeeBeforeSnapshotprofitShareBilledA profit share payable already covers this discount.
profitSharePaidThat payable is paid, so staff cannot cancel it.
discountLinesTwdOpen code discount lines that the change reverses, as a positive amount.
climbingActivescreeningsSource decisions. The target never inherits manual approvals or rejections.
idtraveler_idverdictreviewed_by_user_idreview_notereviewed_atdispositiondisposition_notefollow_up_statesurveyAnswersSource answers, with free text. They stay in history and never count as target answers. Member anonymization sets text_value to null. The history trigger in setup-business-extras allows only that update.
idtraveler_idquestion_idquestion_labeloption_idoption_label_snapshotquantitytext_valuefeetierdaysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
amountTwddescriptioncharge line 的說明,例:「換梯手續費(每人 NT$ 200 × 2 人)」。
surplusremitFeeTwdlottery選填sourceModetargetModestateBeforestateAfter`applied` = a new application that waits for the draw. The source win never carries over. `won` = lottery manual placement confirms the seat.
placement選填failover選填Set when the backup failover made the change. A general target confirms the seat (`won`).
skippedBackup choices that the failover skipped before this one.
rankdepartureIdreasonhitRankRank of the backup choice that this step tries.
remainingDepartureIdsBackup departures that stay after this one (untried choices and kept skips), in rank order. A lottery target keeps them.
applicationKeyBeforeapplicationId選填Set on confirmation: the new application uses the departure change ID.
legacyChain選填effectiveCreditTwd選填policyTotalTwd選填refundDrafts選填participationVersionequipmentblockedrentalsrentalIdrentalCodedepartureIdrentStartDaterentEndDatereturnStatereconStatedeliveredAtdepositClearedAtrentTotalTwddepositTotalTwddepositBalanceTwddeprecated · 下一個版本移除replacesRentalIdreadyblockerlinesitemIdnamequantitycommittedQuantitypaymentWindowStartedAt選填sourceFingerprintrosterFingerprintsourceidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percenttargetidtrip_iddeparture_datereturn_datestatusallocation_modeprice_twdlabeldeposit_modedeposit_amount_twddeposit_percenttotalTwdunitPriceTwddiscountTwdchargeLinesidtypeamount_twddescriptiondepositTwdbalanceTwdbalanceDueAtreceiptsblockedreceiptsidmerchantOrderNostatusinvoiceNumberinvoiceTransNosubmittedoperationPendinglastErrortourNametourNotourDatetotalAmtTwdupdatedAtresolutiontargettourNametourNotourDatetotalAmtTwdcollectedTwdreturnedTwdpaidRefundFeesTwdcustomerCashAppliedTwdoutstandingTwdrefundHeadroomgrossReceivableTwd當前應收。
refundableCashTwd可退現金(`refundableCash`)= 現金淨套用 − 已執行退款的手續費合計。
assessedCancellationFeeTwd此實收單保留的退改費;舊資料沿用人工核算基準。
openRefundGrossTwd同單其他未執行退款的原收合計(送審 / 標記已付時不含本張)。
openRefundCount同單其他未執行退款的張數。
openReceivableReductionTwd同單其他未執行**減應收**退款的退款額合計。它們標記已付時會沖掉同額應收,所以算 上限時看的應收是「它們結清後的應收」;只看當前應收會把它們在額度與應收兩邊各扣一次。
carriedToLiveBackupsTwd已結轉給未取消備案後裔的訂金。那筆錢經濟上已屬於子單,鏈首不可再退。
assessmentPending人工核算單、退改費尚未核算。
baseTwd額度基準 = 可退現金 − 上面三項扣減,下限 0。
overpaymentRefundTwddepositOutstandingTwdnextPaymentPurposenextPaymentTwdmoneyFingerprintrefundDraftId選填retentionDeferred選填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
}
}新增旅客到訂單
/api/v1/orders/{id}/travelers參數
fullName選填旅客全名,須與證件一致;新增旅客時必填,更新時可省略
phone選填旅客聯絡電話
email選填旅客電子郵件
birthDate選填旅客出生日期(格式 YYYY-MM-DD)
lineId選填旅客 LINE ID
lineDisplayName選填旅客 LINE 顯示名稱
englishName選填英文姓名,須與護照一致(大寫英文、空白、連字號、逗號),否則回 422;海外團用
nationality選填國籍使用 ISO 3166-1 alpha-2 代碼;新增時省略代表 TW、更新時省略不改,空字串或 null 代表國籍未知,未知國名回 422
passportExpiryDate選填護照效期(格式 YYYY-MM-DD);海外團效期提醒用
emergencyContactName選填緊急聯絡人姓名
emergencyContactPhone選填緊急聯絡人電話
gender選填malefemaleother旅客性別:male 男、female 女、other 其他
roomPreference選填房型偏好(用於分房作業)
roommatePref選填指定同住室友(用於分房作業)
diet選填飲食需求(葷 / 素 / 蛋奶素… 自由值),供餐食葷素彙總
medicalNotes選填醫療 / 過敏 / 病史備註(自由文字),供出團安全警示
address選填旅客通訊地址
idNumber選填身分證字號,屬個資將加密保存
passportNo選填護照號碼,屬個資將加密保存
surveyAnswers選填行程自訂報名調查項的作答;給陣列 = 整份取代(必填題未答或選到停用選項回 422)。編輯時省略 = 不動既有答案;新增時省略 = 一題都沒答
id路徑訂單 ID
seatMode選填roster_onlyadd_seatroster_only=只補名單(席次已買,旅客數須小於人數);add_seat=加一席(人數與梯次席次加 1,應收加一人成交價)
acknowledgeRosterFreeze選填員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED
回應欄位 · data
ok固定為 true:旅客已新增至訂單。
travelerId新建立旅客的 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": "…"
}
}更新旅客資料
/api/v1/orders/{id}/travelers/{travelerId}參數
fullName選填旅客全名,須與證件一致;新增旅客時必填,更新時可省略
phone選填旅客聯絡電話
email選填旅客電子郵件
birthDate選填旅客出生日期(格式 YYYY-MM-DD)
lineId選填旅客 LINE ID
lineDisplayName選填旅客 LINE 顯示名稱
englishName選填英文姓名,須與護照一致(大寫英文、空白、連字號、逗號),否則回 422;海外團用
nationality選填國籍使用 ISO 3166-1 alpha-2 代碼;新增時省略代表 TW、更新時省略不改,空字串或 null 代表國籍未知,未知國名回 422
passportExpiryDate選填護照效期(格式 YYYY-MM-DD);海外團效期提醒用
emergencyContactName選填緊急聯絡人姓名
emergencyContactPhone選填緊急聯絡人電話
gender選填malefemaleother旅客性別:male 男、female 女、other 其他
roomPreference選填房型偏好(用於分房作業)
roommatePref選填指定同住室友(用於分房作業)
diet選填飲食需求(葷 / 素 / 蛋奶素… 自由值),供餐食葷素彙總
medicalNotes選填醫療 / 過敏 / 病史備註(自由文字),供出團安全警示
address選填旅客通訊地址
idNumber選填身分證字號,屬個資將加密保存
passportNo選填護照號碼,屬個資將加密保存
surveyAnswers選填行程自訂報名調查項的作答;給陣列 = 整份取代(必填題未答或選到停用選項回 422)。編輯時省略 = 不動既有答案;新增時省略 = 一題都沒答
id路徑訂單 ID
travelerId路徑旅客 ID
acknowledgeRosterFreeze選填員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED
回應欄位 · data
ok固定為 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
}
}移除旅客
/api/v1/orders/{id}/travelers/{travelerId}參數
id路徑訂單 ID
travelerId路徑旅客 ID
acknowledgeRosterFreeze選填員工已確認名單凍結(出發前 6 天內):名單可能已送入山證、投保,改完要同步修改送件與保險。凍結期內不帶回 409 EDIT_WINDOW_CLOSED
回應欄位 · data
ok固定為 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.
/api/v1/orders/{id}/travelers/{travelerId}/climbing-records參數
id路徑Resource ID
travelerId路徑Traveler ID
回應欄位 · data[]
idlabelgradeScoresystemGradeScorehasAlpineExperienceclimbedOncreatedAtcurl -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": "…"
}
]
}/api/v1/orders/{id}/travelers/{travelerId}/climbing-records參數
id路徑Resource ID
travelerId路徑Traveler ID
label必填Route label
gradeScore選填Reference grade score. This value does not affect screening. The system uses the route grade table.
hasAlpineExperience選填Alpine experience
climbedOn選填Climb date
回應欄位 · data
okrecordIdcurl -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.
/api/v1/orders/{id}/travelers/{travelerId}/climbing-records/{recordId}參數
id路徑Resource ID
travelerId路徑Traveler ID
recordId路徑Climbing record ID
回應欄位 · data
okcurl -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": "…"
}
}顯示旅客證號/護照全碼
/api/v1/orders/{id}/travelers/{travelerId}/reveal參數
id路徑訂單 ID
travelerId路徑旅客 ID
field必填idNumberpassportNo欲顯示全碼的個資欄位:idNumber 身分證字號、passportNo 護照號碼
回應欄位 · data
field本次解密的欄位:idNumber 身分證字號 / passportNo 護照號碼。
value解密後的證件明碼;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": "…"
}
}更新旅客分房需求
/api/v1/orders/{id}/travelers/{travelerId}/rooming參數
roomPreference選填房型偏好(用於分房作業)
roommatePref選填指定同住室友(用於分房作業)
id路徑訂單 ID
travelerId路徑旅客 ID
回應欄位 · data
ok固定為 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
}
}批次把多張訂單派給同一位業務
/api/v1/orders/bulk-assign參數
requestId必填提交識別;重送同一批次時沿用此值
orderIds必填欲批次派發的訂單 ID 陣列(1 至 100 筆)
assigneeUserId必填受派業務的使用者 ID(所有訂單派給同一人)
reason選填派發事由說明(上限 500 字)
回應欄位 · data
ok固定為 true:批次指派已執行。
assignedCount成功指派的訂單筆數。
skippedCount略過的訂單筆數(如已指派或不在可指派範圍)。
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 單的折扣碼即時試算
/api/v1/orders/discount-preview參數
code必填欲試算的優惠碼字串
departureId必填梯次 id(server 端反查行程,不信任 client 的 tripId)
partySize必填人數;折前小計由 server 依建單同一套定價解析(單價 × 人數),不收 client 的金額
customerType必填directagency成交客戶類型:direct 直客價 / agency 同業價;決定價格通路與客戶分類 gating
primaryEmail選填訂購人 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": "…"
}匯出訂單
/api/v1/orders/export參數
status選填依訂單顯示狀態篩選(如 pending、paid、cancelled)
assignment選填依派發狀態篩選(如 unassigned、assigned)
rooming選填依分房狀態篩選
dateFrom選填出發日期區間起(格式 YYYY-MM-DD,含當日)
dateTo選填出發日期區間迄(格式 YYYY-MM-DD,含當日)
q選填關鍵字搜尋(訂單編號、訂購人姓名或 Email 等)
agencyId選填依合作旅行社 ID 篩選(同業單)
回應欄位 · data
rows符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。
kindid訂單 id(前綴 `ord_`)。
orderNumber人類可讀訂單編號(每租戶 sequence 產生,如 `20260707-0001`)。
bookingState預訂狀態(真相軸):pending_payment → confirmed → completed;cancelled 為終態。
paymentState付款狀態(派生自分類帳、快取於此供過濾):unpaid / partially_paid / deposit_paid / paid / overpaid。paid 只代表「應收被現金覆蓋」,不代表錢未退。
refundState退款狀態(派生快取,只算會影響應收的已付退款):none / partially_refunded / refunded。
grossReceivableTwd應收(TWD 整數,派生自應收分類帳)。
collectedTwd收到現金(TWD 整數,派生)。
customerCashAppliedTwd客戶現金淨套用(收款減已退現金,TWD 整數,派生)。
refundableCashTwd可退現金 = 客戶現金淨套用 − 已執行退款的手續費合計(TWD 整數,派生)。 「還能退多少」一律問這個欄位,**不是** `customerCashAppliedTwd` —— 已 paid 退款 的手續費留在公司但現金列沒有等額 out 列表達它(見 money-state 的 refundableCash)。
outstandingTwd未收(應收減客戶現金淨套用,TWD 整數,派生)。
partySize參團人數(tour 訂單)。
createdAt訂單建立時間。
notes訂單備註(未填 → null)。
userId下單客戶的 user id(同庫 user 表)。
userName下單客戶顯示名。
userEmail下單客戶 Email。
primaryTravelerName主要旅客姓名(is_primary,未登記 → null)。
primaryTravelerPhone主要旅客電話(未登記 → null)。
tripId行程 id(tour 訂單經梯次反查;lodging 為空字串)。
tripTitle行程 / 產品標題。
tripShortName行程內部簡稱(issue 1414);未填或訂房訂單為 null。
tripSlug行程 slug。
departureId梯次 id(tour 訂單;lodging 為空字串)。
departureDate出發日 YYYY-MM-DD(lodging 為入住日)。
returnDate回程日 YYYY-MM-DD(lodging 為退房日)。
assignedToUserId派發給哪位業務的 user id(未派發 → null)。
assigneeName承辦業務顯示名(未派發 / 查無 → null)。
assignmentStatus派發狀態:unassigned / assigned / reassigned / pending_review。
assignedAt最近一次派發時間(未派發 → null)。
assignedByUserId執行派發者的 user id(未派發 → null)。
createdByUserIdS5: who created the order. null / equal to `userId` = customer self-service (自助下單); a staff id ≠ userId = 業務代訂 / K單. Distinct from assignment — a self-service order can still be assigned to a sales rep.
pendingConsent是否尚缺最新版 PDPA 同意書簽署(true = 待客戶重簽)。
roomingStatus分房狀態:由訂單旅客的分房偏好與已分配房間派生。 'unregistered' | 'registered' | 'needs_single' | 'assigned'。
lotteryState抽籤狀態(null = FCFS 非抽籤)。'applied'|'won'|'lost'。
lotteryWaitlisted備取(issue 1691):`applied` 的子狀態,主管機關把這次應募排進備取,結果未定。
failoverFromOrderId備案訂單所對應的原訂單 ID。
isOverdue是否有已到期、尚未收齊的收款計畫。
total符合篩選條件的總筆數。
truncated是否因達安全上限而截斷(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 單的金額試算
/api/v1/orders/quote參數
departureId必填梯次 id(server 端反查行程,不信任 client 的 tripId)
customerType必填directagency成交客戶類型:direct 直客價 / agency 同業價;決定價格通路與客戶分類 gating
partySize必填人數;小計由 server 依建單同一套定價解析(單價 × 人數),不收 client 的金額
paymentPlan必填fulldeposit付款方案:full 全額 / deposit 訂金;梯次沒有訂金規則時改成全額
code選填優惠碼(選填);空字串視為沒有
primaryEmail選填訂購人 email(選填);查得會員才納入每客戶兌換上限判定,空或查不到則該閘放行
回應欄位 · data
quote金額試算:單價、小計、折扣、總計、實際付款方案與訂金 / 尾款。
unitPriceTwdpartySizesubtotalTwd折前小計 = 單價 × 人數。
discountTwdtotalTwd折後總計,也就是訂單應收。
paymentPlan實際採用的付款方案:訂金方案拆不出尾款時改成全額。
depositDueTwdbalanceDueTwddiscount優惠碼結果: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": "…"
}
}退款「標記已退款」用的出款帳戶下拉
/api/v1/orders/remit-accounts回應欄位 · data[]
id收款帳戶 ID(標記已退款時當出款帳戶帶入)。
code帳戶代碼(租戶自訂短碼)。
displayName顯示名稱(下拉選項用)。
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.
/api/v1/orders/remittance-lookup參數
orderNumber必填Order number
回應欄位 · data
orderIdorderNumbercustomerNametripTitleoutstandingTwdbookingStatepaymentStatecurl -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"
}
}/api/v1/orders/screening-preview參數
departureId必填travelers必填回應欄位 · data
resultsAdvisory 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.
/api/v1/orders/split-remittance參數
totalTwd必填Total remittance amount TWD
allocations必填Order allocations
idempotencyKey必填Request retry key
bankReference選填Bank reference
receivingAccountId必填Actual receiving account ID
providerTradeNo選填Gateway trade number; required for a gateway account
bankCreditedOn選填Bank credited date YYYY-MM-DD; required for a bank account
overTheCounter選填Over-the-counter deposit; a bank account then needs no bank reference
note選填Note
回應欄位 · data
retentionDeferredokidempotentremittanceIdordersorderIdorderNumbercollectedTwdcustomerCashAppliedTwdoutstandingTwdpaymentStatecurl -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
/api/v1/orders/stats回應欄位 · data
pendingPayment待付款訂單數(未取消 / 未完成 / 未退款且 payment_state=unpaid)。
depositPaid已付訂金訂單數(payment_state=deposit_paid)。
paid已收齊訂單數(payment_state in paid/overpaid)。
cancelled已取消訂單數(booking_state=cancelled)。
refunded有退款的訂單數(refund_state in refunded/partially_refunded)。
completed已完成訂單數(booking_state=completed)。
thisMonthPaidTwd本月實收現金(payment_transactions direction=in 加總,TWD 整數)。
thisMonthNewOrders本月新建訂單數。
thisMonthCancelled本月取消訂單數(依 `cancelled_at` 計,台北月界)。不依 `updated_at` —— 取消之後的 退款或備註會把單推到錯的月份。`cancelled_at IS NULL` 的單任何月份都不計。
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
/api/v1/equipment/items參數
activeOnly選填只列出啟用中(可租借)的品項
回應欄位 · data[]
id裝備主檔品項 id(equipmentItem_ 前綴)。
name品名。
category分類(如帳篷/睡袋/爐具;未分類為 null)。
spec規格描述(尺寸/型號等;可空)。
rentPriceTwd每日租金單價(TWD)。
depositTwd每件押金(TWD)。
totalCount庫存總件數。
outCount目前在外(已借出未歸還)件數。
maintenanceCount維修中件數(不可借出)。
availableCount可租 = total − out − maintenance(派生,便利 UI)。
isActive是否啟用(可租借)。
createdAt建檔時間。
updatedAt最後更新時間。
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
/api/v1/equipment/items參數
name必填裝備品項名稱
category選填裝備分類(如帳篷、睡袋;選填)
spec選填規格說明(如尺寸、型號;選填)
rentPriceTwd選填每日租金(台幣)
depositTwd選填每件押金(台幣)
totalCount選填總庫存數量
maintenanceCount選填維修中而不可租借的數量
isActive選填是否啟用(可供租借)
回應欄位 · data
id新建立的裝備品項 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.
/api/v1/equipment/items/{id}參數
id路徑裝備品項 ID
回應欄位 · data
id裝備主檔品項 id(equipmentItem_ 前綴)。
name品名。
category分類(如帳篷/睡袋/爐具;未分類為 null)。
spec規格描述(尺寸/型號等;可空)。
rentPriceTwd每日租金單價(TWD)。
depositTwd每件押金(TWD)。
totalCount庫存總件數。
outCount目前在外(已借出未歸還)件數。
maintenanceCount維修中件數(不可借出)。
availableCount可租 = total − out − maintenance(派生,便利 UI)。
isActive是否啟用(可租借)。
createdAt建檔時間。
updatedAt最後更新時間。
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
/api/v1/equipment/items/{id}參數
id路徑要更新的裝備品項 ID
name必填裝備品項名稱
category選填裝備分類(如帳篷、睡袋;選填)
spec選填規格說明(如尺寸、型號;選填)
rentPriceTwd選填每日租金(台幣)
depositTwd選填每件押金(台幣)
totalCount選填總庫存數量
maintenanceCount選填維修中而不可租借的數量
isActive選填是否啟用(可供租借)
回應欄位 · data
ok更新成功旗標,恆為 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
/api/v1/equipment/rentals參數
returnState選填rentedreturnedoverduecancelled依歸還狀態篩選:rented 在租中、returned 已歸還、overdue 逾期、cancelled 已取消
reconState選填pendingreconcileddeposit_pending依驗收結算狀態篩選:pending 待驗收、reconciled 已結算、deposit_pending 待退押金
orderId選填只列出綁定此訂單 ID 的租借單
departureId選填只列出綁定此梯次 ID 的租借單
equipmentItemId選填只列出含此裝備品項的租借單
rentFrom選填租期區間起(含),格式 YYYY-MM-DD。判準是租期與區間**重疊**,跨月的單兩個月都查得到
rentTo選填租期區間迄(含),格式 YYYY-MM-DD
回應欄位 · data[]
orderOnDepartureWhether the order currently includes this rental departure.
deliveredAt選填depositClearedAt選填id租借單 id(equipmentRental_ 前綴)。
rentalCode人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。
orderId掛載的訂單 id。
orderNumber訂單編號;無對應訂單時為 null。
departureId綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。
departureLabel梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。
renterName租借人姓名(可空)。
rentStartDate租期起日(YYYY-MM-DD;可空)。
rentEndDate租期迄日(YYYY-MM-DD;可空)。
returnedAt歸還驗收時間(尚未歸還為 null)。
returnState歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。
inspectedAt驗收時間(尚未驗收為 null)。
damageCostTwd破損/遺失賠償金額(TWD;無為 null)。
reconState對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。
cancelledAt取消時間(未取消為 null)。
cancelReason取消原因(未取消為 null)。
notes備註(可空)。
createdAt建單時間。
updatedAt最後更新時間。
lines租借明細(借出的品項清單)。
id租借明細 id(equipmentRentalLine_ 前綴)。
equipmentItemId借出的裝備主檔品項 id。
itemName裝備品項目前的名稱。
quantity借出數量。
rentPriceTwdSnapshot成交單位總價快照(每日單價 × 計價日數;TWD)。
depositTwdSnapshot成交每件押金快照(TWD,不乘天數)。
returnedQuantity已歸還數量(尚未歸還為 null)。
rentTotalTwd成交租金合計(Σ rent snapshot × qty)。
depositTotalTwd成交押金合計(Σ deposit snapshot × qty)。
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
/api/v1/equipment/rentals參數
orderId必填租借單綁定的訂單 ID(租金與押金會掛入該訂單金流)
departureId必填租借掛的梯次 ID(必填;該梯次的行程須為登山團且已開「可租借裝備」,訂單須報名此梯次)
renterName選填租借人姓名(選填)
rentStartDate選填租借起始日,格式 YYYY-MM-DD(選填)
rentEndDate選填租借結束日,格式 YYYY-MM-DD(選填)
notes選填租借單備註(選填)
lines必填租借明細清單(至少一筆品項)
回應欄位 · data
rentalId新開立的租借單 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
/api/v1/equipment/rentals/{id}參數
id路徑租借單 ID
回應欄位 · data
orderOnDepartureWhether the order currently includes this rental departure.
deliveredAt選填depositClearedAt選填id租借單 id(equipmentRental_ 前綴)。
rentalCode人看得懂的租借單編號 `RT-YYMMDD-NNN`(現場點交唱這個,不唱 id)。
orderId掛載的訂單 id。
orderNumber訂單編號;無對應訂單時為 null。
departureId綁定的梯次 id。issue 240 起新單必填;更早的舊單可能為 null(保留可查閱歸還對款)。
departureLabel梯次可讀標籤:團號 ‧ 行程名 ‧ 出發日(無綁梯次時 null)。
renterName租借人姓名(可空)。
rentStartDate租期起日(YYYY-MM-DD;可空)。
rentEndDate租期迄日(YYYY-MM-DD;可空)。
returnedAt歸還驗收時間(尚未歸還為 null)。
returnState歸還狀態:rented 租借中/returned 已歸還/overdue 逾期/cancelled 已取消。
inspectedAt驗收時間(尚未驗收為 null)。
damageCostTwd破損/遺失賠償金額(TWD;無為 null)。
reconState對款狀態:pending 待對款/reconciled 已結清/deposit_pending 押金待退或待扣。
cancelledAt取消時間(未取消為 null)。
cancelReason取消原因(未取消為 null)。
notes備註(可空)。
createdAt建單時間。
updatedAt最後更新時間。
lines租借明細(借出的品項清單)。
id租借明細 id(equipmentRentalLine_ 前綴)。
equipmentItemId借出的裝備主檔品項 id。
itemName裝備品項目前的名稱。
quantity借出數量。
rentPriceTwdSnapshot成交單位總價快照(每日單價 × 計價日數;TWD)。
depositTwdSnapshot成交每件押金快照(TWD,不乘天數)。
returnedQuantity已歸還數量(尚未歸還為 null)。
rentTotalTwd成交租金合計(Σ rent snapshot × qty)。
depositTotalTwd成交押金合計(Σ deposit snapshot × qty)。
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
}
}作廢一張開錯的租借單
/api/v1/equipment/rentals/{id}/cancel參數
id路徑要取消的租借單 ID
reason必填取消原因(必填;只留在租借單與稽核紀錄,不會印在客人的收據上)
回應欄位 · data
ok取消成功旗標,恆為 true。
reversedReceivableTwd沖銷掉的應收金額(租金 + 押金);訂單本身已取消時為 0。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
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
}
}/api/v1/equipment/rentals/{id}/deliver參數
id路徑回應欄位 · data
okcurl -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
/api/v1/equipment/rentals/{id}/mark-overdue參數
id路徑要標記為逾期的租借單 ID
回應欄位 · data
ok標記逾期成功旗標,恆為 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
}
}/api/v1/equipment/rentals/{id}/reconcile-deposit參數
id路徑回應欄位 · data
okcurl -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
/api/v1/equipment/rentals/{id}/return參數
id路徑要驗收歸還的租借單 ID
returnedLines必填各明細的歸還數量清單
damageCostTwd選填損壞賠償金額(台幣,選填)
回應欄位 · data
ok驗收歸還成功旗標,恆為 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
/api/v1/equipment/rentals/order-options參數
limit選填回傳訂單筆數上限(最多 200,預設取最近多筆)
回應欄位 · data[]
orderId訂單 id。
orderNumber訂單編號(可空)。
customerName訂購人姓名(可空)。
departures這張單報名、且可租借裝備的梯次(issue 240)。通常恰好一個;legacy 匯入的多 line 單 可能多個,開單時要挑一個。 帶出發 / 回程日是為了讓開單表單把**租期預設成梯次日期**(issue #577):租期空著 不只讓清單的日期篩選沒東西可篩,租金還會退回計價 1 日(`computeBillableDays`), 與同一張卡片上印的現場付現估算對不起來。
departureIdlabeldepartureDatereturnDatecurl -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 到梯次
/api/v1/guide-roster/assignments參數
guideStartDate選填帶團開始日期;與結束日期成對,null 回復行程預設
guideEndDate選填帶團結束日期;與開始日期成對
isNameBound選填是否為綁名指派
nameBoundChangeReason選填解除綁名或變更綁名角色的原因
departureId必填指派的目標梯次 ID
guideId必填被指派的嚮導 ID
role必填leaderassistant指派角色(leader 主要隨團人員/assistant 協同)
status必填tentativeconfirmed指派狀態(tentative 預塞暫定/confirmed 正式確認)
回應欄位 · data
id新建立(或重派後)的指派紀錄 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": "…"
}
}移除某筆指派
/api/v1/guide-roster/assignments/{id}參數
id路徑要移除的指派紀錄 ID
nameBoundChangeReason選填移除綁名指派的原因(查詢參數)
回應欄位 · data
ok移除成功旗標,恆為 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
}
}正式確認某筆指派
/api/v1/guide-roster/assignments/{id}/confirm參數
id路徑要正式確認的指派紀錄 ID
回應欄位 · data
ok確認成功旗標,恆為 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
}
}換主要隨團人員
/api/v1/guide-roster/change-leader參數
guideStartDate選填新任主要隨團人員帶團開始日期
guideEndDate選填新任主要隨團人員帶團結束日期
isNameBound選填新任指派是否綁名
nameBoundChangeReason選填變更綁名原因;省略時使用換人原因
departureId必填要換主要隨團人員的目標梯次 ID
fromGuideId選填原主要隨團人員的嚮導 ID(選填;省略表示該梯次原本沒有)
toGuideId必填新任主要隨團人員的嚮導 ID
reason必填換人的原因(必填,記入稽核)
回應欄位 · data
id新任 leader 的指派紀錄 id。
removedGuideIds被移除的舊 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
/api/v1/guide-roster/conflict-check參數
guideStartDate選填預計帶團開始日期;與結束日期成對
guideEndDate選填預計帶團結束日期;與開始日期成對
departureId必填欲指派的目標梯次 ID
guideId必填欲檢查檔期衝突的嚮導 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
/api/v1/guide-roster/conflicts參數
month必填查詢月份(YYYY-MM 格式)
回應欄位 · data[]
guideId發生衝突的嚮導 id。
guideName發生衝突的嚮導姓名。
a衝突梯次之一(含梯次 id/行程名/起訖日)。
departureId梯次 id。
tripTitle行程名稱。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(YYYY-MM-DD)。
b與 a 日期重疊的另一梯次(含梯次 id/行程名/起訖日)。
departureId梯次 id。
tripTitle行程名稱。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(YYYY-MM-DD)。
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
/api/v1/guide-roster/departures參數
month必填查詢月份(YYYY-MM 格式)
includeCancelled選填是否一併納入已取消的梯次(預設不納入)
回應欄位 · data[]
id梯次 id。
tripId所屬行程 id。
tripTitle行程名稱。
tripShortName行程內部簡稱(issue 1414);未填為 null。
label梯次標籤 / 副標(issue 509 ①);null = 無。排班下拉靠它分辨同日兩梯。
groupCode團號(group-code spec §3.3);null = 尚未產生。排班 UI 用它指認梯次。
departureDate出發日(YYYY-MM-DD)。
returnDate回程日(YYYY-MM-DD)。
days帶團天數(含頭尾)。
capacity團位容量(總名額)。
bookedCount已成團報名人數。
status梯次狀態(如 open 開放/full 已滿/cancelled 已取消)。
assignments該梯次所有指派(leader 在前)。
id指派紀錄 id。
guideId被指派的嚮導 id。
guideName被指派的嚮導姓名。
role指派角色:leader 主要隨團人員/assistant 協同。
status指派狀態:tentative 預塞暫定/confirmed 正式確認。
guideStartDateguideEndDateeffectiveStartDateeffectiveEndDateisNameBoundpermitSwappedAt勾「已換領」的時間(ISO);null = 未勾(issue 1731)。
permitSwappedByName勾「已換領」的人的名稱;帳號已刪或未勾時為 null。
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
/api/v1/guide-roster/guides參數
month必填查詢月份(YYYY-MM 格式)
includeInactive選填是否一併列出已停用的嚮導(預設不列出)
回應欄位 · data[]
id嚮導 id。
name嚮導姓名。
rosterRole名冊職能:leader 主要隨團人員/assistant 協同/both 皆可。
specialties可帶路線 / 專長;未設為空陣列。
status嚮導狀態:active 啟用/inactive 停用。
internalNote內部備註(只給後台看,派團時參考);null = 沒填,或檢視者沒有 `guide.read`。
maxDaysPerMonth單一曆月實際帶團天數上限(跨月梯次按實際日期拆分計入各月);NULL = 不限。
monthDays視窗涵蓋月份內 confirmed 指派實際落在月內的帶團天數合計。
monthTrips視窗涵蓋月份內有帶團日的 confirmed 梯次數(每梯只算一次)。
hasTentative視窗涵蓋月份內是否含 tentative(預塞)指派。
availability派生載量狀態:任一涵蓋月達上限即 full。
monthLoads視窗涵蓋的每個曆月的載量(依時間排序)。
month曆月 `YYYY-MM`。
days該月 confirmed 指派實際落在月內的帶團天數。
trips該月有帶團日的 confirmed 梯次數(跨月梯次在兩個月各算一次)。
hasTentative該月是否有 tentative(預塞)指派佔用日期。
availability該月的派生載量狀態。
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
/api/v1/guides參數
slug選填依嚮導公開頁網址代稱(slug)精確查單筆(選填)
status選填allactiveinactive嚮導狀態篩選(all 全部/active 啟用/inactive 停用)
q選填關鍵字搜尋(比對嚮導姓名等欄位)
category選填嚮導分類篩選:分類 ID(gcat_ 開頭,見 guide-categories)
page選填頁碼(從 1 起算)
pageSize選填每頁筆數(上限 200)
curl -X GET "https://your-tenant.example.com/api/v1/guides" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": "…"
}create a guide
/api/v1/guides參數
name必填嚮導姓名
slug選填公開頁網址代稱(選填,英數與連字號;大寫自動轉小寫,省略則由姓名產生)
bio選填嚮導簡介/經歷(選填)
avatarUrl選填大頭照圖片網址(選填,http/https 或本站圖庫資產路徑)
specialties選填專長領域(選填,以逗號分隔多項)
careerStartYear選填入行年份(西元年,1900~今年;選填)。年資由系統推算,回應的 yearsExperience 唯讀
contactPhone選填聯絡電話(選填)
contactEmail選填聯絡 Email(選填)
categoryId選填嚮導分類 ID(gcat_ 開頭;null 為未分類;省略則用第一個啟用中的分類)
status選填activeinactive嚮導狀態(active 啟用/inactive 停用;預設 active)
回應欄位 · data
id新建立的嚮導 id。
slug嚮導公開頁網址代稱(未帶則系統自動產生)。
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
/api/v1/guides/{id}參數
id路徑嚮導 ID
回應欄位 · data
id嚮導 id(guide_ 前綴)。
name嚮導姓名。
slug公開頁網址代稱(slug;小寫英數與連字號)。
bio簡介/經歷(可空)。
avatarUrl大頭照圖片網址(可空)。
specialties專長領域清單。
careerStartYear入行年份(西元年;可空)。
yearsExperience帶團年資(年數;由入行年份與台北今年推算,唯讀;可空)。
contactPhone聯絡電話(可空)。
contactEmail聯絡 Email(可空)。
status嚮導狀態:active 啟用/inactive 停用。
categoryId嚮導分類 id(gcat_ 前綴;名稱與順序見 guide-categories)。null = 未分類。
internalNote內部備註(只給後台看,前台不顯示;可空)。
createdAt建檔時間。
updatedAt最後更新時間。
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
/api/v1/guides/{id}參數
id路徑要更新的嚮導 ID
name選填嚮導姓名(省略則不更動)
slug選填公開頁網址代稱(英數與連字號;大寫自動轉小寫,省略則不更動)
bio選填嚮導簡介/經歷(省略則不更動)
avatarUrl選填大頭照圖片網址(http/https 或本站圖庫資產路徑;省略則不更動)
specialties選填專長領域(以逗號分隔多項;省略則不更動)
careerStartYear選填入行年份(西元年,1900~今年;省略則不更動)。年資由系統推算,回應的 yearsExperience 唯讀
contactPhone選填聯絡電話(省略則不更動)
contactEmail選填聯絡 Email(省略則不更動)
categoryId選填嚮導分類 ID(gcat_ 開頭;null 為未分類;省略則不更動)
status選填activeinactive嚮導狀態(active 啟用/inactive 停用;省略則不更動)
回應欄位 · data
ok更新成功旗標,恆為 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
/api/v1/guides/{id}/archive參數
id路徑要封存(狀態改為停用)的嚮導 ID
回應欄位 · data
ok封存成功旗標,恆為 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.
/api/v1/guides/{id}/certificates參數
id路徑Resource ID
回應欄位 · data[]
idtypeIdtypeNamecertNumber證號(明文)。只給 guide_pii.read 看,其餘讀者由呼叫端清成 null。
issuedOnexpiresOnNULL = 終身有效。
attachmentUrl私有掃描件 URL(/api/assets 以 guide_pii.read 閘讀取)。
hasPii有沒有證號或掃描件。不看 `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
}
]
}/api/v1/guides/{id}/certificates參數
id路徑Resource ID
typeId必填Certificate type ID
issuedOn必填Issue date
expiresOn必填Expiry date; null for lifetime validity
certNumber選填Certificate number; needs guide PII read and manage
回應欄位 · data
okidcurl -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.
/api/v1/guides/{id}/certificates/{certificateId}參數
id路徑Resource ID
certificateId路徑Certificate ID
typeId必填Certificate type ID
issuedOn必填Issue date
expiresOn必填Expiry date; null for lifetime validity
certNumber選填Certificate number; needs guide PII read and manage
回應欄位 · data
okidcurl -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": "…"
}
}/api/v1/guides/{id}/certificates/{certificateId}參數
id路徑Resource ID
certificateId路徑Certificate ID
回應欄位 · data
okcurl -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 登入帳號
/api/v1/guides/{id}/invite-account參數
id路徑要開通登入帳號的嚮導 ID
name必填嚮導帳號的顯示姓名
回應欄位 · data
email已開通登入帳號的 Email(= 嚮導資料的聯絡 Email)。
activationSent是否已寄出啟用信。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
}
}嚮導投保個資
/api/v1/guides/{id}/pii參數
id路徑嚮導 ID
回應欄位 · data
legalName正式姓名。
gender性別 male / female / other;未填為 null。
emergencyContactNameemergencyContactPhoneenglishName英文姓名(與護照一致)。
idNumberMask身分證遮罩(例:*******789);null = 未填。
passportNoMask護照號碼遮罩;null = 未填。
birthDate生日(YYYY-MM-DD)。
nationality國籍;空值 = 本國。
address通訊地址。
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": "…"
}
}寫嚮導個資
/api/v1/guides/{id}/pii參數
id路徑嚮導 ID
legalName選填gender選填emergencyContactName選填emergencyContactPhone選填englishName選填idNumber選填passportNo選填birthDate選填nationality選填address選填回應欄位 · data
changedFields這次實際寫入的欄位。
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"
]
}
}顯示嚮導證件全碼
/api/v1/guides/{id}/pii/reveal參數
id路徑嚮導 ID
field必填idNumberpassportNo欲顯示全碼的證件欄位:idNumber 身分證字號、passportNo 護照號碼
回應欄位 · data
field本次解密的欄位:idNumber 身分證字號 / passportNo 護照號碼。
value解密後的證件全碼;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:上傳檔
/api/v1/guides/import參數
filename必填上傳檔名,副檔名須為 .xlsx 或 .csv
contentBase64必填檔案內容的 base64 編碼字串(上限 5 MB)
回應欄位 · data
filename已匯入的檔名。
result匯入結果(新建 / 更新 / 失敗筆數與逐列結果)。
created新建筆數。
updated更新筆數。
failed失敗筆數(含 dry-run 就是 error 的列)。
rows逐列結果。
rowNumber試算表列號。
statuscreated 已建立 / updated 已更新 / error 失敗未寫入。
guideId寫入的嚮導 id(成功列;部分寫入的失敗列也帶,指出哪位嚮導已被改過)。
name暱稱。
message失敗原因(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:上傳檔
/api/v1/guides/import/validate參數
filename必填上傳檔名,副檔名須為 .xlsx 或 .csv
contentBase64必填檔案內容的 base64 編碼字串(上限 5 MB)
回應欄位 · data
filename已驗證的檔名。
result試算(dry-run)結果(逐列預覽 + 彙總,不寫入)。
rows逐列預覽。
rowNumber試算表列號(含表頭,資料第一列為 2)。
statuscreate 新建 / update 更新既有嚮導 / error 不匯入。
message錯誤原因(多個以「;」串接);非 error 列為 null。
name暱稱。
guideId對到的既有嚮導 id(update 列)。
matchedInactive對到的既有嚮導是停用狀態(更新照做,不會重新啟用)。
legalName正式姓名。
idNumberMask身分證遮罩。
passportNoMask護照遮罩。
birthDate生日(YYYY-MM-DD)。
fields這一列會寫入的欄位(表頭 canonical key)。
summary彙總。
total資料列總數。
create會新建的列數。
update會更新既有嚮導的列數。
error有錯、不匯入的列數。
fileError選填檔案層錯誤(壞檔 / 無表頭 / 超過列數上限);有值時 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": "…"
}
}
}/api/v1/guides/roster-export回應欄位 · data
kindversionexportedAtISO 8601 export time in UTC.
guidesFull tenant directory, including inactive guides. Ordered by stable ID.
idStable guide ID. Use this as the external join key.
statusactive or inactive. Consumers must remove inactive guides from leader choices.
legalNameLegal name. Missing values remain null.
genderStored gender: male, female, or other. Never derived from the ID number.
birthDateISO date: YYYY-MM-DD.
idNumberFull ID number, decrypted with the tenant and guide AAD.
phoneStored contact phone. No format conversion.
emailaddressFull address. The external form adapter must split this value.
emergencyContactNameemergencyContactPhonenicknamePublic 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
/api/v1/journal參數
status選填alldraftpublishedarchived依狀態篩選:all 全部、draft 草稿、published 已發佈、archived 已封存
q選填關鍵字搜尋(標題/內容)
page選填頁碼(從 1 起)
pageSize選填每頁筆數(上限 200)
回應欄位 · data
rows本頁的手記文章列表。
id手記文章 id(journalPost_ 前綴)。
slug文章公開頁網址代稱(slug)。
title文章標題。
excerpt摘要(列表/SEO 用;可空)。
coverImageUrl封面圖網址(可空)。
contentMdx內文原始 MDX 內容。
authorGuideId作者嚮導 id(未指定作者時 null)。
lengthReturns the length of a String object.
seoTitleSEO 標題(覆寫 <title>;可空)。
seoDescriptionSEO 描述(meta description;可空)。
ogImageUrlOpen Graph 分享圖網址(可空)。
status文章狀態:draft 草稿/published 已發佈/archived 已封存。
publishedAt首次發佈時間(尚未發佈為 null)。
createdAt建檔時間。
updatedAt最後更新時間。
total符合條件的文章總數(跨頁)。
page目前頁碼(從 1 起)。
pageSize每頁筆數。
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
/api/v1/journal參數
title必填手記標題,顯示於前台與後台列表
slug選填網址代稱(slug);僅小寫英數與連字號,省略時由系統依標題產生
excerpt選填摘要,列表與分享預覽用;null 清除
coverImageUrl選填封面圖網址(http/https 或本站圖庫資產路徑);null 清除
contentMdx必填內文(MDX 格式)
authorGuideId選填作者嚮導 ID;null 表示無指定作者
seoTitle選填SEO 標題,省略時用 title;null 清除
seoDescription選填SEO 描述(meta description);null 清除
ogImageUrl選填Open Graph 分享圖網址(http/https 或本站圖庫資產路徑);null 清除
status選填draftpublishedarchived發佈狀態:draft 草稿、published 已發佈、archived 已封存
回應欄位 · data
id新建立的手記文章 id。
slug文章公開頁網址代稱(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
/api/v1/journal/{id}參數
id路徑旅誌文章 ID
回應欄位 · data
id手記文章 id(journalPost_ 前綴)。
slug文章公開頁網址代稱(slug)。
title文章標題。
excerpt摘要(列表/SEO 用;可空)。
coverImageUrl封面圖網址(可空)。
contentMdx內文原始 MDX 內容。
authorGuideId作者嚮導 id(未指定作者時 null)。
lengthReturns the length of a String object.
seoTitleSEO 標題(覆寫 <title>;可空)。
seoDescriptionSEO 描述(meta description;可空)。
ogImageUrlOpen Graph 分享圖網址(可空)。
status文章狀態:draft 草稿/published 已發佈/archived 已封存。
publishedAt首次發佈時間(尚未發佈為 null)。
createdAt建檔時間。
updatedAt最後更新時間。
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
/api/v1/journal/{id}參數
title必填手記標題,顯示於前台與後台列表
slug選填網址代稱(slug);僅小寫英數與連字號,省略時由系統依標題產生
excerpt選填摘要,列表與分享預覽用;null 清除
coverImageUrl選填封面圖網址(http/https 或本站圖庫資產路徑);null 清除
contentMdx必填內文(MDX 格式)
authorGuideId選填作者嚮導 ID;null 表示無指定作者
seoTitle選填SEO 標題,省略時用 title;null 清除
seoDescription選填SEO 描述(meta description);null 清除
ogImageUrl選填Open Graph 分享圖網址(http/https 或本站圖庫資產路徑);null 清除
id路徑旅誌文章 ID
status選填draftpublishedarchived發佈狀態:draft 草稿、published 已發佈、archived 已封存;省略時沿用現值
回應欄位 · data
ok更新成功旗標,恆為 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
/api/v1/journal/{id}/archive參數
id路徑旅誌文章 ID
回應欄位 · data
ok封存成功旗標,恆為 true。
curl -X POST "https://your-tenant.example.com/api/v1/journal/<id>/archive" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": true
}
}/rooms
指派旅客進房
/api/v1/rooms/{roomId}/travelers參數
roomId路徑目標房間 ID,旅客將被指派入住此房
travelerId必填欲指派的旅客 ID,須與房間屬於同一梯次
回應欄位 · data
ok指派入房成功旗標,恆為 true。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
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
}
}把旅客移出房間
/api/v1/rooms/travelers/{travelerId}參數
travelerId路徑欲移出房間的旅客 ID
回應欄位 · data
ok移出房間成功旗標,恆為 true。
retentionDeferredtrue = 回訪期間尚未同步,每日排程會補做;本次操作已完成。
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
/api/v1/exchange-rates參數
currency選填幣別篩選(ISO 4217 三碼,如 JPY / USD);省略則回傳所有幣別
monthFrom選填起始月份(YYYY-MM,含當月);省略則不設下界
monthTo選填結束月份(YYYY-MM,含當月);省略則不設上界
回應欄位 · data[]
id匯率牌價列 ID。
rateDate掛牌日期('YYYY-MM-DD',Asia/Taipei)。
currencyISO 4217('JPY' / 'IDR' / 'USD'…)。
cashBuy各報價 canonical「1 外幣 = ? 台幣」(numeric → 字串原值保精度;NULL = 該幣別無此報價)。
cashSell現金賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。
spotBuy即期買入匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。
spotSell即期賣出匯率「1 外幣 = ? 台幣」(字串保精度;null = 無此報價)。
source牌價來源:bot 台銀自動抓取 / manual 租戶手動覆蓋。
createdAt建立時間。
updatedAt最後更新時間。
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
/api/v1/exchange-rates/manual參數
rateDate必填匯率掛牌日期(YYYY-MM-DD),與幣別共同決定覆蓋哪一筆牌價
currency必填幣別(ISO 4217 三碼大寫,如 JPY / USD)
cashBuy選填現金買入匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null
cashSell選填現金賣出匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null
spotBuy選填即期買入匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null
spotSell選填即期賣出匯率(正數最多 6 位小數,以字串表達);四種報價至少填一個,留空傳 null
回應欄位 · data
ok是否覆蓋寫入成功。
id寫入 / 更新的 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 =
/api/v1/exchange-rates/resolve參數
currency必填要換算的外幣幣別(ISO 4217 三碼,如 JPY / USD)
date必填換算基準日期(YYYY-MM-DD),套用手動優先 + 往前承接的解析規則
quote選填cash_buycash_sellspot_buyspot_sell報價類型:cash_buy 現金買入、cash_sell 現金賣出、spot_buy 即期買入、spot_sell 即期賣出;省略預設 spot_sell
回應欄位 · data
currency換算的外幣幣別(ISO 4217 三碼)。
date換算基準日期(YYYY-MM-DD)。
quote使用的報價類型(cash_buy / cash_sell / spot_buy / spot_sell)。
rate解析出的匯率「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 對外應付
/api/v1/payment-requests參數
status選填draftsubmittedapprovedpaidrejectedcancelledall依狀態篩選(draft 草稿 / submitted 已送審 / approved 已核准 / paid 已付款 / rejected 已退件 / cancelled 已取消 / all 全部)
payeeType選填all依收款對象類型篩選(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他 / all 全部)
departureId選填依關聯梯次 id 篩選
createdByUserId選填依建單人 user id 篩選
q選填關鍵字搜尋(請款單號、收款對象名稱等)
page選填頁碼(從 1 起算)
pageSize選填每頁筆數(上限 200)
回應欄位 · data
rows本頁請款單列。
id請款單 ID。
requestNumber請款單號(人可讀,每租戶流水號)。
status核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。
payeeType收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。
payeeName收款對象名稱。
amountTwd請款總額(TWD 整數;= 細項小計合計,代扣稅前)。
netAmountTwd實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。
taxAmountTwd代扣稅額(TWD 整數)。
departureId關聯梯次 ID;未歸屬特定出團為 null。
departureLabel關聯梯次顯示標籤(行程名稱+出發日);無則為 null。
description請款單摘要說明。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單人 user ID。
createdByName建單人姓名;查無為 null。
paidAt標記付款完成時間;未付為 null。
submittedAt送審時間;未送審為 null。
approvedAt核准時間;未核准為 null。
paperSignedBy紙本簽核人;未簽為 null。
total符合篩選條件的總筆數(跨全部分頁)。
page目前頁碼(從 1 起算)。
pageSize每頁筆數。
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
}
}/api/v1/payment-requests參數
payeeType必填supplierguidestaff_commissionother收款對象類型(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他)
payeeName必填收款對象名稱
payeeBankAccount選填收款銀行帳號
payeeBankName選填收款銀行名稱
payeeBankBranch選填收款銀行分行
payeeTaxId選填收款對象統一編號 / 稅籍編號
departureId選填關聯梯次 id(將此請款歸屬至特定出團)
description必填請款單摘要說明
taxAmountTwd選填稅額(TWD),未填視為 0
items必填請款細項陣列(至少一筆)
submitImmediately選填是否建立後立即送審(true 則同交易送出,跳過草稿)
回應欄位 · data
id新建立請款單的 id。
requestNumber新建立請款單的單號(人可讀)。
status建立後狀態(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"
}
}單一對外應付請款單完整明細
/api/v1/payment-requests/{id}參數
id路徑請款單 id(路徑參數)
回應欄位 · data
payeeBankAccount收款銀行帳號。
payeeBankName收款銀行名稱。
payeeBankBranch收款銀行分行。
payeeTaxId收款對象統一編號 / 稅籍編號。
submittedByUserId送審人 user ID;未送審為 null。
submissionEventIdAudit event for the current submission.
submittedByName送審人姓名;無則為 null。
approvedByUserId核准人 user ID;未核准為 null。
approvedByName核准人姓名;無則為 null。
paidByUserId標記付款人 user ID;未付為 null。
paidByName標記付款人姓名;無則為 null。
rejectedAt退件時間;未退件為 null。
rejectedByName退件人姓名;無則為 null。
rejectionReason退件原因;無則為 null。
cancelledAt取消時間;未取消為 null。
cancelledByName取消人姓名;無則為 null。
cancellationReason取消原因;無則為 null。
pdfGeneratedAt請款單 PDF 產生時間;未產生為 null。
paperPrintedAt紙本列印時間;未列印為 null。
bankReference銀行匯款交易參考號(付款後回填);無則為 null。
sourceType來源類別(`departure_cost` 梯次成本 / `profit_share` 折扣碼分潤 / `migration` 匯入); 手動建單為 null。**非 null = 細項與來源列連動,不可編輯**(見 `updatePaymentRequest`)。
items請款細項清單。
id請款細項 ID。
category細項類別(如住宿、交通、餐食)。
description細項說明。
quantity數量。
unitPriceTwd單價(TWD 整數;負值表折讓)。
totalTwd細項小計(TWD 整數;= 數量 × 單價)。
notes細項備註;無則為 null。
sortOrder顯示排序(由小到大)。
audit稽核軌跡(狀態機每次轉移一筆,時間新到舊或建立序)。
id稽核記錄 ID。
action動作代號(如 payable.create、payable.submit、payable.approve)。
createdAt動作發生時間。
actorUserId操作者 user ID;系統動作為 null。
actorName操作者姓名;無則為 null。
metadata動作附帶的結構化資料(欄位隨 action 而定)。
ipAddress操作來源 IP;無則為 null。
id請款單 ID。
requestNumber請款單號(人可讀,每租戶流水號)。
status核簽工作流狀態:draft / submitted / approved / paid / rejected / cancelled。
payeeType收款對象類型:supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他。
payeeName收款對象名稱。
amountTwd請款總額(TWD 整數;= 細項小計合計,代扣稅前)。
netAmountTwd實付淨額(TWD 整數;= 請款總額 − 代扣稅額,即實際匯款金額)。
taxAmountTwd代扣稅額(TWD 整數)。
departureId關聯梯次 ID;未歸屬特定出團為 null。
departureLabel關聯梯次顯示標籤(行程名稱+出發日);無則為 null。
description請款單摘要說明。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單人 user ID。
createdByName建單人姓名;查無為 null。
paidAt標記付款完成時間;未付為 null。
submittedAt送審時間;未送審為 null。
approvedAt核准時間;未核准為 null。
paperSignedBy紙本簽核人;未簽為 null。
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": "…"
}
}/api/v1/payment-requests/{id}參數
id路徑請款單 id(路徑參數)
payeeType必填supplierguidestaff_commissionother收款對象類型(supplier 供應商 / guide 領隊嚮導 / staff_commission 員工獎金 / other 其他)
payeeName必填收款對象名稱
payeeBankAccount選填收款銀行帳號;null 清空
payeeBankName選填收款銀行名稱;null 清空
payeeBankBranch選填收款銀行分行;null 清空
payeeTaxId選填收款對象統一編號 / 稅籍編號;null 清空
departureId選填關聯梯次 id;null 清空
description必填請款單摘要說明
taxAmountTwd選填代扣稅額(TWD);省略則不動
items選填請款細項陣列(整批取代);省略則不動細項
回應欄位 · data
ok是否更新成功。
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
}
}核准請款單
/api/v1/payment-requests/{id}/approve參數
id路徑請款單 id(路徑參數)
operationId必填同次操作重試須沿用的識別
expectedSubmissionId必填明細回傳的 submissionEventId
回應欄位 · data
ok原核准操作已完成;重試不代表目前狀態。
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
}
}取消請款單
/api/v1/payment-requests/{id}/cancel參數
id路徑請款單 id(路徑參數)
reason選填取消原因;留空預設為「使用者取消」(上限 200 字)
回應欄位 · data
ok是否取消成功(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
}
}標記請款單已付
/api/v1/payment-requests/{id}/mark-paid參數
id路徑請款單 id(路徑參數)
bankReference必填網銀交易序號 / 轉帳憑證號(必填)
paperSignedBy選填紙本簽核人姓名
receivingAccountId選填出款帳戶 id(從哪個收款帳戶付出)
回應欄位 · data
ok是否標記付款成功(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/紙本已產生
/api/v1/payment-requests/{id}/mark-printed參數
id路徑請款單 id(路徑參數)
回應欄位 · data
ok是否標記 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
}
}記錄紙本簽核人
/api/v1/payment-requests/{id}/mark-signed參數
id路徑請款單 id(路徑參數)
signedBy必填紙本簽核人姓名(必填)
回應欄位 · data
ok是否記錄紙本簽核人成功。
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
}
}退回請款單
/api/v1/payment-requests/{id}/reject參數
id路徑請款單 id(路徑參數)
operationId必填同次操作重試須沿用的識別
expectedSubmissionId必填明細回傳的 submissionEventId
reason必填退件原因(必填,回饋給建單人)
回應欄位 · data
ok原退回操作已完成;重試不代表目前狀態。
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
}
}送審請款單
/api/v1/payment-requests/{id}/submit參數
id路徑請款單 id(路徑參數)
operationId必填同次操作重試須沿用的識別
回應欄位 · data
ok原送審操作已完成;重試不代表目前狀態。
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 計數
/api/v1/payment-requests/stats回應欄位 · data
draftCount草稿狀態的請款單數。
submittedCount已送審待核准的請款單數。
approvedCount已核准待付款的請款單數。
paidCount已付款的請款單數。
thisMonthPaidCount本月已付款的請款單數。
thisMonthAmount本月已付款的實付淨額合計(TWD 整數;台北月起算)。
totalApprovedAmount已核准未付的實付淨額合計(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
}
}由某梯次的
/api/v1/payment-requests/supplier-suggestions參數
departureId必填梯次 id;用於推導該梯次住宿供應商的請款細項建議
回應欄位 · data[]
category建議的請款細項類別(如住宿)。
description建議的細項說明(住宿廠商 × 房型 × 晚數)。
quantity建議數量(間數 × 晚數)。
unitPriceTwd建議單價(TWD 整數;每間每晚成本)。
totalTwd建議小計(TWD 整數;= 數量 × 單價)。
suggestedPayee建議的收款對象(住宿供應商名稱);查無為 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
/api/v1/payments參數
departureId選填依梯次 ID 篩選
status選填依金流狀態篩選(paid 已收款 / pending 待付 / failed 失敗或逾期 / refunded 已退款 / needs_manual_review 需人工核對退款)
method選填依付款方式篩選(如信用卡、ATM 轉帳)
dateFrom選填收款日期區間起日(YYYY-MM-DD)
dateTo選填收款日期區間迄日(YYYY-MM-DD)
q選填關鍵字搜尋(訂單編號、客戶名稱等)
page選填頁碼(從 1 起算)
pageSize選填每頁筆數(上限 200)
回應欄位 · data
rows本頁付款嘗試列。
reconciliationTransactionsidamountTwdaccountNamestatusid付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。
orderId所屬訂單 ID。
orderNumber所屬訂單編號(人可讀)。
merchantTradeNoprovider_order_ref(= 我們產的 MerchantTradeNo)。
providerTradeNo金流商回傳的交易序號(未成交或手動入帳為 null)。
provider金流商代號(如 ecpay、test;手動入帳為 manual)。
paymentMethod付款方式(如信用卡、ATM 虛擬帳號)。
amountTwd此筆嘗試的金額(TWD 整數)。
purpose收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。
receivingAccountName錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。
statusattempt 狀態:pending | submitted | succeeded | failed | expired。
refunded此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。
needsManualReview此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。
paidAt實際入帳(現金結算)時間;未結算為 null。
bankCreditedOn銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。
createdAt此筆付款嘗試的建立時間。
customerName付款客戶姓名。
customerEmail付款客戶 email。
tripTitle訂單對應的行程名稱。
total符合篩選條件的總筆數(跨全部分頁)。
page目前頁碼(從 1 起算)。
pageSize每頁筆數。
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
}
}匯出金流分類帳
/api/v1/payments/export參數
status選填依金流狀態篩選(如 paid 已收款 / pending 待付 / failed 失敗 / refunded 已退款)
method選填依付款方式篩選(如信用卡、ATM 轉帳)
dateFrom選填收款日期區間起日(YYYY-MM-DD)
dateTo選填收款日期區間迄日(YYYY-MM-DD)
q選填關鍵字搜尋(訂單編號、客戶名稱等)
回應欄位 · data
rows符合篩選條件的所有列(逐頁累積;達安全上限時截斷)。
reconciliationTransactionsidamountTwdaccountNamestatusid付款嘗試或舊收款明細 ID。舊明細 ID 不可用於金流商操作。
orderId所屬訂單 ID。
orderNumber所屬訂單編號(人可讀)。
merchantTradeNoprovider_order_ref(= 我們產的 MerchantTradeNo)。
providerTradeNo金流商回傳的交易序號(未成交或手動入帳為 null)。
provider金流商代號(如 ecpay、test;手動入帳為 manual)。
paymentMethod付款方式(如信用卡、ATM 虛擬帳號)。
amountTwd此筆嘗試的金額(TWD 整數)。
purpose收款類別(payment intent 的 purpose):full 全額 / deposit 訂金 / balance 尾款 / adjustment 補收。
receivingAccountName錢入帳的收款帳戶顯示名(最近一筆入帳現金列的 receiving_account_id);未入帳或未綁帳戶為 null。
statusattempt 狀態:pending | submitted | succeeded | failed | expired。
refunded此 attempt 是否關聯到任何退款 / 退單交易(out 方向)。
needsManualReview此 attempt 收到過「已驗簽但不可入帳」的付款回呼:錢在金流商手上,系統沒有現金列, 需要人工核對後退款。
paidAt實際入帳(現金結算)時間;未結算為 null。
bankCreditedOn銀行入帳日期(YYYY-MM-DD):登記收款選銀行帳戶時填的日期,與 `paidAt` 取自同一筆入帳列。 金流收款、未結算或沒填時為 null。
createdAt此筆付款嘗試的建立時間。
customerName付款客戶姓名。
customerEmail付款客戶 email。
tripTitle訂單對應的行程名稱。
total符合篩選條件的總筆數。
truncated是否因達安全上限而截斷(true 表未回傳完整結果,呼叫端應提示)。
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
/api/v1/payments/stats回應欄位 · data
pendingReconciliationCounttotalAmount累計實收現金(payment_transactions in)。
paidCount已成功收款的付款嘗試數。
paidEcpayCount已成功收款裡走綠界(provider = ecpay)的嘗試數。
paidAtmCount已成功收款裡走虛擬 ATM(method = atm)的嘗試數。
pendingCount待付 / 處理中的付款嘗試數(pending、submitted)。
failedCount失敗或逾期的付款嘗試數(failed、expired)。
refundedCount有關聯退款 / 退單的付款嘗試數。
needsManualReviewCount近期需要人工核對後退款的付款嘗試數。只算最近 90 天收到的異常回呼;更早的紀錄仍會 帶著 `PaymentRow.needsManualReview`,用 `status=needs_manual_review` 篩選查得到。
thisMonthAmount本月累計實收現金(TWD 整數)。
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
逐收款帳戶現金進出對帳
/api/v1/reconciliation/accounts參數
dateFrom選填對帳期間起日(YYYY-MM-DD,含當日),以 Asia/Taipei 牆鐘日界計;省略則不設下界
dateTo選填對帳期間迄日(YYYY-MM-DD,含整日),以 Asia/Taipei 牆鐘日界計;省略則不設上界
回應欄位 · data[]
accountId收款帳戶 id;null = 未歸戶桶。
code帳戶代碼;未歸戶桶為 null。
displayName帳戶顯示名;未歸戶桶為 null。
kind帳戶類型(bank / cash / gateway);未歸戶桶為 null。
inTwd期間內 direction='in' 的金額合計。
outTwd期間內 payment_transactions direction='out' 的金額合計(客戶退款 / gateway 出)。
payableOutTwd期間內供應商出款合計(payables paid 的 net_amount_twd;非 order-scoped,獨立來源 §3.1)。 **不含掛出款批次的 payable**(payout_batch_line_id 非 NULL)——批次出帳事實是一筆 account_transfers(銀行一筆 net),個別 payable 再計入即雙計。
transferInTwd期間內帳戶間移轉**轉入**合計(account_transfers to 端 amount_twd;spec §3.2 / §3.3 口徑)。 排除 refund_payout(markRefundPaid 同 tx 雙寫,現金列已計入 outTwd)與沖正列 / 被沖正列 (更正記錄,非銀行流水)。
transferOutTwd期間內帳戶間移轉**轉出**合計(from 端 amount_twd + fee_twd 實際離帳額;同上排除規則)。
netTwd淨額 = in + transferIn − out − payableOut − transferOut(純現金流向;對帳找銀行入帳用毛額)。
txCount期間內這帳戶的活動筆數(payment_transactions + payables paid + 移轉兩側)。
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
}
]
}未結掛帳追蹤
/api/v1/reconciliation/obligations參數
period選填月結來源期間(YYYY-MM),篩選由該期月結互抵推導出的掛帳;省略則不限期間
reason選填掛帳原因代碼,篩選特定成因的掛帳;省略則不限原因
status選填掛帳狀態(如未結清 / 已結清),篩選特定結清狀態;省略則含全部
回應欄位 · data[]
id帳戶間掛帳 ID。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補目標總額(TWD 整數,恆正)。
settledAmountTwd已結清金額(TWD 整數,0 ≤ settled ≤ amount)。
outstandingTwd待結餘額(派生 = amount − settled,>= 0)。
reason掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份(YYYY-MM,Asia/Taipei)。
status結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註;無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}收款帳戶目錄清單
/api/v1/reconciliation/receiving-accounts參數
activeOnly選填是否只回傳啟用中的收款帳戶(true/false);省略則含停用
回應欄位 · data[]
id收款帳戶 ID。
code帳戶代碼(租戶內唯一穩定識別)。
displayName帳戶顯示名。
kind帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。
gatewayProvider綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `payment/gateway-providers.ts`。
bankName銀行名稱;現金/閘道帳戶為 null。
accountNo銀行帳號;現金/閘道帳戶為 null。
bankCodebankBranchaccountHoldercanReceive可收款(幾乎都 true)。
canRemit可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。
canChargeback可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。
canPaySupplier付款渠道:出團準備的付款登記區可選它付供應商(#1375)。
isDeprecated廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。
isSettlementMaster主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。
payoutAccountId撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。
currency帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位(小者在前)。
usedCount被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。
currencyLocked幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}退款執行清單
/api/v1/reconciliation/refund-executions參數
status選填approvedpaid退款狀態篩選:approved 待執行(已核准)、paid 已執行(已出款);省略則合併回傳兩者
回應欄位 · data
rows退款執行列(合併 approved 待執行 + paid 已執行,或收斂為指定段)。
creationSourceid退款單 ID。
refundNumber退款單號(人可讀,每租戶流水號)。
orderId所屬訂單 ID。
orderNumber所屬訂單編號(人可讀);無則為 null。
status退款工作流狀態:draft / submitted / approved / processing / paid / failed / cancelled。
refundKind退款種類:receivable_reduction 減應收退款(取消 / 降價 / 服務失敗)/ overpayment_return 溢收退還(不動應收,只退多收現金)。
affectsReceivable是否減少應收(receivable_reduction 為 true、overpayment_return 為 false;溢收退還不列入 refund_state)。
amountTwd退款金額(TWD 整數,正值)。
method退款方式:original_gateway 原路退刷 / bank_transfer 銀行匯款 / cash 現金 / manual 手動。
reason退款原因說明。
createdAt退款單建立時間。
paidAt實際退款出款(現金結算)時間;未執行為 null。
createdByName建單人姓名;無則為 null。
executionMethod退款執行方法:chargeback 原信用卡刷退 / remit 匯出;未指定為 null。
gatewayExecutionMode選填gatewayNeedsReview近 90 天已完成帳務、且明確記錄自動退刷降級的退款,需人工核對;不代表可重試。
originAccountId出款來源帳戶 ID(從哪個收款帳戶退出);未指定為 null。
adminFeeTwd內扣手續費(TWD 整數;自退款金額中扣除的行政費)。
remitFeeTwd匯款手續費(TWD 整數;銀行匯出的轉帳費)。
payeeAccountName收款人戶名(匯款退款用);無則為 null。
payeeBankCode收款銀行代碼(匯款退款用);無則為 null。
payeeBranchCode收款分行代碼(匯款退款用,選填);無則為 null。
payeeAccountNumber收款帳號(匯款退款用);無則為 null。
customerName訂購人姓名;無則為 null。
orderCancellationFeeTwd所屬訂單的退改費(TWD 整數,公司收下不退的錢);未收退改費為 null。不含已付、不退的 換梯手續費(customer-cancellation §8.9),那筆寫在退款單事由。
orderCancellationReason所屬訂單的取消事由:lottery_lost 未中籤 / group_not_confirmed 未成團 / customer_request 客人取消 / admin 後台取消 / no_show 未報到 / other 其他;未取消為 null。
paidByName標記已退款的人;未執行為 null。
payoutAccountId實際出款帳戶 ID(已執行退款的出帳現金列歸戶);未執行或未歸戶為 null。
waitingDays從登記到現在已等待的天數;已退款、已失敗、已取消的退款單為 null。
total回傳的退款執行筆數。
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 月結互抵派生總覽
/api/v1/reconciliation/settlement-overview參數
period必填要查詢月結互抵總覽的結算期(YYYY-MM)
回應欄位 · data
period結算月份(YYYY-MM,Asia/Taipei)。
matrix兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。
lines各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補淨額(恆正 > 0)。
components組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。
label組成項標籤(如某費用類型 / 代墊來源)。
amountTwd簽名金額(相對 debtor→creditor 視角)。
unclassified未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。
byAccountlanding 帳戶 → 未分類本金合計。
accountId收款帳戶 ID;未歸戶為 null。
principalTwd該帳戶未分類收款本金合計(TWD 整數)。
totalTwd未分類收款本金總額(TWD 整數)。
obligations本期相關掛帳(period_settlement + adjustment,含結清進度)。
id帳戶間掛帳 ID。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補目標總額(TWD 整數,恆正)。
settledAmountTwd已結清金額(TWD 整數,0 ≤ settled ≤ amount)。
outstandingTwd待結餘額(派生 = amount − settled,>= 0)。
reason掛帳成因:period_settlement 月結互抵 / advance_repayment 代墊償還 / refund_advance 退款代墊 / adjustment 手動調整。
originPeriod產生月份(YYYY-MM,Asia/Taipei)。
status結清狀態:outstanding 未結 / partially_settled 部分結清 / settled 已結清。
note備註;無則為 null。
createdAt建立時間。
updatedAt最後更新時間。
carriedForward跨期掛帳結轉基數(上期未結 period_settlement 殘額,已種入 matrix 淨額;此處供顯示明細 + 小計)。
lines上期未結 period_settlement 殘額逐筆明細(已種入本期互抵基數)。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
outstandingTwd殘額 = amount_twd − settled_amount_twd(恆正 > 0)。
originPeriod原始產生月份(YYYY-MM,供顯示「來源期」)。
totalTwd結轉殘額小計(TWD 整數)。
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
/api/v1/reconciliation/settlement/compute參數
period必填要計算月結互抵的結算期(YYYY-MM),可重跑且冪等(不回退已結額)
回應欄位 · data
period結算月份(YYYY-MM,Asia/Taipei)。
matrix兩層互抵矩陣(各帳戶對主結算帳戶的有向淨額 + 未分類彙總)。
lines各帳戶對主結算帳戶(或其類別 final)的有向淨額;恆正、方向由 debtor/creditor。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
amountTwd應補淨額(恆正 > 0)。
components組成展開(給 UI;簽名相對 debtor→creditor 視角,正 = 加重該方向,負 = 反向抵減)。
label組成項標籤(如某費用類型 / 代墊來源)。
amountTwd簽名金額(相對 debtor→creditor 視角)。
unclassified未分類(未標費用類型)收款彙總,不進互抵,供 UI 提示補 tag。
byAccountlanding 帳戶 → 未分類本金合計。
accountId收款帳戶 ID;未歸戶為 null。
principalTwd該帳戶未分類收款本金合計(TWD 整數)。
totalTwd未分類收款本金總額(TWD 整數)。
upserts本次 run 對每條互抵列 upsert 的結果(含冪等護欄調整)。
debtorAccountId欠款方(債務人)收款帳戶 ID。
creditorAccountId收款方(債權人)收款帳戶 ID。
derivedAmountTwd本次派生的目標淨額。
appliedAmountTwd實際落地的掛帳 amount_twd(受冪等護欄約束,不低於已 settled)。
obligationId對應的帳戶間掛帳 ID(本次 upsert 的目標列)。
action本次動作:created 新建 / updated 更新 / floored_to_settled 派生低於已結被護欄下限鎖住。
adjustmentTwd派生與基準(原 amount + 已動帳 adjustment 簽名和)的差額絕對值(> 0 表示有缺口)。
adjustmentObligationId缺口對應的引擎 adjustment 掛帳 id(新開或重跑沿用 / 改額的同一條;action='floored_to_settled' 時非 null)。
deletedObligationIds本次 run 刪除的失效派生掛帳 id(settled=0 且不在新派生的 period_settlement + 被替換 / 失效的未結引擎 adjustment)。
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": [
"…"
]
}
}/api/v1/reconciliation/statement-imports參數
account必填收款帳戶 ID,回傳該帳戶的對帳單批次 / 行 / 進度彙總
回應欄位 · data
imports該帳戶的對帳單批次清單(新到舊)。
id對帳單批次 ID。
periodStart批次期間起日('YYYY-MM-DD',含當日)。
periodEnd批次期間迄日('YYYY-MM-DD',含當日)。
filename匯入的檔名。
createdAt匯入時間。
lineCount批內總行數。
autoCount自動配對的行數。
manualCount人工配對的行數。
unmatchedCount尚未配對的行數。
ignoredCount已略過(ignored)的行數。
excludedCount已解除配對(excluded)的行數。
lines該帳戶所有對帳單行(跨批次)。
id對帳單行 ID。
importId所屬對帳單批次 ID。
lineNo檔案內行號(1 起算)。
txnDate交易日期('YYYY-MM-DD')。
direction現金流向:in 存入 / out 支出。
amountTwd金額(TWD 整數)。
memo摘要 / 備註文字。
status配對狀態:unmatched 未配 / auto 自動 / manual 人工 / ignored 略過 / excluded 已解除。
matchedSourceType已配對來源種類(payment_transaction / payable / account_transfer);未配為 null。
matchedSourceId已配對來源 ID;未配為 null。
ignoredReason略過原因;非 ignored 為 null。
progress配對進度彙總。
total總行數。
matched已配對行數(auto + manual)。
unmatched未配對行數。
ignored已略過行數。
excluded已解除配對行數。
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
}
}
}/api/v1/reconciliation/statement-imports參數
receivingAccountId必填收款帳戶 ID(僅支援 TWD 的 bank / cash 帳戶)
periodStart必填對帳單期間起日(含當日)
periodEnd必填對帳單期間迄日(含當日)
filename必填上傳檔名,副檔名須為 .xlsx 或 .csv
contentBase64必填對帳單檔案內容的 base64 編碼字串(固定範本填好後另存)
回應欄位 · data
importId新建立的對帳單批次 ID。
autoMatched匯入後即自動配對成功的行數。
unmatched匯入後仍未配對的行數。
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
}
}刪整批
/api/v1/reconciliation/statement-imports/{importId}參數
importId路徑對帳單批次 ID
回應欄位 · data
ok是否刪除整批成功(批內無人工痕跡才可刪)。
curl -X DELETE "https://your-tenant.example.com/api/v1/reconciliation/statement-imports/<importId>" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": true
}
}對該批
/api/v1/reconciliation/statement-imports/{importId}/auto-match參數
importId路徑對帳單批次 ID
回應欄位 · data
matched本輪新增自動配對的行數。
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
}
}某帳戶內、未被
/api/v1/reconciliation/statement-imports/candidates參數
account必填收款帳戶 ID,回傳該帳戶未配對的 ERP 現金流水候選
回應欄位 · data[]
sourceTypeERP 來源種類:payment_transaction 收款交易 / payable 出款 / account_transfer 帳戶移轉。
sourceIdERP 來源紀錄 ID。
date'YYYY-MM-DD'(Asia/Taipei 牆鐘日)。
direction現金流向:in 進帳 / out 出帳。
amountTwd金額(TWD 整數)。
label顯示標籤(來源摘要,供人工配對時辨識)。
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": "…"
}
]
}銀行對帳單匯入固定範本下載
/api/v1/reconciliation/statement-imports/template回應欄位 · data
filename建議另存的檔名(.xlsx,含日期戳)。
contentBase64範本 .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
/api/v1/reconciliation/statement-imports/validate參數
receivingAccountId必填收款帳戶 ID(僅支援 TWD 的 bank / cash 帳戶)
periodStart必填對帳單期間起日(含當日)
periodEnd必填對帳單期間迄日(含當日)
filename必填上傳檔名,副檔名須為 .xlsx 或 .csv
contentBase64必填對帳單檔案內容的 base64 編碼字串
回應欄位 · data
accountId對帳的收款帳戶 ID。
periodStart對帳單期間起日('YYYY-MM-DD',含當日)。
periodEnd對帳單期間迄日('YYYY-MM-DD',含當日)。
filename上傳檔名。
lines解析後的各行預覽(含「若 commit 是否會被自動配對」)。
lineNo檔案內行號(1 起算)。
txnDate交易日期('YYYY-MM-DD')。
direction現金流向:in 存入 / out 支出。
amountTwd金額(TWD 整數)。
memo摘要 / 備註文字。
willAuto依本批行與目前候選估算的配對結果;不保證未來 commit 結果。
parseErrors解析錯誤 + 期間外的行(依行號排序;commit 端會 fail-closed 拒)。
lineNo出錯的對帳單行號(原始列,從 1 起算)。
message錯誤說明(解析失敗原因或期間外提示)。
willAutoCount若現在 commit,預計會被自動配對的行數。
willUnmatchedCount若現在 commit,預計仍未配對的行數。
periodOverlap宣告期間是否與既有批次重疊(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
}
}略過一條對帳單行 →
/api/v1/reconciliation/statement-lines/{lineId}/ignore參數
lineId路徑對帳單行 ID
reason必填略過原因(必填;如「手續費」「利息」)
回應欄位 · data
ok是否標記略過成功(狀態轉為 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
}
}人工配對一條對帳單行到指定
/api/v1/reconciliation/statement-lines/{lineId}/match參數
lineId路徑對帳單行 ID
sourceType必填payment_transactionpayableaccount_transfer配對來源種類:payment_transaction / payable / account_transfer
sourceId必填配對來源 ID(該帳戶內未被配對的 ERP 候選)
回應欄位 · data
ok是否人工配對成功(同帳戶 / 同金額 / 同方向)。
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'
/api/v1/reconciliation/statement-lines/{lineId}/unmatch參數
lineId路徑對帳單行 ID
回應欄位 · data
ok是否解除配對成功(狀態轉為 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
}
}帳戶間移轉統一分類帳查詢
/api/v1/reconciliation/transfers參數
kind選填移轉類型篩選(fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 外幣期初 / reversal 沖正 / payout_batch 出款批次匯出 / gateway_payout 金流商撥款);省略則含全部
account選填帳戶 ID 篩選,回傳該帳戶為出帳或進帳方的移轉;省略則不限帳戶
dateFrom選填移轉日期起日(YYYY-MM-DD,含當日);省略則不設下界
dateTo選填移轉日期迄日(YYYY-MM-DD,含當日);省略則不設上界
settlementPeriod選填對應月結期間(YYYY-MM)篩選;省略則不限月結
obligation選填掛帳 ID 篩選,回傳沖減該筆掛帳的移轉;省略則不限掛帳
回應欄位 · data[]
id帳戶間移轉 ID。
kind移轉類型:fx_conversion 換匯 / replenishment 補款 / advance 代墊 / backfill 回填 / refund_payout 退款匯出 / opening 期初 / reversal 沖正 / payout_batch 出款批次匯出(系統落帳)/ gateway_payout 金流商撥款。
fromAccountId出帳帳戶 ID;期初等單邊移轉為 null。
toAccountId進帳帳戶 ID;單邊移轉為 null。
amountTwd移轉金額(TWD 整數)。
feeTwd手續費(TWD 整數)。
currency外幣幣別(ISO 4217;純台幣移轉為 null)。
foreignAmount外幣金額(整數;非外幣移轉為 null)。
feeForeign外幣手續費(整數;無則為 null)。
grossRate換匯牌價(numeric → 字串原值保精度;顯示/溯源用)。
settlementPeriod對應月結期間(YYYY-MM);未歸屬月結為 null。
obligationId沖減的帳戶間掛帳 ID;未沖減掛帳為 null。
reversesTransferId被本筆沖正的原移轉 ID(kind='reversal' 時非 null)。
occurredAt移轉日期('YYYY-MM-DD',date 欄)。
note備註;無則為 null。
createdByUserId登錄人 user ID。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/reconciliation/transfers參數
kind選填fx_conversionreplenishmentadvancebackfillgateway_payoutreversal移轉類型:fx_conversion 換匯、replenishment 補款、advance 代墊、backfill 回填、gateway_payout 金流商撥款、reversal 沖正(退款匯出 / 出款批次由退款 / 出款模組落帳,不由此登錄)
fromAccountId選填出帳(轉出)帳戶 ID;與進帳帳戶至少填一個,null 表示無出帳方
toAccountId選填進帳(轉入)帳戶 ID;與出帳帳戶至少填一個,null 表示無進帳方
amountTwd選填移轉台幣淨額(整數,不可為負);沖減掛帳時須大於 0。金流商撥款填銀行實際入帳的撥款額
feeTwd選填此筆移轉產生的手續費(台幣整數,不可為負)。金流商撥款填金流商從撥款內扣的手續費
occurredAt選填移轉發生日期(YYYY-MM-DD)
settlementPeriod選填對應月結期間(YYYY-MM),標記此移轉沖減哪一期互抵;換匯不掛單一月結,傳 null
currency選填換匯外幣幣別(ISO 4217 三碼);非換匯傳 null
foreignAmount選填換匯外幣金額(整數最小單位,須大於 0);非換匯傳 null
grossRate選填換匯牌價(正數,最多 6 位小數,以字串表達避免精度遺失);非換匯傳 null
obligationId選填選填沖減的掛帳 ID(aob_ 開頭);換匯不沖減掛帳須傳 null
reversesTransferId選填沖正指向的原移轉 ID(atr_ 開頭);kind=reversal 必填,其餘傳 null
paymentTransactionIds選填金流商撥款包含的現金列 ID(ptxn_ 開頭):收款為加項、同帳戶的刷退為扣項;kind=gateway_payout 必填且至少一筆收款,須滿足「收款合計 − 刷退合計 − 手續費 = 撥款額」,其餘傳 null
回應欄位 · data
ok是否登錄成功(移轉 + 沖減掛帳的原子交易皆完成)。
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
}
}某金流商帳戶上
/api/v1/reconciliation/transfers/gateway-payout-candidates參數
account必填金流商(gateway)帳戶 ID,回傳該帳戶還沒被撥出的收款與刷退
回應欄位 · data[]
paymentTransactionId現金列 ID。
directionin = 收款(加項)/ out = 刷退(撥款內扣的扣項)。
orderId訂單 ID。
orderNumber訂單編號。
date發生日('YYYY-MM-DD',Asia/Taipei 牆鐘)。
amountTwd金額(TWD 整數,正數;刷退的正負看 direction)。
feeTwd現金列記的金流手續費(TWD 整數;多為付款回呼宣告的估計值)。
providerTradeNo金流訂單編號(金流商交易序號,或登記收款時填的編號;沒有為 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
掛帳台帳
/api/v1/accrual-ledger參數
period必填出團月(格式 YYYY-MM,Asia/Taipei 時區)
回應欄位 · data
period結算期間(YYYY-MM,Asia/Taipei 出團月)。
departureSummary梯次彙總(區塊 1):出團月落於 period 的各梯次收入 / 成本 / 毛利。
departureId梯次 ID。
tripTitle團名。
departureDate出團日期(YYYY-MM-DD)。
pax出團人數(該梯次確認人數)。
revenueTwd總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。
cancellationFeeTwd已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。
realCostTwd真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。
grossProfitTwd毛利毛估 = revenue − realCost(含房費)。
costLines成本掛帳逐筆(區塊 2):該期梯次上所有 departure_costs 成本列。
id成本列 ID。
tripTitle團名。
departureDate所屬梯次出團日期(YYYY-MM-DD)。
category成本分類(如 交通 / 餐費 / 保險 / 嚮導)。
vendor廠商:已建檔廠商名優先,否則用成本列上填寫的廠商名;null = 未填。
amountTwd代墊額(真實成本,TWD 整數)。
invoiceAmountTwd憑證額(外帳可申報金額,TWD 整數)。
isDeclarable有無發票憑證。
reviewStatus覆核狀態:掛了支出證明單則用其 status(pending/approved),否則由有無憑證派生。
payables應付清單(區塊 3):該期歸屬的請款單(payables)。
payableNumber請款單號(人類可讀)。
tripTitle團名(未綁定梯次的手動請款顯示「未綁定梯次」)。
payeeName受款對象(供應商 / 嚮導 / 派車人等)。
amountTwd請款金額(整數 TWD)。
statusdraft | submitted | approved | paid | cancelled | rejected。
receivables應收清單(區塊 4):該期梯次上的 tour 訂單應收 / 實收 / 待收。
orderId訂單 ID(後台訂單頁連結用)。
orderNumber訂單編號。
tripTitle團名(該訂單在期間內任一梯次的團名)。
departureDate出團日(YYYY-MM-DD)。同一行程同月常有多個梯次(例:10/15、10/16、10/22 三梯), 只看團名分不出是哪一梯,追尾款時得靠這欄(issue 600)。 ⚠️ 與 `tripTitle` 同一列取出(兩欄必定同梯),但口徑同樣是「該訂單在期間內**任一** 梯次」:跨梯次訂單只顯示最早那一梯,而 `receivableTwd` 是整張單未攤提的應收。真正 逐梯辨識要把來源改成 per (order, departure) 並接上 `orders/allocation.ts` 的攤提, 屬系統級 follow-up,不在本欄範圍。
primaryTravelerName主要旅客姓名:有標記 `is_primary` 取該列,沒標記就取最早建立的旅客(與 departure-prep / agreements / traveler-validation 同一套取法——匯入的歷史單 可能整單都沒標主要旅客)。訂單完全沒有旅客列時為 null。 刻意不取下單會員名:一張訂單的下單者與旅客常常不是同一人(CONTEXT.md「旅客」)。
receivableTwd應收金額(TWD 整數)。
receivedTwd實收金額(收款減退款,TWD 整數)。
outstandingTwd待收 = 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
}
]
}
}掛帳台帳的「梯次彙總」
/api/v1/accrual-ledger/departure-summary參數
period必填出團月(格式 YYYY-MM,Asia/Taipei 時區)
回應欄位 · data
period結算期間(YYYY-MM,Asia/Taipei 出團月),回聲請求參數。
departureSummary梯次彙總:出團月落於 period 的各梯次收入 / 真實成本 / 毛估毛利。
departureId梯次 ID。
tripTitle團名。
departureDate出團日期(YYYY-MM-DD)。
pax出團人數(該梯次確認人數)。
revenueTwd總收入(TWD 整數)= 訂單收入(排除已取消訂單)+ 已認列退改費。
cancellationFeeTwd已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 取消梯次那幾列的收入常常整筆都是它,拆出來會計才看得懂那個數字為什麼不是 0。
realCostTwd真實成本合計(TWD 整數)= 房費底價成本 + 已核准的逐筆成本。逐筆成本區塊不含房費 (房費由分房資料另計),故逐筆成本加總會小於此值,差額即房費(設計如此)。
grossProfitTwd毛利毛估 = revenue − realCost(含房費)。
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
/api/v1/cost-templates參數
status選填activearchived依狀態篩選:active 啟用、archived 已封存
active選填啟用時只回傳輕量的 { id, name } 綁定挑選清單(行程設定的成本範本下拉用)
回應欄位 · data[]
id成本範本 id(ct_ 前綴)。
name成本範本名稱。
curl -X GET "https://your-tenant.example.com/api/v1/cost-templates" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": [
{
"id": "…",
"name": "…"
}
]
}/api/v1/cost-templates參數
name必填成本範本名稱
description選填成本範本說明
status選填activearchived範本狀態:active 啟用、archived 已封存
回應欄位 · data
id新建成本範本 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
/api/v1/cost-templates/{id}參數
id路徑成本範本 ID
回應欄位 · data
lines成本行明細(品項 × 單價 × 數量模型)。
id成本行 ID。
templateId所屬成本範本 ID。
category成本分類(如 交通 / 餐費 / 保險)。
vendorName供應商 / 廠商名(選填)。
description摘要說明(選填)。
unitPriceTwdTWD 行的單價;外幣行 null。
currency幣別('TWD' = 台幣行)。
unitPriceForeign外幣行的外幣單價;TWD 行 null。
internalRateSource外幣行的內帳匯率來源;TWD 行 null。
fxAccountIdinternalRateSource='fx_account' 時的外幣帳戶 id。
quantityMode數量模式:fixed 固定值 / headcount 依人頭公式(ceil(Σ人頭 / 組距))。
quantityFixedfixed 模式的固定數量;headcount 模式為 null。
headcountComponentsheadcount 模式選定的人頭 component(passenger / leader / assistant / driver);fixed 為 null。
groupDivisorheadcount 模式的組距(每 N 人一組,ceil 進位);null = 直接加總。
isDeclarable是否預設有合法憑證(帶入成本列的 is_declarable 初值)。
sortOrder顯示排序。
id成本範本 ID。
name範本名稱。
description範本說明(選填)。
status狀態:active 啟用 / archived 已封存。
lineCount成本行數(派生)。
boundTripCount綁定行程數(派生)。
appliedDepartureCount套用過本範本的梯次數(派生:departure_costs 經 template_line_id 追溯)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
}/api/v1/cost-templates/{id}參數
name必填成本範本名稱
description選填成本範本說明
status選填activearchived範本狀態:active 啟用、archived 已封存
id路徑成本範本 ID
回應欄位 · data
ok是否更新成功。
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.
/api/v1/cost-templates/{id}/lines參數
id路徑成本範本 ID
line必填成本明細列:含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式(fixed 固定/headcount 人數)與對應數量/人數組成、isDeclarable 是否可報帳等欄位
回應欄位 · data
rateNotice新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 null。
id新建成本明細行 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
/api/v1/cost-templates/lines/{lineId}參數
lineId路徑成本範本明細行 ID
line必填成本明細列更新內容:含 category 科目、vendorName 廠商、unitPriceTwd 單價、quantityMode 計量方式(fixed 固定/headcount 人數)與對應數量/人數組成、isDeclarable 是否可報帳等欄位
回應欄位 · data
ok是否更新成功。
rateNotice新外幣的台銀牌告暫時抓不到時的提示(隔天排程會補);其他情況為 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": "…"
}
}/api/v1/cost-templates/lines/{lineId}參數
lineId路徑成本範本明細行 ID
回應欄位 · data
ok是否刪除成功。
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
取消梯次待結轉列表
/api/v1/internal-external-ledger/cancelled-departures回應欄位 · data[]
departureId取消梯次 ID。
tripTitle團名。
tripSlug行程 slug(URL 識別)。
departureDate原出團日期(YYYY-MM-DD)。
returnDate原回程日期(YYYY-MM-DD)。
groupCode團號(group-code),未產生為 null。
residualCostTwd殘餘成本(TWD 整數):已核准的逐筆成本合計 + 房費底價成本合計。
approvedCostCount已核准成本筆數。
pendingCostCount待覆核成本筆數(UI 提示「還有待覆核成本」)。
roomCostTwd房費殘餘成本(房費底價成本合計,整數 TWD)。
conversion結轉狀態:已結轉為特殊損益時的費用列資訊(expenseId / 金額 / 歸屬月 / 摘要);未結轉為 null。
expenseIdamountTwdperioddescriptioncurl -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": "…"
}
]
}結轉取消
/api/v1/internal-external-ledger/cancelled-departures/convert參數
departureId必填梯次 ID
categoryId必填特殊損益費用科目 ID(kind=special)
period必填歸屬月(取消月,格式 YYYY-MM)
amountTwd必填結轉金額(整數 TWD,預設殘餘成本)
description必填摘要
note選填備註(選填)
回應欄位 · data
id新建立的殘餘成本營業費用列 ID(opx_ 前綴)。
residualCostTwd結轉的殘餘成本金額(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
}
}撤銷取消
/api/v1/internal-external-ledger/cancelled-departures/revert參數
departureId必填梯次 ID
回應欄位 · data
ok固定為 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
}
}/api/v1/internal-external-ledger/costs/{costId}參數
category必填成本類別代碼(須為有效的成本分類)
vendorName選填廠商/供應商名稱
description選填成本摘要說明
amountTwd選填真實成本(台幣整數)。台幣路徑必填;外幣路徑忽略,改由外幣金額乘匯率換算
currency選填幣別;TWD 或留空走台幣路徑,其他幣別走外幣路徑
foreignAmount選填外幣金額(最小單位整數,ISO 4217 minor units:JPY 以「円」、USD 以「cent」計);僅外幣路徑使用
internalRateSource選填fx_accountpublishedmanual內帳匯率來源:fx_account 外幣帳戶加權成本、published 台銀牌告、manual 手填成交率
fxAccountId選填外幣帳戶 ID;內帳匯率來源為 fx_account 時使用
manualRate選填手填成交匯率(字串保精度);內帳匯率來源為 manual 時使用
hasReceipt選填是否有發票憑證;預設 true,false 表示無發票並強制可申報額為 0、改填支出證明單欄位
invoiceAmountTwd選填外帳可申報額覆寫(台幣整數,須大於等於 0、無上限)
payeeName選填受款人姓名;無發票時的支出證明單欄位
reasonNoReceipt選填無發票原因;無發票時的支出證明單欄位
proofSummary選填支出證明摘要;無發票時的支出證明單欄位
quantityMode選填fixedheadcount計價方式;未給=一次性總額,fixed=單價×固定數量,headcount=單價×ceil(Σ人頭/組距)
headcountComponents選填依人頭計價的人頭組合(passenger/leader/assistant/driver,至少一項)
groupDivisor選填依人頭計價的組距(≥ 1;空=直接加總)
quantityFixed選填固定數量計價的數量(≥ 0)
unitPriceTwd選填單價(台幣整數);計價方式給值時必填
costId路徑成本列 ID
回應欄位 · data
ok固定為 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
}
}/api/v1/internal-external-ledger/costs/{costId}參數
costId路徑成本列 ID
回應欄位 · data
ok固定為 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
}
}/api/v1/internal-external-ledger/costs/{costId}/approve-declaration參數
costId路徑成本列 ID
回應欄位 · data
ok固定為 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
}
}待覆核的嚮導申報
/api/v1/internal-external-ledger/declarations/pending回應欄位 · data[]
id成本列 ID。
departureId所屬梯次 ID。
tripTitle團名。
departureDate出團日期(YYYY-MM-DD)。
category成本分類。
vendorName供應商 / 廠商名(選填)。
amountTwd代墊 / 實付額(內帳真實成本,整數 TWD)。
invoiceAmountTwd憑證 / 發票額(外帳可申報,整數 TWD)。
isDeclarable是否取得合法憑證。
createdByName登記者(經手人)姓名。
createdAt建立時間(嚮導送出時間)。
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 內外帳列表
/api/v1/internal-external-ledger/departures參數
windowDays選填回看天數;只列出近 N 天內的梯次
tripId選填行程 ID;只列出該行程的梯次
period選填出團月(格式 YYYY-MM);只列出該月的梯次
回應欄位 · data[]
tripTitle梯次標題(trip title)。
tripSlug行程 slug(URL 識別)。
departureDate出團日期(YYYY-MM-DD)。
returnDate回程日期(YYYY-MM-DD)。
groupCode團號(group-code),未產生為 null。
pax報名人數(非取消單 party_size 合計)。
departureStatus梯次狀態。`'cancelled'` 的列在毛利視圖裡只帶已認列退改費(訂單應收與成本都是 0), 呈現面必須標出來,否則會被當成一個真的有出團的梯次(issue 601)。
departureId梯次 ID。
revenueTwd本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。
orderRevenueTwd訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。
cancellationFeeTwd已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。
realCostTwd內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。
declarableCostTwd外帳可申報成本(各成本列憑證額合計,TWD 整數)。
nonDeclarableCostTwd不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。
costBilledTwd已轉請款成本。
costUnbilledTwd未轉請款成本;不含即付(當下已付、不轉請款)。
grossProfitTwd**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。
feeEcpayTwd預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。
feeFongshouTwd預估豐收款手續費(**參考預估**,非權威)。
taxEstTwd預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。
estimatedNetProfitTwd**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。
marginPct毛利率(grossProfit / revenue),revenue=0 時為 null。
pendingProofCount待核(pending)支出證明單數。
feeRates套用的費率(呈現用)。
ecpayFeeBps預估綠界手續費率(basis points,270 = 2.70%)。
fongshouFeeBps預估豐收款手續費率(basis points,50 = 0.50%)。
profitTaxBps預估發票 / 營所稅率(basis points,500 = 5.00%)。
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
/api/v1/internal-external-ledger/departures/{departureId}參數
departureId路徑梯次 ID
回應欄位 · data
departureId梯次 ID。
revenueTwd本團收入(TWD 整數)= 訂單收入 + 已認列退改費。毛利、內外帳、各區毛利都用這個。
orderRevenueTwd訂單收入(梯次應收扣代收暫收款,排除已取消訂單,TWD 整數)。
cancellationFeeTwd已認列退改費(TWD 整數,issue 601):客人自行取消時依階梯留下的錢,攤到本梯次 那一份。**歸屬鎖在取消當下**,本梯次之後被取消也不改寫(見 `finance/cancellation-fee-revenue.ts`)。未中籤的送件行政費不在此欄 —— 那筆走 公司層級其他收入,兩邊沒有交集。
realCostTwd內帳真實成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。
declarableCostTwd外帳可申報成本(各成本列憑證額合計,TWD 整數)。
nonDeclarableCostTwd不可申報(無憑證)真實成本,逐列 Σ GREATEST(amount − invoice, 0)(非跨列 realCost − declarableCost)。
costBilledTwd已轉請款成本。
costUnbilledTwd未轉請款成本;不含即付(當下已付、不轉請款)。
grossProfitTwd**每梯次權威數=毛利** = revenue − realCost(不扣手續費 / 稅,operating-expenses §2.3)。 公司月損益(computeCompanyPnL)的「各區毛利」即逐梯次此值按區彙整;手續費 / 稅在公司層 用實際值扣一次,**不**用下面的預估費率重扣(避免雙重計)。
feeEcpayTwd預估綠界手續費(**參考預估**,非權威;公司層用實際值,§2.3)。
feeFongshouTwd預估豐收款手續費(**參考預估**,非權威)。
taxEstTwd預估發票 / 營所稅(**參考預估**,非權威;公司層用實繳值)。
estimatedNetProfitTwd**參考預估淨利**(非權威)= grossProfit − feeEcpay − feeFongshou − taxEst。純給現場 快速感覺(毛利扣預估費率),**非公司財務真相** —— 公司淨利以 operating-expenses 月損益表 (實際 overhead)為準。權威數請用 `grossProfitTwd`。
marginPct毛利率(grossProfit / revenue),revenue=0 時為 null。
pendingProofCount待核(pending)支出證明單數。
feeRates套用的費率(呈現用)。
ecpayFeeBps預估綠界手續費率(basis points,270 = 2.70%)。
fongshouFeeBps預估豐收款手續費率(basis points,50 = 0.50%)。
profitTaxBps預估發票 / 營所稅率(basis points,500 = 5.00%)。
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
}
}
}/api/v1/internal-external-ledger/departures/{departureId}/convert-to-payable參數
departureId路徑梯次 ID
costIds必填要轉成請款核簽的成本列 ID 陣列(至少一筆,須為尚未轉請款者)
payeeType選填supplierguidestaff_commissionother受款對象類型:supplier 供應商、guide 嚮導、staff_commission 員工佣金、other 其他
payeeName必填受款對象名稱
payeeBankAccount選填受款銀行帳號
payeeBankName選填受款銀行名稱
payeeBankBranch選填受款銀行分行
payeeTaxId選填受款對象統一編號/稅籍編號
taxAmountTwd選填代扣稅額(台幣整數)
submitImmediately選填是否建立後立即送出核簽(true 直接送審)
回應欄位 · data
payableId新建立應付單的 ID(pay_ 前綴)。
payableNumber應付單編號(租戶內流水序號,出款核簽用)。
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": "…"
}
}/api/v1/internal-external-ledger/departures/{departureId}/costs參數
departureId路徑梯次 ID
createdBy選填登記者使用者 ID;只列出該人登記的成本列
回應欄位 · data[]
id成本列 ID。
departureId所屬梯次 ID。
category成本分類(如 交通 / 餐費 / 保險 / 嚮導)。
vendorName供應商 / 廠商名(選填)。
description摘要說明(選填)。
receiptImageUrl憑證照片 URL(G3-2);未附照片 null。app-route 私有 URL,讀取經 route 權限閘。
amountTwd代墊 / 實付額(內帳真實成本,整數 TWD)。
invoiceAmountTwd外帳可申報額(internal-external-ledger §2.1)。
isDeclarable是否取得合法憑證。
reviewStatus覆核狀態 'pending' | 'approved'(L'):pending 不計入毛利 / 可申報(UI 須標示、停用轉請款)。
currency成本幣別(ISO 4217);'TWD' = 台幣列。
foreignAmount外幣金額(最小單位整數);TWD 列 null。
internalRateSource內帳匯率來源;TWD 列 null。
fxAccountIdinternalRateSource='fx_account' 時的外幣帳戶 id。
internalRate內帳匯率快照(numeric 字串);TWD 列 null。
externalRate外帳匯率快照(numeric 字串,台銀牌告);TWD 列 null。
feeCategory費用類型 tag(account-settlement §3.4,成本側類別→領域帳戶映射;null = 未 tag)。
quantityMode計價方式 'fixed' / 'headcount';一次性總額列 null。
headcountComponentsheadcount 人頭組合;非 headcount 列 null。
groupDivisorheadcount 組距;非 headcount 列 null。
quantity解析後(headcount)或自訂(fixed)的數量;一次性總額列 null。
unitPriceTwd單價(台幣整數);一次性總額列 null。
expenseProofId無發票支出掛的支出證明單 id(null = 有憑證)。
proofNumber支出證明單單號(join expense_proofs,null = 無)。
proofStatus支出證明單狀態 'pending' | 'approved'(null = 無)。
payableId已轉請款時連結的請款單 ID(null = 未轉請款)。
payableNumber連結請款單的人類可讀單號(null = 未轉請款)。
payableStatus連結請款單的狀態(draft / submitted / approved / paid…;null = 未轉請款)。
paymentMethod付款方式:'request' 走請款核簽;'paid_on_spot' 即付,算已付、不轉請款。
paidOn即付的付款日('YYYY-MM-DD');請款列 null。
paidAccountId即付的付款帳戶 ID;未指定或請款列 null。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/internal-external-ledger/departures/{departureId}/costs參數
category必填成本類別代碼(須為有效的成本分類)
vendorName選填廠商/供應商名稱
description選填成本摘要說明
amountTwd選填真實成本(台幣整數)。台幣路徑必填;外幣路徑忽略,改由外幣金額乘匯率換算
currency選填幣別;TWD 或留空走台幣路徑,其他幣別走外幣路徑
foreignAmount選填外幣金額(最小單位整數,ISO 4217 minor units:JPY 以「円」、USD 以「cent」計);僅外幣路徑使用
internalRateSource選填fx_accountpublishedmanual內帳匯率來源:fx_account 外幣帳戶加權成本、published 台銀牌告、manual 手填成交率
fxAccountId選填外幣帳戶 ID;內帳匯率來源為 fx_account 時使用
manualRate選填手填成交匯率(字串保精度);內帳匯率來源為 manual 時使用
hasReceipt選填是否有發票憑證;預設 true,false 表示無發票並強制可申報額為 0、改填支出證明單欄位
invoiceAmountTwd選填外帳可申報額覆寫(台幣整數,須大於等於 0、無上限)
payeeName選填受款人姓名;無發票時的支出證明單欄位
reasonNoReceipt選填無發票原因;無發票時的支出證明單欄位
proofSummary選填支出證明摘要;無發票時的支出證明單欄位
quantityMode選填fixedheadcount計價方式;未給=一次性總額,fixed=單價×固定數量,headcount=單價×ceil(Σ人頭/組距)
headcountComponents選填依人頭計價的人頭組合(passenger/leader/assistant/driver,至少一項)
groupDivisor選填依人頭計價的組距(≥ 1;空=直接加總)
quantityFixed選填固定數量計價的數量(≥ 0)
unitPriceTwd選填單價(台幣整數);計價方式給值時必填
departureId路徑梯次 ID
回應欄位 · data
id新建立成本列的 ID(dc_ 前綴)。
expenseProofId隨附憑證的 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": "…"
}
}支出
/api/v1/internal-external-ledger/departures/{departureId}/proofs參數
departureId路徑梯次 ID
回應欄位 · data[]
id支出證明單 ID。
proofNumber人類可讀單號(EP-YYMMDD-NNN)。
departureId所屬梯次 ID。
payeeName受款對象(自然人 / 廠商)。
amountTwd金額(整數 TWD,對應所掛成本列的 amount_twd)。
reasonNoReceipt無法取得單據的原因(如「自然人」)。
summary支出內容及摘要(選填)。
handlerUserId經手人(建單者)user ID。
approverUserId核准人 user ID(強制 ≠ 經手人);未核准為 null。
status狀態:pending 待核准 / approved 已核准(核准後 append-only)。
approvedAt核准時間;未核准為 null。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/internal-external-ledger/departures/{departureId}/proofs/{proofId}參數
departureId路徑梯次 ID
proofId路徑支出證明單 ID
回應欄位 · data
id支出證明單 ID。
proofNumber人類可讀單號(EP-YYMMDD-NNN)。
departureId所屬梯次 ID。
payeeName受款對象(自然人 / 廠商)。
amountTwd金額(整數 TWD,對應所掛成本列的 amount_twd)。
reasonNoReceipt無法取得單據的原因(如「自然人」)。
summary支出內容及摘要(選填)。
handlerUserId經手人(建單者)user ID。
approverUserId核准人 user ID(強制 ≠ 經手人);未核准為 null。
status狀態:pending 待核准 / approved 已核准(核准後 append-only)。
approvedAt核准時間;未核准為 null。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
}/api/v1/internal-external-ledger/proofs/{proofId}/approve參數
proofId路徑支出證明單 ID
回應欄位 · data
ok固定為 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
派生當月
/api/v1/payouts/aggregate參數
period必填出款月份(YYYY-MM),彙整該月已核准未付的應付
scope必填guidesupplierstaff收款對象範圍(guide 領隊嚮導 / supplier 供應商 / staff 員工)
回應欄位 · data[]
payeeType收款對象類型:guide 領隊嚮導 / supplier 供應商 / staff 員工。
payeeRefId收款對象識別 key:供應商為其 ID,領隊 / 員工為收款人姓名。
payeeName收款對象名稱。
payeeAccountName收款人戶名(supplier 取 suppliers / guide 取 guides;staff 暫無主檔 → null)。
payeeBankCode收款銀行代號(同上來源;無主檔為 null)。
payeeAccountNumber收款帳號(同上來源;無主檔為 null,遮罩回傳)。
grossTwd當月已核准未付的請款單淨額合計(TWD 整數)。
items彙整明細(日期 + 團名 + 金額,唯讀派生,不另存)。
payableId請款單 ID。
payableNumber請款單人類可讀單號。
date梯次出發日('YYYY-MM-DD');無連梯次時 null。
tripLabel團名;無連梯次時 null。
amountTwd該請款單的應付淨額(TWD 整數)。
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
}
]
}
]
}建立出款批次草稿
/api/v1/payouts/batches參數
period必填出款月份(YYYY-MM)
payeeScope必填guidesupplierstaff收款對象範圍(guide 領隊嚮導 / supplier 供應商 / staff 員工)
paidFromAccountId選填出帳帳戶 id(從哪個收款帳戶付出);可留空待確認時指定
lines必填納入批次的出款列(至少一列)
回應欄位 · data
id新建立出款批次的 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": "…"
}
}確認出款批次
/api/v1/payouts/batches/{id}/confirm參數
id路徑出款批次 id(路徑參數,格式 pob_…)
bankReference選填網銀交易序號 / 轉帳憑證號(可選)
回應欄位 · data
ok固定為 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
}
}出款批次的標準四欄批次轉帳檔
/api/v1/payouts/batches/{id}/transfer-file參數
id路徑出款批次 id(路徑參數)
format選填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": "…"
}為某出款批次列簽發廠商自助確認
/api/v1/payouts/lines/{lineId}/confirm-token參數
lineId路徑出款批次列 id(路徑參數,格式 pobl_…)
回應欄位 · data
token廠商自助確認 token(拼成對外確認頁網址;未過期重複簽發回原 token)。
expiresAttoken 失效時點(簽發起 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": "…"
}
}出款批次的「出帳帳戶」選項
/api/v1/payouts/remit-accounts回應欄位 · data[]
id收款帳戶 ID。
code帳戶代碼(租戶內唯一穩定識別)。
displayName帳戶顯示名。
kind帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。
gatewayProvider綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `payment/gateway-providers.ts`。
bankName銀行名稱;現金/閘道帳戶為 null。
accountNo銀行帳號;現金/閘道帳戶為 null。
bankCodebankBranchaccountHoldercanReceive可收款(幾乎都 true)。
canRemit可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。
canChargeback可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。
canPaySupplier付款渠道:出團準備的付款登記區可選它付供應商(#1375)。
isDeprecated廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。
isSettlementMaster主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。
payoutAccountId撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。
currency帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位(小者在前)。
usedCount被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。
currencyLocked幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。
createdAt建立時間。
updatedAt最後更新時間。
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
/api/v1/pnl/expense-categories參數
activeOnly選填是否只回傳啟用中的費用類別;預設含停用列
回應欄位 · data[]
id費用類別 ID。
code科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。
displayName顯示名(如 房租 / 行政薪資 / 營業稅)。
kind費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。
isActive是否啟用(停用不刪,既有費用列仍引用得到)。
createdAt建立時間。
updatedAt最後更新時間。
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
/api/v1/pnl/expenses參數
period選填歸屬月(格式 YYYY-MM);只列出該月的費用
category選填費用類別 ID;只列出該類別的費用
kind選填opextaxplatform_feespecial費用大類:opex 營業費用、tax 稅、platform_fee 平台手續費、special 特殊損益
回應欄位 · data[]
id費用列 ID。
categoryId費用科目 ID。
categoryCode費用科目代碼(如 rent / salary_admin)。
categoryDisplayName費用科目顯示名。
categoryKind費用科目大類(opex / tax / platform_fee / special)。
period歸屬月(YYYY-MM,損益表據此彙整;可與支付日不同月)。
incurredOn發生 / 支付日期(YYYY-MM-DD);金流商內扣 / 攤提無單一發生日者為 null。
amountTwd金額(整數 TWD,恆正;損 / 益由 direction 表達)。
direction損益方向:'expense' 費用(預設)| 'income' 特殊收入(僅 kind='special' 科目)。
description摘要(廠商 / 品名,如 台中房租 / 委外廣告投放)。
paidFromAccountId出帳帳戶 ID;金流商內扣者為 null。
paidFromAccountName出帳帳戶顯示名。
frontedByUserId代墊者 user ID;非空代表由此人代墊待回補(走請款回補代墊者)。
frontedByName代墊者姓名。
payableId若走出款核簽,連結的請款單 ID;否則 null。
payableNumber連結請款單的人類可讀單號。
recurring月固定標記(人工登記時備註「月固定」;自動生成走範本表,非此欄)。
status'draft'(月固定範本自動生成、待確認,不入損益)| 'confirmed'(計入損益)。
origin'manual'(手動登記)| 'recurring'(月固定範本自動生成)| 'departure_conversion'(取消梯次結轉,§3.4)。
sourceTemplateId生成來源範本(origin='recurring');手動登記為 null。
note備註。
createdByUserId經手人 user ID(建立此費用列者)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/pnl/expenses參數
categoryId必填費用類別 ID(對應公司費用類別目錄)
period必填歸屬月(格式 YYYY-MM),供月損益表彙整
description必填費用摘要
amountTwd必填費用金額(台幣非負整數;損 / 益由 direction 表達,金額恆正)
direction選填expenseincome損益方向:expense 費用(預設)/ income 特殊收入(保險理賠、政府補助等;僅 kind='special' 科目可用)
incurredOn選填費用發生日期(格式 YYYY-MM-DD)
paidFromAccountId選填支付來源帳戶 ID
frontedByUserId選填代墊人使用者 ID(由員工先行墊付時填寫)
note選填備註
recurring選填是否為週期性費用
回應欄位 · data
ok固定為 true:營業費用列已新增。
id新建立營業費用列的 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": "…"
}
}更正一筆公司營業費用
/api/v1/pnl/expenses/{id}參數
categoryId必填費用類別 ID(對應公司費用類別目錄)
period必填歸屬月(格式 YYYY-MM),供月損益表彙整
description必填費用摘要
amountTwd必填費用金額(台幣非負整數;損 / 益由 direction 表達,金額恆正)
direction選填expenseincome損益方向:expense 費用(預設)/ income 特殊收入(保險理賠、政府補助等;僅 kind='special' 科目可用)
incurredOn選填費用發生日期(格式 YYYY-MM-DD)
paidFromAccountId選填支付來源帳戶 ID
frontedByUserId選填代墊人使用者 ID(由員工先行墊付時填寫)
note選填備註
recurring選填是否為週期性費用
id路徑營業費用列 ID
payableId選填關聯的請款核簽 ID;整列覆寫時須原樣帶回,省略則清為 null
回應欄位 · data
ok固定為 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
/api/v1/pnl/statement參數
period必填損益表結算月(格式 YYYY-MM)
回應欄位 · data
period結算期間(YYYY-MM)。
regions各區毛利明細(出團月落 period 的梯次按區 roll-up)。
region派生 region key(穩定,由 trip 屬性派生)。
label顯示標籤(destination 原文 / 衍生)。
revenueTwd本區收入(出團月落 period 的梯次合計 = 訂單收入 + 已認列退改費,TWD 整數)。
cancellationFeeTwd本區已認列退改費(issue 601,TWD 整數):`revenueTwd` 之中來自取消單退改費的那一段。 拆出來呈現,會計才對得出「這區的收入有多少不是出團賺的」。
directCostTwd本區真實直接成本(TWD 整數)= 房費底價成本 + 已核准的逐筆成本合計。
marginTwd本區毛利 = revenue − directCost。
departures本區梯次數(出團月落 period)。
grossMarginTwd各區毛利加總(整數 TWD)。
revenueTotalTwd各區營收加總(整數 TWD)。
adminFeeIncomeTwd行政手續費收入(退款收取的行政手續費,只計未出團 / 取消單,TWD 整數)。
otherIncomeTwd其他收入合計 = adminFeeIncome(整數 TWD)。GS「額外收入總計」改由 special income 列 承載(specialIncomeTwd,於特殊損益帶號區認列),**不在此重複加總**(防雙計)。
expensesByKind公司營業費用按 kind roll-up(opex / tax / platform_fee,只計已確認)。
kind'opex' / 'tax' / 'platform_fee'。
amountTwd該 kind 本期費用合計(整數 TWD)。
count該 kind 本期費用筆數。
operatingExpenseTotalTwd公司營業費用合計 = Σ opex / tax / platform_fee(整數 TWD)。
special特殊損益逐筆(kind='special',一次性、獨立列、損 / 益雙向,只計已確認)。
id費用列 ID。
categoryId費用科目 ID(特殊損益科目)。
categoryDisplayName費用科目顯示名。
description摘要(如 取消神山床位沒收訂金 / 保險理賠)。
amountTwd金額(整數 TWD ≥ 0,DB CHECK operating_expenses_amount_nonneg)。恆正;損 / 益由 `direction` 表達(0055 特殊損益雙向)。
direction'expense' 損(扣減淨利)| 'income' 益(增益淨利;GS「額外收入」的載體)。
specialExpenseTwd特殊損合計(direction='expense',整數 TWD ≥ 0)。
specialIncomeTwd特殊益合計(direction='income',整數 TWD ≥ 0)= GS「額外收入總計」的載體。
specialTotalTwd特殊損益淨額(**帶號**)= specialExpense − specialIncome(整數 TWD;淨益時為負)。 淨利計算從淨利扣減此值——income 為正貢獻(損 1000 + 益 300 → specialTotal 700 → 淨利 −700)。
netProfitTwd公司淨利 = grossMargin + otherIncome − operatingExpenseTotal − specialTotal(帶號)。
netMarginPct淨利率(netProfit / revenueTotal),revenue=0 時 null。
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
/api/v1/reports/monthly參數
year必填報表年份(西元四位數),月界以台北時區計
month必填報表月份,1 至 12
回應欄位 · data
year報表年份(西元四位數)。
month報表月份(1-12,月界以 Asia/Taipei 計)。
totalOrders本月建立的 tour 訂單數(依 created_at 計)。
paidOrders本月有實收現金的 tour 訂單數(月內有 inbound 交易)。
cancelledOrders本月取消的 tour 訂單數(依 `orders.cancelled_at` 計,Asia/Taipei 月界)。 取消時刻不明的單(`cancelled_at IS NULL`)任何月份都不計 —— 見 repo 內註解。
cancelledOrdersUnknownDate取消時刻不明的 tour 訂單數(`cancelled_at IS NULL`)。**不分月份** —— 它們 不屬於任何一個月,所以每個月的報表都回報同一個值。> 0 時畫面要講出來: 否則這批單在每個月的報表裡都不出現,逐月讀完也看不出它們存在 —— 而它們確實 被取消了。(不要拿它跟訂單清單的取消總數對:報表側是 tour line 口徑、清單側是 `o.kind`,兩者本來就不相等,見 #20。)
totalRevenue本月實際收到的現金。
refundedAmount本月退還客人的現金,含退款與信用卡爭議退款(chargeback)。
netCash本月淨現金:實收減退還現金,再扣手續費。
newCustomers本月新註冊會員數(排除 staff 角色)。
byTrip依行程銷售排行(前 10 名,按本月實收現金的攤提份額)。跨出團/跨行程訂單 的現金按 orders/allocation 份額分(#12),Σ revenue = totalRevenue 守恆。
tripId行程 ID。
tripTitle團名。
orderCount該行程本月有實收現金份額的訂單數。
revenuecollected_cash by trip:本月實收現金攤提份額(tour-scoped)。
byProvider依金流商分組的本月實收現金。
provider金流商代碼(如 ecpay / test)。
orderCount該金流商本月有實收現金的訂單數。
amountcollected_cash by provider:本月實收現金(tour-scoped)。
dailyRevenuecollected_cash by day:本月逐日實收現金(tour-scoped,Asia/Taipei 日界), 整月零填滿(無入帳的日子 amount=0)。Σ amount === totalRevenue,與 KPI 對帳。
day日期(YYYY-MM-DD,Asia/Taipei 日界)。
amount當日實收現金(tour-scoped,整數 TWD)。
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
廠商目錄列表
/api/v1/suppliers參數
status選填activeinactiveall依狀態篩選(active 啟用 / inactive 停用 / all 全部,預設 active)
q選填關鍵字搜尋(廠商名稱或類別)
回應欄位 · data[]
id廠商 ID。
name廠商名稱。
categoryHint慣用類別提示(租戶自定,非硬枚舉)。
payeeAccountName收款人戶名(批次轉帳檔欄 (1))。
payeeBankCode收款銀行代號(批次轉帳檔欄 (3))。
payeeAccountNumber收款帳號(批次轉帳檔欄 (2),遮罩回傳)。
status狀態:active 啟用 / inactive 停用(停用不刪)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/suppliers參數
name必填廠商名稱(出款對象顯示名)
categoryHint選填類別提示(如住宿、交通、餐飲),供分類與搜尋
payeeAccountName選填收款戶名(須與銀行帳戶登記名一致)
payeeBankCode選填銀行代號(3~7 碼數字,台銀通用四欄轉帳檔用)
payeeAccountNumber選填收款銀行帳號(純數字,write-only 寫入後僅回遮罩)
回應欄位 · data
ok固定為 true:廠商已新增。
id新建立廠商的 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": "…"
}
}單一廠商主檔
/api/v1/suppliers/{id}參數
id路徑廠商 id(路徑參數)
回應欄位 · data
id廠商 ID。
name廠商名稱。
categoryHint慣用類別提示(租戶自定,非硬枚舉)。
payeeAccountName收款人戶名(批次轉帳檔欄 (1))。
payeeBankCode收款銀行代號(批次轉帳檔欄 (3))。
payeeAccountNumber收款帳號(批次轉帳檔欄 (2),遮罩回傳)。
status狀態:active 啟用 / inactive 停用(停用不刪)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
}/api/v1/suppliers/{id}參數
name選填廠商名稱(出款對象顯示名)
categoryHint選填類別提示(如住宿、交通、餐飲),供分類與搜尋
payeeAccountName選填收款戶名(須與銀行帳戶登記名一致)
payeeBankCode選填銀行代號(3~7 碼數字,台銀通用四欄轉帳檔用)
payeeAccountNumber選填收款銀行帳號(純數字,write-only 寫入後僅回遮罩)
id路徑廠商 id(路徑參數)
回應欄位 · data
ok固定為 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
/api/v1/audit/log參數
action選填動作代碼篩選,例如 order.update(比對稽核事件的動作)
actor選填操作者篩選,比對執行該動作的使用者 ID
entity選填目標實體篩選,比對被操作對象的類型或 ID
from選填起始時間(ISO 8601),僅回傳此時間之後的事件
to選填結束時間(ISO 8601),僅回傳此時間之前的事件
before選填往更舊翻頁的游標:直接帶前一批最後一列的 cursor 欄位(勿用 createdAt 重組)
after選填往更新翻頁的游標:帶前一批第一列的 cursor 欄位。與 before 併用時以 before 為準
limit選填回傳筆數上限,最多 1000 筆
回應欄位 · data[]
id稽核事件 ID。
actorUserId操作者的使用者 ID;系統事件(webhook/排程等非人為列)為 null。
actorEmail操作者 Email;系統事件或帳號已刪時為 null。
actorName操作者顯示名;系統事件或帳號已刪時為 null。
action動作代碼,例如 order.create、traveler.decrypt。
targetType被操作對象的類型,例如 order、member。
targetId被操作對象的 ID。
metadata該事件的附帶內容(欄位隨動作而異的自由結構 JSON)。
ipAddress發起請求的來源 IP;無法取得時為 null。
createdAt事件發生時間。**只用來顯示** —— 它到毫秒為止(JSON 序列化也是),翻頁請用 `cursor`。
cursor這一列的 keyset 游標(`<ISO 微秒時間>|<id>`)。要往這一列的前後翻頁就直接把它 餵回 `before` / `after`,**不要拿 `createdAt` 重組**:那是 JS `Date`,只到毫秒, 而 `audit_log.created_at` 是微秒。JSON 序列化之後只剩 3 位小數,同一毫秒內更舊 的列會被整批跳過(`/api/v1` 與 CLI 走的正是這條路)。
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
/api/v1/audit/stats參數
actor選填操作者使用者 ID,指定時將統計數據限縮至該操作者
回應欄位 · data
eventsThisMonth本月(Asia/Taipei)稽核事件總數。
eventsToday今日(Asia/Taipei)稽核事件總數。
writesThisMonth本月寫入類事件數(排除 *.read 讀取事件)。
distinctActorsThisMonth本月有動作紀錄的不重複操作者人數。
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
全公司業務業績排行
/api/v1/leaderboard參數
period選填monthquarteryearall業績統計區間:當月、當季、當年或全部,預設 month
回應欄位 · data[]
userId業務的使用者 ID。
name業務顯示姓名。
email業務登入 Email。
role業務角色代碼(admin/sales/op/accountant)。
orderCount承作訂單總數(歸屬此業務、含各狀態的旅遊團訂單)。
paidCount成交訂單數(未取消,且已付清或已完成)。
cancelledCount已取消訂單數。
revenue業績額(TWD 整數):歸屬於該業務、未取消訂單的應收合計。
commissionTwd估算佣金 = round(revenue × sales_commission_bps / 10000)(tenant_settings 費率)。
bonusTwd月度第一名加碼 = round(revenue × monthly_top_bonus_bps / 10000),僅當期 rank 1 且 revenue > 0;其餘為 0。與 isMonthlyTop 同步。
isMonthlyTop當期 rank 1(revenue > 0)=月度第一,享 bonus。
avgOrderTwd客單均價 = round(revenue / orderCount);0 單為 0。
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
/api/v1/leaderboard/review-stats回應欄位 · data
pendingCount待派發(pending_review)訂單筆數。
pendingTotalTwd待派發訂單的應收金額合計(新台幣)。
longestWaitHours目前待派發訂單中,最長已等待的時數。
thisMonthAssigned本月(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
/api/v1/message-templates參數
channel選填lineemail依發送管道篩選範本(line 或 email)
回應欄位 · data[]
id範本 ID。
key穩定識別碼(NULL = 未指定)。
stageSOP 階段(受理 → 出團完成)。
channel發送管道:line 或 email。
title範本標題。
bodySingle單人版內文(含 {{...}} 合併變數)。
bodyMulti多人版變體;NULL = 只有單人版。
isActive是否為該階段目前啟用的範本。
createdAt建立時間。
updatedAt最後更新時間。
updatedBy最後更新者姓名;未知或帳號已刪除時為 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": "…"
}
]
}/api/v1/message-templates參數
key選填範本識別碼,2–64 碼大寫英數 / _ / -(用於程式化引用,選填,自動轉大寫)
stage必填訊息對應的 SOP 階段(合法值 = 租戶階段目錄中的階段名)
channel必填lineemail發送管道(line 或 email)
title必填範本標題(供後台辨識)
bodySingle必填單人版訊息內文
bodyMulti選填多人版訊息內文(留空表示沿用單人版;選填)
isActive選填是否啟用(停用後不出現在可選範本中)
回應欄位 · data
id新建立的訊息範本 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.
/api/v1/message-templates/{id}參數
id路徑訊息範本 ID
回應欄位 · data
id範本 ID。
key穩定識別碼(NULL = 未指定)。
stageSOP 階段(受理 → 出團完成)。
channel發送管道:line 或 email。
title範本標題。
bodySingle單人版內文(含 {{...}} 合併變數)。
bodyMulti多人版變體;NULL = 只有單人版。
isActive是否為該階段目前啟用的範本。
createdAt建立時間。
updatedAt最後更新時間。
updatedBy最後更新者姓名;未知或帳號已刪除時為 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": "…"
}
}/api/v1/message-templates/{id}參數
id路徑要更新的訊息範本 ID
key選填範本識別碼,2–64 碼大寫英數 / _ / -(用於程式化引用,選填,自動轉大寫)
stage必填訊息對應的 SOP 階段(合法值 = 租戶階段目錄中的階段名)
channel必填lineemail發送管道(line 或 email)
title必填範本標題(供後台辨識)
bodySingle必填單人版訊息內文
bodyMulti選填多人版訊息內文(留空表示沿用單人版;選填)
isActive選填是否啟用(停用後不出現在可選範本中)
回應欄位 · data
ok是否成功更新訊息範本。
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
}
}/api/v1/message-templates/{id}參數
id路徑訊息範本 ID
回應欄位 · data
ok是否成功刪除訊息範本。
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
/api/v1/message-templates/{id}/active參數
id路徑要啟用 / 停用的訊息範本 ID
isActive必填true 啟用、false 停用(軟刪除)此範本
回應欄位 · data
ok是否成功切換訊息範本的啟用狀態。
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
/api/v1/roles參數
system選填truefalse是否只列內建角色:true 僅內建、false 僅自訂,省略則全部
回應欄位 · data[]
id角色 ID(內建角色為其代碼)。
name角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。
label角色顯示名稱。
isSystem是否為系統內建角色(內建角色不可修改或刪除)。
permissionCount該角色目前擁有的 (resource, action) 數量。
memberCount持有此角色的使用者人數。
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
}
]
}/api/v1/roles參數
name必填角色代碼,小寫英數與底線、2–32 字且須以字母開頭,建立後不可改
label必填角色顯示名稱,呈現於後台角色清單
permissions選填此角色授予的權限清單,每筆為一組資源與動作
orderScope選填ownall訂單資料範圍:own 只看自己名下訂單(預設)、all 全租戶(含旅客證件解密)
回應欄位 · data
id新建立的角色 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
/api/v1/roles/{id}參數
id路徑角色 ID(內建角色為其代碼)
回應欄位 · data
id角色 ID(內建角色為其代碼)。
name角色代碼(小寫英數與底線,建立後不可改;即帳號綁定的角色值)。
label角色顯示名稱。
isSystem是否為系統內建角色(內建角色不可修改或刪除)。
orderScope訂單資料範圍:'own' 只看名下訂單、'all' 全租戶(含旅客證件解密)。
permissions此角色授予的完整 (resource, action) 權限清單。
resource權限資源代碼,例如 order、member。
action權限動作代碼,例如 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": "…"
}
]
}
}/api/v1/roles/{id}參數
id路徑欲更新的角色 ID
label必填角色顯示名稱,呈現於後台角色清單
permissions選填完整取代後的權限清單,會整批覆寫此角色現有權限
orderScope選填ownall訂單資料範圍:own 只看自己名下訂單、all 全租戶(含旅客證件解密);省略則不變
回應欄位 · data
ok是否成功更新角色。
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
}
}/api/v1/roles/{id}參數
id路徑角色 ID(內建角色為其代碼)
回應欄位 · data
ok是否成功刪除角色。
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
/api/v1/roles/catalog回應欄位 · data[]
resource權限資源代碼,例如 order、member。
label中文名。
actionsaction動作代碼,例如 read、set-role。
label中文說明;指派權限的人看的是這個。
risk選填有值表示高風險,內容是授出去會發生什麼事。
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
/api/v1/settings回應欄位 · data
id設定列 ID(單例,恆為 'singleton')。
companyName公司全名,顯示於發票、合約與對外信件抬頭。**必填**(#87,DB NOT NULL + 非空白 CHECK)。
companyPhone公司聯絡電話,顯示於對外文件;null = 未設定。
companyEmail公司對外聯絡信箱,自建前台的站台資訊輸出它;null = 未設定。
taxId公司統一編號(8 位數字),用於開立發票;null = 未設定。
companyAddress公司登記地址,顯示於對外文件;null = 未設定。
logoUrl公司 Logo 圖片網址,用於後台與對外頁面品牌呈現;null = 未設定。
siteTagline公開站標語(SEO/首頁);null = 未設定。
seoDefaultDescription公開站預設 SEO meta description;null = 未設定。
ogImageUrl社群分享預設 Open Graph 圖片網址;null = 未設定。
emailReplyTo系統寄信時的回覆收件信箱;null = 未設定。
lineOfficialUrl官方 LINE 加好友連結(issue 748);null = 未設定。
facebookUrlFacebook 粉專網址;null = 未設定。
instagramUrlInstagram 網址;null = 未設定。
youtubeUrlYouTube 頻道網址;null = 未設定。
assignmentModeS5: 'auto_round_robin' | 'auto_customer_choice' | 'manual_review'
defaultAssigneeUserIdS5: fallback assignee when round-robin finds no active sales, etc.
allowSalesClaimorder-assignment §6:業務自派搶單開關(per-tenant opt-in,預設 false)。
passportExpiryWarningDays護照效期提醒天數(document-expiry §4.1;NOT NULL DEFAULT 180)。
guideCertExpiryWarningDays嚮導證照到期提醒天數(#563;NOT NULL DEFAULT 60)。回程日 + 此天數 > 到期日即警示。
guideDispatchNearGap派嚮導清單的「快成團」門檻人數(#1377;NOT NULL DEFAULT 2)。
groupCodePattern團號 token 樣板(如 '{YY}{region}{airline?}{MMDD}{seq}')。NULL = 內建預設。
groupCodeSeqStyle序號樣式:'alpha' | 'alpha_no_io' | 'numeric'(NOT NULL DEFAULT 'alpha')。
groupCodeSeqWidthnumeric 序號補零寬度(NOT NULL DEFAULT 2;alpha 樣式忽略)。
ecpayFeeBps預估綠界手續費率(270 = 2.70%)。NOT NULL DEFAULT 270。
fongshouFeeBps預估豐收款手續費率(50 = 0.50%)。NOT NULL DEFAULT 50。
profitTaxBps預估發票 / 營所稅率(500 = 5.00%)。NOT NULL DEFAULT 500。
salesCommissionBps業務抽成率(1000 = 10.00%)。NOT NULL DEFAULT 1000。
monthlyTopBonusBps月度第一名加碼率(500 = 5.00%)。NOT NULL DEFAULT 500。
senderLocalPart寄件人 local-part,未填視為 'info'。
storefrontTemplate前台店面模板 key(storefront-templates §3)。可能對不上 registry(打錯、模板 改名/下架)—— 前台渲染一律經 resolveStorefrontTemplate() fallback `minimal`。
customStorefrontUrlwebsiteModeactiveCustomStorefrontUrlcustomStorefrontTripPathga4MeasurementId轉換追蹤 ID(specs/conversion-tracking.md)。NULL = 不載入該追蹤碼。
metaPixelIdgoogleAdsIdcustomerCancelUnpaidEnabled未付款單可否由客人自行線上取消。
customerCancelPaidEnabled已付款(含只付訂金)單可否由客人自行線上取消。
customerCancelPaidMinDaysBefore已付款單的出發日門檻:距出發 < 此天數即不可線上取消。
customerRescheduleMinDaysBefore自助換梯門檻(customer-cancellation §8.1):null = 不開放,N = 來源與目標距出發 ≥ N 天。
customerRescheduleSurplus自助換梯後新梯較便宜時的差額處理(§8.5)。
cancellationFeeTiers租戶預設退改費階梯(已正規化、降序)。`[]` = 不收退改費。
daysBefore距出發日 ≥ 此天數時適用本列。0 = 出發當天(保底列)。
feePercent選填扣款百分比(0–100,整數),基準為訂單成交總額(沖零前的 gross_receivable)。
feeFixedTwd選填定額扣款(整數 TWD),**按人頭計**(× 這張單的旅客列數),與成交總額無關。
refundRemitFeeTwd退款轉帳費(customer-cancellation §3.4,按單一次)。走匯出的退款才收,刷退恆 0。
refundApprovalPolicy退款核准權限(#1405)。見 `refunds/approval-policy`。
approverRoles可核准退款的角色名單。null = 不另外限縮,持有 `refund.approve` 的角色都可核准。
accountantCanCreate內建會計角色可開退款單並送審(`refund.create`)。
selfApprovalEnabled建單人可以核准自己的退款單。關 = 維持現狀的責任分離:只擋建單人 (`CREATOR_CANNOT_APPROVE`),送審人不受限。
customerCancelReminder客人自助取消提醒文字(customer-cancellation §5.1);null = 不顯示。
lotteryFilingFeeTiers送件行政費的次數階梯(customer-cancellation §3.6,**每人**,已正規化、升序)。 `[]` = 不收。計次範圍是該訂單所屬的備案鏈。
fromCount累計未中籤 ≥ 此次數時適用本列(最小 1)。
totalTwd到 `fromCount` 次為止的**累計總額**(整數 TWD,每位旅客各自計)。
tourAgreementEnabled契約流程總開關(預設關)。
tourAgreementTravelForm舊 API 的單一旅遊型態;只供相容使用。
tourAgreementDomesticTravelFormtourAgreementOverseasTravelFormcompanyRepresentative乙方負責人;null = 未設定 → 契約 fail-closed。
travelAgencyRegistrationNo旅行業註冊編號;null = 未設定 → 契約 fail-closed。
courtJurisdiction合意管轄法院;null = 未設定 → 契約 fail-closed。
tourAgreementChangeDaysDefault可變更第三人期限:免抽籤梯次預設(NOT NULL DEFAULT 35)。
tourAgreementChangeBufferDays可變更第三人期限:抽籤日前的緩衝天數(NOT NULL DEFAULT 5)。
tourAgreementLotteryDeadlineTypeKey選填tourAgreementReviewHardBlock審閱期硬擋 24 小時(預設關,只記錄提供 / 簽署時間)。
tourAgreementGuardianSigning未成年由法定代理人代簽(預設開)。
tourAgreementSoftBlock出團軟擋:未簽列入出團前待辦(預設關;系統永不硬擋)。
escortLeadLabel隨團人員職稱:`leader` 的顯示文字(issue 587;NOT NULL DEFAULT '主要隨團人員')。
escortAssistantLabel隨團人員職稱:`assistant` 的顯示文字(NOT NULL DEFAULT '協同')。
updatedAt設定最後更新時間。
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": "…"
}
}/api/v1/settings參數
companyName選填公司全名,顯示於發票、合約與對外信件抬頭。必填欄,不可清除(省略=不修改)
companyPhone選填公司聯絡電話,顯示於對外文件;傳 null 或空字串清除
taxId選填公司統一編號(8 位數字),用於開立發票;傳 null 或空字串清除
companyAddress選填公司登記地址,顯示於對外文件;傳 null 或空字串清除
logoUrl選填公司 Logo 圖片網址(http/https 或本站圖庫資產路徑),用於後台與對外頁面品牌呈現;傳 null 或空字串清除
emailReplyTo選填系統寄信時的回覆收件信箱,客戶回信會寄到此處;傳 null 或空字串清除
senderLocalPart選填寄件人信箱的帳號部分(@ 前段),與寄件網域組成完整寄件地址;傳 null 或空字串清除
passportExpiryWarningDays選填護照到期前提早幾天提醒(1 至 3650 天),用於行前護照效期預警
guideCertExpiryWarningDays選填嚮導證照到期提醒天數(1 至 3650 天):梯次回程日加上此天數晚於到期日即警示
guideDispatchNearGap選填派嚮導清單的快成團門檻(0 至 99 人):還沒成團、但離成團門檻在此人數以內的梯次預設列進清單
escortLeadLabel選填主要隨團人員(leader)在畫面與信件上的職稱,例:領隊、嚮導(1 至 20 字,不可清空)
escortAssistantLabel選填協同(assistant)在畫面與信件上的職稱,例:導遊、協作嚮導(1 至 20 字,不可清空)
回應欄位 · data
ok是否成功更新租戶設定。
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
/api/v1/settings/assignable-staff回應欄位 · data[]
userId員工的使用者 ID(作為指派對象)。
name員工顯示姓名。
email員工登入 Email。
role員工角色代碼(sales/admin 等可指派角色)。
thisMonthAssigned本月(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
/api/v1/settings/assignment參數
assignmentMode必填auto_round_robinauto_customer_choiceauto_by_destinationmanual_review訂單指派模式:auto_round_robin 輪流自動指派、auto_customer_choice 依客戶選擇指派、auto_by_destination 依目的地地區碼對應規則指派、manual_review 進待審由人工指派
defaultAssigneeUserId選填預設承辦人員的使用者 ID,自動指派找不到對象時的兜底承辦人;空字串表示不設預設
allowSalesClaim選填是否開放業務自派搶單(從待派發池自行搶單);未提供則不變更
回應欄位 · data
ok是否成功更新訂單指派模式設定。
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.
/api/v1/settings/cancellation-policy參數
unpaidEnabled必填Enable unpaid customer cancellation
paidEnabled必填Enable paid customer cancellation
paidMinDaysBefore必填Minimum days before departure
refundRemitFeeTwd必填Refund remittance fee
feeTiers必填Cancellation tiers; exactly one fee per row
lotteryFilingFeeTiers必填Cumulative filing fee tiers
customerCancelReminder選填Plain-text reminder shown before a customer confirms self-cancellation; null or blank clears it, omit to keep it
customerRescheduleMinDaysBefore選填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選填refund_draftkeep_overpaidWhen the new departure is cheaper: refund_draft opens a refund draft, keep_overpaid keeps the surplus on the order; omit to keep it
回應欄位 · data
okcurl -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
/api/v1/settings/departure-owner-rotation回應欄位 · data
domesticmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。
overseasmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 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": "…"
}
}
}/api/v1/settings/departure-owner-rotation參數
region必填domesticoverseasWhich list to replace: domestic (國內線) or overseas (海外線)
userIds必填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
domesticmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 null。
overseasmembersuserIdnameassignablefalse = 目前不可指派(角色改了或封鎖中),輪到時會跳過。
nextUserId下一個新梯次會帶入的人;名單空的或沒人可指派時為 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.
/api/v1/settings/destination-rules回應欄位 · data[]
idregionCoderegionName地區中文名稱。
assigneeUserId受派業務 userId;null = assignee 離職/刪帳號後被 SET NULL(規則退化為未命中)。
assigneeName受派業務姓名;未指派或帳號已刪除時為 null。
assigneeRolecreatedAtupdatedAtcurl -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": "…"
}
]
}/api/v1/settings/destination-rules參數
regionCode必填Region code
assigneeUserId必填Staff user ID
回應欄位 · data
idcurl -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.
/api/v1/settings/destination-rules/{id}參數
id路徑Resource ID
回應欄位 · data
okcurl -X DELETE "https://your-tenant.example.com/api/v1/settings/destination-rules/<id>" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": true
}
}/api/v1/settings/ecpay-credentials參數
merchantId必填綠界 ECPay 特店編號(MerchantID),用於金流請款與簽章
hashKey必填綠界 ECPay HashKey,CheckMacValue 簽章用密鑰;寫入後即 KMS 加密儲存且永不回傳
hashIv必填綠界 ECPay HashIV,CheckMacValue 簽章用初始向量;寫入後即 KMS 加密儲存且永不回傳
回應欄位 · data
ok是否成功儲存 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
}
}/api/v1/settings/ecpay-credentials回應欄位 · data
ok是否成功清除 ECPay 憑證。
curl -X DELETE "https://your-tenant.example.com/api/v1/settings/ecpay-credentials" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": true
}
}公司營業費用類別目錄
/api/v1/settings/expense-categories參數
activeOnly選填是否只回傳啟用中的費用類別(true/false);省略則含停用
回應欄位 · data[]
id費用類別 ID。
code科目代碼(租戶內唯一穩定識別,如 rent / salary_admin / tax_vat)。
displayName顯示名(如 房租 / 行政薪資 / 營業稅)。
kind費用大類:opex 營業費用 / tax 稅 / platform_fee 平台手續費 / special 特殊損益(損益表據此 roll-up)。
isActive是否啟用(停用不刪,既有費用列仍引用得到)。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/settings/expense-categories參數
code必填費用類別代碼(小寫英數與底線),建立後不可變更,作為類別的穩定識別
displayName必填費用類別顯示名稱,呈現於後台費用登錄與報表
kind必填opextaxplatform_feespecial費用類別種類:opex 營業費用、tax 稅務、platform_fee 平台手續費、special 特殊,影響損益表歸類
回應欄位 · data
id新建立的費用類別 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 +
/api/v1/settings/expense-categories/{id}參數
id路徑費用類別 ID(路徑參數),指定要更新的類別
displayName必填費用類別顯示名稱,呈現於後台費用登錄與報表
kind必填opextaxplatform_feespecial費用類別種類:opex 營業費用、tax 稅務、platform_fee 平台手續費、special 特殊,影響損益表歸類
isActive必填是否啟用此費用類別;false 為停用(停用而非刪除)
回應欄位 · data
ok是否成功更新費用類別。
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費用類別
/api/v1/settings/expense-categories/{id}/active參數
id路徑費用類別 ID(路徑參數),指定要切換啟用狀態的類別
isActive必填目標啟用狀態:true 啟用、false 停用(停用而非刪除)
回應欄位 · data
ok是否成功切換費用類別的啟用狀態。
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
/api/v1/settings/fee-category-routes回應欄位 · data[]
id路由設定 ID。
feeCategory費用類型代碼(租戶自定唯一鍵,如 tour_fee/lodging/equipment)。
displayName費用類型顯示名。
finalAccountId此費用類型最終結算進的收款帳戶 ID。
finalAccountName最終收款帳戶名稱;無對應帳戶時為 null。
finalAccountCodefinal 帳戶代號。
isActive此路由是否啟用。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/settings/fee-category-routes參數
feeCategory必填費用類型代碼(小寫英數與底線),此 upsert 的唯一鍵;決定該手續費類型最終結算到哪個帳戶
displayName必填費用類型路由的顯示名稱,呈現於對帳設定
finalAccountId必填此費用類型最終結算進的收款帳戶 ID
isActive選填是否啟用此費用類型路由;省略則維持預設啟用
回應欄位 · data
id新建立或更新的費用類型路由 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
/api/v1/settings/fee-category-routes/{id}/active參數
id路徑費用類型路由 ID(路徑參數,非 feeCategory 代碼),指定要切換啟用狀態的路由
isActive必填目標啟用狀態:true 啟用、false 停用(停用而非刪除)
回應欄位 · data
ok是否成功切換費用類型路由的啟用狀態。
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.
/api/v1/settings/fee-item-presets回應欄位 · data[]
idtext項目文字(租戶內唯一)。
included預設歸「含」(true)或「不含」(false)。
displayOrdercreatedAtupdatedAtcurl -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": "…"
}
]
}/api/v1/settings/fee-item-presets參數
text必填Fee text
included必填Included in trip price
displayOrder選填Display order
回應欄位 · data
idcurl -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.
/api/v1/settings/fee-item-presets/{id}參數
id路徑Resource ID
text必填Fee text
included必填Included in trip price
displayOrder選填Display order
回應欄位 · data
okcurl -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.
/api/v1/settings/fee-item-presets/{id}/delete參數
id路徑Resource ID
回應欄位 · data
okcurl -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.
/api/v1/settings/group-code-pattern參數
pattern必填Pattern; null restores default
seqStyle必填alphaalpha_no_ionumericSequence style
seqWidth必填Sequence width
回應欄位 · data
okcurl -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.
/api/v1/settings/guide-portal-policy參數
loginMode必填password_totppassword_onlyGuide login mode
dossierWindowDays必填Roster access days after return
回應欄位 · data
okcurl -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
}
}各家整合的憑證綁定狀態
/api/v1/settings/integration-credentials回應欄位 · data[]
provider整合代號(`ecpay` / `travelinvoice`… / 轉換追蹤的 `ga4`、`meta`)。列不存在=該家未綁定。
merchantId金鑰綁定的帳號 ID(明文,顯示 / 診斷用):金流是特店 ID,`ga4` 是 Measurement ID,`meta` 是 Pixel ID。
secretsMask金鑰的遮罩碼(`****` + 末 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
/api/v1/settings/ledger-fees參數
ecpayFeeBps選填綠界 ECPay 金流手續費率,單位 basis points(0..10000,10000=100%),用於內外帳參考預估淨利;留空不變更
fongshouFeeBps選填豐收金流手續費率,單位 basis points(0..10000,10000=100%),用於內外帳參考預估淨利;留空不變更
profitTaxBps選填淨利稅率,單位 basis points(0..10000,10000=100%),用於內外帳參考預估淨利;留空不變更
回應欄位 · data
ok是否成功更新內外帳參考預估淨利費率。
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.
/api/v1/settings/modules回應欄位 · data
tourclimbinglodgingaccountinglotteryapi_accessheadless_storefrontcustom_domaincurl -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
}
}/api/v1/settings/payment-provider回應欄位 · data
selectedswitchingAllowedtestAllowedproviderscurl -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": [
"…"
]
}
}/api/v1/settings/payment-provider參數
operation必填switchconfigurechange_merchantrotate_keyunlinkfee_policyprovider必填manualtestecpaypayuninewebpaypaynowsinopacmerchantId選填Required for credential configuration, merchant changes, and key rotation.
environment選填sandboxproductionRequired for credential operations.
hashKey選填Required with HashIV for ECPay and PAYUNi. This secret is never returned.
hashIv選填Required with HashKey for credential operations. This secret is never returned.
transactionPassword選填Required for PayNow credential operations. This secret is never returned.
hashA1選填Required for SinoPac credential operations. This secret is never returned.
hashA2選填Required for SinoPac credential operations. This secret is never returned.
hashB1選填Required for SinoPac credential operations. This secret is never returned.
hashB2選填Required for SinoPac credential operations. This secret is never returned.
xKey選填Required for SinoPac credential operations. This secret is never returned.
notificationFeeBps選填Required for fee_policy. New PAYUNi, NewebPay, and PayNow attempts retain this fee estimate.
回應欄位 · data
okcurl -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.
/api/v1/settings/pnl-regions回應欄位 · data[]
idcodedisplayNamedisplayOrderisActivecreatedAtupdatedAtcurl -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": "…"
}
]
}/api/v1/settings/pnl-regions參數
code必填Region code
displayName必填Region name
displayOrder選填Display order
回應欄位 · data
idcurl -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.
/api/v1/settings/pnl-regions/{id}參數
id路徑Resource ID
displayName必填Region name
displayOrder選填Display order
回應欄位 · data
okcurl -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.
/api/v1/settings/pnl-regions/{id}/active參數
id路徑Resource ID
isActive必填Enabled status
回應欄位 · data
okcurl -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收款帳戶目錄
/api/v1/settings/receiving-accounts參數
activeOnly選填是否只回傳啟用中的收款帳戶(true/false);省略則含停用
回應欄位 · data[]
id收款帳戶 ID。
code帳戶代碼(租戶內唯一穩定識別)。
displayName帳戶顯示名。
kind帳戶類型:bank 銀行 / cash 現金 / gateway 金流閘道。
gatewayProvider綁定的金流商代號(限 gateway 帳戶;null = 未綁定)。金流收款歸戶讀這一欄, 不比對 code(issue #603)。可綁定清單見 `payment/gateway-providers.ts`。
bankName銀行名稱;現金/閘道帳戶為 null。
accountNo銀行帳號;現金/閘道帳戶為 null。
bankCodebankBranchaccountHoldercanReceive可收款(幾乎都 true)。
canRemit可對外匯款(ATM / 匯出退款 / 補款匯出)。荒野只有永豐。
canChargeback可刷退(退回原信用卡)。由綁定的金流商與平台能力表推導,租戶不設定。
canPaySupplier付款渠道:出團準備的付款登記區可選它付供應商(#1375)。
isDeprecated廢帳戶:仍可零星收款,但其收款需由他帳戶代墊歸集。荒野=RU 台銀 / 登山社。
isSettlementMaster主結算帳戶:所有資金最終向它彙整。每租戶恰一個(partial unique index)。荒野=永豐。
payoutAccountId撥款帳戶(限 gateway 帳戶;null = 未設)。月結把這個帳戶的收款落地改算成它 (account-settlement §2.6)。
currency帳戶幣別(ISO 4217;既有帳戶皆 'TWD',外幣帳戶如 IDR / USD)。
isActive此帳戶是否啟用。
displayOrder後台清單排序序位(小者在前)。
usedCount被多少 payment_transactions 引用(UI 鎖頭 / 「使用中 N」)。
currencyLocked幣別是否已鎖定(帳戶已被移轉 / 成本引用 → 改幣別會回頭重新解讀全部歷史)。 與 updateReceivingAccount 的守門同一個 predicate,UI 據此把幣別欄改唯讀。
createdAt建立時間。
updatedAt最後更新時間。
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": "…"
}
]
}/api/v1/settings/receiving-accounts參數
code必填收款帳戶代號,建立後不可變更,作為帳戶的穩定識別
displayName必填收款帳戶顯示名稱,呈現於收款與對帳介面
kind必填bankcashgateway帳戶種類:bank 銀行帳戶、cash 現金、gateway 金流閘道
gatewayProvider選填綁定的金流商代號(如 ecpay),限 gateway 帳戶;該金流商的收款會自動歸入此帳戶。空字串或省略 = 不綁定
payoutAccountId選填撥款帳戶 ID,限 gateway 帳戶:金流商把收款撥進的台幣銀行帳戶(須啟用中)。設定後月結把此帳戶的收款落地改算成撥款帳戶。空字串或省略 = 不設
bankName選填銀行名稱(bank 類別適用);空字串清除
bankCode選填銀行代碼;匯款用途須填完整
bankBranch選填分行;匯款用途須填完整
accountHolder選填戶名;匯款用途須填完整
accountNo選填銀行帳號(bank 類別適用);空字串清除
currency選填帳戶幣別,ISO 4217 三碼(如 TWD / JPY / IDR);空字串預設 TWD,非 TWD 即為外幣池
displayOrder選填排序權重(0..9999),數字越小越前面;預設 0
isActive選填是否啟用此帳戶;省略維持預設
canReceive選填是否可作為收款(進帳)帳戶
canRemit選填是否可作為出款(匯出)帳戶
canPaySupplier選填是否可作為出團準備付款登記的付款渠道(例:小編機)
isDeprecated選填是否標記為已淘汰(保留歷史紀錄但不再新用)
isSettlementMaster選填是否為主結算帳戶;每租戶僅能有一個,月結互抵以此為彙整中心
回應欄位 · data
id新建立的收款帳戶 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收款帳戶
/api/v1/settings/receiving-accounts/{id}參數
id路徑收款帳戶 ID(路徑參數),指定要更新的帳戶
displayName必填收款帳戶顯示名稱,呈現於收款與對帳介面
kind必填bankcashgateway帳戶種類:bank 銀行帳戶、cash 現金、gateway 金流閘道
gatewayProvider選填綁定的金流商代號(如 ecpay),限 gateway 帳戶;省略維持原值,空字串解除綁定
payoutAccountId選填撥款帳戶 ID,限 gateway 帳戶:金流商把收款撥進的台幣銀行帳戶(須啟用中)。省略維持原值,空字串或 null 清除
bankName選填銀行名稱(bank 類別適用);空字串清除
bankCode選填銀行代碼;匯款用途須填完整
bankBranch選填分行;匯款用途須填完整
accountHolder選填戶名;匯款用途須填完整
accountNo選填銀行帳號(bank 類別適用);空字串清除
currency選填帳戶幣別,ISO 4217 三碼(如 TWD / JPY / IDR);省略維持原值,非 TWD 即為外幣池
displayOrder必填排序權重(0..9999),數字越小越前面
isActive選填是否啟用此帳戶;省略維持原值
canReceive選填是否可作為收款(進帳)帳戶
canRemit選填是否可作為出款(匯出)帳戶
canPaySupplier選填是否可作為出團準備付款登記的付款渠道(例:小編機)
isDeprecated選填是否標記為已淘汰(保留歷史紀錄但不再新用)
isSettlementMaster選填是否為主結算帳戶;每租戶僅能有一個,月結互抵以此為彙整中心
回應欄位 · data
ok是否成功更新收款帳戶。
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.
/api/v1/settings/recurring-expenses回應欄位 · data[]
idcategoryIdcategoryCodecategoryDisplayNamecategoryKindamountTwddescriptionpaidFromAccountIdpaidFromAccountNameisActivecreatedByUserIdcreatedAtupdatedAtcurl -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": "…"
}
]
}/api/v1/settings/recurring-expenses參數
categoryId必填Expense category ID
amountTwd必填Default amount TWD
description必填Description
paidFromAccountId選填Payer account ID
回應欄位 · data
idcurl -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.
/api/v1/settings/recurring-expenses/{id}參數
id路徑Resource ID
categoryId必填Expense category ID
amountTwd必填Default amount TWD
description必填Description
paidFromAccountId選填Payer account ID
回應欄位 · data
okcurl -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.
/api/v1/settings/recurring-expenses/{id}/active參數
id路徑Resource ID
isActive必填Enabled status
回應欄位 · data
okcurl -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
/api/v1/settings/sending-domain回應欄位 · data
sendingDomain自有寄件網域;未設定時為 null。
resendDomainId寄件服務商(Resend)的網域識別碼;未設定時為 null。
sendingDomainStatus網域驗證狀態(如 pending/verified);未設定時為 null。
senderLocalPart寄件人信箱的帳號部分(@ 前段);未填視為 info。
records待設定的 DNS 記錄清單(SPF/DKIM 等);Resend 不可達或未設定時為空陣列。
recordDNS 記錄用途分類(如 DKIM/SPF 等,來自 Resend)。
name記錄主機名(需在網域 DNS 新增的 host)。
type記錄類型(如 TXT/MX/CNAME)。
value記錄值(需填入 DNS 的內容)。
ttl選填存活時間(TTL);未指定時省略。
status選填此筆記錄的驗證狀態(如 pending/verified);未指定時省略。
priority選填MX 記錄優先權;非 MX 記錄省略。
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
/api/v1/settings/sending-domain/disable回應欄位 · data
ok是否成功停用自有寄件網域。
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
/api/v1/settings/sending-domain/enable回應欄位 · data
ok是否成功啟用自有寄件網域。
domain啟用的寄件網域(由綁定的站台網域派生)。
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
/api/v1/settings/sending-domain/verify回應欄位 · data
ok是否成功觸發驗證狀態同步。
status從 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
/api/v1/settings/seo參數
siteTagline選填網站標語,顯示於公開站標題與品牌呈現;空字串清除
seoDefaultDescription選填SEO 預設頁面描述(meta description),未個別設定的頁面套用此值;空字串清除
ogImageUrl選填社群分享預設縮圖(Open Graph image)網址(http/https 或本站圖庫資產路徑);空字串清除
回應欄位 · data
ok是否成功更新公開站 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
}
}/api/v1/settings/storefront回應欄位 · data
bannersimageUrlaltlinkUrlnamefaqsquestionanswercategoriesnametagimageUrlwebsiteModeactiveCustomStorefrontUrltemplatecustomStorefrontUrlcustomStorefrontTripPathslotsaboutContentMdxcurl -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": "…"
}
}/api/v1/settings/storefront參數
websiteMode選填platformheadlessExplicitly activate the saved website address or restore the platform website
template選填outdoorresortminimalvoyageApply a platform template without changing the website mode
customStorefrontUrl選填Prepared HTTPS website address; saving does not activate it
customStorefrontTripPath選填Trip page path on the headless storefront, with one {slug}, such as /shop/{slug}; null keeps trip links on the platform trip page
slots選填Partial content overrides; null restores the template default
aboutContentMdx選填About page content; null clears it
banners選填Home page banner carousel in display order; replaces the whole list
faqs選填Home page FAQ in display order; replaces the whole list
categories選填Home page trip categories in display order; replaces the whole list
回應欄位 · data
okcurl -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.
/api/v1/settings/tour-agreement參數
enabled必填Enable agreements
domesticTravelForm選填individualgroupDomestic travel form
overseasTravelForm選填individualgroupOverseas travel form
travelForm選填individualgroupLegacy travel form for both regions
companyRepresentative必填Company representative
travelAgencyRegistrationNo必填Agency registration number
courtJurisdiction必填Court jurisdiction
changeDaysDefault必填Default change days
lotteryDeadlineTypeKey選填Deadline type for the lottery date
changeBufferDays必填Change buffer days
reviewHardBlock必填Enforce review period
guardianSigning必填Allow guardian signing
softBlock必填Enable soft block
回應欄位 · data
okcurl -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
}
}/api/v1/settings/workflow-controls回應欄位 · data
newPaymentsPausednewAgreementsPausedcurl -X GET "https://your-tenant.example.com/api/v1/settings/workflow-controls" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"newPaymentsPaused": true,
"newAgreementsPaused": true
}
}/api/v1/settings/workflow-controls參數
newPaymentsPaused必填Pause new payment forms
newAgreementsPaused必填Pause new agreements
回應欄位 · data
newPaymentsPausednewAgreementsPausedcurl -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
/api/v1/staff回應欄位 · data[]
userId員工的使用者 ID。
email員工登入 Email(帳號識別)。
name員工顯示姓名。
role員工角色代碼(admin/sales/op/accountant)。
createdAt帳號建立時間。
bannedAccount frozen via ban (離職 / 停權). False after a temporary ban ends, also before the next sign-in clears it.
twoFactorEnabled是否已完成 TOTP 兩步驟驗證註冊。
emailVerifiedEmail 是否已驗證。**不是**啟用判準:員工邀請流程不寄信(一次性密碼當場交付), 所以受邀者走完整條流程這個旗標也不會變 true。啟用看 `activated`。
lastLoginAt最後一次登入時間;`null` = 從來沒有人登入過這個帳號。代理登入不計。
activated派生的「已啟用」狀態:至少成功登入過一次,代表發出去的一次性密碼有人在用。
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
/api/v1/staff/{userId}參數
userId路徑欲移除員工身分的使用者 ID(將降為一般顧客)
回應欄位 · data
ok是否成功移除員工身分(降為一般顧客)。
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.
/api/v1/staff/{userId}/ban參數
userId路徑Resource ID
reason選填Ban reason
回應欄位 · data
okcurl -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
/api/v1/staff/{userId}/role參數
userId路徑欲變更角色的員工使用者 ID
role必填變更後的員工角色(內建 admin/sales/op/accountant,或本租戶自訂角色),決定權限範圍
回應欄位 · data
ok是否成功變更員工角色。
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.
/api/v1/staff/{userId}/unban參數
userId路徑Resource ID
回應欄位 · data
okcurl -X POST "https://your-tenant.example.com/api/v1/staff/<userId>/unban" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": "…"
}
}建立一個新員工帳號
/api/v1/staff/invite參數
email必填受邀員工的登入 Email,作為帳號識別
name必填員工顯示姓名
role必填指派的員工角色(內建 admin/sales/op/accountant,或本租戶自訂角色),決定權限範圍
回應欄位 · data
userId新建立員工的使用者 ID。
tempPassword一次性明文暫時密碼,僅此次回傳(請立即轉交並要求員工首次登入改密)。
email新員工的登入 Email。
role指派的員工角色(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": "…"
}
}/consent-kinds
Use the canonical tenant operation.
/api/v1/consent-kinds回應欄位 · data[]
id`cnsk_<ulid>`;同時是這個種類的範本列 `consent_templates.kind`。
labelsortOrderisActivesignTimingsignerScopeallTripstrue = 所有行程適用;false = 只適用 `tripIds`。
tripIdstemplateCount此種類已建的範本版本數。
curl -X GET "https://your-tenant.example.com/api/v1/consent-kinds" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": [
{
"id": "…",
"label": "…",
"sortOrder": 0,
"isActive": true,
"signTiming": "after_confirm",
"signerScope": "order",
"allTrips": true,
"tripIds": [
"…"
],
"templateCount": 0
}
]
}/api/v1/consent-kinds參數
label必填Kind label
sortOrder選填Display order
signTiming必填checkoutafter_confirmSign timing
signerScope必填ordertravelerSigner scope
allTrips必填Apply to all trips
tripIds必填Selected trip IDs
回應欄位 · data
okidcurl -X POST "https://your-tenant.example.com/api/v1/consent-kinds" \
-H "Authorization: Bearer $TOKO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"label": "example-label",
"signTiming": "checkout",
"signerScope": "order",
"allTrips": true,
"tripIds": [
"example-tripIds"
]
}'{
"ok": true,
"data": {
"ok": "…",
"id": "…"
}
}Use the canonical tenant operation.
/api/v1/consent-kinds/{id}參數
id路徑Resource ID
label必填Kind label
sortOrder選填Display order
signTiming必填checkoutafter_confirmSign timing
signerScope必填ordertravelerSigner scope
allTrips必填Apply to all trips
tripIds必填Selected trip IDs
isActive必填Kind enabled
回應欄位 · data
okidcurl -X PUT "https://your-tenant.example.com/api/v1/consent-kinds/<id>" \
-H "Authorization: Bearer $TOKO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"label": "example-label",
"signTiming": "checkout",
"signerScope": "order",
"allTrips": true,
"tripIds": [
"example-tripIds"
],
"isActive": true
}'{
"ok": true,
"data": {
"ok": "…",
"id": "…"
}
}/api/v1/consent-kinds/{id}參數
id路徑Resource ID
回應欄位 · data
okidcurl -X DELETE "https://your-tenant.example.com/api/v1/consent-kinds/<id>" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"ok": "…",
"id": "…"
}
}/departure-op-assignments
Use the canonical tenant operation.
/api/v1/departure-op-assignments/{id}參數
id路徑Resource ID
回應欄位 · data
okdepartureIduserIdcurl -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
跨梯次到期待辦
/api/v1/departure-prep/deadlines參數
range選填todayalltoday = 只列逾期、超級緊急、可以開始三級;all(預設)= 再加注意準備
horizon選填scope選填allunassignedall(預設)= 全公司;unassigned = 只看尚未指派承辦的梯次
anomalies選填設為 true 時一併回傳日期設定異常(規則適用卻沒有日期列);預設 false
回應欄位 · data
todayhorizonrangerowssoftDatehardDatesourcedayMode梯次期限列存的 day_mode(產生或人工寫入當下解析出的有效規則)。距離單位:`workday` 算工作天, 其他模式(含 `month_same_day`)算日曆天。
hardDistancesoftDistanceurgencylotteryDraw期限日取自抽籤時程表時的時段與原抽籤日(lottery-schedule spec §3.5)。
slotStartslotEndfirstDrawDatelabeldepartureIdtripIdtripTitletripShortName行程內部簡稱(issue 1414);未填為 null。
groupCodedepartureDateopNames承辦小編姓名(依姓名排序);空陣列 = 未指派。
typeKeyanomalies`anomalies: false` 時恆為空陣列。
labeldepartureIdtripIdtripTitletripShortName行程內部簡稱(issue 1414);未填為 null。
groupCodedepartureDateopNames承辦小編姓名(依姓名排序);空陣列 = 未指派。
typeKeycountsoverduecriticalstartupcomingmissingHolidayYears未逾期的工作天事項「今天 → 硬 deadline」之間假日表未維護年度的聯集。
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
/api/v1/email-history參數
startDate選填endDate選填status選填queuedsendingsentfailedcategory選填authorderpaymentguidecontractmessagesystemrecipient選填departureId選填orderId選填guideId選填asOf選填page選填pageSize選填回應欄位 · data
itemsidtoEmailsubjecttemplateKeycategorystatuserrorattemptsorderIddepartureIdguideIdcreatedAtsentAtcanRetryretryRecipientretryUnavailableReasontotalpagepageSizeasOfcurl -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": "…"
}
}/api/v1/email-history/{id}參數
id路徑回應欄位 · data
htmltextcontentStateidtoEmailsubjecttemplateKeycategorystatuserrorattemptsorderIddepartureIdguideIdcreatedAtsentAtcanRetryretryRecipientretryUnavailableReasoncurl -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"
}
}/api/v1/email-history/{id}/retry參數
id路徑expectedRecipient選填回應欄位 · data
retriedcurl -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
/api/v1/guide-categories回應欄位 · data[]
idnamesortOrderisActive停用 = 不供新選用(既有嚮導照舊顯示這個分類)。
guideCount引用此分類的嚮導數(>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
}
]
}/api/v1/guide-categories參數
name必填Guide category name
sortOrder選填Display order; also the default guide sort order
回應欄位 · data
okidcurl -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
/api/v1/guide-categories/{id}參數
id路徑Resource ID
name選填Guide category name
sortOrder選填Display order; also the default guide sort order
isActive選填Category enabled; inactive categories stay on existing guides but are not offered for new ones
回應欄位 · data
okcurl -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": "…"
}
}/api/v1/guide-categories/{id}參數
id路徑Resource ID
回應欄位 · data
okremovednamecurl -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.
/api/v1/guide-certificate-types回應欄位 · data[]
idnamesortOrderisActive停用 = 不供新證照選用(既有證照不受影響)。
certificateCount引用此類別的證照數(>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
}
]
}/api/v1/guide-certificate-types參數
name必填Certificate type name
sortOrder選填Display order
回應欄位 · data
okidcurl -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.
/api/v1/guide-certificate-types/{id}參數
id路徑Resource ID
name選填Type name
sortOrder選填Display order
isActive選填Type enabled
回應欄位 · data
okcurl -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": "…"
}
}/api/v1/guide-certificate-types/{id}參數
id路徑Resource ID
回應欄位 · data
okremovednamecurl -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
嚮導顯示自己帶梯次旅客的證號
/api/v1/guide-portal/travelers/{travelerId}/reveal參數
travelerId路徑旅客 ID
field必填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.
/api/v1/lottery-filings/adjustments參數
personId必填Person ID
orderId必填Order ID
delta必填Signed adjustment
reason必填Adjustment reason
回應欄位 · data
personIdchains依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。
headOrderId鏈首訂單(分組鍵)。
headOrderNumberfilingCount送件紀錄筆數(這條鏈上)。
adjustmentTotal調整差額加總(這條鏈上,可負)。
count目前送件次數加上調整差額,下限為 0。
nextSeq下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。
filingsidorderIdorderNumbertravelerName送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。
createdAtadjustmentsidorderId這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。
orderNumberdeltareasonactorName下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。
createdAtcurl -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.
/api/v1/lottery-filings/count參數
personId必填Person ID
orderId必填Order ID
回應欄位 · data
personIdchains依鏈首訂單分組,**新的鏈排前面**(承辦手上那張通常是最新的)。
headOrderId鏈首訂單(分組鍵)。
headOrderNumberfilingCount送件紀錄筆數(這條鏈上)。
adjustmentTotal調整差額加總(這條鏈上,可負)。
count目前送件次數加上調整差額,下限為 0。
nextSeq下一次送件的計費序號,可為 0 或負數。不要用 count 加 1 代替。
filingsidorderIdorderNumbertravelerName送件對象的旅客姓名。旅客列被刪或匿名化之後為 null(`traveler_id` 是快照 id,無 FK)。
createdAtadjustmentsidorderId這筆調整掛在哪一張單(生效範圍是該單所屬的鏈)。
orderNumberdeltareasonactorName下這筆調整的承辦。**恆有值**:CHECK 逼 `adjusted_by_user_id` 在調整列上必填,而它的 FK 是 `NO ACTION`(同 `audit_log.actor_user_id`)—— 有調整紀錄的員工帳號刪不掉。
createdAtcurl -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.
/api/v1/lottery-filings/lookup參數
docType必填id_numberpassportDocument type
docNumber必填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
/api/v1/lottery-notice-templates回應欄位 · data[]
idlengthReturns the length of a String object.
namecontentMdxcreatedAtupdatedAtcurl -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": "…"
}
]
}/api/v1/lottery-notice-templates參數
name必填範本名稱,可依抽籤天數或路線命名
contentMdx必填須知 MDX 內容,可使用 Notice 醒目提醒區塊
回應欄位 · data
idlengthReturns 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
}
}
}/api/v1/lottery-notice-templates/{id}參數
id路徑抽籤須知範本 ID
回應欄位 · data
idlengthReturns the length of a String object.
namecontentMdxcreatedAtupdatedAtcurl -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": "…"
}
}/api/v1/lottery-notice-templates/{id}參數
name必填範本名稱,可依抽籤天數或路線命名
contentMdx必填須知 MDX 內容,可使用 Notice 醒目提醒區塊
id路徑抽籤須知範本 ID
回應欄位 · data
okcurl -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
}
}/api/v1/lottery-notice-templates/{id}參數
id路徑抽籤須知範本 ID
回應欄位 · data
okcurl -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.
/api/v1/lottery-schedules回應欄位 · data
schedulesidnamesourcelastSyncAttemptedAtlastSyncedAtlastSyncErrorentryCountwarningcurl -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.
/api/v1/lottery-schedules/{id}/entries/batch參數
id路徑Lottery schedule ID
rows必填Rows to write. A stay date that is already on the table is updated.
回應欄位 · data
changedStayDateswrittenCountrecomputedDepartureCountcurl -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.
/api/v1/message-template-stages回應欄位 · data[]
id階段 ID('mts_<ulid>')。
name階段顯示名(FK 錨點;改名 ON UPDATE CASCADE 連動範本列)。
sortOrderisActive停用 = 不供新範本選用(既有綁此階段的範本不受影響)。
templateCount綁此階段的範本數(>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
}
]
}/api/v1/message-template-stages參數
name必填Stage name
sortOrder選填Display order
回應欄位 · data
okidcurl -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.
/api/v1/message-template-stages/{id}參數
id路徑Resource ID
name選填Stage name
sortOrder選填Display order
isActive選填Stage enabled
回應欄位 · data
okcurl -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": "…"
}
}/api/v1/message-template-stages/{id}參數
id路徑Resource ID
回應欄位 · data
okremovednamesortOrderisActivecurl -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.
/api/v1/operating-expenses/{id}/confirm參數
id路徑Resource ID
amountTwd選填Actual amount TWD; omit to retain draft amount
回應欄位 · data
okcurl -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
待回覆的訂單對話
/api/v1/order-conversations/awaiting-reply參數
olderThanHours必填最後一則訂購人留言距今至少幾小時(含),整數 1–720,必填
page選填頁碼,從 1 起算,預設第 1 頁
pageSize選填每頁筆數,上限 200
回應欄位 · data
rowsorderIdorderNumbercustomerNamelastCustomerMessageAttotalpagepageSizecurl -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
/api/v1/permit-applications/{id}參數
id路徑申請單 ID(pmt_ 前綴)
回應欄位 · data
application申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
files證件檔清單。檔案本身只能從後台下載。
id證件檔 ID(pmf_ 前綴)。
kind檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。
contentType檔案類型:application/pdf、image/png 或 image/jpeg。
sizeBytes檔案大小(位元組)。
sha256檔案的 sha256(hex)。
originalName原始檔名。
uploadedAt上傳時間。
uploadedByUserId上傳者的使用者 ID。
source來源:staff(後台)或 api(送籤台)。
events歷程,新的在前。身分證只有遮罩值。
id歷程 ID(pme_ 前綴)。
kind歷程種類,例:created、status_changed、status_ignored、renumbered。
source來源:staff(後台)或 api(送籤台)。
actorUserId寫入者的使用者 ID。
actorName寫入者的姓名。
apiKeyId送籤台寫入時的 API 金鑰 ID。
apiKeyName寫入的 API 金鑰名稱;金鑰已刪為 null。
changes改了什麼:{ 欄位: { from, to } }。身分證只有遮罩值。 領隊是嚮導或旅客時,歷程只存來源 id;讀取時補上來源目前的姓名與遮罩。 補的欄是 `name`、`idNumber`;建單歷程是 `leaderName`、`leaderIdNumber`。 去識別化的旅客顯示去識別化後的名字。
reason原因(強制覆蓋、作廢)。
createdAt寫入時間。
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": "…"
}
]
}
}/api/v1/permit-applications/{id}參數
office選填one_stoppoliceforestryother申請處:one_stop(國家公園一站式)/ police(警政署入山)/ forestry(林務局山屋/營地)/ other(其他)。建單時必填
officeLabel選填申請處名稱;office = other 時必填,例:一葉蘭許可
route選填路線(站方表單上的路線名)
groupLabel選填組別,例:A 組。分組送件時用來分辨同一梯的多張單
partySize選填申請人數(1–99)
entryDate選填入園日(YYYY-MM-DD)
exitDate選填離園日(YYYY-MM-DD),不得早於入園日
teamName選填隊名(站方表單上的隊伍名稱)
applicantName選填申請人姓名
applicantIdNumber選填申請人身分證明碼(加密存放);需要 permit_pii.read,沒有時回 403
applicantAccount選填申請用的帳號或信箱
leaderKind選填same_as_applicantguidetravelerother領隊來源:same_as_applicant(同申請人)/ guide(嚮導,帶 leaderGuideId)/ traveler(本團旅客,帶 leaderTravelerId)/ other(手填 leaderName 與 leaderIdNumber)
leaderGuideId選填leaderKind = guide 時的嚮導 ID。伺服器端從嚮導資料取姓名與身分證快照
leaderTravelerId選填leaderKind = traveler 時的旅客 ID(須在本梯)。伺服器端取姓名與身分證快照
leaderName選填領隊姓名;只在 leaderKind = other 時使用
leaderIdNumber選填領隊身分證明碼;只在 leaderKind = other 時使用。需要 permit_pii.read,沒有時回 403
applicationNo選填申請編號(英數與連字號,6–20 字)。改號時直接給新號,舊號留在歷程
oneStopSerial選填一站式序號
caseNo選填項目案件編號
submittedAt選填申請(送出)時間(ISO 8601,含時區)
status選填draftsubmitted_no_numbersubmittedin_reviewwaitlistedlost_to_waitlistwon_pending_paymentwon_needs_documentsapprovedlostrejecteddeniedwaitlist_failedcancelled狀態。弱的狀態不蓋強的:較弱時不套用,回應 applied.status.reason = weaker_status。voided 只能由重送產生
statusNote選填狀態說明
checkedAt選填最近一次查籤的時間(ISO 8601,含時區)
siteDetail選填站方明細原文(查詢頁的文字摘要)
waitlistRank選填備取順位
eligibility選填pendinggrantednot_granted入園資格:pending(待定)/ granted(取得)/ not_granted(未取得)
eligibilityNote選填資格說明
bedNumbers選填床位/營位編號,原文照存
paymentDueAt選填繳費期限(ISO 8601,含時區;林務局中籤後繳費)
latestMailSummary選填最近來信摘要。不要放身分證
orderIds選填對應的訂單 ID(整組取代,須在本梯)。空陣列 = 整梯的單
idempotencyKey選填冪等鍵(8–64 字英數或連字號)。同一把 key 再送一次不重複寫入,回傳第一次的結果;內容不同回 409 idempotency_conflict
expectedVersion選填目前的 version。和伺服器上的不同時回 409 stale_version
id路徑申請單 ID(pmt_ 前綴)
回應欄位 · data
application更新後的申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
applied每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。
createdPATCH 恆為 false。
replayed這次是同一個 idempotencyKey 的重送,沒有再寫入。
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
}
}上傳一份證件檔
/api/v1/permit-applications/{id}/files參數
id路徑申請單 ID(pmt_ 前綴)
kind必填entry_permitmountain_permitbed_permitsite_snapshotother檔案種類:entry_permit(入園證)/ mountain_permit(入山證)/ bed_permit(床位證)/ site_snapshot(查詢頁快照)/ other
contentBase64必填檔案內容的 base64 編碼字串(PDF / PNG / JPEG,上限 8MB)
originalName選填原始檔名,只顯示用
回應欄位 · data
file證件檔資訊。
id證件檔 ID(pmf_ 前綴)。
kind檔案種類:entry_permit / mountain_permit / bed_permit / site_snapshot / other。
contentType檔案類型:application/pdf、image/png 或 image/jpeg。
sizeBytes檔案大小(位元組)。
sha256檔案的 sha256(hex)。
originalName原始檔名。
uploadedAt上傳時間。
uploadedByUserId上傳者的使用者 ID。
source來源:staff(後台)或 api(送籤台)。
createdfalse = 這張單已有同一個檔案,沒有再存一份。
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
}
}顯示申請人或領隊的身分證全碼
/api/v1/permit-applications/{id}/reveal參數
id路徑申請單 ID(pmt_ 前綴)
field必填applicantIdNumberleaderIdNumber要顯示的欄位:applicantIdNumber 申請人身分證、leaderIdNumber 領隊身分證
回應欄位 · data
field本次顯示的欄位。
value身分證全碼;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": "…"
}
}用找單規則找一張申請單
/api/v1/permit-applications/lookup參數
applicationId選填申請單 ID;有帶時直接用它
applicationNo選填申請編號,配 office。找不到有效單時,再從歷程的改號紀錄找舊號
office選填one_stoppoliceforestryother申請處,配 applicationNo 或 departureId
departureId選填梯次 ID,配 office 與 groupLabel。跳過草稿與已作廢的單
groupLabel選填組別,配 departureId 與 office;不帶或 null = 沒有組別的單
entryDate選填入園日(YYYY-MM-DD),配 departureId 時可再收斂
回應欄位 · data
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
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": "…"
}
}送籤台寫回申請單的主要入口
/api/v1/permit-applications/sync參數
office選填one_stoppoliceforestryother申請處:one_stop(國家公園一站式)/ police(警政署入山)/ forestry(林務局山屋/營地)/ other(其他)。建單時必填
officeLabel選填申請處名稱;office = other 時必填,例:一葉蘭許可
route選填路線(站方表單上的路線名)
groupLabel選填組別,例:A 組。分組送件時用來分辨同一梯的多張單
partySize選填申請人數(1–99)
entryDate選填入園日(YYYY-MM-DD)
exitDate選填離園日(YYYY-MM-DD),不得早於入園日
teamName選填隊名(站方表單上的隊伍名稱)
applicantName選填申請人姓名
applicantIdNumber選填申請人身分證明碼(加密存放);需要 permit_pii.read,沒有時回 403
applicantAccount選填申請用的帳號或信箱
leaderKind選填same_as_applicantguidetravelerother領隊來源:same_as_applicant(同申請人)/ guide(嚮導,帶 leaderGuideId)/ traveler(本團旅客,帶 leaderTravelerId)/ other(手填 leaderName 與 leaderIdNumber)
leaderGuideId選填leaderKind = guide 時的嚮導 ID。伺服器端從嚮導資料取姓名與身分證快照
leaderTravelerId選填leaderKind = traveler 時的旅客 ID(須在本梯)。伺服器端取姓名與身分證快照
leaderName選填領隊姓名;只在 leaderKind = other 時使用
leaderIdNumber選填領隊身分證明碼;只在 leaderKind = other 時使用。需要 permit_pii.read,沒有時回 403
applicationNo選填申請編號(英數與連字號,6–20 字)。改號時直接給新號,舊號留在歷程
oneStopSerial選填一站式序號
caseNo選填項目案件編號
submittedAt選填申請(送出)時間(ISO 8601,含時區)
status選填draftsubmitted_no_numbersubmittedin_reviewwaitlistedlost_to_waitlistwon_pending_paymentwon_needs_documentsapprovedlostrejecteddeniedwaitlist_failedcancelled狀態。弱的狀態不蓋強的:較弱時不套用,回應 applied.status.reason = weaker_status。voided 只能由重送產生
statusNote選填狀態說明
checkedAt選填最近一次查籤的時間(ISO 8601,含時區)
siteDetail選填站方明細原文(查詢頁的文字摘要)
waitlistRank選填備取順位
eligibility選填pendinggrantednot_granted入園資格:pending(待定)/ granted(取得)/ not_granted(未取得)
eligibilityNote選填資格說明
bedNumbers選填床位/營位編號,原文照存
paymentDueAt選填繳費期限(ISO 8601,含時區;林務局中籤後繳費)
latestMailSummary選填最近來信摘要。不要放身分證
orderIds選填對應的訂單 ID(整組取代,須在本梯)。空陣列 = 整梯的單
idempotencyKey選填冪等鍵(8–64 字英數或連字號)。同一把 key 再送一次不重複寫入,回傳第一次的結果;內容不同回 409 idempotency_conflict
match必填找單條件(§6.3)
departureId選填找不到單時要建在哪一梯;match 帶了 departureId 時可省略
replacesId選填重送:被取代的舊單 ID
replacesApplicationNo選填重送:被取代的舊單申請編號(同 match.office 或 office)
回應欄位 · data
application更新或新建後的申請單(身分證遮罩)。
id申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
office申請處:one_stop / police / forestry / other。
officeLabel申請處名稱(office = other 時有值)。
route路線。
groupLabel組別。
partySize申請人數。
entryDate入園日(YYYY-MM-DD)。
exitDate離園日(YYYY-MM-DD)。
teamName隊名。
applicantName申請人姓名。
applicantIdNumberMask申請人身分證遮罩(末 3 碼)。
applicantAccount申請用的帳號或信箱。
leaderKind領隊來源:same_as_applicant / guide / traveler / other。
leaderGuideId領隊是嚮導時的嚮導 ID。
leaderTravelerId領隊是本團旅客時的旅客 ID。
leaderName有效的領隊姓名。`same_as_applicant` 時是申請人姓名。
leaderIdNumberMask有效的領隊身分證遮罩。`same_as_applicant` 時是申請人的遮罩。
leaderChangedAt最近一次換領的時間。
applicationNo申請編號(大寫)。
oneStopSerial一站式序號。
caseNo項目案件編號。
submittedAt申請(送出)時間。
status狀態(見 specs/permit-applications.md §4.1)。
statusNote狀態說明。
checkedAt最近一次查籤的時間。
siteDetail站方明細原文。
waitlistRank備取順位。
eligibility入園資格:pending / granted / not_granted。
eligibilityNote資格說明。
bedNumbers床位/營位編號。
paymentDueAt繳費期限。
latestMailSummary最近來信摘要。
replacesId重送時被這張單取代的舊單 ID。
replacedById取代這張單的新單;沒有被取代為 null。
orderIds對應的訂單 ID;空陣列 = 整梯的單。
fileCount證件檔數。
version版本,每次寫入加 1。PATCH 的 expectedVersion 用它。
createdAt建立時間。
updatedAt最後更新時間。
createdByUserId建單的使用者 ID。
applied每個有帶的欄位是否套用;狀態沒套用時帶 reason: weaker_status。
created這次是否建了新單。
replayed這次是同一個 idempotencyKey 的重送,沒有再寫入。
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
列出還沒完成的申請單取消請求
/api/v1/permit-cancel-requests參數
status選填pendingclaimed只列這個狀態:pending(待處理)或 claimed(已取走)。不帶時兩種都列
limit選填最多列幾筆(1–100,預設 50)
回應欄位 · data
requests還沒完成的請求,依截止時間排序。
id取消請求 ID(pcr_ 前綴)。
applicationId申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
kindcancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。
trigger觸發點:order_cancelled / departure_changed / traveler_removed。
orderId觸發的訂單 ID。
orderNumber觸發的訂單編號。
travelers離開的旅客:只有 id、姓名與身分證遮罩。
idnameidNumberMaskstatuspending(待處理)/ claimed(送籤台已取走)/ done(已完成)。
attempts送籤台回報失敗的次數。
claimedAt送籤台取走的時間。
resultNote最近一次回報的說明。
dueAt最晚要完成的時間:入園日前一天的台北時間 12:00。
createdAt建立時間。
completedAt完成時間。
application申請單摘要,送籤台到站方找單用。
office申請處。
officeLabel申請處名稱(office = other 時有值)。
applicationNo申請編號。
groupLabel組別。
entryDate入園日(YYYY-MM-DD)。
status申請單目前的狀態。
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"
}
}
]
}
}送籤台回報一筆取消請求的結果
/api/v1/permit-cancel-requests/{id}/result參數
id路徑取消請求 ID(pcr_ 前綴)
result必填donefaileddone(已在站方完成)或 failed(這次沒有完成)
note選填說明,例:站方回覆的取消編號,或失敗的原因
idempotencyKey選填冪等鍵(8–64 字英數或連字號)。同一把 key 重送回傳目前的請求
回應欄位 · data
request回報後的請求。
id取消請求 ID(pcr_ 前綴)。
applicationId申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
kindcancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。
trigger觸發點:order_cancelled / departure_changed / traveler_removed。
orderId觸發的訂單 ID。
orderNumber觸發的訂單編號。
travelers離開的旅客:只有 id、姓名與身分證遮罩。
idnameidNumberMaskstatuspending(待處理)/ claimed(送籤台已取走)/ done(已完成)。
attempts送籤台回報失敗的次數。
claimedAt送籤台取走的時間。
resultNote最近一次回報的說明。
dueAt最晚要完成的時間:入園日前一天的台北時間 12:00。
createdAt建立時間。
completedAt完成時間。
application申請單摘要,送籤台到站方找單用。
office申請處。
officeLabel申請處名稱(office = other 時有值)。
applicationNo申請編號。
groupLabel組別。
entryDate入園日(YYYY-MM-DD)。
status申請單目前的狀態。
replayed這次是同一個 idempotencyKey 的重送,沒有再寫入。
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
}
}送籤台取走待處理的申請單取消請求
/api/v1/permit-cancel-requests/claim參數
limit選填一次最多取幾筆(1–100,預設 50)
回應欄位 · data
requests這次取走的請求,已標成 claimed。
id取消請求 ID(pcr_ 前綴)。
applicationId申請單 ID(pmt_ 前綴)。
departureId梯次 ID。
kindcancel_application(整張取消)或 remove_travelers(從申請單移除離開的旅客)。
trigger觸發點:order_cancelled / departure_changed / traveler_removed。
orderId觸發的訂單 ID。
orderNumber觸發的訂單編號。
travelers離開的旅客:只有 id、姓名與身分證遮罩。
idnameidNumberMaskstatuspending(待處理)/ claimed(送籤台已取走)/ done(已完成)。
attempts送籤台回報失敗的次數。
claimedAt送籤台取走的時間。
resultNote最近一次回報的說明。
dueAt最晚要完成的時間:入園日前一天的台北時間 12:00。
createdAt建立時間。
completedAt完成時間。
application申請單摘要,送籤台到站方找單用。
office申請處。
officeLabel申請處名稱(office = other 時有值)。
applicationNo申請編號。
groupLabel組別。
entryDate入園日(YYYY-MM-DD)。
status申請單目前的狀態。
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
依付款日期區間查全部梯次的付款登記
/api/v1/supplier-payments參數
from必填付款日期起日(YYYY-MM-DD,含)
to必填付款日期迄日(YYYY-MM-DD,含);區間最多 366 天
回應欄位 · data
fromtopaymentsiddepartureIdgroupCode團號;未產生為 null。
tripTitledepartureDate出發日(YYYY-MM-DD)。
paidOn付款日期(YYYY-MM-DD)。
handlerUserIdhandlerName經手人姓名。
receivingAccountId付款渠道(收款帳戶 ID)。
channelName付款帳戶名稱(例:小編機)。
payee付給誰/項目。
note說明;未填為 null。
amountTwd金額(TWD 整數);退費為負數。
createdAt登記時間(ISO 8601,UTC)。
updatedAt最後修改時間(ISO 8601,UTC)。
totalTwdcurl -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
/api/v1/travelinvoice回應欄位 · data
rowsidorderIdorderNumbermerchantOrderNoprovidercategorybuyerNamebuyerUbntotalAmtTwdstatusdeclaredStatusinvoiceNumberinvoiceTransNo平台開立流水號;pending 列有值代表平台已受理預約開立。
displayUrltourNametourNotourDatelastErrorlastSyncedAtcreatedAttotalpagepageSizecurl -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.
/api/v1/travelinvoice參數
orderId必填Paid order ID; one active receipt per order
buyer必填Buyer details
mode選填immediateholdIssue mode
回應欄位 · data
idmerchantOrderNostatusinvoiceNumberlastError落缺件(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.
/api/v1/travelinvoice/{id}參數
id路徑Resource ID
回應欄位 · data
idorderIdorderNumbermerchantOrderNoprovidercategorybuyerNamebuyerUbntotalAmtTwdstatusdeclaredStatusinvoiceNumberinvoiceTransNo平台開立流水號;pending 列有值代表平台已受理預約開立。
displayUrltourNametourNotourDatelastErrorlastSyncedAtcreatedAtcurl -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.
/api/v1/travelinvoice/{id}/abandon參數
id路徑Resource ID
回應欄位 · data
okresultidstatuscurl -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.
/api/v1/travelinvoice/{id}/allowance參數
id路徑Resource ID
amountTwd必填Allowance TWD
reason必填Allowance reason
回應欄位 · data
okresultallowanceIdallowanceNocurl -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.
/api/v1/travelinvoice/{id}/cancel-scheduled參數
id路徑Resource ID
回應欄位 · data
okresultidstatuscurl -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.
/api/v1/travelinvoice/{id}/invalidate參數
id路徑Resource ID
reason必填回應欄位 · data
okresultinvalidationIdcurl -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.
/api/v1/travelinvoice/{id}/sync參數
id路徑Resource ID
回應欄位 · data
okresultdeclaredStatusstatus查回後的本地收據狀態(預約收據回補後可能轉 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.
/api/v1/travelinvoice/{id}/touch-issue參數
id路徑Resource ID
回應欄位 · data
okresultidmerchantOrderNostatusinvoiceNumberlastError落缺件(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
/api/v1/whoami回應欄位 · data
idemailnamerolecurl -X GET "https://your-tenant.example.com/api/v1/whoami" \
-H "Authorization: Bearer $TOKO_TOKEN"{
"ok": true,
"data": {
"id": "…",
"email": "…",
"name": "…",
"role": "…"
}
}