# API 接口清单

V2 的全部 63 个接口，按业务分组。每个接口都是 `POST https://open.cli.im/api/v2/rpc/{路径}`，请求体为 JSON。本页由 [openapi.json](https://cli.im/open-api/openapi/v2/overview.md#%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83-openapi-json) 生成，各接口的请求字段以它为准。

- **最低权限**：能调用这个接口的[个人 API Key 或 OAuth 档位](https://cli.im/open-api/openapi/v2/auth.md#org-policy)下限。组织最高权限和成员自己的资源权限仍然生效。
- **组织 Key**：[历史组织 Key](https://cli.im/open-api/openapi/v2/auth.md#org-key) 能否调用。
- 带链接的接口有独立文档页。

## 凭证与额度

查询当前凭证所属组织、档位和可用能力，以及组织当日额度。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [查询当前凭证的组织、权限和可用操作](https://cli.im/open-api/openapi/v2/reference/auth_get_context.md) | `auth/getContext` | 只读 | 可以 |
| [查询当前组织的当日额度](https://cli.im/open-api/openapi/v2/reference/usage_get.md) | `usage/get` | 只读 | 可以 |

## 活码

查询活码列表、内容和操作面板。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [活码内容](https://cli.im/open-api/openapi/v2/api/qrcodes-get-content.md) | `qrcodes/getContent` | 只读 | 可以 |
| [活码关联的操作项](https://cli.im/open-api/openapi/v2/api/qrcodes-get-operation.md) | `qrcodes/getOperation` | 只读 | 可以 |
| [活码列表](https://cli.im/open-api/openapi/v2/api/qrcodes-list.md) | `qrcodes/list` | 只读 | 可以 |

## 模板与子码

查询批量模板及其子码。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [批量模板列表](https://cli.im/open-api/openapi/v2/api/templates/templates-list.md) | `templates/list` | 只读 | 可以 |
| [批量模板结构](https://cli.im/open-api/openapi/v2/api/templates/templates-get.md) | `templates/get` | 只读 | 可以 |
| [模板下子码列表](https://cli.im/open-api/openapi/v2/api/templates/templates-list-qrcodes.md) | `templates/listQrcodes` | 只读 | 可以 |
| [子码内容](https://cli.im/open-api/openapi/v2/api/templates/templates-get-subcode.md) | `templates/getSubcode` | 只读 | 可以 |

## 表单与记录

查询表单结构和填写记录，新增填写记录，核销凭证。

调用流程见：[查询二维码关联表单和记录](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)。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [表单结构/内容](https://cli.im/open-api/openapi/v2/api/record/forms-get-template.md) | `forms/getTemplate` | 只读 | 可以 |
| [获取单条记录详情](https://cli.im/open-api/openapi/v2/api/record/record-get-record.md) | `record/getRecord` | 只读 | 可以 |
| [获取记录列表](https://cli.im/open-api/openapi/v2/api/record/record-get-records.md) | `record/getRecords` | 只读 | 可以 |
| [获取表单列表](https://cli.im/open-api/openapi/v2/api/record/record-get-form-list.md) | `record/getFormList` | 只读 | 可以 |
| [添加记录](https://cli.im/open-api/openapi/v2/api/record/record-add-record.md) | `record/addRecord` | 读写 | 可以 |
| [凭证核销](https://cli.im/open-api/openapi/v2/api/record/certificates-verify.md) | `certificates/verify` | 读写 | 可以 |
| [分页读取填写记录的后续动态](https://cli.im/open-api/openapi/v2/reference/record_activities_list.md) | `record/getActivities` | 只读 | — |
| [按条件检索记录摘要](https://cli.im/open-api/openapi/v2/api/record/record-search-records.md) | `record/searchRecords` | 只读 | 可以 |

## 分区

查询组织内的分区。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [分区列表](https://cli.im/open-api/openapi/v2/api/projects-list.md) | `projects/list` | 只读 | 可以 |

## 指标

查询指标定义并按维度取数。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [列出业务对象和可用指标](https://cli.im/open-api/openapi/v2/api/metrics/metrics-list.md) | `metrics/list` | 只读 | 可以 |
| [读取指标定义](https://cli.im/open-api/openapi/v2/api/metrics/metrics-get.md) | `metrics/get` | 只读 | 可以 |
| [查询指标数据](https://cli.im/open-api/openapi/v2/api/metrics/metrics-query.md) | `metrics/query` | 只读 | 可以 |

## 官方模板

浏览官方模板库，并用官方模板生成单个码或批量生成二维码。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [浏览官方模板库的场景和行业分类](https://cli.im/open-api/openapi/v2/reference/gallery_categories.md) | `gallery/categories` | 只读 | — |
| [搜索官方模板库](https://cli.im/open-api/openapi/v2/reference/gallery_list.md) | `gallery/list` | 只读 | — |
| [读取官方模板详情](https://cli.im/open-api/openapi/v2/reference/gallery_get.md) | `gallery/get` | 只读 | — |
| [准备官方模板生成二维码方案](https://cli.im/open-api/openapi/v2/reference/gallery_prepare_creation.md) | `gallery/prepare-creation` | 读写 | — |
| [用官方模板生成单个码](https://cli.im/open-api/openapi/v2/reference/gallery_create_qrcode.md) | `gallery/create-qrcode` | 读写 | — |
| [执行官方模板生成二维码方案](https://cli.im/open-api/openapi/v2/reference/gallery_create_from_plan.md) | `gallery/create-from-plan` | 读写 | — |

## 生成二维码与批量任务

创建普通码、网址跳转码、网址聚合码和静态码；按已有模板预校验并提交批量生成二维码，查询任务进度和逐项结果。

调用流程见：[按模板批量生成二维码](https://cli.im/open-api/openapi/v2/scenarios/batch-create-qrcodes.md)。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [批量生成二维码预校验，不创建二维码](https://cli.im/open-api/openapi/v2/reference/qrcodes_prevalidate.md) | `qrcodes/prevalidate` | 读写 | — |
| [提交批量生成二维码任务](https://cli.im/open-api/openapi/v2/reference/qrcodes_create_batch.md) | `qrcodes/createBatch` | 读写 | — |
| [查询生成二维码任务进度](https://cli.im/open-api/openapi/v2/reference/qrcode_tasks_get.md) | `qrcodeTasks/get` | 读写 | — |
| [查询当前可用于新建的分区或目录](https://cli.im/open-api/openapi/v2/reference/qrcodes_list_create_targets.md) | `qrcodes/listCreateTargets` | 只读 | — |
| [分页读取批量生成二维码逐项结果](https://cli.im/open-api/openapi/v2/reference/qrcode_tasks_get_results.md) | `qrcodeTasks/getResults` | 读写 | — |
| [创建普通图文码并绑定表单](https://cli.im/open-api/openapi/v2/reference/qrcodes_create.md) | `qrcodes/create` | 读写 | — |
| [创建网址跳转码](https://cli.im/open-api/openapi/v2/reference/qrcodes_create_url_jump.md) | `qrcodes/createUrlJump` | 读写 | — |
| [创建网址聚合码](https://cli.im/open-api/openapi/v2/reference/qrcodes_create_multi_url.md) | `qrcodes/createMultiUrl` | 读写 | — |
| [创建文本或网址静态码](https://cli.im/open-api/openapi/v2/reference/static_qrcodes_create.md) | `staticQrcodes/create` | 读写 | — |

## 编辑与删除

修改和删除码、表单。修改前先读取编辑状态取得 version；删除分两步，先预览取得确认令牌，再凭令牌删除。

调用流程见：[修改和删除码、表单](https://cli.im/open-api/openapi/v2/scenarios/edit-and-delete.md)。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [修改码之前读取当前内容、版本和是否可改](https://cli.im/open-api/openapi/v2/reference/qrcodes_get_edit_state.md) | `qrcodes/getEditState` | 读写 | — |
| [修改普通码或图文展示码](https://cli.im/open-api/openapi/v2/reference/qrcodes_edit.md) | `qrcodes/edit` | 读写 | — |
| [修改网址跳转码的名称或跳转地址](https://cli.im/open-api/openapi/v2/reference/qrcodes_edit_url_jump.md) | `qrcodes/editUrlJump` | 读写 | — |
| [修改网址聚合码的名称或链接清单](https://cli.im/open-api/openapi/v2/reference/qrcodes_edit_multi_url.md) | `qrcodes/editMultiUrl` | 读写 | — |
| [修改批量生成的单个子码](https://cli.im/open-api/openapi/v2/reference/qrcode_children_edit.md) | `qrcodeChildren/edit` | 读写 | — |
| [修改表单之前读取字段、版本和是否可改](https://cli.im/open-api/openapi/v2/reference/forms_get_edit_state.md) | `forms/getEditState` | 读写 | — |
| [修改表单的名称或字段](https://cli.im/open-api/openapi/v2/reference/forms_edit.md) | `forms/edit` | 读写 | — |
| [预览要删除的码并取得确认令牌，不删除](https://cli.im/open-api/openapi/v2/reference/qrcodes_preview_delete.md) | `qrcodes/previewDelete` | 完全 | — |
| [凭确认令牌删除码](https://cli.im/open-api/openapi/v2/reference/qrcodes_delete.md) | `qrcodes/delete` | 完全 | — |
| [预览要删除的表单并取得确认令牌，不删除](https://cli.im/open-api/openapi/v2/reference/forms_preview_delete.md) | `forms/previewDelete` | 完全 | — |
| [凭确认令牌删除表单](https://cli.im/open-api/openapi/v2/reference/forms_delete.md) | `forms/delete` | 完全 | — |

## 模板与表单管理

查找、创建和修改基础信息模板，创建填写表单。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [查找可用于生成二维码的模板](https://cli.im/open-api/openapi/v2/reference/templates_list_editable.md) | `templates/listEditable` | 只读 | — |
| [读取模板字段结构和版本](https://cli.im/open-api/openapi/v2/reference/templates_get_schema.md) | `templates/getSchema` | 只读 | — |
| [创建基础信息模板](https://cli.im/open-api/openapi/v2/reference/templates_create.md) | `templates/create` | 读写 | — |
| [预览模板修改及影响范围](https://cli.im/open-api/openapi/v2/reference/templates_preview_edit.md) | `templates/previewEdit` | 读写 | — |
| [保存基础信息模板修改](https://cli.im/open-api/openapi/v2/reference/templates_edit.md) | `templates/edit` | 读写 | — |
| [创建填写表单及可选周期](https://cli.im/open-api/openapi/v2/reference/forms_create.md) | `forms/create` | 读写 | — |

## 素材上传

为本地图片和文件申请临时上传，取得生成二维码时引用的 file_key。

调用流程见：[按模板批量生成二维码](https://cli.im/open-api/openapi/v2/scenarios/batch-create-qrcodes.md#upload)。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [申请临时文件上传](https://cli.im/open-api/openapi/v2/reference/assets_request_upload.md) | `assets/requestUpload` | 读写 | — |
| [查询临时文件上传状态](https://cli.im/open-api/openapi/v2/reference/assets_get_upload.md) | `assets/getUpload` | 读写 | — |

## 标签

读取标签样式，预览并导出指定码的标签。

调用流程见：[导出可打印的标签](https://cli.im/open-api/openapi/v2/scenarios/export-labels.md)。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [读取当前标签样式与支持的导出格式](https://cli.im/open-api/openapi/v2/reference/labels_get_config.md) | `labels/getConfig` | 只读 | — |
| [按当前样式预览指定码的标签](https://cli.im/open-api/openapi/v2/reference/labels_preview.md) | `labels/preview` | 只读 | — |
| [为明确指定的码创建标签导出任务](https://cli.im/open-api/openapi/v2/reference/label_exports_create.md) | `labelExports/create` | 读写 | — |
| [查询标签导出任务及下载文件](https://cli.im/open-api/openapi/v2/reference/label_exports_get.md) | `labelExports/get` | 读写 | — |

## 周期计划

查询周期计划及各周期的完成情况。

| 接口 | 路径 | 最低权限 | 组织 Key |
|---|---|---|---|
| [分页查询周期计划](https://cli.im/open-api/openapi/v2/reference/cycle_plans_list.md) | `cyclePlans/list` | 只读 | — |
| [读取周期计划详情](https://cli.im/open-api/openapi/v2/reference/cycle_plans_get.md) | `cyclePlans/get` | 只读 | — |
| [分页查询某个周期内各码的执行情况](https://cli.im/open-api/openapi/v2/reference/cycle_tasks_list_qrcodes.md) | `cycleTasks/listQrcodes` | 只读 | — |
| [查询各周期的完成情况](https://cli.im/open-api/openapi/v2/reference/cycle_tasks_get_completion.md) | `cycleTasks/getCompletion` | 只读 | — |
