OpenAPI V2 说明
本文介绍草料开放平台 API 2.0（OpenAPI V2） 的通用约定、OpenAPI 文档地址、典型场景入口及接口索引。
Base URL
- Base URL：
https://open.cli.im - 路径前缀：
/api/v2/rpc/，即完整地址形如https://open.cli.im/api/v2/rpc/{服务}/{方法}。
鉴权方式见单独页面 鉴权（OpenAPI V2）。
所有 V2 接口均为 POST，请求体为 application/json。
OpenAPI JSON 文档地址
V2 的 OpenAPI 3.x 规范可通过以下地址获取，用于代码生成、接口调试或导入 Swagger/Postman 等工具：
- 地址：
https://open.cli.im/openapi.json
该接口不要求鉴权，可直接 GET 请求获取 JSON 文档。文档包含所有 /api/v2/rpc/* 接口的路径、请求体 Schema、响应及错误码说明。
MCP 接入说明见 Agent · 开放平台 MCP。
从哪里开始
- 首次接入：先阅读 鉴权（OpenAPI V2），确认 API Key 与请求方式
- 需要导入到 Swagger/Postman 或生成 SDK：直接使用
https://open.cli.im/openapi.json - 需要按业务目标看调用顺序：阅读 典型场景
- 需要按接口逐个查字段与示例：继续查看下方“接口分类索引”
接口分类索引
活码
| 接口 | 路径 | 说明 |
|---|---|---|
| 活码列表 | POST /api/v2/rpc/qrcodes/list | 分页获取组织下的活码名称与 coding |
| 活码内容 | POST /api/v2/rpc/qrcodes/getContent | 根据活码 coding 或 URL 获取展示内容（元信息与字段列表） |
| 活码关联操作项列表 | POST /api/v2/rpc/qrcodes/getOperation | 根据活码 coding 或 URL 获取关联的操作项元素列表（扁平化结构） |
表单与记录
| 接口 | 路径 | 说明 |
|---|---|---|
| 获取表单结构 | POST /api/v2/rpc/forms/getTemplate | 根据表单模板 ID（tpl_id）获取表单结构定义（表单名、模板 ID、字段列表） |
| 获取单条记录 | POST /api/v2/rpc/record/getRecord | 根据记录 ID 或记录 URL 获取单条记录详情 |
| 获取记录列表 | POST /api/v2/rpc/record/getRecords | 根据 filters（record_template.id / qrcode.id）、关键字、筛选条件、时间、分页等获取记录列表 |
| 获取表单列表 | POST /api/v2/rpc/record/getFormList | 根据企业获取表单列表（list + 分页） |
| 添加记录 | POST /api/v2/rpc/record/addRecord | 根据 code_id + tpl_id 提交一条填写记录 |
| 核销记录凭证 | POST /api/v2/rpc/certificates/verify | 对凭证类记录执行核销（推进下一状态或设置为指定状态） |
共享参考
- 表单组件类型总览：统一说明
field_type的名称、分类、共性语义与命名约定；配置结构看“表单结构”，记录值结构看“获取单条记录”
指标与分析
回答「多少、占比、分布」类问题的接口组，一般按 目录 → 出数 → 下钻 的顺序调用。
| 接口 | 路径 | 说明 |
|---|---|---|
| 指标目录 | POST /api/v2/rpc/metrics/list | 组织的业务对象目录（表单/分区/活码/周期计划）+ 可计算的指标清单，分析入口 |
| 指标定义 | POST /api/v2/rpc/metrics/get | 某个指标的统计口径、可用维度与注意事项 |
| 按指标出数 | POST /api/v2/rpc/metrics/query | 出数与分布（按表单/分区/活码/日/月等分组），每个分组自带下钻条件 |
| 检索记录行摘要（下钻） | POST /api/v2/rpc/record/searchRecords | 按多维条件检索记录行摘要，承接出数结果的下钻，从数字直达具体记录 |
批量模板与子码
| 接口 | 路径 | 说明 |
|---|---|---|
| 批量模板列表 | POST /api/v2/rpc/templates/list | 分页获取批量模板（占位码）列表 |
| 批量模板结构 | POST /api/v2/rpc/templates/get | 占位码的元信息与字段结构 |
| 模板下子码列表 | POST /api/v2/rpc/templates/listQrcodes | 分页获取模板下的子码 |
| 子码内容 | POST /api/v2/rpc/templates/getSubcode | 某个子码各字段的实际内容 |
分区
| 接口 | 路径 | 说明 |
|---|---|---|
| 分区列表 | POST /api/v2/rpc/projects/list | 组织下的分区名单；分区可用于统计分组与范围过滤 |