# 活码关联操作项列表

根据活码 `coding` 或完整 URL，获取该码关联的操作项元素列表。

该接口返回的是**扁平化结果**：

- `data` 中每一项代表一个“操作项元素”
- 如果同一个操作项下配置了多个元素，则会拆成多条记录返回
- 如果活码未关联任何操作项，返回空数组 `[]`

## 请求示例

:::::: code-group

```python [Python + requests]
import requests

url = "https://open.cli.im/api/v2/rpc/qrcodes/getOperation"
data = {
    "qrcode": "qk3mJHJ"
}
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/qrcodes/getOperation' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"qrcode":"qk3mJHJ"}'
```

::::::

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `qrcode` | string | 是 | 活码 `coding` 或完整 URL，例如 `qk3mJHJ` 或 `https://qr61.cn/xxxx/yyy` |

## 请求体示例

```json
{
  "qrcode": "qk3mJHJ"
}
```

## 完整返回示例

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "operation_name": "巡检操作",
      "operation_description": "每日巡检填写",
      "element_type": 2,
      "element_type_title": "填写表单",
      "element_value": 122507
    },
    {
      "operation_name": "巡检操作",
      "operation_description": "每日巡检填写",
      "element_type": 1,
      "element_type_title": "更新状态",
      "element_value": 88001
    }
  ]
}
```

上例表示该活码关联了一个名为“巡检操作”的操作项，其中包含两个元素：

- 一个“填写表单”元素，关联表单 ID(`tpl_id`) = `122507`
- 一个“更新状态”元素，关联状态 ID(`state_id`) = `88001`

## 响应结构总览

| 路径 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 平台状态码，`0` 表示成功 |
| `message` | string | 状态消息；成功时通常为 `ok`，也可能为空字符串 |
| `data` | array | 操作项元素列表，返回扁平化数组 |

### `data[]` 元素字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `operation_name` | string | 操作项标题 |
| `operation_description` | string | 操作项副标题或描述；无值时可能为空字符串 |
| `element_type` | integer | 元素类型，见下方枚举表 |
| `element_type_title` | string | 元素类型中文标题 |
| `element_value` | integer\|string\|object | 元素关联值，具体含义取决于 `element_type` |

## `element_type` 枚举

| `element_type` | `element_type_title` | 含义 | `element_value` 含义 |
| --- | --- | --- | --- |
| `1` | `更新状态` | 将活码更新到某个状态选项 | 状态 ID |
| `2` | `填写表单` | 跳转或关联到某个表单 | 表单模板 ID |
| `3` | `跳转链接` | 跳转到外部链接 | 链接配置值 |
| `4` | `更新子码内容` | 更新子码字段内容 | 子码字段配置值 |
| `5` | `更新子码内容` | 更新关联码字段内容 | 关联码字段配置值 |

说明：

- `element_type_title` 是服务端直接返回的展示文案。
- `element_type=4` 与 `element_type=5` 的返回标题当前都可能是 `更新子码内容`，但业务语义并不完全相同。
- 如果你的程序需要做自动分支判断，建议以 `element_type` 为准，不要只依赖 `element_type_title`。

接入建议：

- 当 `element_type=2` 时，`element_value` 即关联表单的 `tpl_id`。
- 拿到 `tpl_id` 后，建议先调用 [`获取表单结构`](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md) 获取字段定义、选项 ID 和提交所需的结构化信息。
- 如果需要读取该码或该表单的历史记录，可继续调用 [`获取记录列表`](https://cli.im/open-api/openapi/v2/api/record/record-get-records.md)。
- 如果需要向该码下的该表单提交新记录，可继续调用 [`添加记录`](https://cli.im/open-api/openapi/v2/api/record/record-add-record.md)。

## 空结果示例

当活码存在，但未关联任何操作项，返回如下：

```json
{
  "code": 0,
  "message": "ok",
  "data": []
}
```

## 错误响应

请求参数非法或活码无法识别时，通常会返回非成功状态，例如：

```json
{
  "code": 400,
  "error_code": 0,
  "message": "Invalid qrcode data, need coding or url"
}
```

```json
{
  "code": 400,
  "error_code": 0,
  "message": "Invalid qrcode url"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 错误状态码，常见为 `400` |
| `error_code` | integer | 业务错误码；不同错误场景下可能为不同值 |
| `message` | string | 错误摘要 |

常见错误场景：

- 未传 `qrcode`
- `qrcode` 不是合法的活码 URL
- `qrcode` 对应的活码不存在

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