# 添加记录

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

本文档聚焦“如何构造请求体”。如果你需要先知道有哪些字段可填、每个字段的 `field_id` / `option_id` / 列 ID / 检查项 ID 是什么，请先调用 [`获取表单结构`](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md)。

## 请求示例



```python [Python + requests]
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]
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，应从 [`获取表单结构`](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md) 返回结果中获取。
- 外部接口只需要传 `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` 等子结构；列定义和可用类型应以 [`获取表单结构`](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md) 为准。

### 自增表格

适用 `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[]` 项。

补充说明：

- [`获取表单结构`](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md) 返回的 `is_required`，主要用于前端填写、扫码填写等交互场景的展示与校验语义。
- 接入方可以读取 `is_required` 做本地校验或提示，但不要假定 OpenAPI 会因为未传某个表单必填组件而直接拒绝请求。

## 显隐规则说明

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

补充说明：

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

## Excel 批量新增边界说明

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

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

1. 先调用 [`获取表单结构`](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md)，获取 `field_id`、`option_id`、`item_id`、`column_id` 等结构化 ID。
2. 解析 Excel，每一行映射为一次 `fields[]` 输入。
3. 按行逐次调用本接口提交记录。
4. 汇总每条记录的成功或失败结果，并按需重试可恢复错误。

补充说明：

- 该方案本质上是多次单条提交，不是原子批处理；部分成功、部分失败属于正常结果，需要调用方自行汇总处理。
- 批量提交前，建议先校验目标表单中是否包含当前 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` 规则校验缺省字段；错误判断应结合实际请求参数、字段值结构和业务状态理解。

具体错误码定义见：[错误码与调用额度](https://cli.im/open-api/openapi/v2/error-codes.md)。

## 接入建议

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

## 相关文档

- [`获取表单结构`](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md)：获取字段定义、选项 ID、检查项 ID、矩阵列 ID
- [`表单组件类型总览`](https://cli.im/open-api/openapi/v2/api/record/components-field-types.md)：查看 `field_type` 的命名与分类
- [`获取单条记录`](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md)：查看记录写入后的返回内容结构
- [`获取记录列表`](https://cli.im/open-api/openapi/v2/api/record/record-get-records.md)：批量查询记录
