設定與範本
設定是整個租戶共用的一份——公司抬頭、寄件身分、訂單怎麼指派、錢收進哪個帳戶。你用 settings API 讀寫的，和管理者在後台設定頁做的完全等價。
本篇帶你看租戶設定的全貌，以及兩種「範本」資源：給客人發訊息的罐頭訊息，與要客人簽署的同意書。
租戶設定是一份 singleton
每個租戶只有一份設定，不是 per-user：
- 讀整份：
GET /api/v1/settings；改一部分：PATCH /api/v1/settings（partial update——只帶你要改的欄位，沒帶到的不動）。 - 可寫欄位包含公司抬頭（
companyName/companyPhone/taxId/companyAddress/logoUrl）、回覆信箱（emailReplyTo）、寄件人 local-part（senderLocalPart）、證件效期提醒天數（passportExpiryWarningDays）。 - 站台 SEO 預設另走
PATCH /api/v1/settings/seo。
設定屬管理範圍：/settings 多數端點要 role.manage 權限，連讀取都擋（與後台「機密遮罩」一致）。少數子資源用更細的權限——收款帳戶與費用路由要 receiving_account.manage、費用類別要 operating_expense.*，下面各段會標。
你方案啟用了哪些模組（訂房 / 會計 / 登山…）是平台方決定的，你只能唯讀查：GET /api/v1/settings/modules。租戶端改不了模組開通。
付款憑證（per-tenant、只回遮罩）
ECPay 收款憑證是每個租戶各自設定的，不是平台共用：
- 一次填齊特店 ID、HashKey、HashIV：
PUT /api/v1/settings/ecpay-credentials；清除：DELETE。 - HashKey / HashIV 加密保存、永不回讀，查詢只回末幾碼的遮罩值供顯示確認（write-only）。
詳細的收款生命週期、測試模式與「上線未設定憑證即擋下收款」的行為，見 付款流程。
寄件網域
寄交易信（訂單確認、付款成功、同意書提醒…）不需要你準備任何憑證——平台代為寄送。你能控制的是寄件身分，分兩層：
- 預設（零設定）：從平台共用網域寄出，顯示名稱用你的公司名、回信導去你的
emailReplyTo。客人不會看到平台網域以外的東西，你也不必動任何 DNS。 - 自有網域（可選升級）：若你已綁定自有站台網域，可改用
info@<你的網域>寄件。
升級走一條 DNS 驗證生命週期：
| 動作 | 端點 |
|---|---|
| 查目前狀態與待設 DNS record | GET /api/v1/settings/sending-domain |
| 啟用（無網域參數，用你綁定的網域） | POST /api/v1/settings/sending-domain/enable |
| 設好 DNS 後重新檢查驗證 | POST /api/v1/settings/sending-domain/verify |
| 停用、退回平台網域 | POST /api/v1/settings/sending-domain/disable |
寄信是 fail-open：自有網域驗證一旦失效，會自動退回平台網域寄送，信照寄不中斷——和付款憑證「設錯就擋下」的 fail-closed 取捨相反。寄件人 local-part 用 senderLocalPart 調整（預設 info）。
訂單指派
新訂單要落到哪個業務手上，由租戶的指派模式決定：
- 設定模式與兜底業務：
PATCH /api/v1/settings/assignment。 - 可被指派的業務名單：
GET /api/v1/settings/assignable-staff。
模式（assignmentMode） | 行為 |
|---|---|
manual_review | 進待審池，由人工指派 |
auto_round_robin | 自動輪流分配給可受派業務 |
auto_customer_choice | 由客人選擇承辦業務 |
收款帳戶與費用分類
你可以維護自己的收款帳戶目錄，並決定不同性質的款項各自路由到哪個帳戶；公司營業費用也有一套可自訂的分類。
| 用途 | 端點 | 權限 |
|---|---|---|
| 收款帳戶目錄（銀行 / 現金 / 外幣池…） | GET · POST · PATCH /api/v1/settings/receiving-accounts | receiving_account.manage |
| 費用性質 → 最終收款帳戶的路由 | GET · PUT /api/v1/settings/fee-category-routes | receiving_account.manage |
| 公司營業費用類別目錄 | GET · POST · PATCH /api/v1/settings/expense-categories | operating_expense.read / .manage |
| 內外帳利潤試算的費率 | PATCH /api/v1/settings/ledger-fees | role.manage |
收款帳戶是租戶自管、與產品種類無關的——同一個帳戶可收任何訂單的款。停用某帳戶不刪歷史，只是讓它不再出現在新的收款選項中。
罐頭訊息與同意書範本
兩種「範本」資源，性質很不一樣——一個可改可刪，一個只增不改。
罐頭訊息範本（可編輯）
給客人發 LINE / Email 通知用的可重複文字：
- 列表 / 建立：
GET·POST /api/v1/message-templates；單筆 / 改 / 刪：/api/v1/message-templates/{id}；啟停：POST /api/v1/message-templates/{id}/active。 - 一筆範本帶
stage（對應 SOP 階段）、channel（line或email）、title、bodySingle（單人版內文），可選bodyMulti（多人版，留空沿用單人版）、key（程式化引用識別碼）、isActive。 - 讀取要
message_template.read，異動要message_template.manage。
同意書範本（版本化、不可竄改）
要客人簽署的同意書是只增不改的——你不會「編輯」一份已存在的同意書，而是發布新版本：
- 列表（同類別最新版在前，每筆帶其綁定的簽署份數）：
GET /api/v1/consent-templates，可用kind過濾類別。 - 發布新版本：
POST /api/v1/consent-templates；看單一版本：GET /api/v1/consent-templates/{id}。 - 一律
consent_template.create權限（後台讀寫共用同一把）。
同意書範本沒有改 / 刪端點——這是刻意的。已簽署的版本必須原封保留（簽署當下客人同意的是哪份文字，是法遵的證據），任何文字調整都要走「發布新版本」。
下一步
- 付款流程：ECPay 憑證、收款 redirect、webhook 與測試模式。
- 權限與角色：
role.manage、receiving_account.manage等權限怎麼分派給角色。 - settings API · message-templates · consent-templates：逐端點的參數與回應。