> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Management API 概览

> 完整的 Scanova Management API——management.scanova.io 上提供的一切功能，外加令牌创建与用量统计。

**Management API** 是 Scanova 仪表盘中一切操作的编程接口：创建和更新二维码、管理文件夹与标签、读取线索和表单提交内容、拉取分析数据，以及管理共享用户与角色。它与 Scanova 其余 API 接口面运行在不同的主机上，拥有自己独立的身份验证方案。

<Note>
  本页介绍适用于每一个 Management API 端点的整体架构。完整的端点列表请见本页底部链接的各个子页面。
</Note>

## 两个主机，两套身份验证方案

这是集成 Management API 时最常见的困惑来源，因此请在编写任何代码之前先阅读本节。

|          | 令牌管理                                                                     | 数据端点                                                                                   |
| :------- | :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| **主机**   | `qcg-api.scanova.io`（常规的 Scanova API 主机）                                 | `management.scanova.io`（专用主机）                                                          |
| **身份验证** | 您正常的登录仪表盘会话——一个 OAuth 访问令牌，以 `Authorization: Bearer <access_token>` 形式发送 | 一个原始的 Management API 密钥，以 `Authorization: <key>` 形式发送——**完全不带任何前缀**                    |
| **端点**   | `console/token/*`、`console/usage/*`                                      | `qr/`、`qrcode/`、`folder/`、`tag/`、`lead/`、`forms/`、`analytics/`、`plans/`、`multi-users/` |
| **调用者**  | 您本人，从可信的后端或管理工具中一次性调用，用于创建/管理/监控密钥                                       | 您的集成程序，在每一次读取或写入二维码/文件夹/线索等数据的请求中调用                                                    |

换句话说：您以*您自己*的身份（仪表盘登录）进行身份验证，来创建一个 Management API 密钥；而您以*该密钥*的身份进行身份验证，来实际使用 Management API。

<Warning>
  数据主机的 `Authorization` 请求头只接受原始密钥，不接受其他任何内容。包含多个以空格分隔的部分的请求头——`Bearer <key>`、`Token <key>` 或类似形式——都会被直接拒绝。请精确发送：

  ```
  Authorization: 401f7ac837da42b97f613d789819ff93537bee6a
  ```

  这也意味着发往数据端点的请求必须将其 `Host` 请求头设置为 `management.scanova.io`——将同一个密钥发送给 `qcg-api.scanova.io` 不会通过身份验证。
</Warning>

## 快速上手

<Steps>
  <Step title="创建一个 Management API 密钥">
    在登录 Scanova 仪表盘的状态下，通过 [`POST /console/token/`](/zh/api-reference/management-api/tokens/create)（或仪表盘的密钥管理界面，参见[创建与管理 API 密钥](/zh/api-keys/creating-and-managing-keys)）创建一个密钥。创建时请选择一个 `environment`——`sandbox`、`live`、`zapier` 或 `mcp`——这一选择对该密钥而言是永久性的，并决定了该密钥发出的每一次请求会检查哪一种套餐配额（见下文）。
  </Step>

  <Step title="保存密钥的原始值">
    创建调用返回的密钥值是您唯一能够看到其完整内容的一次——请妥善保存。事后不存在任何"重新显示"的端点。
  </Step>

  <Step title="调用数据端点">
    将该密钥作为原始 `Authorization` 请求头的值发送给 `management.scanova.io`，例如通过 [`GET /qr/`](/zh/api-reference/management-api/qr/list) 列出您的二维码。
  </Step>
</Steps>

## 套餐配额

每一次对数据端点发起的请求都会检查一项与密钥的 `environment` 绑定的套餐配额：

| `environment`      | 所检查的配额               | 另外要求                                |
| :----------------- | :------------------- | :---------------------------------- |
| `live` 或 `sandbox` | `MANAGEMENT_API`     | ——                                  |
| `zapier`           | `INTEGRATION_ZAPIER` | 请求的 `User-Agent` 请求头必须严格等于 `zapier` |
| `mcp`              | `INTEGRATION_MCP`    | 请求的 `User-Agent` 请求头必须严格等于 `mcp`    |

<Note>
  如果对数据主机的请求返回 `401`，并附带消息\*\*"Your plan does not have management API quota"\*\*（或 Zapier/MCP 专属的等价消息），说明您的套餐不包含该配额。目前，标准 Pro 套餐并不包含 Management API 访问权限——只有 Free Trial、Enterprise 和 Internal 套餐才包含。如果您认为自己的账户应当拥有该权限，请联系 [support@scanova.io](mailto:support@scanova.io)。
</Note>

<Warning>
  `sandbox` 仅仅是一个标签和配额层面的概念——它**并不是**一个隔离的测试环境。使用 `environment: sandbox` 创建的密钥，读写的是与 `live` 密钥相同的真实二维码、文件夹和线索数据。请不要依赖它来存放可随意丢弃的测试数据。
</Warning>

`zapier`/`mcp` 密钥还要求调用方客户端的 `User-Agent` 请求头与其 environment 相匹配才能通过身份验证——`zapier` 密钥会拒绝除 `User-Agent: zapier` 之外的请求，`mcp` 密钥同理。这一规则独立于上文所述的配额检查，单独强制执行。

## 本节内容

<CardGroup cols={2}>
  <Card title="创建一个 API 令牌" icon="key" href="/zh/api-reference/management-api/tokens/create">
    `POST /console/token/` —— 为选定的 environment 生成一个新密钥。
  </Card>

  <Card title="移除一个 API 令牌" icon="trash" href="/zh/api-reference/management-api/tokens/remove">
    `DELETE /console/token/{key}/` —— 立即吊销一个密钥。
  </Card>

  <Card title="用量统计" icon="chart-line" href="/zh/api-reference/management-api/tokens/usage-stats">
    `GET /console/usage/` —— 滚动时间窗口内的请求次数。
  </Card>

  <Card title="列出二维码" icon="qrcode" href="/zh/api-reference/management-api/qr/list">
    `GET /qr/` —— 大多数集成项目着手使用的核心数据端点。
  </Card>

  <Card title="创建二维码" icon="qrcode" href="/zh/api-reference/management-api/qr/create">
    `POST /qr/` —— 大多数集成项目着手使用的核心数据端点。
  </Card>
</CardGroup>

完整列表请见侧边栏，包括获取/更新/删除单个二维码、下载二维码图片，以及浏览回收站。

## 相关内容

* [API 参考简介](/zh/api-reference/getting-started/introduction) —— 本概览所属的上级章节。
* [创建一个 API 令牌](/zh/api-reference/management-api/tokens/create) —— 生成整个 API 接口面据以进行身份验证的密钥。
* [列出二维码](/zh/api-reference/management-api/qr/list) —— 大多数集成项目着手使用的核心数据端点。
* [创建二维码](/zh/api-reference/management-api/qr/create) —— 大多数集成项目着手使用的核心数据端点。
* [MCP 概览](/zh/mcp/overview) —— 一个完全构建于同一 API 之上的集成，使用专属的 `mcp` environment。