17. 集成 API 与 API 密钥

集成 API 可以让你自己的程序、电子表格或脚本以机器方式读取项目数据：项目列表、电缆和材料清单、配电箱的回路表和端子清单、工程量统计以及图纸包的组成。该 API 只读：不会修改图纸和项目。

谁可以获得 API 密钥

API 密钥由运营方按账户启用。账户获得权限后，个人资料页面会显示 API 密钥卡片；没有权限时该卡片不会显示。一个账户同时最多可以有 5 个有效密钥。

密钥看到的项目与你自己看到的相同：你自己的项目，以及按请求共享给你的项目。对于共享项目，只有在共享设置允许导出时，才会返回其清单和统计。

创建密钥

在个人资料页面的 API 密钥卡片上，点击新建密钥按钮。
为密钥起一个名称（例如将要使用它的程序的名称）。
选择权限范围：读取项目提供项目列表和项目数据，读取文档提供清单、统计和图纸包。只选择程序真正需要的权限。
选择有效期：30、90 或 365 天。过期的密钥不再有效，请改为创建新的密钥。
输入你当前的密码（没有密码的账户需要重新登录）。创建第一个密钥时，请接受 API 使用条款。

创建之后，密钥只显示一次：请复制并保存在安全的地方。之后列表中只显示它的前缀（avk_…），以及创建和到期日期、最近一次使用和调用次数。我们还会就新密钥发送电子邮件通知（不含密钥本身）。

撤销密钥

点击卡片上密钥旁边的撤销按钮，该密钥会立即失效；此操作无法撤回。当你不再使用某个密钥、停用了使用它的程序，或怀疑它已泄露时，请撤销该密钥。

安全建议

把密钥当作密码来对待：任何知道它的人都可以在其权限范围内读取你的项目。
请存放在密钥存储中（密码管理器、服务器的环境变量或 CI 的机密变量），而不是源代码里：不要提交到 git 仓库，也不要放进共享的电子表格或电子邮件。
不要在浏览器中运行的代码里使用（网页、浏览器扩展）：在那里任何人都可以读取它。密钥应放在服务器、脚本或桌面程序中。
让每个程序都有自己的密钥，权限范围尽量窄，有效期尽量短；这样撤销一个密钥不会让其他程序停止工作。

在程序中使用

密钥以 Bearer 令牌的形式放在请求头中发送：Authorization: Bearer avk_…。接口位于 /api/v1/ 之下（例如 GET /api/v1/projects），返回 JSON。OpenAPI 格式的完整说明可在 /api/v1/openapi.json 获取；大多数开发工具都可以导入它。

调用次数按密钥和按账户分别限制（默认每分钟 60 次，每天 10,000 次）；超过限制时服务器返回 429，此时请稍等片刻。通过网站登录（Cookie）不会开放 API，密钥也不能用来登录网页界面。