> ## 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 分頁參數與回應格式說明

## 分頁參數

所有回傳列表的端點都支援分頁。使用以下查詢參數控制分頁行為：

| 參數         | 類型      | 預設值  | 說明            |
| ---------- | ------- | ---- | ------------- |
| `page`     | integer | `1`  | 頁碼，從 1 開始     |
| `per_page` | integer | `20` | 每頁筆數，最大 `100` |

### 範例

```bash theme={null}
# 取得第 2 頁，每頁 50 筆
curl -X GET "https://api.zangsho.com/v1/customers?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## 回應格式

分頁回應包含 `data` 陣列與 `meta` 物件：

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "email": "wang.xiaoming@example.com",
      "name": "王小明",
      "created_at": "2026-01-15T08:00:00Z"
    },
    {
      "id": 2,
      "email": "chen.meiling@example.com",
      "name": "陳美玲",
      "created_at": "2026-01-16T09:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 98
  }
}
```

### meta 欄位說明

| 欄位             | 類型      | 說明     |
| -------------- | ------- | ------ |
| `current_page` | integer | 目前頁碼   |
| `last_page`    | integer | 最後一頁頁碼 |
| `per_page`     | integer | 每頁筆數   |
| `total`        | integer | 總筆數    |

## 遍歷所有頁面

以下範例展示如何遍歷所有分頁資料：

<CodeGroup>
  ```javascript Node.js theme={null}
  async function fetchAllCustomers(token) {
    const customers = [];
    let page = 1;
    let lastPage = 1;

    do {
      const response = await fetch(
        `https://api.zangsho.com/v1/customers?page=${page}&per_page=100`,
        {
          headers: {
            'Authorization': `Bearer ${token}`,
            'Accept': 'application/json'
          }
        }
      );

      const result = await response.json();
      customers.push(...result.data);

      lastPage = result.meta.last_page;
      page++;
    } while (page <= lastPage);

    console.log(`共取得 ${customers.length} 位客戶`);
    return customers;
  }
  ```

  ```php PHP (Laravel) theme={null}
  function fetchAllCustomers(string $token): array
  {
      $customers = [];
      $page = 1;

      do {
          $response = Http::withToken($token)
              ->acceptJson()
              ->get('https://api.zangsho.com/v1/customers', [
                  'page' => $page,
                  'per_page' => 100,
              ]);

          $data = $response->json();
          $customers = array_merge($customers, $data['data']);

          $lastPage = $data['meta']['last_page'];
          $page++;
      } while ($page <= $lastPage);

      echo "共取得 " . count($customers) . " 位客戶\n";
      return $customers;
  }
  ```

  ```bash cURL (Shell Script) theme={null}
  #!/bin/bash
  TOKEN="YOUR_API_TOKEN"
  PAGE=1
  LAST_PAGE=1

  while [ $PAGE -le $LAST_PAGE ]; do
    RESPONSE=$(curl -s "https://api.zangsho.com/v1/customers?page=$PAGE&per_page=100" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Accept: application/json")

    echo "$RESPONSE" | jq '.data[]'

    LAST_PAGE=$(echo "$RESPONSE" | jq '.meta.last_page')
    PAGE=$((PAGE + 1))
  done
  ```
</CodeGroup>

<Tip>
  * 使用 `per_page=100`（最大值）可以減少請求次數
  * 注意[頻率限制](/api-reference/rate-limiting)，大量分頁請求時適當加入延遲
  * 如果只需要確認總筆數，可以只請求 `per_page=1` 並讀取 `meta.total`
</Tip>