获取单条记录

根据记录 ID 或记录 URL 获取单条记录详情，支持 json、json-ld、markdown 三种输出格式。

本文档正文聚焦响应结构与接入要点；完整 schema 与完整 demo 已拆分到同目录配套资源中。文中的示例文件均已做脱敏处理。

请求示例

Python + requestscurl

python

import requests

url = 'https://open.cli.im/api/v2/rpc/record/getRecord'
data = {
    'record_id': 10001,
    'format': 'json'
}
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/getRecord' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"record_id": 10001, "format": "json"}'

请求参数

参数	类型	必填	说明
`record_id`	integer	否	记录 ID。与 `record_url` 二选一，至少传一个
`record_url`	string	否	记录短链接 URL，通常为记录码 `r` 开头的完整访问地址。与 `record_id` 二选一，至少传一个
`format`	string	否	输出格式，默认 `json`。可选值：`json`、`json-ld`、`markdown`

返回格式概览

`format`	`data.content_type`	`data.data` 类型	适用场景
`json`	`application/json; charset=utf-8`	object	程序化解析、字段级处理、数据同步
`json-ld`	`application/ld+json; charset=utf-8`	object	语义化数据交换、Schema.org 风格接入
`markdown`	`text/markdown; charset=utf-8`	string	阅读展示、归档导出、摘要生成

完整示例：

普通记录：json 完整响应、json-ld 完整响应、markdown 完整响应
子码编辑记录：json 完整响应、json-ld 完整响应、markdown 完整响应

完整返回示例

以下代码块仅展示三种格式的完整响应骨架；完整大样例请使用上面的配套文件。

format=jsonformat=json-ldformat=markdown

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "json",
    "version": "v1",
    "content_type": "application/json; charset=utf-8",
    "data": {
      "record_id": 10001,
      "record_number": "REC-001",
      "record_code": "record_demo_code_001",
      "record_url": "https://example.com/records/record-demo-001",
      "submit_at": 1773056539,
      "submit_at_iso": "2026-03-09 19:42:19(UTC+08:00)",
      "submit_method": "扫一扫填写",
      "recorder": { "auth_id": 20001, "user_id": 30001, "name": "张**" },
      "project": { "id": 40001, "name": "示例园区", "number": "P001" },
      "qrcode": { "id": 50001, "name": "示例点位A", "type": 0, "type_text": "普通二维码", "template_id": 50010, "qrcode_url": "https://example.com/qrcodes/qrcode-demo-001", "number": "", "category_id": 50020 },
      "org": { "id": 60001, "name": "示例企业", "code": "org_demo_code", "logo_url": "https://example.com/assets/logo-demo.png" },
      "record_template": { "id": 70001, "name": "设备巡检示例", "type": 0, "type_text": "普通表单", "number": "TPL-001" },
      "audit": { "enabled": true, "current_stage_id": 80001, "current_stage_title": "组长审批", "status": 0, "status_text": "待审核", "auditor_name": "李**" },
      "process_status": { "enabled": true, "text": "处理中", "color": "#155EB7" },
      "state_changes": [],
      "tpl_groups": [ { "...": "完整字段结构见示例文件与 schema" } ]
    }
  }
}

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "json-ld",
    "version": "v1",
    "content_type": "application/ld+json; charset=utf-8",
    "data": {
      "@context": "https://schema.org",
      "@type": "CreativeWork",
      "identifier": "record-demo-001",
      "name": "设备巡检示例-REC-001",
      "url": "https://example.com/records/record-demo-001",
      "mainEntity": { "@type": "ItemList", "name": "组件数据" }
    }
  }
}

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "markdown",
    "version": "v1",
    "content_type": "text/markdown; charset=utf-8",
    "data": "---\ntitle: 设备巡检示例-REC-001\nrecord_id: 10001\n...\n---\n\n# 设备巡检示例-REC-001\n\n## 基本信息\n\n**记录编号：** REC-001"
  }
}

响应结构总览

路径	类型	说明
`code`	integer	平台状态码，`0` 表示成功
`message`	string	状态消息
`data`	object	统一业务包装层
`data.format`	string	实际返回格式，对应请求中的 `format`
`data.version`	string	记录内容版本号，当前固定为 `v1`
`data.content_type`	string	业务内容 MIME 类型
`data.data`	object \| string	业务内容本体，具体类型由 `data.format` 决定

统一包装层示例：

json

{
  "format": "json",
  "version": "v1",
  "content_type": "application/json; charset=utf-8",
  "data": { "...": "..." }
}

`format=json` 结构详解

format=json 时，data.data 为结构化记录对象。完整 payload schema 见 content-json-v1.schema.json，完整示例见 payload-normal.json。

记录详情对象

字段	类型	说明
`record_id`	integer	记录 ID
`record_number`	string	记录编号
`record_code`	string	记录 code，平台内唯一标识
`record_url`	string	记录访问链接
`submit_at`	integer	提交时间的 Unix 时间戳，单位秒
`submit_at_iso`	string	提交时间的格式化字符串，包含时区信息
`submit_method`	string	提交方式
`recorder`	object	提交人信息
`project`	object	所属分区信息
`qrcode`	object	所属二维码信息
`org`	object	所属企业信息
`record_template`	object	所属表单信息
`audit`	object	审核信息
`process_status`	object	处理进度信息
`state_changes`	array	触发状态变更列表
`tpl_groups`	array	记录中的分组与组件内容

关键子对象

对象	关键字段	说明
`recorder`	`auth_id`、`user_id`、`name`	提交人信息
`project`	`id`、`name`、`number`	分区信息
`qrcode`	`id`、`name`、`type`、`qrcode_url`	二维码信息
`org`	`id`、`name`、`code`、`logo_url`	企业信息
`record_template`	`id`、`name`、`type`、`number`	表单信息
`audit`	`enabled`、`current_stage_id`、`status`	审核信息
`process_status`	`enabled`、`text`、`color`	处理进度
`state_changes[]`	`state`、`from_state_option`、`to_state_option`	状态变更明细

`tpl_groups[]`

字段	类型	说明
`group_id`	integer	分组 ID
`group_title`	string	分组标题，空字符串表示无标题
`show_group_title`	boolean	是否显示分组标题
`is_page_break_group`	boolean	是否为分页标记组。该类分组的 `fields` 通常为空数组
`fields`	array	分组内的组件列表

`tpl_groups[].fields[]`

字段	类型	说明
`field_id`	integer	组件 ID
`field_title`	string	组件标题
`field_desc`	string	组件描述或提示文字
`field_type`	string	组件类型标识，决定 `field_value` 的数据格式
`field_short_name`	string	组件短名称
`group_id`	integer	所属分组 ID
`field_value`	mixed	组件值，格式随 `field_type` 变化
`options`	object	组件显示选项，含 `is_result`、`is_highlight`、`is_hidden`、`is_masked`

`field_type` 与 `field_value`

组件名称、分类和命名约定总览见：表单组件类型总览。

在 record/getRecord 中，建议接入时先读取 field_type，再按对应结构解析 field_value。本节只关注“某种组件类型会返回什么值结构”；完整映射以 content-json-v1.schema.json 为准。

分类	`field_type`	`field_value` 结构
纯文本	`name`、`tel`、`recorder`、`identity`、`job_number`、`text`、`textarea`、`date`、`time`、`customer_name`、`customer_mobile`、`customer_number`、`carnumber`	string
单选	`sex`、`radio`	object，含 `option_text`、`option_id`
数字	`number`	object，含 `value`、`unit`、`unit_enabled`
多选	`checkbox`	object，含 `values[]`
检查项	`checklist`	array，元素含 `item_id`、`item_title`、`value`
单行表格	`matrix`	object，含 `columns[]`
自增表格	`dynamic_matrix`	object，含 `rows[]`
定位	`address`	object，含 `address`、`lat`、`lng`
地址	`owner_address`	object，含 `province`、`city`、`district`、`street`、`detail`、`full_address`
多级选择	`chained_selects`	object，含 `values[]`
图片/签名	`image`、`signature`	array，元素为媒体对象
音频	`audio`	array，元素含 `url`、`size`、`duration` 等
视频	`video`	array，元素含 `url`、`size`、`duration`
文件	`file`	array，元素含 `url`、`size`、`file_name`
说明	`description`	object，含 `description_html`
OCR	`ocr_*`	object，含 `items[]` 与 `image`
子码编辑差异	`sub_qrcode_edit_diff`	array，元素含 `before_value`、`after_value`

`format=json-ld` 说明

format=json-ld 时，data.data 返回 Schema.org 风格的语义化对象。适合对接知识图谱、语义搜索或需要保留上下文语义的系统。

配套文件：

Schema：content-jsonld-v1.schema.json
普通记录 payload：payload-normal.json
子码编辑 payload：payload-child-qrcode-edit.json

`format=markdown` 说明

format=markdown 时，data.data 返回完整 Markdown 文本，适合直接展示、导出归档或交给 LLM 进行阅读类处理。

配套文件：

Schema：content-markdown-v1.schema.json
普通记录完整响应（data.data 为 Markdown 文本）：success-normal.response.json
子码编辑完整响应（同上）：success-child-qrcode-edit.response.json

Schema 与示例文件

Schema

response.schema.json：完整接口响应 schema
content-json-v1.schema.json：format=json payload schema
content-jsonld-v1.schema.json：format=json-ld payload schema
content-markdown-v1.schema.json：format=markdown payload schema

完整示例

其他字段约定

空值约定

场景	返回规则
组件未填写	`field_value` 可能返回 `null`
关联实体不存在	结构保持不变，但子字段值可能为 `null`
字符串字段无内容	通常返回空字符串 `""`
数组字段无内容	通常返回空数组 `[]`

脱敏约定

场景	说明
接口实际返回	OpenAPI 默认按企业授权返回记录内容；是否脱敏取决于业务侧授权和输出配置
文档配套示例	本文档链接到的示例文件均已做脱敏处理，仅用于结构说明和联调参考
`tpl_groups[].fields[].options.is_masked`	表示组件是否开启脱敏开关，不代表当前返回值一定已经脱敏

AI 图片审核字段

以下图片对象中可能包含可选对象 ai_audit_result：

image / signature 的 field_value[] 元素
检查项 value.images[]
OCR 的 image
子码编辑差异中的 media_items[]

字段	类型	说明
`ai_audit_result.audit_status`	integer	`0` 默认、`1` 通过、`2` 不通过、`3` 失败、`4` 待审核
`ai_audit_result.audit_status_text`	string	与 `audit_status` 对应的中文说明
`ai_audit_result.reason`	string	AI 返回的原因说明

错误响应

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

json

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

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

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

二维码

活码

表单

批量模板 & 子码

记录

成员

活码

表单与记录

安装教程

企业微信版购买

常见问题

获取单条记录

请求示例

请求参数

返回格式概览

完整返回示例

响应结构总览

`format=json` 结构详解

记录详情对象

关键子对象

`tpl_groups[]`

`tpl_groups[].fields[]`

`field_type` 与 `field_value`

`format=json-ld` 说明

`format=markdown` 说明

Schema 与示例文件

Schema

完整示例

其他字段约定

空值约定

脱敏约定

AI 图片审核字段

错误响应

获取单条记录 ​

请求示例 ​

请求参数 ​

返回格式概览 ​

完整返回示例 ​

响应结构总览 ​

format=json 结构详解 ​

记录详情对象 ​

关键子对象 ​

tpl_groups[] ​

tpl_groups[].fields[] ​

field_type 与 field_value ​

format=json-ld 说明 ​

format=markdown 说明 ​

Schema 与示例文件 ​

Schema ​

完整示例 ​

其他字段约定 ​

空值约定 ​

脱敏约定 ​

AI 图片审核字段 ​

错误响应 ​

获取单条记录

请求示例

请求参数

返回格式概览

完整返回示例

响应结构总览

`format=json` 结构详解

记录详情对象

关键子对象

`tpl_groups[]`

`tpl_groups[].fields[]`

`field_type` 与 `field_value`

`format=json-ld` 说明

`format=markdown` 说明

Schema 与示例文件

Schema

完整示例

其他字段约定

空值约定

脱敏约定

AI 图片审核字段

错误响应