請款與出款

當旅行社要付錢給第三方——供應商、嚮導、業務佣金——你開一張請款單，經核簽後付款。這跟「退錢給客人」是兩回事：退客人錢動的是訂單金流，請款出款動的是對外應付。

本篇說明請款單的核簽生命週期、出款對象、供應商資料，以及把當月多筆請款月結成一批匯出的出款批次。

出款 ≠ 退款

兩者方向都是「錢出去」，但資料源與流程完全不同，別混用：

概念	付給誰	走哪條流程	API
請款 / 出款	供應商 / 嚮導 / 佣金等第三方	請款單核簽	payment-requests · payouts
客戶退款	客人本人	訂單退款工作流	`/orders/{id}/refunds`

注意

出款核簽不是客戶退款的資料源。退客人錢一律走訂單的退款流程（反映在訂單的 refundState）；對供應商 / 嚮導 / 佣金付款一律走請款單。即使金額相同，也不要拿請款單代替退款，反之亦然。

請款單的生命週期

一張請款單（payment request）代表一筆要付給第三方的款，從草稿到付清會經過幾個狀態。建單、核准、付款分屬不同人：建單人不能核准自己的單，會計只對已核准的單付款。

狀態	意義	誰推進
`draft`	建單人編輯中，尚未送審	建單人
`submitted`	已送出，等候核准	建單人 `submit`
`approved`	已核准，可付款	核准人 `approve`（非建單人）
`paid`	已依紙本付款並回填匯款參照，終態	會計 `mark-paid`
`rejected`	送審後被退回	核准人 `reject`（須附原因）
`cancelled`	非 `paid` 的單被作廢	建單人 / 主管 `cancel`

對應動作端點：POST /payment-requests/{id}/submit、/approve、/reject、/mark-paid、/cancel。每次狀態轉換都會留下稽核紀錄（請款單詳情回傳的 audit[]）。

建立請款單

以 POST /payment-requests 開單，帶上出款對象與明細：

payeeType / payeeName：出款對象的類型與名稱（見下節）。
payeeBankAccount / payeeBankName / payeeBankBranch / payeeTaxId：收款銀行與稅籍資料（選填）。
departureId：若這筆款歸屬某個梯次，帶上以利歸帳（選填）。
description：請款事由（必填）。
items[]：請款明細，每筆有 category / description / quantity / unitPriceTwd；金額逐筆加總成請款總額。
taxAmountTwd：稅額；扣稅後得淨額。
submitImmediately：建單即送審（等同建完直接 submit）。

回傳的請款單上，amountTwd 是明細總額、taxAmountTwd 是稅額、netAmountTwd 是實付淨額。金額一律整數台幣。

說明

請款明細可以手 key，也可以從梯次成本帶入。用 GET /payment-requests/supplier-suggestions?departureId=... 取某梯次尚未轉請款的成本，做為 items 的建議草稿，再開單。

核簽與付款

請款單核准後，會計依紙本流程實際匯款，再回系統把單標記為已付：

POST /payment-requests/{id}/mark-paid 必須帶 bankReference（匯款參照號），可選 paperSignedBy（紙本簽核人）與 receivingAccountId（從哪個帳戶匯出）。標記後即進入終態 paid。
請款單可列印用於紙本簽核與存查。mark-printed / mark-signed 記錄列印與用印動作（請款單詳情回傳 paperPrintedAt / paperSignedBy）。

注意

系統記錄的是核簽與匯款的事實，不代表系統替你完成轉帳。mark-paid 是「我已在網銀付了這筆、參照號是這個」的回填，實際匯款仍由會計在銀行端執行。

權限以 payable.* 控管，角色分工：

角色	讀	建單 / 送審	核准 / 退回	標記付款	列印 / 取消
`admin`	✅	✅	✅	✅	✅
`op`（線控）	✅	✅	❌	❌	✅
`sales`（業務）	✅	✅	❌	❌	✅
`accountant`（會計）	✅	❌	✅	✅	✅

讀取走 GET /payment-requests（可依 status / payeeType / departureId 篩選）與 GET /payment-requests/{id}（含明細、核簽時間軸、稽核）。彙總計數看 GET /payment-requests/stats。

出款對象

請款單的 payeeType 標明你在付給誰：

`payeeType`	用途
`supplier`	旅宿、交通、餐飲、保險、地接等供應商
`guide`	嚮導 / 領隊費
`staff_commission`	業務 / 內部佣金
`other`	其他需走核簽的出款

收款對象的銀行資料隨對象走：供應商建在供應商目錄、嚮導與員工掛在各自紀錄上。同一筆請款的銀行欄位也可在開單時直接帶入。

供應商資料

供應商會跨月重複出現，所以建一次檔、之後直接引用，收款銀行資料隨供應商走，免每月重 key：

GET /suppliers 列出供應商（可依 status / q 搜尋），POST /suppliers 建檔，PATCH /suppliers/{id} 維護。
每筆供應商有 name、categoryHint（慣用類別提示，自由文字）、收款銀行三欄 payeeAccountName / payeeBankCode / payeeAccountNumber，以及 status（停用以 inactive，不刪除）。
供應商目錄受 accounting 模組與 supplier.* 權限控管。全部 per-tenant 自填，不預載任何廠商或銀行。

出款批次（月結匯出）

同一個對象當月常有多筆已核准請款，實務上月結一次匯出。出款批次把這些彙整成一筆出納動作，產出可匯入網銀的轉帳檔：

GET /payouts/aggregate?period=YYYY-MM&scope=...：把某月某範圍的對象，各自加總已核准請款成 grossTwd，並列出組成的請款明細（日期 / 團名 / 金額）供對帳。
POST /payouts/batches：以彙整結果建批次，指定 paidFromAccountId（從哪個可匯款帳戶出，見 GET /payouts/remit-accounts）與各 lines。
POST /payouts/lines/{lineId}/confirm-token：產對外確認連結，讓供應商免登入核對自己當月明細再確認。
POST /payouts/batches/{id}/confirm：確認批次，把納入的請款一併標記為已付並回填匯款參照。
GET /payouts/batches/{id}/transfer-file：下載標準格式的批次轉帳檔（收款人戶名 / 帳號 / 銀行代號 / 金額），匯入網銀執行轉帳。

說明

出款批次是出納動作，不是算薪。扣款項（如自付保費、借支）是建批次時手 key 的通用欄位，系統不內建任何薪資級距或法規費率——這些一律 per-tenant 自填或由外部系統提供。

下一步

付款流程：跟客人收款的 redirect、webhook 與 ECPay 設定。
收款帳戶與結算：帳戶能力、可匯款帳戶與跨帳戶結算。
payouts API · payment-requests API。