# 获取表单结构

根据表单模板 ID（`tpl_id`）获取表单的完整结构定义，便于动态渲染表单、校验字段输入、生成提交流程，或在接入侧做结构同步。

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

## 请求示例



```python [Python + requests]
import requests

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



## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tpl_id` | integer | 是 | 表单模板 ID |

## 响应结构总览

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


| 路径 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 平台状态码，`0` 表示成功 |
| `message` | string | 状态消息 |
| `data` | object | 统一业务包装层 |
| `data.data` | object | 表单结构对象本体 |

统一包装层示例：

```json
{
  "data": { "...": "..." }
}
```

## `data.data` 结构详解

`data.data` 为表单结构对象。完整 payload schema 与示例见下方折叠区域。

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


**完整示例**
<<< ./forms-get-template/examples/json/success-normal.response.json


### 顶层字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `form` | object | 表单基础信息 |
| `org` | object | 所属企业信息 |
| `project` | object | 所属分区信息 |
| `groups` | array | 分组与字段定义列表 |
| `audit_config` | object | 审批流程配置 |
| `process_status_config` | object | 处理状态配置 |
| `rules` | object | 填写规则配置 |

## `form` 对象

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 表单 ID |
| `name` | string | 表单名称 |
| `type` | integer | 表单类型编码 |
| `type_text` | string | 表单类型说明 |
| `number` | string | 表单编号 |
| `description` | string | 表单描述 |
| `submit_button_title` | string | 提交按钮文案 |
| `created_at_iso` | string | 创建时间，带时区的格式化字符串 |
| `updated_at_iso` | string | 最后更新时间，带时区的格式化字符串 |

### `form.type` 枚举

| 值 | 说明 |
| --- | --- |
| `0` | 普通表单 |
| `1` | 普通表单 |
| `2` | 普通表单 |
| `3` | 保密承诺系统表单 |
| `7` | 码状态手动变更记录系统表单 |
| `12` | 身份组成员申请加入记录表单 |
| `13` | 子码编辑记录系统表单 |
| `21` | 码留言记录系统表单 |
| `22` | 码协作记录系统表单 |

## `org` / `project` 对象

| 对象 | 字段 | 类型 | 说明 |
| --- | --- | --- | --- |
| `org` | `id` | integer | 企业 ID |
| `project` | `id` | integer | 分区 ID |

## `groups[]`

`groups` 为数组，每个元素代表一个字段分组。支持分页分组（page break）模式；分页断点组本身不承载字段，仅用于页面分隔。

### `groups[]` 元素字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `group_id` | integer | 分组 ID |
| `group_title` | string | 分组标题；无标题时为空字符串 |
| `show_group_title` | boolean | 是否显示分组标题 |
| `is_page_break_group` | boolean | 是否为分页断点组；为 `true` 时，`fields` 通常为空数组 |
| `fields` | array | 分组内字段列表 |

分页逻辑说明：

- 当 `is_page_break_group=true` 时，该分组表示分页标记。
- 紧随其后的普通分组通常承载该页的实际字段。
- 接入侧不应假定"有标题的组一定含字段"，应始终结合 `is_page_break_group` 判断。

## `groups[].fields[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `field_id` | integer | 字段 ID |
| `field_title` | string | 字段标题 |
| `field_desc` | string | 字段说明或提示文字 |
| `field_type` | string | 字段类型标识 |
| `field_short_name` | string | 字段别名/短名称 |
| `group_id` | integer | 所属分组 ID |
| `settings` | object | 字段配置对象，包含通用配置与按类型扩展配置 |

过滤规则：

- 子字段不会出现在输出中。
- 已禁用字段不会出现在输出中。
- 文档中的 `ocr_*` 为 OCR 主字段结构，不包含内部实现细节。

## `settings` 通用配置

所有字段类型都包含以下 6 个布尔配置：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `is_required` | boolean | 是否必填 |
| `is_hidden` | boolean | 是否隐藏 |
| `is_result` | boolean | 是否结果字段 |
| `is_masked` | boolean | 是否启用隐私脱敏 |
| `is_unique` | boolean | 是否开启唯一校验 |
| `is_highlight` | boolean | 是否高亮显示 |

## `settings` 扩展配置

不同 `field_type` 会在 `settings` 中追加额外配置字段。未列出的字段类型仅包含上面的 6 个通用布尔值。

### 日期时间类：`date` / `time`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `format` | string | 日期/时间格式 |
| `default_to_current` | boolean | 是否默认填入当前日期/时间 |

### 数字类：`number`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `unit` | string | 单位文字，无单位时为空字符串 |
| `unit_enabled` | boolean | 是否启用单位显示 |
| `range` | object | 数值范围限制 |
| `range.minimum` | number \| null | 最小值限制 |
| `range.maximum` | number \| null | 最大值限制 |
| `allow_negative` | boolean | 是否允许负数 |

### 选项类：`sex` / `radio` / `checkbox`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `options` | array | 选项列表 |
| `options[].option_id` | integer | 选项 ID |
| `options[].option_text` | string | 选项文本 |
| `options[].is_custom` | boolean | 是否允许自定义输入 |

### 检查项：`checklist`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `is_allow_entry_desc` | boolean | 是否允许填写备注说明 |
| `checklist_items` | array | 检查项列表 |
| `checklist_items[].item_id` | integer | 检查项 ID |
| `checklist_items[].item_title` | string | 检查项标题 |
| `checklist_result_options` | array | 结果选项列表 |
| `checklist_result_options[].option_id` | integer | 结果选项 ID |
| `checklist_result_options[].option_value` | string | 结果选项值 |
| `checklist_result_options[].option_text` | string | 结果选项文本 |

### 表格类：`matrix` / `dynamic_matrix`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `columns` | array | 列定义列表 |
| `columns[].column_id` | integer | 列 ID |
| `columns[].column_title` | string | 列标题 |
| `columns[].column_type` | string | 列类型 |
| `columns[].format` | string | 日期/时间列格式，仅部分列类型出现 |
| `columns[].options` | array | 选项列候选项，仅 `sex` / `radio` 等列类型出现 |
| `columns[].options[].option_uuid` | string | 选项 UUID |
| `columns[].options[].option_text` | string | 选项文本 |
| `columns[].options[].is_custom` | boolean | 是否允许自定义输入 |

### 级联选择：`chained_selects`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `chained_options` | array | 级联选项树 |
| `chained_options[].option_id` | integer | 选项 ID |
| `chained_options[].option_text` | string | 选项文本 |
| `chained_options[].level` | integer | 层级深度，从 `1` 开始 |
| `chained_options[].children` | array | 子选项列表，叶子节点为空数组 |

### OCR：`ocr_*`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `ocr_items` | array | OCR 识别项列表 |
| `ocr_items[].item_id` | integer | 识别项 ID |
| `ocr_items[].item_title` | string | 识别项标题 |
| `ocr_items[].unit` | string | 单位文字 |
| `ocr_items[].unit_enabled` | boolean | 是否启用单位显示 |

### 说明类：`description`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `description_html` | string | HTML 富文本说明内容 |

## `audit_config`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `enabled` | boolean | 是否启用审批流程 |
| `stages` | array | 审批阶段列表；未启用时通常为空数组 |
| `stages[].id` | integer | 审批阶段 ID |
| `stages[].title` | string | 审批阶段标题 |
| `stages[].level` | integer | 审批层级，从 `1` 开始递增 |

## `process_status_config`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `enabled` | boolean | 是否启用处理状态功能 |
| `options` | array | 处理状态选项列表 |
| `options[].text` | string | 状态文本 |
| `options[].color` | string | 状态颜色，十六进制色值 |

## `rules`

`rules` 描述表单填写限制，包含时间限制、每人填写次数限制、表单总填写次数限制三部分。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `time_limit_record` | array | 时间限制规则列表 |
| `tpl_limit_record` | object \| null | 每人填写次数限制 |
| `owner_tpl_limit_record` | object \| null | 表单总填写次数限制 |

### `time_limit_record[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `start_time` | integer \| string | 开始时间。当前示例返回 Unix 时间戳；接入时建议不要强依赖单一展示格式 |
| `end_time` | integer \| string | 结束时间。当前示例返回 Unix 时间戳；接入时建议不要强依赖单一展示格式 |
| `time_limit_type` | integer | 时间限制类型：`0` 不限制、`1` 日期时间范围、`2` 每日时间段 |

### `tpl_limit_record` / `owner_tpl_limit_record`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `limit_type` | integer | 限制类型：`0` 不限制、`1` 仅一次、`2` 自定义周期 |
| `custom_type` | integer | 周期类型：`0` 天、`1` 周、`2` 月、`3` 年 |
| `custom_limit` | integer | 周期内允许填写次数 |
| `custom_type_limit` | integer | 周期跨度值 |

## `field_type` 枚举表

常见组件类型与分类总览见：[表单组件类型总览](https://cli.im/open-api/openapi/v2/api/record/components-field-types.md)。

在 `forms/getTemplate` 中，`field_type` 的主要作用是决定该字段在 `settings` 中会带出哪些配置项。接入时建议优先按下面的配置视角理解：

| 分类 | 常见 `field_type` | 配置侧关注点 |
| --- | --- | --- |
| 文本/身份信息 | `name`、`tel`、`recorder`、`identity`、`job_number`、`text`、`textarea`、`customer_name`、`customer_mobile`、`customer_number`、`carnumber` | 通常只有通用布尔配置 |
| 选项类 | `sex`、`radio`、`checkbox` | 关注 `options[]` |
| 数值/时间类 | `number`、`date`、`time` | 关注 `unit`、`range`、`format`、`default_to_current` |
| 复合类 | `checklist`、`matrix`、`dynamic_matrix`、`chained_selects` | 关注嵌套结构，如 `checklist_items`、`columns`、`chained_options` |
| 媒体/展示/OCR | `image`、`audio`、`video`、`file`、`signature`、`description`、`ocr_*` | 关注媒体能力开关、`description_html` 或 `ocr_items` |

如果你更关心某类组件在记录详情里会返回什么值结构，请跳转到 [获取单条记录](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) 查看 `field_type` 与 `field_value` 的映射。

## 其他字段约定

### 空值约定

| 场景 | 返回规则 |
| --- | --- |
| 可选限制规则未配置 | `tpl_limit_record`、`owner_tpl_limit_record` 可能返回 `null` |
| 字符串字段无内容 | 通常返回空字符串 `""` |
| 数组字段无内容 | 通常返回空数组 `[]` |
| 范围边界未设置 | 例如 `range.minimum` / `range.maximum` 可能返回 `null` |

### 脱敏约定

| 场景 | 说明 |
| --- | --- |
| 接口实际返回 | 是否脱敏取决于企业授权与字段配置 |
| 示例文件 | 本文档链接到的示例文件已做脱敏或示例化处理，仅用于结构说明和联调参考 |
| `settings.is_masked` | 表示字段开启了脱敏开关，不代表当前看到的示例值一定来自实时接口 |

## 错误响应

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

```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)。
