訂單與金流模型
訂單列表與 GET /api/v1/orders 同時包含行程訂單與訂房單。回應的 kind 為 tour 或 lodging。訂房單的 tripTitle 是旅宿名稱,departureDate 與 returnDate 是入住日與退房日,tripId 與 departureId 為空字串。後台列表的行程、出發日、同意書、分房、抽籤與派發欄對訂房單留空:同意書與審單派發只用在行程訂單。使用行程、梯次、同意書、分房、抽籤或派發篩選時,只列行程訂單。
一張訂單的錢怎麼算
一張訂單有四種明細。後台訂單頁的「款項」分頁逐一列出:
| 明細 | 記什麼 | 例 |
|---|---|---|
| 應收明細 | 客人為什麼欠錢。折扣與少收是負數。 | 團費 2 人、折扣碼、房型升級 |
| 收款計畫 | 應收分幾期收、每期何時到期。 | 訂金 3,000、尾款 7,000 |
| 收款 | 每一次「打算收」的錢,例如一條付款連結。 | 尾款刷卡連結 |
| 現金紀錄 | 真正收到或退出的錢。報表只認這一層。 | 綠界入帳 3,000 |
訂單上的金額都從明細算出:
- 應收 = 全部應收明細加總。
- 已收 = 全部收進來的現金。
- 已收淨額 = 已收 − 已退還給客人的現金。
- 尚欠 = 應收 − 已收淨額。
所以折扣、加價、房升補款都是應收明細裡的一列,不是改訂單上的某個數字。付款後加價時,系統新增一列應收,訂單重新出現尚欠,再產生補款連結。系統不會把已付訂單的金額直接改大。
金額都是整數台幣。客人一律付台幣。
›訂單回傳的金額欄位
GET /orders/{id} 回傳的金額都是派生值,不能直接設定。訂單沒有 total 與 paidAt 欄位。
| 欄位 | 意義 |
|---|---|
orderNumber | 訂單編號 |
kind | tour(梯次團)或 lodging(住宿) |
grossReceivableTwd | 應收(chargeLines 加總,含負數) |
collectedTwd | 已收現金,含保留款轉入。已取消訂單對帳讀 accounting.cancelledCash |
customerCashAppliedTwd | 已收淨額(已收 − 已退) |
outstandingTwd | 尚欠(應收 − 已收淨額) |
refundableCashTwd | 可退現金(已收淨額 − 已執行退款的手續費)。實際可退款額度另見取消與退款指南。 |
actions | 呼叫者現在可做的動作,與不可做的原因 |
chargeLines / schedules / intents / transactions / travelers | 應收明細、收款計畫、收款、現金紀錄、旅客 |
讀取用 GET /orders(依角色自動限縮可見範圍)與 GET /orders/{id}。判斷能不能補尾款、開付款連結,請讀 actions,不要只看 paymentState。
怎麼看訂單狀態
訂單沒有單一的「狀態」欄。系統分三個面向記錄,後台再合成一個標籤顯示:
| 面向 | 問的是 | 可能的值 |
|---|---|---|
| 訂位 | 這張單成立了沒有 | 待付款 → 已確認 → 已完成;任一階段都可能已取消 |
| 付款 | 應收被現金蓋住多少 | 未付、部分付款、已付訂金、已付款、多付 |
| 退款 | 退過減應收的退款嗎 | 無、部分退款、已退款 |
後台列表與訂單頁的標籤依這個順序取第一個符合的:已取消 → 已退款 → 部分退款 → 已完成 → 付款面向(待付款、部分付款、已付訂金、多付、已付款)。
「已付款」只代表應收已被現金蓋住,不代表錢還在公司手上。全額退款的訂單,付款面向仍是已付款,退款面向才是已退款。判斷時三個面向一起看。
›三軸狀態值
bookingState : pending_payment → confirmed → completed ;(任一 → cancelled)
paymentState : unpaid | partially_paid | deposit_paid | paid | overpaid
refundState : none | partially_refunded | refunded後台標籤的對應:cancelled 已取消、refunded 已退款、partially_refunded 部分退款、completed 已完成、unpaid 待付款、partially_paid 部分付款、deposit_paid 已付訂金、overpaid 多付、paid 已付款。
只有減應收的退款計入 refundState。退還多付的錢、取消後退回現金都不計入,詳見取消與退款。
建立訂單(K 單)
承辦代客人建單,叫做 K 單。從頂列「新增」選單或 ⌘K 選「K 單」。
K 單需要行程模組。未開通時隱藏入口,POST /orders 回 403 module_disabled。獨立訂房建單不受影響。既有行程訂單仍可收款與退款。
- 選行程與梯次。訂購人須為會員:從會員資料搜尋帶入,或輸入會員註冊的 Email。
- 填旅客。第 1 位是主要聯絡人。證件等資料可以先建單、之後補。
- 選訂購人分類,決定套直客價或同業價。
- 需要時填「少收申請與尾款到期日」。少收要由管理員核准才生效。
- 選付款方式,勾選條款,建立訂單。
規則:
- 可以先存草稿。 草稿不佔名額,也不產生應收。只有建立者看得到、改得到。送出時重新檢查名額與資料,同一份草稿重送不會建出兩張單。
- 建單就保座。 名額不夠時建單失敗。
- 尾款到期日可以指定。 留空時照行程規則。期限是台北時間當日結束。抽籤梯次不能指定,期限在中籤當天加上公司設定的天數。
- 登山行程可以先預覽資格。 預覽只用這次填的登山經歷,不查證件或過去紀錄。建單時重新計算,預覽不能代替審核。
›建單 API
POST /orders帶tripId、departureId、travelers、paymentMethod等。名額不足回409 conflict。旅客的birthDate須是存在的YYYY-MM-DD日期,否則回422 validation。一般訂單的idNumber/passportNo可後補;受管制抽籤須擇一,受限名額須idNumber。缺件時回422 validation並指出第幾位旅客(見旅客與個資)。- 建單前試算金額用
POST /orders/quote,見折扣碼與分潤。 - 登山資格預覽用
POST /orders/screening-preview,帶departureId與travelers[].climbingRecords。每筆經歷只給label與選填的hasAlpineExperience,分數由公司的路線分級表算。需要order.create與登山模組。 - K 單草稿只有後台入口。
調整應收:掛帳與少收
訂單金額要改時,在訂單頁「款項」分頁按「掛帳 / 少收」:
- 掛帳:加收一筆,例如加購保險。
- 少收:減收一筆,例如議價。
兩者都新增一列應收明細,必填原因。登記後不能刪除;填錯時用沖正,把那一列抵銷。
少收要不要經管理員核准
在「後台 → 公司設定 → 付款設定 → 少收核准」開啟「少收必須經核准」後:
- 管理員以外的人只能掛帳,不能直接少收。
- 沖正只限自己開的掛帳列。
- 跨行程換梯時,不能填負數的人工調整。
要少收時,在訂單頁送「手動少收申請」。規則:
- 待核准的金額不影響應收、試算與收款。
- 送出時,鈴鐺通知可核准的管理員。管理員的工作台另有「少收待核」清單。已取消或已完成的訂單不列入。
- 管理員在訂單頁核准或拒絕,結果通知申請人。拒絕可填原因。撤回不通知。
- 送出後訂單金流有變動時,原申請不能核准。請撤回後重新申請。
- 核准只減應收,不會自動退款。
›調整 API 與錯誤碼
- 掛帳與少收:
POST /orders/{id}/adjust,kind為surcharge(掛帳)或allowance(少收)。需要order.adjust。 - 沖正:
POST /orders/{id}/reverse。 - 開啟「少收必須經核准」時,非管理員送
kind: "allowance"回409 conflict;沖正別人開的列、團費、折扣、少收或匯入列也回409 conflict。 - 手動少收申請與核准只有後台入口。
派發與搶單
客人在前台自己下的訂單,要指派給一位業務,才計入那位業務的業績。派發模式、手動派發與通知規則見訂單派發。
公司開啟「開放業務自派搶單」後,業務可在訂單列表選「可搶單」篩選,自己接下待派發的訂單。搶到之前只看得到非個資欄位。
›搶單 API
POST /orders/{id}/claim:需要 order.claim,且公司開啟搶單。
登山資格審核
登山行程的訂單建立時,系統依旅客的登山經歷算出能力分。能力不足的旅客標成「待人工審核」,不擋下單也不擋收款。判定方式見旅客與個資。
待審訂單在「後台 → 訂單 → 派發 / 資格審核」處理:
- 核可:旅客通過。
- 駁回:必須選一種處置,系統只記錄,不會自動取消、換團或退款。
| 處置 | 後續 |
|---|---|
| 補件重審 | 等客人補經歷。訂單標成待回覆。 |
| 換團 | 請客人選別的梯次。訂單標成待回覆。 |
| 退款 | 轉退款作業,不標待回覆。 |
可以一次裁決整張單,也可以只裁決一位旅客。可附通知範本寄信給客人;寄信失敗不撤回裁決。客人回覆並處理完成後,按「標記已解決」解除待回覆。
›審核 API
POST /orders/{id}/review-screening:decision為approve或reject。駁回必帶disposition(resupplement、switch_trip、refund),未帶回422。核可不接受disposition。- 選填
travelerId只裁決該旅客。重新裁決過期的人工結果時帶redecide: true與travelerId。 - 選填
templateId寄通知,核可與駁回都可帶。note會填入範本的{{補充說明}}。回應emailSent表示已排入寄送佇列。不要因emailSent: false重送裁決。 - 結束待回覆:
POST /orders/{id}/resolve-screening-follow-up。沒有待回覆時回409。 - 需要
screening.review與登山模組。未知欄位回422。 - CLI:
orders review-screening <id> --decision reject --disposition resupplement --traveler-id <id> --template-id <id> --confirm;核可寄通知用--decision approve --template-id <id>;重新裁決加--redecide;orders resolve-screening-follow-up <id> --confirm。
訂單對話
每張訂單都有一條與訂購人的留言串,客人不用先開口。最後一則是客人留言時,對話變成待回覆;承辦回覆或按「標記已解決」後解除。
所有待回覆的對話集中在「後台 → 訂單 → 訂單對話」。要讓外部機器人讀取待回覆清單,見待回覆留言機器人。
舊轉單鏈的訂單
從舊系統搬入的部分訂單是一條「轉單鏈」:客人先報 A 團,再轉到 B 團,錢留在 A。這類訂單今天仍會遇到,規則如下:
- 舊單收到的錢留在舊單。轉過來的金額叫「結轉款」,用來抵減目前這張單的應收,不算進這張單的已收。
- 所以結轉款已付清訂金時,這張單仍可能顯示待付款或部分付款。補尾款、開付款連結、寄尾款繳款單照常可用。
- 訂單頁「訂單細項」列出全鏈累計入款、有效結轉款與全鏈已退現金。
例:舊單已收 8,000,新團費 10,000。這張單還沒收錢時,尚欠 2,000。再收 500 後,尚欠 1,500。
相關指南
- 付款流程:客人怎麼付款、怎麼登記收款。
- 取消與退款:取消政策、退款單、保留款。
- 換梯與拆單:換梯次、跨行程換梯、拆出旅客。
- 折扣碼與分潤:折扣怎麼變成應收的一列。
- orders API · CLI orders。