API 概述
业务系统通过 V2 接口读码内容、读写表单记录、查指标,也可以直接生成二维码、维护模板、编辑表单和导出标签。AI 客户端通过管理端 MCP 使用同一批能力。
调用 V2 接口默认使用个人 API Key,第三方应用用 OAuth。以前创建的组织 Key 只能调部分存量接口。v1 接口不再更新,文档保留在历史版本。
基址与调用约定
- 基址:
https://open.cli.im - 路径前缀:
/api/v2/rpc/,完整地址形如https://open.cli.im/api/v2/rpc/{服务}/{方法} - 请求方式:所有接口均为 POST,请求体为 application/json
- 鉴权:请求头带
Authorization: Bearer <个人 API Key>,见鉴权
第一次调用
先创建个人 API Key 并验证所属组织。只查码列表时选择「只读」即可。需要写入但无法选对应档位时,请超级管理员查看组织策略。以下示例读取一页活码。
curl -X POST 'https://open.cli.im/api/v2/rpc/qrcodes/list' \
-H 'Authorization: Bearer <你的API Key>' \
-H 'Content-Type: application/json' \
-d '{"page_size": 20}'import requests
url = "https://open.cli.im/api/v2/rpc/qrcodes/list"
headers = {
"Authorization": "Bearer <你的API Key>",
"Content-Type": "application/json"
}
response = requests.post(url, json={"page_size": 20}, headers=headers)
print(response.text)拿到码的 coding 后,继续调活码内容。术语含义见核心概念,出错时看错误码与调用额度。
接口规范 openapi.json
https://open.cli.im/openapi.json 是 OpenAPI 3.x 规范文件,不需要鉴权,可直接 GET。用于生成 SDK、调试接口,或导入 Swagger、Postman 等工具。
文件随服务发布自动生成,包含当前线上所有 /api/v2/rpc/* 接口的路径、请求体 Schema 和响应,包括管理接口。下方标 v1 的接口不在其中。
线上不提供 Swagger 页面。想在界面里浏览或试调,把这个地址导入 Postman,或贴进 Swagger Editor(File → Import URL)。
和 MCP 怎么分工
| 你要做的事 | 用什么 |
|---|---|
| 生成二维码、维护模板和表单、导出标签 | REST 管理接口 或管理端 MCP |
| 业务系统定时读码内容、记录和指标 | API,见下方接口索引 |
| 向表单提交记录、核销凭证 | API,这两项不在管理端 MCP 的默认工具里 |
接口索引
全部接口及各自需要的权限见接口清单。下面是有独立文档页的接口,个人 Key、OAuth 和历史组织 Key 都能调。生成二维码、编辑、删除、标签导出等接口见码、模板与表单管理,只接受个人 Key 或 OAuth。标 v1 的接口只接受组织 Key。
码
| 接口 | 路径 | 说明 |
|---|---|---|
| 活码列表 | 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/templates/list | 分页获取批量模板列表 |
| 批量模板结构 | POST /api/v2/rpc/templates/get | 批量模板的元信息与字段结构 |
| 子码列表 | POST /api/v2/rpc/templates/listQrcodes | 分页获取模板下的子码 |
| 子码内容 | POST /api/v2/rpc/templates/getSubcode | 某个子码各字段的实际内容 |
创建子码 v1 | POST /api/v1/createSubCode | 在指定模板下创建子码 |
编辑子码 v1 | POST /api/v1/editSubCode | 修改子码内容 |
删除子码 v1 | POST /api/v1/deleteSubCode | 删除子码 |
表单与记录
| 接口 | 路径 | 说明 |
|---|---|---|
| 表单列表 | POST /api/v2/rpc/record/getFormList | 根据企业获取表单列表(list + 分页) |
| 表单结构 | 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/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/projects/list | 组织下的分区名单;分区可用于统计分组与范围过滤 |
批量新增成员 v1 | POST /api/member/addMember | 批量新增或编辑成员 |
不走 /api/v2/rpc/ 的接口
下面这些接口的地址和鉴权与主体接口不同。注意 open.cli.im 和 open-api.cli.im 是两个域名。
| 能力 | 地址 | 鉴权 |
|---|---|---|
| 生成二维码、解码 | https://api.2dcode.biz/v1/ | 不需要 |
识别码的来源 v1 | https://open.cli.im/api/v1/qrcode/scan_url | 组织 Key |
| 标签生成 API | https://open-api.cli.im/cli-open-platform-service/v1/ | 公共样式不需要;私有样式用 api_key 加签名 |
v1 接口全部不再更新。标 v1 的接口在当前版本没有一一对应的替代,继续可用;其余 v1 接口都有替代,见从 v1 迁移到当前版本。