获取表单结构

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

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

请求示例

Python + requestscurl

python

import requests

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

请求参数

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

完整返回示例

以下代码块仅展示成功响应的完整骨架；完整 payload 与完整 success response 请使用下面“Schema 与示例文件”章节中的配套文件。

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "version": "v1",
    "data": {
      "form": {
        "id": 122507,
        "name": "设备巡检",
        "type": 0,
        "type_text": "普通表单",
        "number": "D32",
        "description": "请仔细填写表单中的内容",
        "submit_button_title": "提交",
        "created_at_iso": "2026-02-27 10:26:42(UTC+08:00)",
        "updated_at_iso": "2026-03-09 17:13:04(UTC+08:00)"
      },
      "org": { "id": 94910252 },
      "project": { "id": 1104 },
      "groups": [
        {
          "group_id": 71399639089153,
          "group_title": "",
          "show_group_title": false,
          "is_page_break_group": false,
          "fields": [
            {
              "field_id": 71399639089153,
              "field_title": "巡检人姓名",
              "field_desc": "",
              "field_type": "name",
              "field_short_name": "",
              "group_id": 71399639089153,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            }
          ]
        }
      ],
      "audit_config": {
        "enabled": true,
        "stages": [
          { "id": 20241, "title": "组长审批", "level": 1 },
          { "id": 20242, "title": "厂长审批", "level": 2 }
        ]
      },
      "process_status_config": {
        "enabled": true,
        "options": [
          { "text": "待处理", "color": "#E64340" },
          { "text": "处理中", "color": "#155EB7" },
          { "text": "已完成", "color": "#06AE56" }
        ]
      },
      "rules": {
        "time_limit_record": [
          {
            "start_time": 1773030000,
            "end_time": 1773036000,
            "time_limit_type": 0
          }
        ],
        "tpl_limit_record": null,
        "owner_tpl_limit_record": null
      }
    }
  }
}

完整示例：

响应结构总览

路径	类型	说明
`code`	integer	平台状态码，`0` 表示成功
`message`	string	状态消息
`data`	object	统一业务包装层
`data.version`	string	内容版本号，当前固定为 `v1`
`data.data`	object	表单结构对象本体

统一包装层示例：

json

{
  "version": "v1",
  "data": { "...": "..." }
}

`data.data` 结构详解

data.data 为表单结构对象。完整 payload schema 见 content-json-v1.schema.json，完整示例见 payload-normal.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` 枚举表

常见组件类型与分类总览见：表单组件类型总览。

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

如果你更关心某类组件在记录详情里会返回什么值结构，请跳转到获取单条记录查看 field_type 与 field_value 的映射。

Schema 与示例文件

Schema

response.schema.json：完整接口响应 schema
content-json-v1.schema.json：data.data payload schema

完整示例

JSON：normal response、normal payload

其他字段约定

空值约定

场景	返回规则
可选限制规则未配置	`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	详细错误信息，可能为空字符串

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

获取表单结构 ​

请求示例 ​

请求参数 ​

完整返回示例 ​

响应结构总览 ​

data.data 结构详解 ​

顶层字段 ​

form 对象 ​

form.type 枚举 ​

org / project 对象 ​

groups[] ​

groups[] 元素字段 ​

groups[].fields[] ​

settings 通用配置 ​

settings 扩展配置 ​

日期时间类：date / time ​

数字类：number ​

选项类：sex / radio / checkbox ​

检查项：checklist ​

表格类：matrix / dynamic_matrix ​

级联选择：chained_selects ​

OCR：ocr_* ​

说明类：description ​

audit_config ​

process_status_config ​

rules ​

time_limit_record[] ​

tpl_limit_record / owner_tpl_limit_record ​

field_type 枚举表 ​

Schema 与示例文件 ​

Schema ​

完整示例 ​

其他字段约定 ​

空值约定 ​

脱敏约定 ​

错误响应 ​

获取表单结构

请求示例

请求参数

完整返回示例

响应结构总览

`data.data` 结构详解

顶层字段

`form` 对象

`form.type` 枚举

`org` / `project` 对象

`groups[]`

`groups[]` 元素字段

`groups[].fields[]`

`settings` 通用配置

`settings` 扩展配置

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

数字类：`number`

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

检查项：`checklist`

表格类：`matrix` / `dynamic_matrix`

级联选择：`chained_selects`

OCR：`ocr_*`

说明类：`description`

`audit_config`

`process_status_config`

`rules`

`time_limit_record[]`

`tpl_limit_record` / `owner_tpl_limit_record`

`field_type` 枚举表

Schema 与示例文件

Schema

完整示例

其他字段约定

空值约定

脱敏约定

错误响应