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

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

## 前置条件

- 已完成 [鉴权](https://cli.im/open-api/openapi/v2/auth.md)
- 已知二维码 `coding` 或二维码 URL
- 已确认当前 API Key 对目标二维码和目标表单有可见与写入权限

## 推荐调用顺序

### 第 1 步：获取 `code_id`

调用 [活码内容](https://cli.im/open-api/openapi/v2/api/qrcodes-get-content.md)，从返回值中读取 `data.meta.id`，作为后续写入所需的 `code_id`。

### 第 2 步：获取目标 `tpl_id`

调用 [活码关联操作项列表](https://cli.im/open-api/openapi/v2/api/qrcodes-get-operation.md)，从返回结果中定位目标表单，拿到对应的 `tpl_id`。

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

### 第 3 步：读取表单结构

调用 [获取表单结构](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md)，提取提交记录所需的结构化 ID，例如：

- `field_id`
- `option_id`
- `item_id`
- `column_id`

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

### 第 4 步：提交记录

调用 [添加记录](https://cli.im/open-api/openapi/v2/api/record/record-add-record.md)，按 `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_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 添加记录时，不按组件必填配置校验是否传入对应字段
- 字段校验失败、请求参数错误、当前二维码状态不允许提交等错误，通常都需要按业务错误逐条处理，而不是无条件重试

## 相关接口

- [活码内容](https://cli.im/open-api/openapi/v2/api/qrcodes-get-content.md)
- [活码关联操作项列表](https://cli.im/open-api/openapi/v2/api/qrcodes-get-operation.md)
- [获取表单结构](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md)
- [添加记录](https://cli.im/open-api/openapi/v2/api/record/record-add-record.md)
