# Excel 批量新增记录（需逐行调用）

适用于你已有一份 Excel 或其他表格数据，希望批量写入到某个二维码关联表单中。

## 结论

当前 API **未提供官方的 Excel 上传 / 导入 / 原子批量新增记录接口**。

如果需要批量新增，推荐做法是：由接入方在本地解析 Excel，然后逐行调用 [添加记录](https://cli.im/open-api/openapi/v2/api/record/record-add-record.md) 实现。

## 推荐实现链路

### 第 1 步：确定目标二维码与表单

先参考 [向指定二维码下的表单提交记录](https://cli.im/open-api/openapi/v2/scenarios/add-record-by-qrcode.md)，拿到：

- `code_id`
- `tpl_id`
- 表单字段所需的结构化 ID

### 第 2 步：本地解析 Excel

接入侧自行读取 Excel 文件，将每一行转换成内部数据对象，再映射到接口要求的 `fields[]` 结构。

### 第 3 步：逐行调用 `addRecord`

对每一行数据分别调用 [添加记录](https://cli.im/open-api/openapi/v2/api/record/record-add-record.md)。

这意味着该方案本质上是：

- 多次单条提交
- 非原子批处理
- 每条记录都可能独立成功或失败

## 适合自行补充的能力

由于平台不提供统一批处理事务语义，建议接入侧自行处理以下能力：

- 单行数据校验
- 错误汇总
- 幂等控制
- 重试策略
- 导入进度与结果回显

## 常见注意点

- 不要把该方案理解为“上传一个 Excel 文件后由平台一次性入库”
- 某一条记录提交失败，不代表前面已经成功的记录会自动回滚
- 在批量导入前，最好先通过 [获取表单结构](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.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)
- [向指定二维码下的表单提交记录](https://cli.im/open-api/openapi/v2/scenarios/add-record-by-qrcode.md)
