# 获取记录列表

按 `filters`、关键字、时间和分页条件获取记录列表，支持 `json`、`json-ld`、`markdown` 三种输出格式。

本文档聚焦列表接口自己的查询与分页语义；`data.list[]` 中每一条记录的内容结构，与 [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 在相同 `format` 下的 `data.data` 保持一致。包括 `trusted_notary` 在内的记录详情字段，也随对应 `format` 一并复用。

## 请求示例



```python [Python + requests]
import requests

url = 'https://open.cli.im/api/v2/rpc/record/getRecords'
data = {
    'filters': {
        'record_template': {'id': 10001},
        'qrcode': {'id': 30001}
    },
    'format': 'json',
    'search_key': '张三',
    'record_type': 0,
    'page_size': 10,
    'get_total_count': 1
}
headers = {
    'Authorization': 'Bearer <你的API Key>',
    'Content-Type': 'application/json'
}
response = requests.post(url, json=data, headers=headers)
print(response.text)
```

```bash [curl]
curl -X POST 'https://open.cli.im/api/v2/rpc/record/getRecords' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"filters": {"record_template": {"id": 10001}, "qrcode": {"id": 30001}}, "format": "json", "page_size": 10}'
```



## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `format` | string | 否 | 输出格式，默认 `json`。可选值：`json`、`json-ld`、`markdown` |
| `search_key` | string | 否 | 组件内容关键字模糊查询，对记录内字段全文检索 |
| `filters` | object | 否 | 筛选条件对象，可组合使用；详见下方「`filters` 子字段说明」 |
| `record_type` | integer | 否 | 记录类型筛选：`0` 全部，`3` 状态变更，`7` 子码编辑。默认 `0` |
| `start_time` | string \| integer | 否 | 开始时间，支持 Unix 时间戳或 ISO 8601 字符串 |
| `end_time` | string \| integer | 否 | 结束时间，支持 Unix 时间戳或 ISO 8601 字符串 |
| `page_size` | integer | 否 | 每页记录数，最大 50，默认 10 |
| `page_token` | string | 否 | 分页游标，由上一页响应返回 |
| `last_record_id` | integer | 否 | 记录 ID 偏移，从此 ID 之后开始查 |
| `order_by` | string | 否 | 排序方式，格式为 `{字段},{方向}`。支持 `submit_at,desc`（按提交时间降序）和 `submit_at,asc`（按提交时间升序）；默认 `submit_at,desc` |
| `get_total_count` | integer | 否 | 是否返回总数：`1` 返回，`0` 可跳过总数统计以提升性能。默认 `1` |

### `filters` 子字段说明

`filters` 为可选对象，可包含以下子字段，支持组合使用。

缺省范围说明：

- `filters` 整体可省略；省略时，表示在当前 API Key 可见范围内查询记录，通常为当前企业范围内的记录。
- 未传 `filters.qrcode.id` 时，表示不按二维码限制；如果仅传 `filters.record_template.id`，则表示查询该表单下的记录。
- 未传 `filters.record_template.id` 时，表示不按表单限制；如果仅传 `filters.qrcode.id`，则表示查询该二维码下的记录。
- 同时传 `filters.qrcode.id + filters.record_template.id` 时，表示查询“该二维码下、该表单产生的记录”，适合精确定位某个码上的某个表单记录。
- 其他 `filters.*` 子字段与上述条件按组合条件共同生效。

#### `filters.record_template`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 表单模板 ID |

#### `filters.qrcode`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer  | 二维码 ID，支持单个 |
| `template_id` | integer | 二维码模板 ID（批量模板） |
| `category_id` | integer  | 二维码分组 ID，支持单个 |

#### `filters.project`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 分区 ID |

#### `filters.audit`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `stage_id` | integer | 审核阶段 ID |
| `status` | integer | 审核状态：`0` 待审核 / `1` 审核通过 / `2` 审核不通过；不传表示全部状态 |

#### `filters.process_status`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `text` | string | 处理状态文本，精确匹配；可选值参考表单详情中的 `process_status_config` |

#### `filters.state_changes`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `state_id` | integer | 状态组 ID，筛选触发了该状态变更的记录 |

#### `filters.recorder`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `auth_id` | integer | 填表人 `auth_id`（草料二维码平台用户授权 ID） |

## 返回格式概览

| 请求 `format` | `data.list[]` 类型 | 列表项内容来源 | 适用场景 |
| --- | --- | --- | --- |
| `json` | object | 与 [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 中 `format=json` 的 `data.data` 一致 | 程序化解析、数据同步、字段级处理 |
| `json-ld` | object | 与 [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 中 `format=json-ld` 的 `data.data` 一致 | 语义化数据交换、知识图谱、语义检索 |
| `markdown` | string | 与 [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 中 `format=markdown` 的 `data.data` 一致 | 阅读展示、归档导出、交给 LLM 做阅读类处理 |

## 完整返回示例

以下代码块展示三种 `format` 的成功响应骨架。



```json [format=json]
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "record_id": 10001,
        "record_number": "L10001",
        "record_code": "aBcDeFgH",
        "record_url": "https://qr61.cn/oXXXXX/aBcDeFg",
        "submit_at": 1763102668,
        "submit_at_iso": "2025-11-14 14:44:28(UTC+08:00)",
        "submit_method": "微信其他入口填写",
        "recorder": { "auth_id": 10001, "user_id": 20001, "name": "张**" },
        "project": { "id": 100, "name": "示例分区", "number": "F1" },
        "qrcode": { "id": 30001, "name": "示例二维码", "type": 0, "type_text": "普通二维码" },
        "org": { "id": 90001, "name": "示例科技有限公司", "code": "oXXXXX" },
        "record_template": { "id": 10001, "name": "日常记录", "type": 0, "type_text": "普通表单", "number": "D100" },
        "audit": { "enabled": false, "current_stage_id": null, "status": null, "status_text": null },
        "process_status": { "enabled": false, "text": null, "color": null },
        "state_changes": [],
        "tpl_groups": [
          {
            "group_id": 27178,
            "group_title": "",
            "show_group_title": false,
            "is_page_break_group": false,
            "fields": [
              { "field_id": 50001, "field_title": "示例图片", "field_type": "image", "field_value": [{ "url": "https://example.com/sample.jpg" }] }
            ]
          }
        ]
      }
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}
```

```json [format=json-ld]
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "@context": "https://schema.org",
        "@type": "CreativeWork",
        "identifier": "aBcDeFgH",
        "name": "日常记录-L10001",
        "url": "https://qr61.cn/oXXXXX/aBcDeFg",
        "mainEntity": { "@type": "ItemList", "name": "组件数据" }
      }
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}
```

```json [format=markdown]
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      "---\\ntitle: 日常记录-L10001\\nrecord_id: 10001\\n...\\n---\\n\\n# 日常记录-L10001\\n\\n## 基本信息\\n\\n**记录编号：** L10001"
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}
```



## 响应结构总览

| 路径 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 平台状态码，`0` 表示成功 |
| `message` | string | 状态消息 |
| `data` | object | 业务响应包装层 |
| `data.list` | array | 记录列表；元素类型由请求 `format` 决定 |
| `data.next_page_token` | string | 下一页分页游标；无下一页时通常返回空字符串 |
| `data.total` | integer | 符合条件的记录总数；通常在 `get_total_count=1` 时返回准确统计值 |

## 列表项结构说明

### 与 `getRecord` 的复用关系

`getRecords` 不额外定义记录内容 schema。相同 `format` 下，`data.list[]` 中每一项的结构与 [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 的 `data.data` 完全一致。

这也包括区块链可信存证相关内容：

- `format=json` 时，列表项中的 `trusted_notary` 字段与 `getRecord` 完全一致
- `format=json-ld` 时，存证相关信息按 JSON-LD 语义化结构输出
- `format=markdown` 时，存证相关内容直接体现在 Markdown 文本中

字段定义、`tpl_groups` 结构、`field_type` 与 `field_value` 的映射规则等，详见 [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 和 [`表单组件类型总览`](https://cli.im/open-api/openapi/v2/api/record/components-field-types.md)。各 `format` 对应的 schema（复用自 `getRecord`）：

**content-json.schema.json（json payload schema）**
<<< ./record-get-record/schema/content-json.schema.json


**content-jsonld.schema.json（json-ld payload schema）**
<<< ./record-get-record/schema/content-jsonld.schema.json


**content-markdown.schema.json（markdown payload schema）**
<<< ./record-get-record/schema/content-markdown.schema.json


> 当 `format=json` 时，列表中每一项已是完整记录详情对象，批量读取记录内容通常不需要再逐条调用 `getRecord`。`getRecord` 更适合已拿到单个 `record_id` / `record_url` 的精确查询场景。

## 推荐过滤策略

| 目标 | 推荐参数 |
| --- | --- |
| 查询某个二维码下的全部记录 | `filters.qrcode.id` |
| 查询某个二维码下某个表单的记录 | `filters.qrcode.id + filters.record_template.id` |
| 查询某个表单在当前可见范围内的全部记录 | `filters.record_template.id` |
| 在当前 API Key 可见范围内做全局记录检索 | 可不传 `filters.qrcode.id` 与 `filters.record_template.id`，再按需叠加 `search_key`、时间范围或其他 `filters.*` |

## 空列表示例

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [],
    "next_page_token": "",
    "total": 0
  }
}
```

## 其他字段约定

### 分页约定

| 场景 | 说明 |
| --- | --- |
| 首次查询 | 可不传 `page_token` |
| 存在下一页 | 将上一次响应中的 `data.next_page_token` 原样传回请求参数 `page_token` |
| 无下一页 | `data.next_page_token` 通常为空字符串 |
| 是否继续翻页 | 建议始终以 `data.next_page_token` 是否为空作为判断依据 |
| `get_total_count=0` | 服务端可跳过总数统计以提升性能；此时不建议依赖 `data.total` 作为翻页终止条件 |

### 空值与脱敏约定

列表项中的空值、空数组、空字符串、关联对象为空值以及脱敏规则，与 [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 完全一致。

文档中链接到的示例文件均已做脱敏处理，仅用于结构说明与联调参考。

## 错误响应

失败时通常返回非成功状态，响应体可能包含以下字段：

```json
{
  "code": 400,
  "error_code": 100300,
  "message": "System error",
  "message_detail": ""
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | HTTP 状态码或平台错误状态 |
| `error_code` | integer | 业务错误码 |
| `message` | string | 错误摘要 |
| `message_detail` | string | 详细错误信息，可能为空字符串 |

具体错误码定义见：[错误码与调用额度](https://cli.im/open-api/openapi/v2/error-codes.md)。
