Skip to content

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 并验证所属组织。只查码列表时选择「只读」即可。需要写入但无法选对应档位时,请超级管理员查看组织策略。以下示例读取一页活码。

bash
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}'
python
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某个子码各字段的实际内容
创建子码 v1POST /api/v1/createSubCode在指定模板下创建子码
编辑子码 v1POST /api/v1/editSubCode修改子码内容
删除子码 v1POST /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组织下的分区名单;分区可用于统计分组与范围过滤
批量新增成员 v1POST /api/member/addMember批量新增或编辑成员

不走 /api/v2/rpc/ 的接口 ​

下面这些接口的地址和鉴权与主体接口不同。注意 open.cli.im 和 open-api.cli.im 是两个域名。

能力地址鉴权
生成二维码、解码https://api.2dcode.biz/v1/不需要
识别码的来源 v1https://open.cli.im/api/v1/qrcode/scan_url组织 Key
标签生成 APIhttps://open-api.cli.im/cli-open-platform-service/v1/公共样式不需要;私有样式用 api_key 加签名

v1 接口全部不再更新。标 v1 的接口在当前版本没有一一对应的替代,继续可用;其余 v1 接口都有替代,见从 v1 迁移到当前版本。

典型场景 ​