添加记录

向指定 code_id + tpl_id 下提交一条填写记录。

本文档聚焦“如何构造请求体”。如果你需要先知道有哪些字段可填、每个字段的 field_id / option_id / 列 ID / 检查项 ID 是什么，请先调用 获取表单结构。

请求示例

Python + requestscurl

python

import requests

url = 'https://open.cli.im/api/v2/rpc/record/addRecord'
data = {
    'code_id': 6762875,
    'tpl_id': 122507,
    'fields': [
        { 'field_id': 71399639089153, 'field_type': 'name', 'field_value': '张三' },
        { 'field_id': 71399639089154, 'field_type': 'tel', 'field_value': '13800138000' },
        { 'field_id': 71399639089158, 'field_type': 'sex', 'field_value': { 'option_id': 71399639089192 } },
        { 'field_id': 71399639089161, 'field_type': 'number', 'field_value': { 'value': 30.6 } },
        { 'field_id': 71399639089170, 'field_type': 'checkbox', 'field_value': {
            'values': [
                { 'option_id': 71399639089361 },
                { 'option_id': 71399639089369, 'custom_text': '电线杆子' }
            ]
        } }
    ]
}
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/addRecord' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"code_id":6762875,"tpl_id":122507,"fields":[{"field_id":71399639089153,"field_type":"name","field_value":"张三"},{"field_id":71399639089158,"field_type":"sex","field_value":{"option_id":71399639089192}}]}'

请求参数

参数	类型	必填	说明
`code_id`	integer	是	二维码 ID
`tpl_id`	integer	是	表单模板 ID
`fields`	array	是	要提交的字段值列表；每一项对应一个组件，详见下方 `fields[]` 结构

`fields[]` 元素结构

字段	类型	必填	说明
`field_id`	integer	是	组件 ID，对应表单结构中的字段 ID
`field_type`	string	是	组件类型，如 `name`、`radio`、`checkbox`、`matrix`
`field_value`	string \| object \| array	是	组件值，结构由 `field_type` 决定

补充说明：

field_id、option_id、item_id、column_id 等结构化 ID，应从 获取表单结构 返回结果中获取。
外部接口只需要传 code_id、tpl_id、fields。

`field_value` 输入格式

输入格式速查

类型分类	`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`
数字类	`number`	`object`
多选类	`checkbox`	`object`
复合类	`checklist`	`array`
复合类	`matrix`、`dynamic_matrix`、`chained_selects`	`object`
地址类	`address`、`owner_address`	`object`
OCR 类	`ocr_*`	`object`

文本 / 时间类

适用 field_type：

name
tel
recorder
identity
job_number
text
textarea
date
time
customer_name
customer_mobile
customer_number
carnumber

field_value 直接传字符串：

json

{
  "field_id": 71399639089153,
  "field_type": "name",
  "field_value": "张三"
}

时间格式建议：

date：2026-03-09 或 2026-03-09 17:24
time：2026-03-09 17:24

单选类

适用 field_type：

sex
radio

普通选项：

json

{
  "field_id": 71399639089158,
  "field_type": "sex",
  "field_value": {
    "option_id": 71399639089192
  }
}

“其他”选项可额外传 custom_text：

json

{
  "field_id": 71399639089168,
  "field_type": "radio",
  "field_value": {
    "option_id": 71399639089337,
    "custom_text": "一点小问题"
  }
}

字段	类型	必填	说明
`option_id`	integer	是	选项 ID
`custom_text`	string	否	“其他”选项的补充文本

数字类

适用 field_type：

number

json

{
  "field_id": 71399639089161,
  "field_type": "number",
  "field_value": {
    "value": 30.6
  }
}

字段	类型	必填	说明
`value`	number	是	数值内容

多选类

适用 field_type：

checkbox

json

{
  "field_id": 71399639089170,
  "field_type": "checkbox",
  "field_value": {
    "values": [
      { "option_id": 71399639089361 },
      { "option_id": 71399639089369, "custom_text": "电线杆子" }
    ]
  }
}

字段	类型	必填	说明
`values`	array	是	已选项列表
`values[].option_id`	integer	是	选项 ID
`values[].custom_text`	string	否	“其他”选项的补充文本

检查项

适用 field_type：

checklist

json

{
  "field_id": 71399639089163,
  "field_type": "checklist",
  "field_value": [
    {
      "item_id": 71399639089266,
      "value": { "option_value": "1" }
    },
    {
      "item_id": 71399639089267,
      "value": {
        "option_value": "2",
        "description": "生锈了，需要注意"
      }
    }
  ]
}

字段	类型	必填	说明
`item_id`	integer	是	检查项 ID
`value.option_value`	string	是	检查结果值
`value.description`	string	否	补充描述

option_value 的实际枚举含义应以表单结构配置为准。当前 V2 不支持在 checklist 中提交图片等静态资源内容。

表格

适用 field_type：

matrix

json

{
  "field_id": 71399639089164,
  "field_type": "matrix",
  "field_value": {
    "columns": [
      {
        "column_id": 71399639089283,
        "column_type": "text",
        "value": { "text": "黄金龙" }
      },
      {
        "column_id": 71399639089285,
        "column_type": "sex",
        "value": {
          "text": "男",
          "option_uuid": "25587b8b-485d-4038-a5ab-9bcd7c4af880"
        }
      }
    ]
  }
}

字段	类型	必填	说明
`columns`	array	是	列值列表
`columns[].column_id`	integer	是	列 ID
`columns[].column_type`	string	是	列类型
`columns[].value`	object	是	列值对象，结构随列类型而变化

当列为地址类时，columns[].value 可能包含 address_detail 等子结构；列定义和可用类型应以 获取表单结构 为准。

自增表格

适用 field_type：

dynamic_matrix

json

{
  "field_id": 71399639089165,
  "field_type": "dynamic_matrix",
  "field_value": {
    "rows": [
      {
        "columns": [
          {
            "column_id": 71399639089294,
            "column_type": "text",
            "value": { "text": "螺丝" }
          }
        ]
      }
    ]
  }
}

字段	类型	必填	说明
`rows`	array	是	行列表
`rows[].columns`	array	是	每行的列值列表，元素结构与 `matrix.columns[]` 一致

地址类

适用 field_type：

address
owner_address

定位地址：

json

{
  "field_id": 71399639089173,
  "field_type": "address",
  "field_value": {
    "address": "浙江省宁波市海曙区启文路157弄",
    "lat": 29.856985405815973,
    "lng": 121.53253689236111
  }
}

手动地址：

json

{
  "field_id": 71399639089174,
  "field_type": "owner_address",
  "field_value": {
    "province": "浙江省",
    "city": "宁波市",
    "district": "海曙区",
    "street": "南门街道",
    "detail": "海曙区甬水桥科创中心(启文路157弄北150米)"
  }
}

address 字段：

字段	类型	必填	说明
`address`	string	是	地址文本
`lat`	number	是	纬度
`lng`	number	是	经度

owner_address 字段：

字段	类型	必填	说明
`province`	string	是	省份
`city`	string	是	城市
`district`	string	是	区 / 县
`street`	string	否	街道 / 乡镇
`detail`	string	否	详细地址

级联选择

适用 field_type：

chained_selects

json

{
  "field_id": 71399639089177,
  "field_type": "chained_selects",
  "field_value": {
    "values": [
      { "option_id": 71399639089433 },
      { "option_id": 71399639089443 },
      { "option_id": 71399639089447 }
    ]
  }
}

字段	类型	必填	说明
`values`	array	是	各级选项列表，按层级顺序排列
`values[].option_id`	integer	是	选项 ID

OCR 类

适用 field_type：

ocr_id_card
ocr_business_license
ocr_electric_meter
其他 ocr_*

json

{
  "field_id": 71399639089185,
  "field_type": "ocr_electric_meter",
  "field_value": {
    "items": [
      {
        "item_id": 71399639089571,
        "key": "度数",
        "value": "10890.1"
      }
    ]
  }
}

字段	类型	必填	说明
`items`	array	是	OCR 识别项列表
`items[].item_id`	integer	是	识别项 ID
`items[].key`	string	否	识别项键名
`items[].value`	string	是	识别结果文本

OCR 类在 V2 中仅建议写入识别后的文本结果；当前不支持随请求提交 OCR 源图片等静态资源内容。

当前不支持提交的内容

静态资源类组件

当前 V2 暂不支持提交以下静态资源类组件内容：

image
signature
audio
video
file

当前 V2 不支持通过 API 提交这些组件内容。即使这些组件在表单配置中被设为必填，API 来源请求也不会因此受到组件必填规则拦截；是否接受对应字段为空，应由接入方按业务自行判断。

非业务值组件

以下类型不用于提交业务采集值：

description

与表单必填配置的关系

通过 OpenAPI addRecord 提交的记录属于 API 来源写入，不按表单编辑器中组件的“必填”配置校验是否传入对应的 fields[] 项。

补充说明：

获取表单结构 返回的 is_required，主要用于前端填写、扫码填写等交互场景的展示与校验语义。
接入方可以读取 is_required 做本地校验或提示，但不要假定 OpenAPI 会因为未传某个表单必填组件而直接拒绝请求。

显隐规则说明

通过 API 添加记录时，表单配置中的显隐规则不生效。

补充说明：

显隐规则主要用于表单前端交互展示，不作为 OpenAPI 写入时的服务端字段裁剪规则。
请求中是否提交某个字段，应由调用方自行根据业务逻辑决定；不要假定平台会按显隐规则自动忽略未显示字段。
如果需要了解显隐规则的产品侧功能说明，可参考帮助中心：设置显隐规则。

Excel 批量新增边界说明

当前 OpenAPI V2 未提供官方的 Excel 上传、Excel 导入或批量新增记录接口。

如果需要基于 Excel 批量新增记录，建议由接入方或 skill 在本地完成以下步骤：

先调用 获取表单结构，获取 field_id、option_id、item_id、column_id 等结构化 ID。
解析 Excel，每一行映射为一次 fields[] 输入。
按行逐次调用本接口提交记录。
汇总每条记录的成功或失败结果，并按需重试可恢复错误。

补充说明：

该方案本质上是多次单条提交，不是原子批处理；部分成功、部分失败属于正常结果，需要调用方自行汇总处理。
批量提交前，建议先校验目标表单中是否包含当前 V2 不支持提交的静态资源类字段；这些字段无法通过 API 填充，是否适合导入应由业务侧根据是否允许留空自行判断，而不是按表单中的组件必填配置判断。
业务错误码应按条处理；例如请求参数错误、字段值格式不合法、当前二维码状态不允许提交等场景，不建议直接盲目重试。

成功响应示例

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "version": "v1",
    "record_id": 2644408,
    "record_number": "L136",
    "record_code": "r06mEwjF7vqSvXpfTbrF781",
    "record_url": "https://qr46.cn/oEuE2E/r06mEwjF7vqSvXpfTbrF781",
    "submit_at": 1773056540,
    "submit_at_iso": "2026-03-09 19:42:20(UTC+08:00)"
  }
}

响应结构总览

路径	类型	说明
`code`	integer	平台状态码，`0` 表示成功
`message`	string	状态消息
`data`	object	提交结果
`data.version`	string	内容版本号，当前为 `v1`
`data.record_id`	integer	记录 ID
`data.record_number`	string	记录编号
`data.record_code`	string	记录码
`data.record_url`	string	记录访问链接
`data.submit_at`	integer	提交时间，Unix 时间戳（秒）
`data.submit_at_iso`	string	带时区的格式化时间字符串

错误响应

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

json

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

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

说明：通过 API 来源提交 addRecord 时，不按表单组件的 is_required 规则校验缺省字段；错误判断应结合实际请求参数、字段值结构和业务状态理解。

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

接入建议

先调用 获取表单结构，拿到 field_id、字段类型和可选项信息。
按本页中的 field_type -> field_value 规则构造 fields[]。
跳过当前 V2 不支持的静态资源类组件；若业务依赖这些字段，请先确认允许 API 写入时留空。
如需批量导入，可在本地解析 Excel 或其他表格文件后，逐行调用本接口；当前不提供官方批量导入接口。
提交成功后，如需读取记录内容，可调用 获取单条记录 或 获取记录列表。

二维码

活码

表单

批量模板 & 子码

记录

成员

活码

表单与记录

安装教程

企业微信版购买

常见问题

添加记录

请求示例

请求参数

`fields[]` 元素结构

`field_value` 输入格式

输入格式速查

文本 / 时间类

单选类

数字类

多选类

检查项

表格

自增表格

地址类

级联选择

OCR 类

当前不支持提交的内容

静态资源类组件

非业务值组件

与表单必填配置的关系

显隐规则说明

Excel 批量新增边界说明

成功响应示例

响应结构总览

错误响应

接入建议

相关文档

添加记录 ​

请求示例 ​

请求参数 ​

fields[] 元素结构 ​

field_value 输入格式 ​

输入格式速查 ​

文本 / 时间类 ​

单选类 ​

数字类 ​

多选类 ​

检查项 ​

表格 ​

自增表格 ​

地址类 ​

级联选择 ​

OCR 类 ​

当前不支持提交的内容 ​

静态资源类组件 ​

非业务值组件 ​

与表单必填配置的关系 ​

显隐规则说明 ​

Excel 批量新增边界说明 ​

成功响应示例 ​

响应结构总览 ​

错误响应 ​

接入建议 ​

相关文档 ​

添加记录

请求示例

请求参数

`fields[]` 元素结构

`field_value` 输入格式

输入格式速查

文本 / 时间类

单选类

数字类

多选类

检查项

表格

自增表格

地址类

级联选择

OCR 类

当前不支持提交的内容

静态资源类组件

非业务值组件

与表单必填配置的关系

显隐规则说明

Excel 批量新增边界说明

成功响应示例

响应结构总览

错误响应

接入建议

相关文档