跳到主要内容
Rex,您的 AI 助手:繁琐工作交给它,创意由您做主 👉 认识 Rex

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 格式:

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 参考文档。设置 > 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 页面会向拥有 所有者、管理员 或 经理 角色的用户显示。令牌的权限永远不会超过创建它的用户。

需要帮助?

仍需要帮助?

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

  • 与我们聊天

    登录后点击右下角的聊天按钮。Rex 会立即回复,我们的团队也只需一键即可联系。

  • 预约会议

    与我们的团队进行免费 30 分钟视频通话:产品演示、活动创意或设置协助。

  • 给我们发邮件

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