> 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-cn/developers/api/pagination.md).

# 分页

> 使用基于游标的分页遍历 BoxHero API 中的长列表。

列表端点每次返回一页结果，并使用基于游标的分页。

## 查询参数

| 参数 | 说明 |
| --- | --- |
| `cursor` | 页面的起始位置。传入上一次响应中的 `cursor` 字段。首次调用时省略。 |
| `limit` | 每页大小。允许的范围和默认值列在各端点中，例如[获取商品列表](https://www.boxhero.io/docs/zh-cn/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-cn/developers/api/reference/transactions/list-transactions)会先返回最新的库存记录（按库存记录时间排序，时间相同时按 id 排序）。

> **Tip**
>
> **专业提示**：如需保持库存记录副本同步，请保存每条库存记录的 `revision`。再次遍历列表时，如果 `revision` 变大，就说明该库存记录在您上次查看后被编辑过。