Skip to content

向某个二维码的表单提交记录 ​

适用于你已经知道目标二维码,希望向该二维码关联的某个表单提交一条新记录。

前置条件 ​

  • 已完成 鉴权
  • 已知二维码 coding 或二维码 URL
  • 已确认当前 API Key 对目标二维码和目标表单有可见与写入权限

推荐调用顺序 ​

第 1 步:获取 code_id ​

调用 活码内容,从返回值中读取 data.meta.id,作为后续写入所需的 code_id。

第 2 步:获取目标 tpl_id ​

调用 活码关联操作项列表,从返回结果中定位目标表单,拿到对应的 tpl_id。

如果同一个二维码下关联了多个表单,建议接入侧先依据表单名称、业务类型或其他上下文选择正确的目标表单,再继续后续调用。

第 3 步:读取表单结构 ​

调用 获取表单结构,提取提交记录所需的结构化 ID,例如:

  • field_id
  • option_id
  • item_id
  • column_id

这一步的目的不是只看表单长什么样,而是确保你提交 fields[] 时使用的是接口要求的结构化标识,而不是页面展示名称。

第 4 步:提交记录 ​

调用 添加记录,按 code_id + tpl_id + fields[] 组装请求体并提交一条记录。

完整示例 ​

四步连起来是这样的。最后一步会真实提交一条记录。示例里的 qk3mJHJ、6762875、122507 等都是演示值,每一步都要换成上一步返回的真实值,整段复制不会自动传值。每个接口的完整参数和返回结构见各自的接口页。

bash
# 第 1 步:用码的 coding 换取 code_id,在返回的 data.meta.id 里
curl -X POST 'https://open.cli.im/api/v2/rpc/qrcodes/getContent' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"qrcode": "qk3mJHJ", "format": "json"}'

# 第 2 步:查这张码关联的表单。element_type=2 的元素,element_value 就是 tpl_id
curl -X POST 'https://open.cli.im/api/v2/rpc/qrcodes/getOperation' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"qrcode": "qk3mJHJ"}'

# 第 3 步:读表单结构,拿到 field_id、option_id 等结构化 ID
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}'

# 第 4 步:提交一条记录
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}}]}'

关键 ID 关系 ​

名称来源用途
code_idqrcodes/getContent -> data.meta.id标识目标二维码
tpl_idqrcodes/getOperation 中关联表单元素标识要写入的表单模板
field_id / option_id / item_id / column_idforms/getTemplate组装 fields[] 所需的结构化字段标识

常见注意点 ​

  • 不建议直接根据表单展示名称手写字段映射,应始终以 forms/getTemplate 返回的结构化 ID 为准
  • 同一个二维码下可能存在多个表单,提交前应先明确目标 tpl_id
  • forms/getTemplate 返回的 is_required 主要用于前端填写场景;通过 API 添加记录时,不按组件必填配置校验是否传入对应字段
  • 字段校验失败、请求参数错误、当前二维码状态不允许提交等错误,通常都需要按业务错误逐条处理,而不是无条件重试

相关接口 ​