Skip to content

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

适用于你只有二维码 coding 或二维码 URL,希望进一步查到:

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

前置条件 ​

  • 已完成 鉴权
  • 已知二维码 coding 或二维码 URL

推荐调用顺序 ​

第 1 步:获取 code_id ​

调用 活码内容,根据活码 coding 或 URL 获取 data.meta.id,该值就是后续接口中使用的 code_id。

第 2 步:获取关联表单 tpl_id ​

调用 活码关联操作项列表,筛选 element_type=2 的元素,得到该码关联的一个或多个 tpl_id。

第 3 步:按需读取表单结构 ​

如果你需要展示表单标题、字段定义、可选项、组件类型等信息,调用 获取表单结构。

这一步通常用于:

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

第 4 步:查询记录列表 ​

调用 获取记录列表,推荐过滤策略如下:

目标推荐参数
查询该二维码下的全部记录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 时,获取记录列表 的 data.list[] 中每一项已经是完整记录详情对象。

因此通常只有在以下场景下,才需要继续调用 获取单条记录:

  • 已经明确拿到了某个 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_idqrcodes/getContent -> data.meta.id标识目标二维码
tpl_idqrcodes/getOperation 中 element_type=2 的表单元素标识目标表单模板
record_idgetRecords.data.list[] 或其他业务上下文用于精确读取单条记录

常见注意点 ​

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

相关接口 ​