> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/zh-tw/developers/api/pagination.md).

# 分頁

> 使用以游標為基礎的分頁，逐頁讀取 BoxHero API 中的長清單。

清單端點會一次傳回一頁結果，並使用以游標為基礎的分頁。

## 查詢參數

| 參數 | 說明 |
| --- | --- |
| `cursor` | 頁面的起始位置。傳入上一次回應中的 `cursor` 欄位。第一次呼叫時省略。 |
| `limit` | 每頁大小。允許的範圍與預設值列於各端點中，例如[列出品項](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/list-items)。 |

## 回應

每一頁都包含結果，以及取得下一頁所需的欄位：

```json
{
  "items": [...],
  "count": 100,
  "limit": 100,
  "cursor": 1234567,
  "has_more": true
}
```

| 欄位 | 說明 |
| --- | --- |
| `count` | 此頁的結果數量 |
| `limit` | 此頁使用的每頁大小 |
| `cursor` | 將此值作為 `cursor` 查詢參數傳入即可取得下一頁。沒有更多頁面時為 `null`。 |
| `has_more` | 若此頁之後還有更多結果，則為 `true` |

## 取得所有頁面

1. 不帶 `cursor` 呼叫清單端點。
2. 只要 `has_more` 為 `true`，就將 `cursor` 設為上一次回應中的 `cursor`，再次呼叫。
3. 當 `has_more` 為 `false` 時停止。

```bash
curl "https://rest.boxhero-app.com/v1/items?cursor=1234567" \
  -H "Authorization: Bearer $BOXHERO_API_TOKEN"
```

第一次呼叫時使用的篩選條件，在之後的每次呼叫中都要保持相同。

## 排序

每種資源都定義了自己的排序方式。大多數清單端點會依 id 遞增傳回結果。[列出庫存記錄](https://www.boxhero.io/docs/zh-tw/developers/api/reference/transactions/list-transactions)會先傳回最新的庫存記錄（依庫存記錄時間排序，時間相同時依 id 排序）。

> **Tip**
>
> **專業提示**：若要讓庫存記錄的副本保持同步，請儲存每筆庫存記錄的 `revision`。再次逐頁讀取清單時，若 `revision` 變大，就表示該庫存記錄在您上次查看後已被編輯。