向指定二维码下的表单提交记录

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

前置条件

• 已完成 鉴权（OpenAPI V2）
• 已知二维码 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[] 组装请求体并提交一条记录。

关键 ID 关系

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

常见注意点

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

相关接口

• 活码内容
• 活码关联操作项列表
• 获取表单结构
• 添加记录