# 获取单条记录

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

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

## 请求示例



```python [Python + requests]
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]
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 [format=json]
{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "json",
    "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": [],
      "trusted_notary": { "tx_hash": "a1b2c3d4...", "evidence_url": "https://example.com/notary/...", "notarized_at": 1775539953, "notarized_at_iso": "2026-04-07 13:32:33(UTC+08:00)" },
      "tpl_groups": [ { "...": "完整字段结构见示例文件与 schema" } ]
    }
  }
}
```

```json [format=json-ld]
{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "json-ld",
    "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 [format=markdown]
{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "markdown",
    "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"
  }
}
```



## 响应结构总览

**response.schema.json（完整接口响应 schema）**
<<< ./record-get-record/schema/response.schema.json


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

统一包装层示例：

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

## `format=json` 结构详解

`format=json` 时，`data.data` 为结构化记录对象。完整 payload schema 与示例见下方折叠区域。

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


:::: details 完整示例

<<< ./record-get-record/examples/json/success-normal.response.json [普通记录]
<<< ./record-get-record/examples/json/success-child-qrcode-edit.response.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 | 触发状态变更列表 |
| `trusted_notary` | object \| null | 最新区块链可信存证摘要；无存证数据时返回 `null` |
| `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` | 状态变更明细 |
| `trusted_notary` | `tx_hash`、`evidence_url`、`notarized_at`、`notarized_at_iso` | 最新区块链可信存证摘要 |

### `trusted_notary`

无存证数据时，返回 `null`。

有最新存证数据时，返回最新一条存证摘要：

```json
{
  "tx_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "evidence_url": "https://example.com/notary/2026/0407/13/evidence-demo-001.md",
  "notarized_at": 1775539953,
  "notarized_at_iso": "2026-04-07 13:32:33(UTC+08:00)"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `tx_hash` | string | 链上存证哈希 |
| `evidence_url` | string | 当前最新存证对应的源文件 URL |
| `notarized_at` | integer | 最新存证时间的 Unix 时间戳，单位秒 |
| `notarized_at_iso` | string | 最新存证时间的格式化字符串，包含时区信息 |

### `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`

组件名称、分类和命名约定总览见：[表单组件类型总览](https://cli.im/open-api/openapi/v2/api/record/components-field-types.md)。

在 `record/getRecord` 中，建议接入时先读取 `field_type`，再按对应结构解析 `field_value`。本节只关注“某种组件类型会返回什么值结构”；完整映射以 `content-json.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 风格的语义化对象。适合对接知识图谱、语义搜索或需要保留上下文语义的系统。

当记录存在区块链可信存证信息时，相关内容也会在 JSON-LD 结构中体现；该格式以语义化表达为主，固定字段名以实际返回为准。

配套文件：

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


:::: details 完整示例

<<< ./record-get-record/examples/jsonld/success-normal.response.json [普通记录]
<<< ./record-get-record/examples/jsonld/success-child-qrcode-edit.response.json [子码编辑记录]

::::

## `format=markdown` 说明

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

当记录存在区块链可信存证信息时，Markdown 文本中会体现对应存证内容，适合阅读、归档和存证源文件核验等场景。

配套文件：

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


:::: details 完整示例

<<< ./record-get-record/examples/markdown/success-normal.response.json [普通记录]
<<< ./record-get-record/examples/markdown/success-child-qrcode-edit.response.json [子码编辑记录]

::::

## 其他字段约定

### 空值约定

| 场景 | 返回规则 |
| --- | --- |
| 组件未填写 | `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 | 详细错误信息，可能为空字符串 |

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