> ## 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.

# 訂單

> 了解帳獸中訂單的狀態流程、支付方式與 MRR 計算關係

## 什麼是訂單

訂單（Order）是帳獸中**最核心的資料單位**，代表一筆交易紀錄。所有的營收分析、SaaS 指標計算都以訂單資料為基礎。

## 訂單狀態

每筆訂單都有一個狀態，代表該筆交易的當前進度：

| 狀態          | 說明       |
| ----------- | -------- |
| `pending`   | 待處理，尚未付款 |
| `paid`      | 已付款，交易成功 |
| `failed`    | 付款失敗     |
| `refunded`  | 已退款      |
| `cancelled` | 已取消      |

### 狀態流程

```
pending → paid → refunded
pending → failed
pending → cancelled
```

<Note>
  訂單狀態只能**向前流轉**，不能回到前一個狀態。例如 `paid` 的訂單可以變成 `refunded`，但 `refunded` 不能變回 `paid`。
</Note>

## 訂單屬性

| 屬性               | 類型       | 必填 | 說明                |
| ---------------- | -------- | -- | ----------------- |
| `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   |

<Info>
  只有經常性收入訂單（`monthly`、`quarterly`、`semi-annual`、`yearly`）會計入 MRR 計算。`one-time` 訂單不參與 MRR 或活躍客戶統計。
</Info>

## 冪等處理

建立訂單時，建議使用 `X-Idempotency-Key` 標頭來防止重複建立：

```bash theme={null}
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", ...}'
```

<Tip>
  即使網路中斷導致你不確定上一次請求是否成功，只要使用相同的 `X-Idempotency-Key` 重新發送，帳獸就不會建立重複的訂單。
</Tip>

## 訂單與營收分析

訂單資料會直接影響儀表板上的關鍵指標：

* **Revenue**：所有 `paid` 訂單的金額加總
* **Net Revenue**：`paid` 訂單金額 − `refunded` 訂單金額
* **Orders**：訂單總數
* **Customers**：有訂單的不重複客戶數

## 下一步

<CardGroup cols={2}>
  <Card title="訂閱" icon="repeat" href="/concepts/subscriptions">
    了解訂閱如何與訂單互動，驅動 SaaS 指標。
  </Card>

  <Card title="資料匯入" icon="upload" href="/guides/data-import">
    使用批次 API 匯入歷史訂單資料。
  </Card>
</CardGroup>