# API 概述

业务系统通过 V2 接口读码内容、读写表单记录、查指标，也可以直接生成二维码、维护模板、编辑表单和导出标签。AI 客户端通过[管理端 MCP](https://cli.im/open-api/agent/open-platform-mcp/quick-start.md) 使用同一批能力。

调用 V2 接口默认使用[个人 API Key](https://cli.im/open-api/openapi/v2/auth.md#create-key)，第三方应用用 OAuth。以前创建的组织 Key 只能调[部分存量接口](https://cli.im/open-api/openapi/v2/auth.md#org-key)。v1 接口不再更新，文档保留在[历史版本](https://cli.im/open-api/openapi/migrate-from-v1.md)。

## 基址与调用约定

- **基址**：`https://open.cli.im`
- **路径前缀**：`/api/v2/rpc/`，完整地址形如 `https://open.cli.im/api/v2/rpc/{服务}/{方法}`
- **请求方式**：所有接口均为 **POST**，请求体为 **application/json**
- **鉴权**：请求头带 `Authorization: Bearer <个人 API Key>`，见[鉴权](https://cli.im/open-api/openapi/v2/auth.md)

## 第一次调用

先[创建个人 API Key](https://cli.im/open-api/openapi/v2/auth.md#create-key) 并[验证所属组织](https://cli.im/open-api/openapi/v2/auth.md#verify-key)。只查码列表时选择「只读」即可。需要写入但无法选对应档位时，请超级管理员[查看组织策略](https://cli.im/open-api/openapi/v2/auth.md#org-policy)。以下示例读取一页活码。



```bash [curl]
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 [Python + requests]
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` 后，继续调[活码内容](https://cli.im/open-api/openapi/v2/api/qrcodes-get-content.md)。术语含义见[核心概念](https://cli.im/open-api/start/concepts.md)，出错时看[错误码与调用额度](https://cli.im/open-api/openapi/v2/error-codes.md)。

## 接口规范 openapi.json

`https://open.cli.im/openapi.json` 是 OpenAPI 3.x 规范文件，不需要鉴权，可直接 GET。用于生成 SDK、调试接口，或导入 Swagger、Postman 等工具。

文件随服务发布自动生成，包含当前线上所有 `/api/v2/rpc/*` 接口的路径、请求体 Schema 和响应，包括[管理接口](https://cli.im/open-api/openapi/v2/management.md)。下方标 v1 的接口不在其中。

线上不提供 Swagger 页面。想在界面里浏览或试调，把这个地址导入 Postman，或贴进 [Swagger Editor](https://editor.swagger.io/)（File → Import URL）。

## 和 MCP 怎么分工

| 你要做的事 | 用什么 |
|---|---|
| 生成二维码、维护模板和表单、导出标签 | [REST 管理接口](https://cli.im/open-api/openapi/v2/management.md) 或[管理端 MCP](https://cli.im/open-api/agent/open-platform-mcp/tools.md) |
| 业务系统定时读码内容、记录和指标 | API，见下方[接口索引](https://cli.im/open-api/openapi/v2/overview.html#接口索引) |
| 向表单提交记录、核销凭证 | API，这两项不在管理端 MCP 的默认工具里 |

## 接口索引

全部接口及各自需要的权限见[接口清单](https://cli.im/open-api/openapi/v2/api-index.md)。下面是有独立文档页的接口，个人 Key、OAuth 和历史组织 Key 都能调。生成二维码、编辑、删除、标签导出等接口见[码、模板与表单管理](https://cli.im/open-api/openapi/v2/management.md)，只接受个人 Key 或 OAuth。标 `v1` 的接口只接受组织 Key。

### 码

| 接口 | 路径 | 说明 |
|------|------|------|
| [活码列表](https://cli.im/open-api/openapi/v2/api/qrcodes-list.md) | `POST /api/v2/rpc/qrcodes/list` | 分页获取组织下的活码名称与 coding |
| [活码内容](https://cli.im/open-api/openapi/v2/api/qrcodes-get-content.md) | `POST /api/v2/rpc/qrcodes/getContent` | 根据活码 coding 或 URL 获取展示内容（元信息与字段列表） |
| [活码关联的操作项](https://cli.im/open-api/openapi/v2/api/qrcodes-get-operation.md) | `POST /api/v2/rpc/qrcodes/getOperation` | 根据活码 coding 或 URL 获取关联的操作项元素列表（扁平化结构） |

### 批量模板与子码

| 接口 | 路径 | 说明 |
|------|------|------|
| [批量模板列表](https://cli.im/open-api/openapi/v2/api/templates/templates-list.md) | `POST /api/v2/rpc/templates/list` | 分页获取批量模板列表 |
| [批量模板结构](https://cli.im/open-api/openapi/v2/api/templates/templates-get.md) | `POST /api/v2/rpc/templates/get` | 批量模板的元信息与字段结构 |
| [子码列表](https://cli.im/open-api/openapi/v2/api/templates/templates-list-qrcodes.md) | `POST /api/v2/rpc/templates/listQrcodes` | 分页获取模板下的子码 |
| [子码内容](https://cli.im/open-api/openapi/v2/api/templates/templates-get-subcode.md) | `POST /api/v2/rpc/templates/getSubcode` | 某个子码各字段的实际内容 |
| [创建子码](https://cli.im/open-api/openapi/api/template-qrcodes/create-qrcode.md) `v1` | `POST /api/v1/createSubCode` | 在指定模板下创建子码 |
| [编辑子码](https://cli.im/open-api/openapi/api/template-qrcodes/edit-qrcode.md) `v1` | `POST /api/v1/editSubCode` | 修改子码内容 |
| [删除子码](https://cli.im/open-api/openapi/api/template-qrcodes/delete-qrcode.md) `v1` | `POST /api/v1/deleteSubCode` | 删除子码 |

### 表单与记录

| 接口 | 路径 | 说明 |
|------|------|------|
| [表单列表](https://cli.im/open-api/openapi/v2/api/record/record-get-form-list.md) | `POST /api/v2/rpc/record/getFormList` | 根据企业获取表单列表（list + 分页） |
| [表单结构](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md) | `POST /api/v2/rpc/forms/getTemplate` | 根据表单模板 ID（tpl_id）获取表单名、模板 ID、字段列表 |
| [单条记录](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) | `POST /api/v2/rpc/record/getRecord` | 根据记录 ID 或记录 URL 获取单条记录详情 |
| [记录列表](https://cli.im/open-api/openapi/v2/api/record/record-get-records.md) | `POST /api/v2/rpc/record/getRecords` | 根据 filters（record_template.id / qrcode.id）、关键字、筛选条件、时间、分页等获取记录列表 |
| [添加记录](https://cli.im/open-api/openapi/v2/api/record/record-add-record.md) | `POST /api/v2/rpc/record/addRecord` | 根据 code_id + tpl_id 提交一条填写记录 |
| [核销记录凭证](https://cli.im/open-api/openapi/v2/api/record/certificates-verify.md) | `POST /api/v2/rpc/certificates/verify` | 对凭证类记录执行核销（推进下一状态或设置为指定状态） |

[表单组件类型](https://cli.im/open-api/openapi/v2/api/record/components-field-types.md)统一说明 `field_type` 的名称、分类、共性语义与命名约定；配置结构看“表单结构”，记录值结构看“单条记录”。

### 指标与分析

回答「多少、占比、分布」类问题的接口组，一般按 目录 → 出数 → 下钻 的顺序调用。

| 接口 | 路径 | 说明 |
|------|------|------|
| [指标目录](https://cli.im/open-api/openapi/v2/api/metrics/metrics-list.md) | `POST /api/v2/rpc/metrics/list` | 组织的业务对象目录（表单/分区/活码/周期计划）+ 可计算的指标清单，分析入口 |
| [指标定义](https://cli.im/open-api/openapi/v2/api/metrics/metrics-get.md) | `POST /api/v2/rpc/metrics/get` | 某个指标的统计口径、可用维度与注意事项 |
| [按指标出数](https://cli.im/open-api/openapi/v2/api/metrics/metrics-query.md) | `POST /api/v2/rpc/metrics/query` | 出数与分布（按表单/分区/活码/日/月等分组），每个分组自带下钻条件 |
| [下钻检索记录](https://cli.im/open-api/openapi/v2/api/record/record-search-records.md) | `POST /api/v2/rpc/record/searchRecords` | 按多维条件检索记录行摘要，承接出数结果的下钻，从数字直达具体记录 |

### 组织

| 接口 | 路径 | 说明 |
|------|------|------|
| [分区列表](https://cli.im/open-api/openapi/v2/api/projects-list.md) | `POST /api/v2/rpc/projects/list` | 组织下的分区名单；分区可用于统计分组与范围过滤 |
| [批量新增成员](https://cli.im/open-api/openapi/api/member/add-member.md) `v1` | `POST /api/member/addMember` | 批量新增或编辑成员 |

### 不走 `/api/v2/rpc/` 的接口

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

| 能力 | 地址 | 鉴权 |
|------|------|------|
| [生成二维码](https://cli.im/open-api/qrcode-api/create-qr-code.md)、[解码](https://cli.im/open-api/qrcode-api/read-qr-code.md) | `https://api.2dcode.biz/v1/` | 不需要 |
| [识别码的来源](https://cli.im/open-api/openapi/api/qr-codes/scan-url.md) `v1` | `https://open.cli.im/api/v1/qrcode/scan_url` | 组织 Key |
| [标签生成 API](https://cli.im/open-api/label-api/intro.md) | `https://open-api.cli.im/cli-open-platform-service/v1/` | 公共样式不需要；私有样式用 `api_key` 加签名 |

v1 接口全部不再更新。标 `v1` 的接口在当前版本没有一一对应的替代，继续可用；其余 v1 接口都有替代，见[从 v1 迁移到当前版本](https://cli.im/open-api/openapi/migrate-from-v1.md)。

## 典型场景

- [查二维码关联的表单和记录](https://cli.im/open-api/openapi/v2/scenarios/query-qrcode-records.md)
- [向某个码的表单提交记录](https://cli.im/open-api/openapi/v2/scenarios/add-record-by-qrcode.md)
- [Excel 批量新增记录](https://cli.im/open-api/openapi/v2/scenarios/bulk-import-records.md)
