---
title: "REST API 入门"
description: "创建具有合适权限范围的个人访问令牌，或注册 OAuth 应用，即可从您自己的系统读取活动、潜在客户和列表。"
url: https://scratcher.io/zh/help/developers/rest-api
language: zh-Hans
---

1. [帮助中心](https://scratcher.io/zh/help)
2. [API、Webhook 与 MCP](https://scratcher.io/zh/help/developers)
3. REST API 入门

# REST API 入门

创建具有合适权限范围的个人访问令牌，或注册 OAuth 应用，即可从您自己的系统读取活动、潜在客户和列表。

借助 Scratcher REST API，您自己的系统可以读取您的活动、潜在客户和列表，添加和更新潜在客户，以及管理产品和投放位置。本文面向负责设置的开发人员。

API 包含在提供 **Webhooks 和 API** 的套餐中（Basic 及以上）。在其他套餐中，创建令牌和应用的按钮会被锁定。

## 创建个人访问令牌

个人访问令牌是从您自己的脚本和系统调用 API 的最快方式。

1. 前往 **设置** > **API**（在 **开发者** 下）。
2. 在 **个人访问令牌** 下，点击 **创建个人访问令牌**。对话框中写着：“生成用于验证 API 请求的令牌。”
3. 填写一个之后便于识别的 **名称**，例如“数据仓库”。
4. 在 **权限范围** 下，选择该令牌可以执行的操作（见下文）。**全选** 会选中所有权限范围。请只授予令牌所需的访问权限。
5. 点击 **保存**。您会看到“您的访问令牌已创建”。
6. 复制 **密钥** 下的令牌。“请保存上面的密钥，这是您唯一一次能看到它。”请妥善保管，例如保存在密码管理器中。
7. 点击 **关闭**。

令牌归属于您的用户。它可以按照您选择的权限范围，访问您所属的每一个 Scratcher 账户。

## 权限范围

- `read:campaigns`（**查看活动**）：列出和读取活动
- `read:lists`（**查看列表**）：列出和读取潜在客户列表
- `read:leads`（**查看潜在客户**）：读取潜在客户
- `write:leads`（**写入潜在客户**）：在列表中创建、更新和删除潜在客户
- `read:placements`（**查看投放位置**）：读取投放位置
- `write:placements`（**写入投放位置**）：创建、更新和删除投放位置
- `read:products`（**查看产品**）：读取产品
- `write:products`（**写入产品**）：创建、更新和删除产品

要读取某个活动的潜在客户，令牌需要同时拥有 `read:campaigns` 和 `read:leads`。创建和更改投放位置还需要您的套餐包含 **嵌入 / URL**。

## 撤销令牌

点击列表中的令牌，打开 **显示个人访问令牌**。其中会显示 **名称** 和 **权限范围**。点击 **撤销** 并确认（“确定要删除此令牌吗？此操作无法撤销！”）。所有使用该令牌的程序都会立即停止工作。

## 发送请求

基础 URL 为 `https://platform.scratcher.io/api/v1/`。在 `Authorization` 请求头中发送令牌，并请求 JSON 格式：

```text
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
```

## 主要端点

- `GET /me`：令牌所属的用户
- `GET /accounts`：您有权访问的账户。在其他调用中使用账户 id。
- `GET /accounts/{account}/campaigns` 和 `/campaigns/{campaign}`：您的活动
- `GET /accounts/{account}/campaigns/{campaign}/leads`：某个活动的潜在客户，按从新到旧排列，包含其字段、已接受的同意项，以及中奖者的奖品和代码
- `GET /accounts/{account}/lists` 和 `/lists/{list}`：您的潜在客户列表
- `/accounts/{account}/lists/{list}/leads`：某个列表的潜在客户。`GET` 用于读取，`POST` 用于创建，`PUT` 用于更新，`DELETE` 用于删除。潜在客户包含 `email`、`phone_number` 以及可选的 `custom_token`。
- `/accounts/{account}/products`：产品（`GET`、`POST`、`PUT`、`DELETE`）
- `/accounts/{account}/placements`：投放位置（`GET`、`POST`、`PUT`、`DELETE`）

列表是分页的：添加 `?page=2` 等参数即可。您只能访问您所属的账户；其他账户 id 会返回错误。

## 限制

每位用户每分钟最多可发送 60 个请求。超出后，API 会返回状态码 429；请稍等片刻再试。

## API 参考

包含所有字段、筛选器、示例以及 Postman 集合的完整参考，请参阅 [API 参考文档](https://platform.scratcher.io/docs/index.html)。**设置** > **API** 顶部的 **API 参考** 按钮也会链接到该文档。

## 使用 OAuth 构建应用

如果您构建的应用需要让其他 Scratcher 用户连接到他们自己的账户，请注册 OAuth 应用，而不是使用个人令牌。

1. 前往 **设置** > **API**。在 **我的应用** 下，点击 **创建应用**（“为 API 注册 OAuth 应用。”）。
2. 填写 **应用名称**（用户在批准您的应用时会看到它）和 **重定向 URI**（用户批准后返回的地址）。
3. 点击 **保存**。您会看到“您的应用已创建！”，以及 **客户端 ID** 和 **客户端密钥**。
4. 立即复制客户端密钥：“请保存上面的客户端密钥，这是您唯一一次能看到它。”点击 **继续**。

您的应用会将用户带到 `https://platform.scratcher.io/oauth/authorize`，并附上您的客户端 ID、重定向 URI 以及所需的权限范围。用户登录 Scratcher 后会看到 **授权请求**：“此应用将能够：”，后面列出各项权限范围。用户点击 **授权** 或 **取消**。随后，您的应用在 `https://platform.scratcher.io/oauth/token` 用授权码换取令牌。

- 通过 OAuth 获得的访问令牌有效期为两个月。刷新令牌有效期为三个月；可用它获取新的访问令牌。
- 如需更改名称或重定向 URI，请点击 **我的应用** 下的该应用，修改后点击 **保存**（“您的设置已保存”）。“之后您将无法再查看密钥。”
- **删除应用** 会移除该应用，所有用户与它的连接都会失效：“确定要删除此应用吗？此操作无法撤销！”

## 您已批准的应用

**已授权的应用** 列出了您已授予账户访问权限的应用（例如 Zapier）及其拥有的权限范围。点击 **撤销** 即可收回访问权限。

## 谁可以使用 API？

**API** 页面会向拥有 **所有者**、**管理员** 或 **经理** 角色的用户显示。令牌的权限永远不会超过创建它的用户。

API、Webhook 与 MCP

- [REST API 入门](https://scratcher.io/zh/help/developers/rest-api)
- [通过 Webhooks 将数据发送到您的系统](https://scratcher.io/zh/help/developers/webhooks)
- [用于你自己 AI 工具的 Scratcher MCP](https://scratcher.io/zh/help/developers/mcp)

继续学习

## 相关文章

- [通过 Webhooks 将数据发送到您的系统](https://scratcher.io/zh/help/developers/webhooks): 当有人报名、参与或中奖时，向您自己的 URL 发送请求，支持签名负载、基本身份验证、自定义负载，并记录每一次发送。
- [用于你自己 AI 工具的 Scratcher MCP](https://scratcher.io/zh/help/developers/mcp): 使用 MCP 将 Claude、ChatGPT 和其他 AI 工具连接到你的 Scratcher 账户。本文介绍如何设置，以及你的 AI 能做什么。
- [通过 Zapier 连接 8,000 多款应用](https://scratcher.io/zh/help/integrations/zapier): 借助 Zapier，将 Scratcher 的新注册用户发送到 Google Sheets、Slack、您的 CRM 或成千上万款其他应用。

需要帮助？

## 仍需要帮助？

真人团队随时为您提供帮助。如果您已在使用 Scratcher，最快的方式是使用平台内的聊天功能。

- **[与我们聊天](https://platform.scratcher.io/zh-Hans/login)**

    登录后点击右下角的聊天按钮。Rex 会立即回复，我们的团队也只需一键即可联系。
- **[预约会议](https://scratcher.io/zh/book-a-meeting)**

    与我们的团队进行免费 30 分钟视频通话：产品演示、活动创意或设置协助。
- **[给我们发邮件](mailto:contact@scratcher.io)**

    发送邮件至 contact@scratcher.io，我们会尽快回复您。
