# 查询二维码关联表单和记录

适用于你只有二维码 `coding` 或二维码 URL，希望进一步查到：

- 这个二维码关联了哪些表单
- 某个表单的字段结构是什么
- 该二维码下已经提交了哪些记录

## 前置条件

- 已完成 [鉴权](https://cli.im/open-api/openapi/v2/auth.md)
- 已知二维码 `coding` 或二维码 URL

## 推荐调用顺序

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

调用 [活码内容](https://cli.im/open-api/openapi/v2/api/qrcodes-get-content.md)，根据活码 `coding` 或 URL 获取 `data.meta.id`，该值就是后续接口中使用的 `code_id`。

### 第 2 步：获取关联表单 `tpl_id`

调用 [活码关联操作项列表](https://cli.im/open-api/openapi/v2/api/qrcodes-get-operation.md)，筛选 `element_type=2` 的元素，得到该码关联的一个或多个 `tpl_id`。

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

如果你需要展示表单标题、字段定义、可选项、组件类型等信息，调用 [获取表单结构](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md)。

这一步通常用于：

- 前端动态渲染表单
- 后端校验字段映射
- 为后续写入记录准备 `field_id`、`option_id` 等结构化 ID

### 第 4 步：查询记录列表

调用 [获取记录列表](https://cli.im/open-api/openapi/v2/api/record/record-get-records.md)，推荐过滤策略如下：

| 目标 | 推荐参数 |
| --- | --- |
| 查询该二维码下的全部记录 | `filters.qrcode.id=code_id` |
| 查询该二维码下某个表单的记录 | `filters.qrcode.id=code_id` + `filters.record_template.id=tpl_id` |
| 查询某个表单在当前 API Key 可见范围内的记录 | `filters.record_template.id=tpl_id` |
| 在当前 API Key 可见范围内做全局记录检索 | 可不传上述两个过滤条件，再按需叠加搜索词、时间范围等参数 |

### 第 5 步：是否还要调用单条详情接口

当 `format=json` 时，[获取记录列表](https://cli.im/open-api/openapi/v2/api/record/record-get-records.md) 的 `data.list[]` 中每一项已经是完整记录详情对象。

因此通常只有在以下场景下，才需要继续调用 [获取单条记录](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md)：

- 已经明确拿到了某个 `record_id`
- 已经明确拿到了某个 `record_url`
- 只需要精确读取某一条记录，而不是批量读取

## 完整示例

四步连起来是这样的。示例里的 `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 步（按需）：读表单结构，拿到字段定义
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/getRecords' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"filters": {"record_template": {"id": 122507}, "qrcode": {"id": 6762875}}, "format": "json", "page_size": 10}'
```

## 关键 ID 关系

| 名称 | 来源 | 用途 |
| --- | --- | --- |
| `code_id` | `qrcodes/getContent -> data.meta.id` | 标识目标二维码 |
| `tpl_id` | `qrcodes/getOperation` 中 `element_type=2` 的表单元素 | 标识目标表单模板 |
| `record_id` | `getRecords.data.list[]` 或其他业务上下文 | 用于精确读取单条记录 |

## 常见注意点

- 一个二维码可能关联多个表单，不要默认只会返回单个 `tpl_id`
- `getRecords` 已经可以直接返回完整记录详情，批量读取时不建议逐条再调用 `getRecord`
- 如果不传 `filters.qrcode.id`，结果范围通常会扩展到当前 API Key 可见范围，而不再局限于某一个二维码

## 相关接口

- [活码内容](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-get-records.md)
- [获取单条记录](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md)
