Documentation Index
Fetch the complete documentation index at: https://developers.zangsho.com/llms.txt
Use this file to discover all available pages before exploring further.
什麼是訂單
訂單（Order）是帳獸中最核心的資料單位，代表一筆交易紀錄。所有的營收分析、SaaS 指標計算都以訂單資料為基礎。訂單狀態
每筆訂單都有一個狀態，代表該筆交易的當前進度：| 狀態 | 說明 |
|---|---|
pending | 待處理，尚未付款 |
paid | 已付款，交易成功 |
failed | 付款失敗 |
refunded | 已退款 |
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 標頭來防止重複建立：
訂單與營收分析
訂單資料會直接影響儀表板上的關鍵指標：- Revenue：所有
paid訂單的金額加總 - Net Revenue：
paid訂單金額 −refunded訂單金額 - Orders：訂單總數
- Customers：有訂單的不重複客戶數
下一步
訂閱
了解訂閱如何與訂單互動，驅動 SaaS 指標。
資料匯入
使用批次 API 匯入歷史訂單資料。