什麼是訂單
訂單（Order）是帳獸中最核心的資料單位，代表一筆交易紀錄。所有的營收分析、SaaS 指標計算都以訂單資料為基礎。
訂單狀態
每筆訂單都有一個狀態，代表該筆交易的當前進度：
| 狀態 | 說明 |
|---|
pending | 待處理，尚未付款 |
paid | 已付款，交易成功 |
failed | 付款失敗 |
refunded | 已退款 |
cancelled | 已取消 |
狀態流程
pending → paid → refunded
pending → failed
pending → cancelled
訂單狀態只能向前流轉，不能回到前一個狀態。例如 paid 的訂單可以變成 refunded，但 refunded 不能變回 paid。
訂單屬性
| 屬性 | 類型 | 必填 | 說明 |
|---|
order_no | string | ✅ | 訂單編號，在同一商家內唯一 |
customer_id | integer | ✅ | 關聯的客戶 ID |
amount | string | ✅ | 訂單金額（保留 2 位小數） |
currency | string | ✅ | 幣別（預設 TWD） |
status | string | ✅ | 訂單狀態 |
payment_method | string | — | 支付方式 |
billing_cycle | string | — | 訂閱週期 |
paid_at | datetime | — | 付款時間 |
refunded_at | datetime | — | 退款時間 |
failed_at | datetime | — | 付款失敗時間 |
metadata | object | — | JSON 擴充資料 |
訂單來源
每筆訂單都會記錄其來源（source），方便你追蹤資料從何而來：
| 來源 | 說明 |
|---|
api | 透過 API 建立 |
import | 透過批次匯入建立 |
manual | 在後台手動建立 |
webhook | 由 Webhook 觸發建立 |
newebpay | 由藍新金流付款通知自動建立 |
ecpay | 由綠界科技付款通知自動建立 |
支付方式
帳獸支援以下支付方式：
| 值 | 說明 |
|---|
credit_card | 信用卡 |
atm | ATM 轉帳 |
cvs | 超商繳費 |
line_pay | LINE Pay |
jkopay | 街口支付 |
apple_pay | Apple Pay |
訂閱週期與 MRR
訂單的 billing_cycle 欄位用於標示該筆交易的訂閱週期，這對 SaaS 指標中的 MRR（月經常性收入）計算至關重要。
| 週期 | 值 | MRR 正規化 |
|---|
| 月繳 | monthly | 金額 ÷ 1 |
| 季繳 | quarterly | 金額 ÷ 3 |
| 半年繳 | semi-annual | 金額 ÷ 6 |
| 年繳 | yearly | 金額 ÷ 12 |
| 一次性 | one-time | 不計入 MRR |
計算範例
| 訂單金額 | 訂閱週期 | MRR 貢獻 |
|---|
| NT$990 | monthly | NT$990 |
| NT$2,490 | quarterly | NT$830 |
| NT$4,800 | semi-annual | NT$800 |
| NT$9,600 | yearly | NT$800 |
| NT$199 | one-time | NT$0 |
只有經常性收入訂單（monthly、quarterly、semi-annual、yearly）會計入 MRR 計算。one-time 訂單不參與 MRR 或活躍客戶統計。
冪等處理
建立訂單時，建議使用 X-Idempotency-Key 標頭來防止重複建立：
curl -X POST https://api.zangsho.com/v1/orders \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: unique-order-key-001" \
-d '{"order_no": "ORD-001", ...}'
即使網路中斷導致你不確定上一次請求是否成功，只要使用相同的 X-Idempotency-Key 重新發送，帳獸就不會建立重複的訂單。
訂單與營收分析
訂單資料會直接影響儀表板上的關鍵指標：
- Revenue：所有
paid 訂單的金額加總
- Net Revenue：
paid 訂單金額 − refunded 訂單金額
- Orders：訂單總數
- Customers：有訂單的不重複客戶數
下一步
