获取记录列表

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

本文档聚焦列表接口自己的查询与分页语义；data.list[] 中每一条记录的内容结构，与 获取单条记录 在相同 format 下的 data.data 保持一致。包括 trusted_notary 在内的记录详情字段，也随对应 format 一并复用。

请求示例

Python + requestscurl

python

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 -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	与 `获取单条记录` 中 `format=json` 的 `data.data` 一致	程序化解析、数据同步、字段级处理
`json-ld`	object	与 `获取单条记录` 中 `format=json-ld` 的 `data.data` 一致	语义化数据交换、知识图谱、语义检索
`markdown`	string	与 `获取单条记录` 中 `format=markdown` 的 `data.data` 一致	阅读展示、归档导出、交给 LLM 做阅读类处理

完整返回示例

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

format=jsonformat=json-ldformat=markdown

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

{
  "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

{
  "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[] 中每一项的结构与 获取单条记录 的 data.data 完全一致。

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

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

字段定义、tpl_groups 结构、field_type 与 field_value 的映射规则等，详见 获取单条记录 和 表单组件类型总览。各 format 对应的 schema（复用自 getRecord）：

content-json.schema.json（json payload schema）

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "content-json.schema.json",
  "title": "record/getRecord content schema (format=json)",
  "description": "`record/getRecord` 在 `format=json` 时 `data.data` 的结构定义。用于说明记录详情对象本体，不含最外层 code/message/data 包装。",
  "type": "object",
  "required": [
    "record_id",
    "record_number",
    "record_code",
    "record_url",
    "submit_at",
    "submit_at_iso",
    "submit_method",
    "tpl_groups",
    "recorder",
    "qrcode",
    "org",
    "record_template"
  ],
  "properties": {
    "record_id": {
      "type": "integer",
      "description": "记录ID（企业下唯一）"
    },
    "record_number": {
      "type": "string",
      "description": "记录编号（企业内唯一）"
    },
    "record_code": {
      "type": "string",
      "description": "记录code（平台唯一）"
    },
    "record_url": {
      "type": "string",
      "format": "uri",
      "description": "记录码访问地址（平台唯一）"
    },
    "submit_at": {
      "type": "integer",
      "description": "记录提交时间（Unix 时间戳，秒）"
    },
    "submit_at_iso": {
      "type": "string",
      "description": "记录提交时间（格式：Y-m-d H:i:s(UTC+08:00)）"
    },
    "submit_method": {
      "type": "string",
      "description": "记录填写方式，如\"扫一扫填写\"、\"手动添加\"等"
    },
    "recorder": {
      "$ref": "#/$defs/Recorder"
    },
    "tpl_groups": {
      "type": "array",
      "description": "模板分组列表，每个分组包含若干字段",
      "items": {
        "$ref": "#/$defs/TplGroup"
      }
    },
    "project": {
      "$ref": "#/$defs/Project"
    },
    "qrcode": {
      "$ref": "#/$defs/Qrcode"
    },
    "org": {
      "$ref": "#/$defs/Org"
    },
    "record_template": {
      "$ref": "#/$defs/RecordTemplate"
    },
    "audit": {
      "$ref": "#/$defs/Audit"
    },
    "process_status": {
      "$ref": "#/$defs/ProcessStatus"
    },
    "state_changes": {
      "type": "array",
      "description": "状态变更记录列表",
      "items": {
        "$ref": "#/$defs/StateChange"
      }
    },
    "trusted_notary": {
      "description": "记录最新区块链可信存证摘要。无存证数据时返回 null",
      "oneOf": [
        {
          "$ref": "#/$defs/TrustedNotary"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Recorder": {
      "type": "object",
      "description": "记录提交人信息",
      "required": [
        "auth_id",
        "user_id",
        "name"
      ],
      "properties": {
        "auth_id": {
          "type": "integer",
          "description": "提交人权限ID"
        },
        "user_id": {
          "type": "integer",
          "description": "提交人用户ID"
        },
        "name": {
          "type": "string",
          "description": "提交人姓名"
        }
      },
      "additionalProperties": false
    },
    "TrustedNotary": {
      "type": "object",
      "description": "记录最新区块链可信存证摘要",
      "required": [
        "tx_hash",
        "evidence_url",
        "notarized_at",
        "notarized_at_iso"
      ],
      "properties": {
        "tx_hash": {
          "type": "string",
          "description": "链上存证哈希"
        },
        "evidence_url": {
          "type": "string",
          "format": "uri",
          "description": "当前最新存证对应的源文件URL"
        },
        "notarized_at": {
          "type": "integer",
          "description": "最新存证时间（Unix 时间戳，秒）"
        },
        "notarized_at_iso": {
          "type": "string",
          "description": "最新存证时间（格式：Y-m-d H:i:s(UTC+08:00)）"
        }
      },
      "additionalProperties": false
    },
    "Project": {
      "type": "object",
      "description": "所属项目信息",
      "required": [
        "id",
        "name",
        "number"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "项目ID"
        },
        "name": {
          "type": "string",
          "description": "项目名称"
        },
        "number": {
          "type": "string",
          "description": "项目编号"
        }
      },
      "additionalProperties": false
    },
    "Qrcode": {
      "type": "object",
      "description": "关联二维码信息",
      "required": [
        "id",
        "name",
        "type",
        "type_text",
        "template_id",
        "qrcode_url",
        "number"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "二维码ID"
        },
        "name": {
          "type": "string",
          "description": "二维码名称"
        },
        "type": {
          "type": "integer",
          "description": "二维码类型（0=普通二维码）"
        },
        "type_text": {
          "type": "string",
          "description": "二维码类型文本"
        },
        "template_id": {
          "type": "integer",
          "description": "二维码模板ID"
        },
        "qrcode_url": {
          "type": "string",
          "format": "uri",
          "description": "二维码短链接地址"
        },
        "number": {
          "type": "string",
          "description": "二维码编号"
        },
        "category_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "目录ID"
        }
      },
      "additionalProperties": false
    },
    "Org": {
      "type": "object",
      "description": "所属组织/企业信息",
      "required": [
        "id",
        "name",
        "code",
        "logo_url"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "企业ID（平台唯一）"
        },
        "name": {
          "type": "string",
          "description": "企业名称"
        },
        "code": {
          "type": "string",
          "description": "企业唯一编码"
        },
        "logo_url": {
          "type": "string",
          "format": "uri",
          "description": "企业Logo URL"
        }
      },
      "additionalProperties": false
    },
    "RecordTemplate": {
      "type": "object",
      "description": "记录模板（表单）信息",
      "required": [
        "id",
        "name",
        "type",
        "type_text",
        "number"
      ],
      "properties": {
        "id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "表单ID"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "表单名称"
        },
        "type": {
          "type": [
            "integer",
            "null"
          ],
          "description": "表单类型：0/1/2=普通表单, 3=保密承诺系统表单, 7=码状态手动变更记录系统表单, 12=身份组成员申请加入记录表单, 13=子码编辑记录系统表单, 21=码留言记录系统表单, 22=码协作记录系统表单",
          "enum": [
            null,
            0,
            1,
            2,
            3,
            7,
            12,
            13,
            21,
            22
          ]
        },
        "type_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "表单类型说明"
        },
        "number": {
          "type": [
            "string",
            "null"
          ],
          "description": "表单编号"
        }
      },
      "additionalProperties": false
    },
    "Audit": {
      "type": "object",
      "description": "当前审核阶段信息（仅在启用审核时出现）",
      "required": [
        "enabled"
      ],
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "是否启用审核"
        },
        "current_stage_id": {
          "type": [
            "integer",
            "null"
          ],
          "description": "当前审核阶段ID"
        },
        "current_stage_title": {
          "type": [
            "string",
            "null"
          ],
          "description": "当前审核阶段名称"
        },
        "status": {
          "type": [
            "integer",
            "null"
          ],
          "description": "审核状态码（0=待审核, 1=审核通过, 2=审核拒绝）"
        },
        "status_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "审核状态文本"
        },
        "auditor_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "审核人姓名"
        }
      },
      "additionalProperties": false
    },
    "ProcessStatus": {
      "type": "object",
      "description": "处理状态信息（仅在启用处理状态时出现）",
      "required": [
        "enabled"
      ],
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "是否启用处理状态"
        },
        "text": {
          "type": [
            "string",
            "null"
          ],
          "description": "当前处理状态文本"
        },
        "color": {
          "type": [
            "string",
            "null"
          ],
          "description": "状态颜色（Hex 格式，如 #155EB7）"
        }
      },
      "additionalProperties": false
    },
    "StateChange": {
      "type": "object",
      "description": "单条状态变更记录",
      "required": [
        "state",
        "from_state_option",
        "to_state_option"
      ],
      "properties": {
        "state": {
          "type": "object",
          "description": "状态定义",
          "required": [
            "id",
            "name",
            "number"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "状态ID"
            },
            "name": {
              "type": "string",
              "description": "状态名称"
            },
            "number": {
              "type": "string",
              "description": "状态编号"
            }
          },
          "additionalProperties": false
        },
        "from_state_option": {
          "$ref": "#/$defs/StateOption"
        },
        "to_state_option": {
          "$ref": "#/$defs/StateOption"
        }
      },
      "additionalProperties": false
    },
    "StateOption": {
      "type": "object",
      "description": "状态选项值",
      "required": [
        "name",
        "color"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "状态选项名称"
        },
        "color": {
          "type": "string",
          "description": "状态选项颜色（Hex 格式）"
        }
      },
      "additionalProperties": false
    },
    "TplGroup": {
      "type": "object",
      "description": "模板分组",
      "required": [
        "group_id",
        "group_title",
        "show_group_title",
        "is_page_break_group",
        "fields"
      ],
      "properties": {
        "group_id": {
          "type": "integer",
          "description": "分组ID"
        },
        "group_title": {
          "type": "string",
          "description": "分组标题（空字符串表示无标题）"
        },
        "show_group_title": {
          "type": "boolean",
          "description": "是否显示分组标题"
        },
        "is_page_break_group": {
          "type": "boolean",
          "description": "是否为分页标记组（分页组的 fields 通常为空数组）"
        },
        "fields": {
          "type": "array",
          "description": "分组内的字段列表",
          "items": {
            "$ref": "#/$defs/Field"
          }
        }
      },
      "additionalProperties": false
    },
    "Field": {
      "type": "object",
      "description": "单个表单字段",
      "required": [
        "field_id",
        "field_title",
        "field_type",
        "field_value",
        "options"
      ],
      "properties": {
        "field_id": {
          "type": "integer",
          "description": "字段ID"
        },
        "field_title": {
          "type": "string",
          "description": "字段标题"
        },
        "field_desc": {
          "type": "string",
          "description": "字段描述/提示文字"
        },
        "field_type": {
          "type": "string",
          "description": "字段类型标识",
          "enum": [
            "name",
            "tel",
            "recorder",
            "identity",
            "job_number",
            "text",
            "textarea",
            "date",
            "time",
            "customer_name",
            "customer_mobile",
            "customer_number",
            "carnumber",
            "sex",
            "radio",
            "number",
            "checkbox",
            "checklist",
            "matrix",
            "dynamic_matrix",
            "address",
            "owner_address",
            "chained_selects",
            "image",
            "signature",
            "audio",
            "video",
            "file",
            "description",
            "ocr_id_card",
            "ocr_bank_card",
            "ocr_vehicle_license",
            "ocr_driving_license",
            "ocr_car_number",
            "ocr_car_vin",
            "ocr_business_license",
            "ocr_way_bill",
            "ocr_special_operate",
            "ocr_general_cert",
            "ocr_degree_cert",
            "ocr_diploma_cert",
            "ocr_dashboard_mile",
            "ocr_electric_meter",
            "ocr_water_meter",
            "ocr_hygrother_mograp",
            "ocr_gas_meter",
            "ocr_pressure_meter",
            "ocr_general_meter",
            "ocr_digital_meter",
            "ocr_roll_meter",
            "ocr_pointer_meter",
            "ocr_liquid_column_meter",
            "sub_qrcode_edit_diff"
          ]
        },
        "field_short_name": {
          "type": "string",
          "description": "字段短名称"
        },
        "group_id": {
          "type": "integer",
          "description": "所属分组ID"
        },
        "field_value": {
          "description": "字段值，类型随 field_type 不同而变化，详见 $defs/FieldValue*",
          "oneOf": [
            {
              "$ref": "#/$defs/FieldValueString"
            },
            {
              "$ref": "#/$defs/FieldValueSingleOption"
            },
            {
              "$ref": "#/$defs/FieldValueNumber"
            },
            {
              "$ref": "#/$defs/FieldValueCheckbox"
            },
            {
              "$ref": "#/$defs/FieldValueChecklist"
            },
            {
              "$ref": "#/$defs/FieldValueMatrix"
            },
            {
              "$ref": "#/$defs/FieldValueDynamicMatrix"
            },
            {
              "$ref": "#/$defs/FieldValueAddress"
            },
            {
              "$ref": "#/$defs/FieldValueOwnerAddress"
            },
            {
              "$ref": "#/$defs/FieldValueChainedSelects"
            },
            {
              "$ref": "#/$defs/FieldValueImageList"
            },
            {
              "$ref": "#/$defs/FieldValueAudioList"
            },
            {
              "$ref": "#/$defs/FieldValueVideoList"
            },
            {
              "$ref": "#/$defs/FieldValueFileList"
            },
            {
              "$ref": "#/$defs/FieldValueDescription"
            },
            {
              "$ref": "#/$defs/FieldValueOcr"
            },
            {
              "$ref": "#/$defs/FieldValueSubQrcodeEditChangeList"
            }
          ]
        },
        "options": {
          "$ref": "#/$defs/FieldOptions"
        }
      },
      "additionalProperties": false
    },
    "FieldOptions": {
      "type": "object",
      "description": "字段显示选项",
      "required": [
        "is_result",
        "is_highlight",
        "is_hidden",
        "is_masked"
      ],
      "properties": {
        "is_result": {
          "type": "boolean",
          "description": "是否为结果字段"
        },
        "is_highlight": {
          "type": "boolean",
          "description": "是否高亮显示"
        },
        "is_hidden": {
          "type": "boolean",
          "description": "是否隐藏"
        },
        "is_masked": {
          "type": "boolean",
          "description": "是否脱敏显示"
        }
      },
      "additionalProperties": false
    },
    "FieldValueString": {
      "type": "string",
      "description": "纯文本字段值。适用 field_type: name, tel, recorder, identity, job_number, text, textarea, date, time, customer_name, customer_mobile, customer_number, carnumber"
    },
    "FieldValueSingleOption": {
      "type": "object",
      "description": "单选字段值。适用 field_type: sex, radio",
      "required": [
        "option_text",
        "option_id"
      ],
      "properties": {
        "option_text": {
          "type": "string",
          "description": "选项文本。若选择\"其他\"并填写补充，格式为 \"其他[补充内容]\""
        },
        "option_id": {
          "type": "integer",
          "description": "选项ID"
        }
      },
      "additionalProperties": false
    },
    "FieldValueNumber": {
      "type": "object",
      "description": "数字字段值。适用 field_type: number",
      "required": [
        "value",
        "unit",
        "unit_enabled"
      ],
      "properties": {
        "value": {
          "type": "number",
          "description": "数值"
        },
        "unit": {
          "type": "string",
          "description": "单位文本（无单位时为空字符串）"
        },
        "unit_enabled": {
          "type": "boolean",
          "description": "是否启用单位"
        }
      },
      "additionalProperties": false
    },
    "FieldValueCheckbox": {
      "type": "object",
      "description": "多选字段值。适用 field_type: checkbox",
      "required": [
        "values"
      ],
      "properties": {
        "values": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "option_id",
              "option_text"
            ],
            "properties": {
              "option_id": {
                "type": "integer",
                "description": "选项ID"
              },
              "option_text": {
                "type": "string",
                "description": "选项文本。若选择\"其他\"并填写补充，格式为 \"其他[补充内容]\""
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "FieldValueChecklist": {
      "type": "array",
      "description": "检查清单字段值。适用 field_type: checklist",
      "items": {
        "type": "object",
        "required": [
          "item_id",
          "item_title",
          "value"
        ],
        "properties": {
          "item_id": {
            "type": "integer",
            "description": "检查项ID"
          },
          "item_title": {
            "type": "string",
            "description": "检查项标题"
          },
          "value": {
            "type": "object",
            "required": [
              "option_id",
              "option_text",
              "description",
              "images"
            ],
            "properties": {
              "option_id": {
                "type": "integer",
                "description": "选择的选项ID"
              },
              "option_text": {
                "type": "string",
                "description": "选择的选项文本（如 正常、异常、需要关注）"
              },
              "description": {
                "type": "string",
                "description": "补充描述（无描述时为空字符串）"
              },
              "images": {
                "type": "array",
                "description": "补充图片列表",
                "items": {
                  "$ref": "#/$defs/ImageItem"
                }
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueMatrix": {
      "type": "object",
      "description": "矩阵（单行）字段值。适用 field_type: matrix",
      "required": [
        "columns"
      ],
      "properties": {
        "columns": {
          "type": "array",
          "description": "列数据列表",
          "items": {
            "$ref": "#/$defs/MatrixColumn"
          }
        }
      },
      "additionalProperties": false
    },
    "FieldValueDynamicMatrix": {
      "type": "object",
      "description": "动态矩阵（多行）字段值。适用 field_type: dynamic_matrix",
      "required": [
        "rows"
      ],
      "properties": {
        "rows": {
          "type": "array",
          "description": "行数据列表",
          "items": {
            "type": "object",
            "required": [
              "columns"
            ],
            "properties": {
              "columns": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/MatrixColumn"
                }
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "MatrixColumn": {
      "type": "object",
      "description": "矩阵中的单个列",
      "required": [
        "column_id",
        "column_title",
        "column_type",
        "value"
      ],
      "properties": {
        "column_id": {
          "type": "integer",
          "description": "列ID"
        },
        "column_title": {
          "type": "string",
          "description": "列标题"
        },
        "column_type": {
          "type": "string",
          "description": "列类型（text, sex, identity, date, owner_address 等）"
        },
        "value": {
          "type": "object",
          "required": [
            "text",
            "option_uuid"
          ],
          "properties": {
            "text": {
              "type": [
                "string",
                "null"
              ],
              "description": "文本值"
            },
            "option_uuid": {
              "type": [
                "string",
                "null"
              ],
              "description": "选项 UUID，非选择类列为 null"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "FieldValueAddress": {
      "type": "object",
      "description": "地址定位字段值。适用 field_type: address",
      "required": [
        "address",
        "lat",
        "lng"
      ],
      "properties": {
        "address": {
          "type": "string",
          "description": "地址文本"
        },
        "lat": {
          "type": "number",
          "description": "纬度"
        },
        "lng": {
          "type": "number",
          "description": "经度"
        }
      },
      "additionalProperties": false
    },
    "FieldValueOwnerAddress": {
      "type": "object",
      "description": "详细地址字段值（省/市/区/街道/详细）。适用 field_type: owner_address",
      "required": [
        "province",
        "city",
        "district",
        "street",
        "detail",
        "full_address"
      ],
      "properties": {
        "province": {
          "type": "string",
          "description": "省份"
        },
        "city": {
          "type": "string",
          "description": "城市"
        },
        "district": {
          "type": "string",
          "description": "区/县"
        },
        "street": {
          "type": "string",
          "description": "街道/乡镇"
        },
        "detail": {
          "type": "string",
          "description": "详细地址"
        },
        "full_address": {
          "type": "string",
          "description": "完整地址拼接"
        }
      },
      "additionalProperties": false
    },
    "FieldValueChainedSelects": {
      "type": "object",
      "description": "级联选择字段值。适用 field_type: chained_selects",
      "required": [
        "values"
      ],
      "properties": {
        "values": {
          "type": "array",
          "description": "各级选择值（按 level 升序排列）",
          "items": {
            "type": "object",
            "required": [
              "option_id",
              "option_text",
              "level"
            ],
            "properties": {
              "option_id": {
                "type": "integer",
                "description": "选项ID"
              },
              "option_text": {
                "type": "string",
                "description": "选项文本"
              },
              "level": {
                "type": "integer",
                "description": "层级（从 1 开始）"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "FieldValueImageList": {
      "type": "array",
      "description": "图片/签名字段值。适用 field_type: image, signature",
      "items": {
        "$ref": "#/$defs/ImageItem"
      }
    },
    "FieldValueAudioList": {
      "type": "array",
      "description": "音频字段值。适用 field_type: audio",
      "items": {
        "type": "object",
        "required": [
          "url",
          "size",
          "duration"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "音频文件 URL"
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "文件大小（字节），可能为 null"
          },
          "duration": {
            "type": "number",
            "description": "时长（秒）"
          },
          "translated_text": {
            "type": [
              "string",
              "null"
            ],
            "description": "语音转文字内容"
          },
          "abstract_text": {
            "type": [
              "string",
              "null"
            ],
            "description": "语音摘要文本"
          },
          "upload_time_iso": {
            "type": "string",
            "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueVideoList": {
      "type": "array",
      "description": "视频字段值。适用 field_type: video",
      "items": {
        "type": "object",
        "required": [
          "url",
          "size",
          "duration"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "视频文件 URL"
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "文件大小（字节）"
          },
          "duration": {
            "type": "number",
            "description": "时长（秒）"
          },
          "upload_time_iso": {
            "type": "string",
            "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueFileList": {
      "type": "array",
      "description": "文件字段值。适用 field_type: file",
      "items": {
        "type": "object",
        "required": [
          "url",
          "size",
          "file_name"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "文件下载 URL"
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "文件大小（字节）"
          },
          "file_name": {
            "type": "string",
            "description": "文件名（含扩展名）"
          },
          "upload_time_iso": {
            "type": "string",
            "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
          }
        },
        "additionalProperties": false
      }
    },
    "FieldValueDescription": {
      "type": "object",
      "description": "说明/描述字段值。适用 field_type: description",
      "required": [
        "description_html"
      ],
      "properties": {
        "description_html": {
          "type": "string",
          "description": "富文本 HTML 内容"
        }
      },
      "additionalProperties": false
    },
    "FieldValueOcr": {
      "type": "object",
      "description": "OCR 识别字段值。适用 field_type: ocr_id_card, ocr_bank_card, ocr_vehicle_license, ocr_driving_license, ocr_car_number, ocr_car_vin, ocr_business_license, ocr_way_bill, ocr_special_operate, ocr_general_cert, ocr_degree_cert, ocr_diploma_cert, ocr_dashboard_mile, ocr_electric_meter, ocr_water_meter, ocr_hygrother_mograp, ocr_gas_meter, ocr_pressure_meter, ocr_general_meter, ocr_digital_meter, ocr_roll_meter, ocr_pointer_meter, ocr_liquid_column_meter",
      "required": [
        "items",
        "image"
      ],
      "properties": {
        "items": {
          "type": "array",
          "description": "OCR 识别结果项列表",
          "items": {
            "type": "object",
            "required": [
              "item_id",
              "item_title",
              "value",
              "unit",
              "unit_enabled"
            ],
            "properties": {
              "item_id": {
                "type": "integer",
                "description": "识别项ID"
              },
              "item_title": {
                "type": "string",
                "description": "识别项标题"
              },
              "value": {
                "type": "string",
                "description": "识别结果值"
              },
              "unit": {
                "type": "string",
                "description": "单位（无单位时为空字符串）"
              },
              "unit_enabled": {
                "type": "boolean",
                "description": "是否启用单位"
              }
            },
            "additionalProperties": false
          }
        },
        "image": {
          "oneOf": [
            {
              "$ref": "#/$defs/ImageItem"
            },
            {
              "type": "null"
            }
          ],
          "description": "OCR 源图片（部分 OCR 类型无源图片时为 null）"
        }
      },
      "additionalProperties": false
    },
    "AiImageAuditResult": {
      "type": "object",
      "description": "AI 图片审核结果（仅当原始数据含审核信息时输出）",
      "required": [
        "audit_status",
        "audit_status_text",
        "reason"
      ],
      "properties": {
        "audit_status": {
          "type": "integer",
          "description": "0=默认，1=通过，2=不通过，3=失败，4=待审核"
        },
        "audit_status_text": {
          "type": "string",
          "description": "与 audit_status 对应的中文说明（默认、通过、不通过、失败、待审核）"
        },
        "reason": {
          "type": "string",
          "description": "AI 针对当前审核状态返回的原因说明"
        }
      },
      "additionalProperties": false
    },
    "ImageItem": {
      "type": "object",
      "description": "图片资源",
      "required": [
        "url",
        "size",
        "width",
        "height"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "图片 URL"
        },
        "size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "文件大小（字节）"
        },
        "width": {
          "type": "integer",
          "description": "图片宽度（像素）"
        },
        "height": {
          "type": "integer",
          "description": "图片高度（像素）"
        },
        "upload_time_iso": {
          "type": "string",
          "description": "上传时间（格式：Y-m-d H:i:s(UTC+08:00)）"
        },
        "ai_audit_result": {
          "$ref": "#/$defs/AiImageAuditResult",
          "description": "可选；无 AI 审核数据时不返回"
        }
      },
      "additionalProperties": false
    },
    "FieldValueSubQrcodeEditChangeList": {
      "type": "array",
      "description": "子码编辑变更记录列表。适用 field_type: sub_qrcode_edit_diff。每个元素代表一个被修改的字段及其修改前后的值。",
      "items": {
        "$ref": "#/$defs/SubQrcodeEditChangeItem"
      }
    },
    "SubQrcodeEditChangeItem": {
      "type": "object",
      "description": "子码编辑的单个字段变更记录",
      "required": [
        "field_id",
        "field_title",
        "field_type",
        "before_value",
        "after_value"
      ],
      "properties": {
        "field_id": {
          "type": "integer",
          "description": "被修改的原始字段ID"
        },
        "field_title": {
          "type": "string",
          "description": "被修改的原始字段标题"
        },
        "field_type": {
          "type": "string",
          "description": "被修改的原始字段类型",
          "enum": [
            "text",
            "textarea",
            "number",
            "date",
            "time",
            "radio",
            "checkbox",
            "address",
            "image",
            "signature",
            "audio",
            "video",
            "file"
          ]
        },
        "before_value": {
          "$ref": "#/$defs/SubQrcodeEditChangeContent"
        },
        "after_value": {
          "$ref": "#/$defs/SubQrcodeEditChangeContent"
        }
      },
      "additionalProperties": false
    },
    "SubQrcodeEditChangeContent": {
      "type": "object",
      "description": "变更前/后的内容。非媒体字段使用 text_content；媒体字段使用 media_items。",
      "required": [
        "text_content",
        "media_items"
      ],
      "properties": {
        "text_content": {
          "type": "string",
          "description": "文本内容（非媒体字段的值，媒体字段时为空字符串）"
        },
        "media_items": {
          "type": "array",
          "description": "媒体项列表（媒体字段的值，非媒体字段时为空数组）。元素结构随所属变更项的 field_type 不同而变化。",
          "items": {
            "$ref": "#/$defs/SubQrcodeEditChangeMediaItem"
          }
        }
      },
      "additionalProperties": false
    },
    "SubQrcodeEditChangeMediaItem": {
      "type": "object",
      "description": "变更内容中的媒体资源项。根据所属变更项的 field_type 不同，包含不同属性：image/signature 有 width/height；audio 有 duration/translated_text/abstract_text；video 有 duration；file 有 file_name。",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "资源 URL"
        },
        "size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "文件大小（字节）"
        },
        "width": {
          "type": "integer",
          "description": "图片宽度（px）—— 仅 image/signature"
        },
        "height": {
          "type": "integer",
          "description": "图片高度（px）—— 仅 image/signature"
        },
        "duration": {
          "type": "number",
          "description": "时长（秒）—— 仅 audio/video"
        },
        "file_name": {
          "type": "string",
          "description": "文件名（含扩展名）—— 仅 file"
        },
        "translated_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "语音转文字 —— 仅 audio"
        },
        "abstract_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "语音摘要 —— 仅 audio"
        },
        "ai_audit_result": {
          "$ref": "#/$defs/AiImageAuditResult",
          "description": "可选；image/signature 变更项在含审核数据时返回"
        }
      },
      "additionalProperties": false
    }
  }
}

content-jsonld.schema.json（json-ld payload schema）

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "content-jsonld.schema.json",
  "title": "record/getRecord content schema (format=json-ld)",
  "description": "`record/getRecord` 在 `format=json-ld` 时 `data.data` 的结构定义。该结构基于 Schema.org 风格输出，保留主字段约束并允许扩展属性。",
  "type": "object",
  "required": [
    "@context",
    "@type",
    "identifier",
    "name",
    "url",
    "mainEntity"
  ],
  "properties": {
    "@context": {
      "type": "string"
    },
    "@type": {
      "type": "string"
    },
    "identifier": {
      "type": "string"
    },
    "alternateName": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "dateCreated": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "author": {
      "type": "object"
    },
    "sourceOrganization": {
      "type": "object"
    },
    "isBasedOn": {
      "type": "object"
    },
    "isPartOf": {
      "type": "object"
    },
    "additionalProperty": {
      "type": "array"
    },
    "review": {
      "type": "object"
    },
    "potentialAction": {
      "type": "array"
    },
    "mainEntity": {
      "type": "object"
    }
  },
  "additionalProperties": true
}

content-markdown.schema.json（markdown payload schema）

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "content-markdown.schema.json",
  "title": "record/getRecord content schema (format=markdown)",
  "description": "`record/getRecord` 在 `format=markdown` 时 `data.data` 的结构定义。返回值为完整 Markdown 文本。",
  "type": "string"
}

当 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` 作为翻页终止条件

空值与脱敏约定

列表项中的空值、空数组、空字符串、关联对象为空值以及脱敏规则，与 获取单条记录 完全一致。

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

错误响应

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

json

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

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

具体错误码定义见：错误码说明。

二维码

活码

表单

批量模板 & 子码

记录

成员

活码

表单与记录

安装教程

企业微信版购买

常见问题

获取记录列表

请求示例

请求参数

`filters` 子字段说明

`filters.record_template`

`filters.qrcode`

`filters.project`

`filters.audit`

`filters.process_status`

`filters.state_changes`

`filters.recorder`

返回格式概览

完整返回示例

响应结构总览

列表项结构说明

与 `getRecord` 的复用关系

推荐过滤策略

空列表示例

其他字段约定

分页约定

空值与脱敏约定

错误响应

获取记录列表 ​

请求示例 ​

请求参数 ​

filters 子字段说明 ​

filters.record_template ​

filters.qrcode ​

filters.project ​

filters.audit ​

filters.process_status ​

filters.state_changes ​

filters.recorder ​

返回格式概览 ​

完整返回示例 ​

响应结构总览 ​

列表项结构说明 ​

与 getRecord 的复用关系 ​

推荐过滤策略 ​

空列表示例 ​

其他字段约定 ​

分页约定 ​

空值与脱敏约定 ​

错误响应 ​

获取记录列表

请求示例

请求参数

`filters` 子字段说明

`filters.record_template`

`filters.qrcode`

`filters.project`

`filters.audit`

`filters.process_status`

`filters.state_changes`

`filters.recorder`

返回格式概览

完整返回示例

响应结构总览

列表项结构说明

与 `getRecord` 的复用关系

推荐过滤策略

空列表示例

其他字段约定

分页约定

空值与脱敏约定

错误响应