获取表单结构

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

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

请求示例

Python + requestscurl

python

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 -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）

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "response.schema.json",
  "title": "forms/getTemplate response schema",
  "description": "`forms/getTemplate` 的完整响应结构，包含成功响应与错误响应。",
  "oneOf": [
    {
      "$ref": "#/$defs/SuccessResponse"
    },
    {
      "$ref": "#/$defs/ErrorResponse"
    }
  ],
  "$defs": {
    "SuccessResponse": {
      "type": "object",
      "required": [
        "code",
        "message",
        "data"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "const": 0
        },
        "message": {
          "type": "string"
        },
        "data": {
          "type": "object",
          "required": [
            "data"
          ],
          "properties": {
            "data": {
              "$ref": "content-json.schema.json"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "ErrorResponse": {
      "type": "object",
      "required": [
        "code",
        "error_code",
        "message",
        "message_detail"
      ],
      "properties": {
        "code": {
          "type": "integer"
        },
        "error_code": {
          "type": "integer"
        },
        "message": {
          "type": "string"
        },
        "message_detail": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  }
}

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

统一包装层示例：

json

{
  "data": { "...": "..." }
}

`data.data` 结构详解

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

content-json.schema.json（payload schema）

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "content-json.schema.json",
  "title": "forms/getTemplate content schema",
  "description": "`forms/getTemplate` 在 `data.data` 下返回的表单结构对象定义。",
  "type": "object",
  "required": [
    "form",
    "org",
    "project",
    "groups",
    "audit_config",
    "process_status_config",
    "rules"
  ],
  "properties": {
    "form": {
      "$ref": "#/$defs/Form"
    },
    "org": {
      "$ref": "#/$defs/IdObject"
    },
    "project": {
      "$ref": "#/$defs/IdObject"
    },
    "groups": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Group"
      }
    },
    "audit_config": {
      "$ref": "#/$defs/AuditConfig"
    },
    "process_status_config": {
      "$ref": "#/$defs/ProcessStatusConfig"
    },
    "rules": {
      "$ref": "#/$defs/Rules"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "IdObject": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "integer"
        }
      },
      "additionalProperties": false
    },
    "Form": {
      "type": "object",
      "required": [
        "id",
        "name",
        "type",
        "type_text",
        "number",
        "description",
        "submit_button_title",
        "created_at_iso",
        "updated_at_iso"
      ],
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "type": {
          "type": "integer",
          "enum": [
            0,
            1,
            2,
            3,
            7,
            12,
            13,
            21,
            22
          ]
        },
        "type_text": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "submit_button_title": {
          "type": "string"
        },
        "created_at_iso": {
          "type": "string"
        },
        "updated_at_iso": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "Group": {
      "type": "object",
      "required": [
        "group_id",
        "group_title",
        "show_group_title",
        "is_page_break_group",
        "fields"
      ],
      "properties": {
        "group_id": {
          "type": "integer"
        },
        "group_title": {
          "type": "string"
        },
        "show_group_title": {
          "type": "boolean"
        },
        "is_page_break_group": {
          "type": "boolean"
        },
        "fields": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Field"
          }
        }
      },
      "additionalProperties": false
    },
    "Field": {
      "type": "object",
      "required": [
        "field_id",
        "field_title",
        "field_desc",
        "field_type",
        "field_short_name",
        "group_id",
        "settings"
      ],
      "properties": {
        "field_id": {
          "type": "integer"
        },
        "field_title": {
          "type": "string"
        },
        "field_desc": {
          "type": "string"
        },
        "field_type": {
          "type": "string",
          "description": "字段类型。固定类型使用枚举；OCR 类字段统一匹配 `ocr_*`。",
          "anyOf": [
            {
              "enum": [
                "name",
                "tel",
                "recorder",
                "identity",
                "job_number",
                "sex",
                "radio",
                "checkbox",
                "text",
                "textarea",
                "number",
                "date",
                "time",
                "checklist",
                "matrix",
                "dynamic_matrix",
                "chained_selects",
                "address",
                "owner_address",
                "customer_name",
                "customer_mobile",
                "customer_number",
                "carnumber",
                "signature",
                "image",
                "audio",
                "video",
                "file",
                "description"
              ]
            },
            {
              "pattern": "^ocr_"
            }
          ]
        },
        "field_short_name": {
          "type": "string"
        },
        "group_id": {
          "type": "integer"
        },
        "settings": {
          "$ref": "#/$defs/FieldSettings"
        }
      },
      "additionalProperties": false
    },
    "FieldSettings": {
      "type": "object",
      "required": [
        "is_required",
        "is_hidden",
        "is_result",
        "is_masked",
        "is_unique",
        "is_highlight"
      ],
      "properties": {
        "is_required": {
          "type": "boolean"
        },
        "is_hidden": {
          "type": "boolean"
        },
        "is_result": {
          "type": "boolean"
        },
        "is_masked": {
          "type": "boolean"
        },
        "is_unique": {
          "type": "boolean"
        },
        "is_highlight": {
          "type": "boolean"
        },
        "format": {
          "type": "string"
        },
        "default_to_current": {
          "type": "boolean"
        },
        "unit": {
          "type": "string"
        },
        "unit_enabled": {
          "type": "boolean"
        },
        "range": {
          "$ref": "#/$defs/NumberRange"
        },
        "allow_negative": {
          "type": "boolean"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OptionItem"
          }
        },
        "is_allow_entry_desc": {
          "type": "boolean"
        },
        "checklist_items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChecklistItem"
          }
        },
        "checklist_result_options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChecklistResultOption"
          }
        },
        "columns": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/MatrixColumn"
          }
        },
        "chained_options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChainedOption"
          }
        },
        "ocr_items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OcrItem"
          }
        },
        "description_html": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "NumberRange": {
      "type": "object",
      "required": [
        "minimum",
        "maximum"
      ],
      "properties": {
        "minimum": {
          "type": [
            "number",
            "null"
          ]
        },
        "maximum": {
          "type": [
            "number",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "OptionItem": {
      "type": "object",
      "required": [
        "option_text",
        "is_custom"
      ],
      "properties": {
        "option_id": {
          "type": "integer"
        },
        "option_uuid": {
          "type": "string"
        },
        "option_text": {
          "type": "string"
        },
        "is_custom": {
          "type": "boolean"
        }
      },
      "additionalProperties": false,
      "anyOf": [
        {
          "required": [
            "option_id"
          ]
        },
        {
          "required": [
            "option_uuid"
          ]
        }
      ]
    },
    "ChecklistItem": {
      "type": "object",
      "required": [
        "item_id",
        "item_title"
      ],
      "properties": {
        "item_id": {
          "type": "integer"
        },
        "item_title": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "ChecklistResultOption": {
      "type": "object",
      "required": [
        "option_id",
        "option_value",
        "option_text"
      ],
      "properties": {
        "option_id": {
          "type": "integer"
        },
        "option_value": {
          "type": "string"
        },
        "option_text": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "MatrixColumn": {
      "type": "object",
      "required": [
        "column_id",
        "column_title",
        "column_type"
      ],
      "properties": {
        "column_id": {
          "type": "integer"
        },
        "column_title": {
          "type": "string"
        },
        "column_type": {
          "type": "string"
        },
        "format": {
          "type": "string"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OptionItem"
          }
        }
      },
      "additionalProperties": false
    },
    "ChainedOption": {
      "type": "object",
      "required": [
        "option_id",
        "option_text",
        "level",
        "children"
      ],
      "properties": {
        "option_id": {
          "type": "integer"
        },
        "option_text": {
          "type": "string"
        },
        "level": {
          "type": "integer"
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChainedOption"
          }
        }
      },
      "additionalProperties": false
    },
    "OcrItem": {
      "type": "object",
      "required": [
        "item_id",
        "item_title",
        "unit",
        "unit_enabled"
      ],
      "properties": {
        "item_id": {
          "type": "integer"
        },
        "item_title": {
          "type": "string"
        },
        "unit": {
          "type": "string"
        },
        "unit_enabled": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "AuditConfig": {
      "type": "object",
      "required": [
        "enabled",
        "stages"
      ],
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "stages": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AuditStage"
          }
        }
      },
      "additionalProperties": false
    },
    "AuditStage": {
      "type": "object",
      "required": [
        "id",
        "title",
        "level"
      ],
      "properties": {
        "id": {
          "type": "integer"
        },
        "title": {
          "type": "string"
        },
        "level": {
          "type": "integer"
        }
      },
      "additionalProperties": false
    },
    "ProcessStatusConfig": {
      "type": "object",
      "required": [
        "enabled",
        "options"
      ],
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ProcessStatusOption"
          }
        }
      },
      "additionalProperties": false
    },
    "ProcessStatusOption": {
      "type": "object",
      "required": [
        "text",
        "color"
      ],
      "properties": {
        "text": {
          "type": "string"
        },
        "color": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "Rules": {
      "type": "object",
      "required": [
        "time_limit_record",
        "tpl_limit_record",
        "owner_tpl_limit_record"
      ],
      "properties": {
        "time_limit_record": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/TimeLimitItem"
          }
        },
        "tpl_limit_record": {
          "type": [
            "object",
            "null"
          ],
          "allOf": [
            {
              "if": {
                "type": "object"
              },
              "then": {
                "$ref": "#/$defs/RecordLimit"
              }
            }
          ]
        },
        "owner_tpl_limit_record": {
          "type": [
            "object",
            "null"
          ],
          "allOf": [
            {
              "if": {
                "type": "object"
              },
              "then": {
                "$ref": "#/$defs/RecordLimit"
              }
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "TimeLimitItem": {
      "type": "object",
      "required": [
        "start_time",
        "end_time",
        "time_limit_type"
      ],
      "properties": {
        "start_time": {
          "type": [
            "integer",
            "string"
          ]
        },
        "end_time": {
          "type": [
            "integer",
            "string"
          ]
        },
        "time_limit_type": {
          "type": "integer",
          "enum": [
            0,
            1,
            2
          ]
        }
      },
      "additionalProperties": false
    },
    "RecordLimit": {
      "type": "object",
      "required": [
        "limit_type",
        "custom_type",
        "custom_limit",
        "custom_type_limit"
      ],
      "properties": {
        "limit_type": {
          "type": "integer",
          "enum": [
            0,
            1,
            2
          ]
        },
        "custom_type": {
          "type": "integer",
          "enum": [
            0,
            1,
            2,
            3
          ]
        },
        "custom_limit": {
          "type": "integer"
        },
        "custom_type_limit": {
          "type": "integer"
        }
      },
      "additionalProperties": false
    }
  }
}

完整示例

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "data": {
      "form": {
        "id": 10001,
        "name": "日常记录",
        "type": 0,
        "type_text": "普通表单",
        "number": "D100",
        "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
              }
            },
            {
              "field_id": 71399639089154,
              "field_title": "巡检人手机号",
              "field_desc": "",
              "field_type": "tel",
              "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
              }
            },
            {
              "field_id": 71399639089155,
              "field_title": "巡检人微信名",
              "field_desc": "",
              "field_type": "recorder",
              "field_short_name": "",
              "group_id": 71399639089153,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089156,
              "field_title": "巡检人身份证号",
              "field_desc": "",
              "field_type": "identity",
              "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
              }
            },
            {
              "field_id": 71399639089157,
              "field_title": "巡检人工号",
              "field_desc": "",
              "field_type": "job_number",
              "field_short_name": "",
              "group_id": 71399639089153,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089158,
              "field_title": "巡检人性别",
              "field_desc": "",
              "field_type": "sex",
              "field_short_name": "",
              "group_id": 71399639089153,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "options": [
                  {
                    "option_id": 71399639089192,
                    "option_text": "男",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089193,
                    "option_text": "女",
                    "is_custom": false
                  }
                ]
              }
            }
          ]
        },
        {
          "group_id": 71399639089154,
          "group_title": "巡检人基本信息",
          "show_group_title": true,
          "is_page_break_group": true,
          "fields": []
        },
        {
          "group_id": 72331175133185,
          "group_title": "",
          "show_group_title": false,
          "is_page_break_group": false,
          "fields": [
            {
              "field_id": 71399639089159,
              "field_title": "巡检内容",
              "field_desc": "",
              "field_type": "text",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089160,
              "field_title": "巡检描述",
              "field_desc": "",
              "field_type": "textarea",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089161,
              "field_title": "当前温度",
              "field_desc": "",
              "field_type": "number",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false,
                "unit": "摄氏度",
                "unit_enabled": true,
                "range": {
                  "minimum": -100,
                  "maximum": 200
                },
                "allow_negative": true
              }
            },
            {
              "field_id": 71399639089162,
              "field_title": "巡检次数",
              "field_desc": "",
              "field_type": "number",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false,
                "unit": "",
                "unit_enabled": false,
                "range": {
                  "minimum": null,
                  "maximum": null
                },
                "allow_negative": false
              }
            },
            {
              "field_id": 71399639089163,
              "field_title": "灭火器检查",
              "field_desc": "",
              "field_type": "checklist",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "is_allow_entry_desc": true,
                "checklist_items": [
                  {
                    "item_id": 71399639089266,
                    "item_title": "压力正常"
                  },
                  {
                    "item_id": 71399639089267,
                    "item_title": "外观完好"
                  },
                  {
                    "item_id": 71399639089268,
                    "item_title": "配件齐全"
                  }
                ],
                "checklist_result_options": [
                  {
                    "option_id": 71399639089271,
                    "option_value": "1",
                    "option_text": "正常"
                  },
                  {
                    "option_id": 71399639089272,
                    "option_value": "2",
                    "option_text": "异常"
                  },
                  {
                    "option_id": 71399639089273,
                    "option_value": "3",
                    "option_text": "需要关注"
                  }
                ]
              }
            },
            {
              "field_id": 71399639089164,
              "field_title": "同行人信息",
              "field_desc": "",
              "field_type": "matrix",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false,
                "columns": [
                  {
                    "column_id": 71399639089283,
                    "column_title": "姓名",
                    "column_type": "text"
                  },
                  {
                    "column_id": 71399639089284,
                    "column_title": "手机号",
                    "column_type": "text"
                  },
                  {
                    "column_id": 71399639089285,
                    "column_title": "性别",
                    "column_type": "sex",
                    "options": [
                      {
                        "option_uuid": "25587b8b-485d-4038-a5ab-9bcd7c4af880",
                        "option_text": "男",
                        "is_custom": false
                      },
                      {
                        "option_uuid": "6d190f28-bb05-41c8-aa0f-57553227f0cd",
                        "option_text": "女",
                        "is_custom": false
                      }
                    ]
                  },
                  {
                    "column_id": 71399639089286,
                    "column_title": "身份证",
                    "column_type": "identity"
                  },
                  {
                    "column_id": 71399639089287,
                    "column_title": "年龄",
                    "column_type": "number"
                  },
                  {
                    "column_id": 72326603341946,
                    "column_title": "婚姻状况",
                    "column_type": "radio",
                    "options": [
                      {
                        "option_uuid": "33ac08a2-4d8e-4b9b-885f-378fbb3535dc",
                        "option_text": "已婚",
                        "is_custom": false
                      },
                      {
                        "option_uuid": "f99e79e7-948b-4c18-8bc0-3785c6a778fa",
                        "option_text": "未婚",
                        "is_custom": false
                      },
                      {
                        "option_uuid": "bae11104-9131-43b6-89e8-9bfaebc92450",
                        "option_text": "其他",
                        "is_custom": true
                      }
                    ]
                  }
                ]
              }
            },
            {
              "field_id": 71399639089165,
              "field_title": "检查具体内容项",
              "field_desc": "",
              "field_type": "dynamic_matrix",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false,
                "columns": [
                  {
                    "column_id": 71399639089294,
                    "column_title": "物品名称",
                    "column_type": "text"
                  },
                  {
                    "column_id": 71399639089295,
                    "column_title": "物品厂家地址",
                    "column_type": "owner_address"
                  },
                  {
                    "column_id": 71399639089296,
                    "column_title": "生成日期",
                    "column_type": "date",
                    "format": "YYYY年M月D日"
                  },
                  {
                    "column_id": 72326603341957,
                    "column_title": "单位",
                    "column_type": "radio",
                    "options": [
                      {
                        "option_uuid": "329f1af8-f849-4aee-93fa-974a1bbfb704",
                        "option_text": "个",
                        "is_custom": false
                      },
                      {
                        "option_uuid": "b145e3df-9bef-4690-afe9-f0bae872b5ad",
                        "option_text": "箱",
                        "is_custom": false
                      },
                      {
                        "option_uuid": "87936ac7-fb80-472f-ad4b-1c5ff6a71b8b",
                        "option_text": "其他",
                        "is_custom": true
                      }
                    ]
                  }
                ]
              }
            },
            {
              "field_id": 71399639089166,
              "field_title": "巡检日期",
              "field_desc": "",
              "field_type": "date",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "format": "YYYY年M月D日 HH时mm分",
                "default_to_current": true
              }
            },
            {
              "field_id": 71399639089167,
              "field_title": "巡检时间",
              "field_desc": "",
              "field_type": "time",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "format": "YYYY-MM-DD HH:mm",
                "default_to_current": true
              }
            },
            {
              "field_id": 72331175133185,
              "field_title": "是否需要报销",
              "field_desc": "",
              "field_type": "radio",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "options": [
                  {
                    "option_id": 72331175133356,
                    "option_text": "需要",
                    "is_custom": false
                  },
                  {
                    "option_id": 72331175133357,
                    "option_text": "不需要",
                    "is_custom": false
                  }
                ]
              }
            },
            {
              "field_id": 71399639089168,
              "field_title": "设备情况",
              "field_desc": "",
              "field_type": "radio",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": true,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": true,
                "options": [
                  {
                    "option_id": 71399639089335,
                    "option_text": "正常",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089336,
                    "option_text": "异常",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089337,
                    "option_text": "其他",
                    "is_custom": true
                  }
                ]
              }
            },
            {
              "field_id": 71399639089169,
              "field_title": "环境情况",
              "field_desc": "",
              "field_type": "radio",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "options": [
                  {
                    "option_id": 71399639089348,
                    "option_text": "正常",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089349,
                    "option_text": "异常",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089350,
                    "option_text": "其他",
                    "is_custom": true
                  }
                ]
              }
            },
            {
              "field_id": 71399639089170,
              "field_title": "消耗工具",
              "field_desc": "",
              "field_type": "checkbox",
              "field_short_name": "",
              "group_id": 72331175133185,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "options": [
                  {
                    "option_id": 71399639089361,
                    "option_text": "螺丝刀",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089362,
                    "option_text": "扳手",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089363,
                    "option_text": "万用表",
                    "is_custom": false
                  },
                  {
                    "option_id": 71399639089369,
                    "option_text": "其他",
                    "is_custom": true
                  }
                ]
              }
            }
          ]
        },
        {
          "group_id": 71399639089156,
          "group_title": "巡检内容",
          "show_group_title": true,
          "is_page_break_group": true,
          "fields": []
        },
        {
          "group_id": 72331175133186,
          "group_title": "",
          "show_group_title": false,
          "is_page_break_group": false,
          "fields": [
            {
              "field_id": 71399639089171,
              "field_title": "负责人姓名",
              "field_desc": "",
              "field_type": "customer_name",
              "field_short_name": "",
              "group_id": 72331175133186,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089172,
              "field_title": "负责人手机号",
              "field_desc": "",
              "field_type": "customer_mobile",
              "field_short_name": "",
              "group_id": 72331175133186,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089173,
              "field_title": "设备定位",
              "field_desc": "",
              "field_type": "address",
              "field_short_name": "",
              "group_id": 72331175133186,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089174,
              "field_title": "安装地址",
              "field_desc": "",
              "field_type": "owner_address",
              "field_short_name": "",
              "group_id": 72331175133186,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089175,
              "field_title": "运输车辆车牌",
              "field_desc": "",
              "field_type": "carnumber",
              "field_short_name": "",
              "group_id": 72331175133186,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089176,
              "field_title": "负责人手写签名",
              "field_desc": "",
              "field_type": "signature",
              "field_short_name": "",
              "group_id": 72331175133186,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089177,
              "field_title": "培训学校",
              "field_desc": "",
              "field_type": "chained_selects",
              "field_short_name": "",
              "group_id": 72331175133186,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "chained_options": [
                  {
                    "option_id": 71399639089433,
                    "option_text": "浙江省",
                    "level": 1,
                    "children": [
                      {
                        "option_id": 71399639089443,
                        "option_text": "杭州市",
                        "level": 2,
                        "children": [
                          {
                            "option_id": 71399639089447,
                            "option_text": "下城区",
                            "level": 3,
                            "children": [
                              {
                                "option_id": 71399639089448,
                                "option_text": "学校1",
                                "level": 4,
                                "children": []
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "option_id": 71399639089453,
                    "option_text": "江苏省",
                    "level": 1,
                    "children": [
                      {
                        "option_id": 71399639089454,
                        "option_text": "南京市",
                        "level": 2,
                        "children": [
                          {
                            "option_id": 71399639089455,
                            "option_text": "鼓楼区",
                            "level": 3,
                            "children": [
                              {
                                "option_id": 71399639089456,
                                "option_text": "学校1",
                                "level": 4,
                                "children": []
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          ]
        },
        {
          "group_id": 71399639089158,
          "group_title": "负责人信息",
          "show_group_title": true,
          "is_page_break_group": true,
          "fields": []
        },
        {
          "group_id": 72331175133187,
          "group_title": "",
          "show_group_title": false,
          "is_page_break_group": false,
          "fields": [
            {
              "field_id": 71399639089178,
              "field_title": "补充图片",
              "field_desc": "",
              "field_type": "image",
              "field_short_name": "",
              "group_id": 72331175133187,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089179,
              "field_title": "补充录音",
              "field_desc": "",
              "field_type": "audio",
              "field_short_name": "",
              "group_id": 72331175133187,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089180,
              "field_title": "补充文件",
              "field_desc": "",
              "field_type": "file",
              "field_short_name": "",
              "group_id": 72331175133187,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            },
            {
              "field_id": 71399639089181,
              "field_title": "补充视频",
              "field_desc": "",
              "field_type": "video",
              "field_short_name": "",
              "group_id": 72331175133187,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            }
          ]
        },
        {
          "group_id": 71399639089160,
          "group_title": "其他补充材料",
          "show_group_title": true,
          "is_page_break_group": true,
          "fields": []
        },
        {
          "group_id": 72331175133188,
          "group_title": "",
          "show_group_title": false,
          "is_page_break_group": false,
          "fields": [
            {
              "field_id": 71399639089182,
              "field_title": "填表时请注意以下说明",
              "field_desc": "",
              "field_type": "description",
              "field_short_name": "",
              "group_id": 72331175133188,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "description_html": "<p><span style=\"font-size: 14px;\">设备巡检示例说明：本文档中的返回示例已做脱敏处理，用于演示说明和结构校验。</span></p>"
              }
            },
            {
              "field_id": 71399639089183,
              "field_title": "卖家身份证信息",
              "field_desc": "请正面拍摄身份证，要求内容清晰完整，方便AI识别",
              "field_type": "ocr_id_card",
              "field_short_name": "",
              "group_id": 72331175133188,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false,
                "ocr_items": [
                  {
                    "item_id": 71399639089533,
                    "item_title": "身份证号",
                    "unit": "",
                    "unit_enabled": false
                  },
                  {
                    "item_id": 71399639089534,
                    "item_title": "姓名",
                    "unit": "",
                    "unit_enabled": false
                  },
                  {
                    "item_id": 71399639089538,
                    "item_title": "地址",
                    "unit": "",
                    "unit_enabled": false
                  }
                ]
              }
            }
          ]
        },
        {
          "group_id": 71399639089162,
          "group_title": "操作说明",
          "show_group_title": true,
          "is_page_break_group": true,
          "fields": []
        },
        {
          "group_id": 72331175133189,
          "group_title": "",
          "show_group_title": false,
          "is_page_break_group": false,
          "fields": [
            {
              "field_id": 71399639089184,
              "field_title": "营业执照信息",
              "field_desc": "请正面拍摄营业执照，要求内容清晰完整，方便AI识别",
              "field_type": "ocr_business_license",
              "field_short_name": "",
              "group_id": 72331175133189,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": true,
                "is_unique": false,
                "is_highlight": false,
                "ocr_items": [
                  {
                    "item_id": 71399639089549,
                    "item_title": "统一社会信用代码",
                    "unit": "",
                    "unit_enabled": false
                  },
                  {
                    "item_id": 71399639089550,
                    "item_title": "企业名称",
                    "unit": "",
                    "unit_enabled": false
                  },
                  {
                    "item_id": 71399639089553,
                    "item_title": "法人/负责人",
                    "unit": "",
                    "unit_enabled": false
                  }
                ]
              }
            },
            {
              "field_id": 71399639089185,
              "field_title": "电表读数",
              "field_desc": "请正面拍摄电表，要求内容清晰完整，方便AI识别",
              "field_type": "ocr_electric_meter",
              "field_short_name": "",
              "group_id": 72331175133189,
              "settings": {
                "is_required": false,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false,
                "ocr_items": [
                  {
                    "item_id": 71399639089571,
                    "item_title": "度数",
                    "unit": "度",
                    "unit_enabled": true
                  }
                ]
              }
            },
            {
              "field_id": 71399639089186,
              "field_title": "产品编号",
              "field_desc": "",
              "field_type": "customer_number",
              "field_short_name": "",
              "group_id": 72331175133189,
              "settings": {
                "is_required": true,
                "is_hidden": false,
                "is_result": false,
                "is_masked": false,
                "is_unique": false,
                "is_highlight": false
              }
            }
          ]
        },
        {
          "group_id": 71399639089164,
          "group_title": "其他信息",
          "show_group_title": true,
          "is_page_break_group": true,
          "fields": []
        }
      ],
      "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"
          },
          {
            "text": "无需处理",
            "color": "#666"
          },
          {
            "text": "暂无处理进度",
            "color": "#999"
          }
        ]
      },
      "rules": {
        "time_limit_record": [
          {
            "start_time": 1773030000,
            "end_time": 1773036000,
            "time_limit_type": 0
          }
        ],
        "tpl_limit_record": null,
        "owner_tpl_limit_record": null
      }
    }
  }
}

顶层字段

字段	类型	说明
`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 的映射。

其他字段约定

空值约定

场景	返回规则
可选限制规则未配置	`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 枚举表 ​

其他字段约定 ​

空值约定 ​

脱敏约定 ​

错误响应 ​

获取表单结构

请求示例

请求参数

响应结构总览

`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` 枚举表

其他字段约定

空值约定

脱敏约定

错误响应