分页与游标

普通分页

大部分列表接口走标准 page-based 分页：

参数	说明	限制
pageNum	页码，从 1 开始	上限 10000
pageSize	每页条数	上限 100（部分接口 200）

响应：

{
  "code": 0,
  "data": {
    "list": [ ... ],
    "total": 1234,
    "pageNum": 1,
    "pageSize": 20
  }
}

增量同步（推荐用于全量场景）

不要在分页接口上 pageNum 递增遍历全量数据，深分页性能差且会触发 MAX_OFFSET 限制。

资源类增量同步用：

GET /openapi/v2/resource/sync?cursor={ISO 时间戳}&size=100

• 首次：cursor 留空，返回最早 100 条 + 下次 cursor
• 后续：把上一次响应的 nextCursor 传入
• 跑到 nextCursor 为空时停下，进入实时模式（可改用 Webhook）

响应：

{
  "code": 0,
  "data": {
    "items": [ ... ],
    "nextCursor": "2026-05-15T12:34:56Z",
    "hasMore": true
  }
}

批量获取

很多接口提供批量入口，用法是 POST 一组 ID：

接口	上限
POST /openapi/v2/resource/batch	50 个 postId
POST /openapi/v2/file/batch	50 个 fileId
POST /openapi/v1/post/batch-detail	20 个 postId

批量接口返回严格按入参顺序排列；不存在的 ID 不会报错，而是返回 null 占位（建议代码侧用 data[i] != null 判断）。

软删 vs 硬删

返回结果默认不含 isDelete = 1 的记录。如果在 Webhook 中收到 resource.deleted 事件，不要再去主接口查询；用 Webhook payload 中的快照数据即可。