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

# API 概覽

> 帳獸 Zangsho REST API 的基本資訊、資源與快速入門

## 歡迎使用帳獸 API

帳獸（Zangsho）提供完整的 REST API，讓你以程式化方式管理客戶、訂單、訂閱與訂閱事件。所有 API 使用 JSON 格式傳輸資料，時間欄位統一使用 ISO 8601 UTC 格式。

## Base URL

```
https://api.zangsho.com/v1
```

所有端點都以此 Base URL 為前綴，例如：`https://api.zangsho.com/v1/customers`。

## 可用資源

<CardGroup cols={2}>
  <Card title="客戶 Customers" icon="users" href="/api-reference/endpoint/post-customers">
    建立、查詢、更新、刪除客戶，支援批次匯入。
  </Card>

  <Card title="訂單 Orders" icon="receipt" href="/api-reference/endpoint/post-orders">
    建立與查詢訂單，取得訂單統計，支援批次匯入。
  </Card>

  <Card title="訂閱 Subscriptions" icon="arrows-rotate" href="/api-reference/endpoint/post-subscriptions">
    管理客戶訂閱，支援建立、更新、取消、暫停與重新啟用。
  </Card>

  <Card title="訂閱事件 Subscription Events" icon="timeline" href="/api-reference/endpoint/post-subscriptions-events">
    記錄訂閱變動事件（升級、降級、取消、重新啟用）。
  </Card>
</CardGroup>

## 快速開始

<Steps>
  <Step title="取得 API Token">
    在後台 **金鑰管理** 頁面建立 API Token。詳見 [API 金鑰管理](/guides/api-keys)。
  </Step>

  <Step title="發送第一個請求">
    使用 Token 呼叫 API：

    ```bash theme={null}
    curl -X GET https://api.zangsho.com/v1/customers \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Accept: application/json"
    ```
  </Step>

  <Step title="查看回應">
    成功的回應會包含 JSON 資料與分頁資訊：

    ```json theme={null}
    {
      "data": [...],
      "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 5
      }
    }
    ```
  </Step>
</Steps>

## 核心概念

| 概念   | 說明                             | 詳細文件                                 |
| ---- | ------------------------------ | ------------------------------------ |
| 認證   | Bearer Token 認證，每個商家一把有效 Token | [認證](/api-reference/authentication)  |
| 錯誤處理 | 標準錯誤格式，包含欄位驗證錯誤                | [錯誤處理](/api-reference/errors)        |
| 頻率限制 | 已認證 3,600 次/小時，未認證 10 次/分鐘     | [頻率限制](/api-reference/rate-limiting) |
| 分頁   | 支援 `page` 與 `per_page` 參數      | [分頁](/api-reference/pagination)      |

## 批次匯入

帳獸支援批次匯入歷史資料，適合初次遷移或定期同步：

* 每次請求最多 **100 筆**
* 採用**部分成功策略**（不全部回滾）
* 回傳 `created` / `updated` / `skipped` / `failed` 詳細結果

<Warning>
  批次匯入不觸發 Webhook。如需觸發 Webhook，請使用單筆建立 API。
</Warning>

詳見 [資料匯入指南](/guides/data-import)。

## 時間格式

所有時間欄位使用 **ISO 8601 格式（UTC）**：

```
2026-01-09T08:00:00Z
```

商家需自行將本地時間轉換為 UTC 後傳入。