将应用连接到 API
创建 API 密钥，授权 Zapier 等应用，并控制它们可以访问的内容。
面向高级用户
本页面介绍 ITB 面向开发者的部分：API 密钥和 OAuth 应用连接。如果您只是想在发生事件时将数据推送到其他工具，请先参阅 Webhooks。
外部应用可以通过 Go Toolbelt 外部 API 以两种方式访问您的账户：
- API 密钥——您创建一个密钥，粘贴到自己的脚本或需要密钥的工具中。最适合服务器到服务器的集成和自定义软件。
- OAuth——Zapier 等应用会把您带到 ITB 的授权页面，您只需一次点击即可批准访问。无需处理密钥。
开始之前
- API 密钥和 webhooks 位于 设置集成。
- API 密钥操作的是您自己账户的数据。它只获得您在创建时选择的权限，而且几乎所有权限都是只读的（唯一的例外是 webhook 管理）。
- 您最多可以同时拥有 10 个有效的 API 密钥。
创建 API 密钥
为密钥命名并选择权限
点击创建 API 密钥。给密钥起一个能说明用途的名字（例如"Zapier 集成"），然后勾选它需要的权限。**订单（只读）和联系人（只读）**是预先选中的；完整列表请参阅下方的权限表。
您应该看到的结果
新密钥出现在 API 密钥列表中，显示名称、权限标记和创建日期。一旦有应用开始使用它，还会显示最后使用日期。
如果您是开发者：向 https://api.gotoolbelt.com/v1/... 发起请求时，在 X-API-Key 请求头中发送密钥。交互式端点文档位于 api.gotoolbelt.com/docs（API 密钥卡片中也有链接）。
撤销 API 密钥
在 API 密钥列表中找到该密钥，点击旁边的垃圾桶按钮。
点击撤销确认。使用此密钥的所有集成会立即停止工作。
通过 OAuth 授权应用
某些应用（Zapier、Make 以及其他已注册的合作伙伴）通过 OAuth 而非 API 密钥连接。从您这边看，流程是这样的：
在外部应用中选择连接您的 ITB / Go Toolbelt 账户。该应用会把您带到 ITB 的授权页面（如果尚未登录，会先要求您登录）。
授权页面显示该应用的名称、您当前登录的账户，以及该应用将能够做什么——例如"查看您的Orders和订单详情"。
点击允许访问批准，或点击拒绝取消。无论哪种，您都会被送回该应用。
应用永远不会获得超出其注册范围的权限——与下方权限表相同的列表。
您不能注册自己的 OAuth 应用
OAuth 应用由 ITB 团队注册，无法从您的账户设置中注册。如果您在为自己构建自定义集成，请改用 API 密钥。
连接 Zapier 或 Make
Zapier 和 Make 通过上面的 OAuth 流程连接——在它们的应用目录中搜索 ITB / Go Toolbelt 应用并点击连接。当您设置 Zap 触发器时，Zapier 会自动在您的账户上创建对应的 webhook 订阅，因此您无需自己在 Webhooks 下做任何配置。
可用的 Zapier 触发器有：Order已创建、已批准、已完成、已重新安排和状态已更改，以及发票已支付和Report已发布。具体数据结构记录在 Webhook 事件参考中。
权限参考
以下是 API 密钥或 OAuth 应用可以持有的权限（scope）：
| 权限 | Scope | 允许的操作 |
|---|---|---|
| 订单（只读） | orders:read | 查看Orders及其详情 |
| 联系人（只读） | contacts:read | 查看联系人 |
| 发票与账单（只读） | billing:read | 查看发票和交易 |
| 日历（只读） | calendar:read | 查看日历事件和可用时间 |
| 模板（只读） | templates:read | 查看Report模板 |
| 公司资料（只读） | company:read | 查看您的公司资料 |
| 团队成员（只读） | team:read | 查看团队成员 |
| 通知（只读） | notifications:read | 查看通知设置 |
| Webhooks（只读） | webhooks:read | 查看 webhook 端点配置 |
| Webhooks（管理） | webhooks:write | 创建、更新和删除 webhook 端点 |
除 **Webhooks（管理）**之外的所有权限都是只读的——密钥或已连接的应用永远无法通过 API 创建、更改或删除您的Orders、联系人或发票。
如果出了问题
- 某个集成突然停止工作——检查它的 API 密钥是否被撤销（撤销立即生效），以及该密钥是否拥有该集成所需的全部权限。缺少权限的请求会被拒绝，并返回 "missing required scope" 错误。
- "Invalid API key" 错误——密钥输错了或已被撤销。密钥创建后无法再次查看；请创建一个新的。
- 创建密钥按钮没有反应——需要填写名称并至少勾选一个权限；也可能您已达到 10 个密钥的上限（先撤销一个旧密钥）。
相关内容
- Webhook 事件 — API 发送的每个事件和数据结构
- Webhooks — 在您自己的端点接收实时事件数据
- 集成 — 集成标签页上的全部内容