借助 Scratcher REST API,您自己的系统可以读取您的活动、潜在客户和列表,添加和更新潜在客户,以及管理产品和投放位置。本文面向负责设置的开发人员。
API 包含在提供 Webhooks 和 API 的套餐中(Basic 及以上)。在其他套餐中,创建令牌和应用的按钮会被锁定。
创建个人访问令牌
个人访问令牌是从您自己的脚本和系统调用 API 的最快方式。
- 前往 设置 > API(在 开发者 下)。
- 在 个人访问令牌 下,点击 创建个人访问令牌。对话框中写着:“生成用于验证 API 请求的令牌。”
- 填写一个之后便于识别的 名称,例如“数据仓库”。
- 在 权限范围 下,选择该令牌可以执行的操作(见下文)。全选 会选中所有权限范围。请只授予令牌所需的访问权限。
- 点击 保存。您会看到“您的访问令牌已创建”。
- 复制 密钥 下的令牌。“请保存上面的密钥,这是您唯一一次能看到它。”请妥善保管,例如保存在密码管理器中。
- 点击 关闭。
令牌归属于您的用户。它可以按照您选择的权限范围,访问您所属的每一个 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 应用,而不是使用个人令牌。
- 前往 设置 > API。在 我的应用 下,点击 创建应用(“为 API 注册 OAuth 应用。”)。
- 填写 应用名称(用户在批准您的应用时会看到它)和 重定向 URI(用户批准后返回的地址)。
- 点击 保存。您会看到“您的应用已创建!”,以及 客户端 ID 和 客户端密钥。
- 立即复制客户端密钥:“请保存上面的客户端密钥,这是您唯一一次能看到它。”点击 继续。
您的应用会将用户带到 https://platform.scratcher.io/oauth/authorize,并附上您的客户端 ID、重定向 URI 以及所需的权限范围。用户登录 Scratcher 后会看到 授权请求:“此应用将能够:”,后面列出各项权限范围。用户点击 授权 或 取消。随后,您的应用在 https://platform.scratcher.io/oauth/token 用授权码换取令牌。
- 通过 OAuth 获得的访问令牌有效期为两个月。刷新令牌有效期为三个月;可用它获取新的访问令牌。
- 如需更改名称或重定向 URI,请点击 我的应用 下的该应用,修改后点击 保存(“您的设置已保存”)。“之后您将无法再查看密钥。”
- 删除应用 会移除该应用,所有用户与它的连接都会失效:“确定要删除此应用吗?此操作无法撤销!”
您已批准的应用
已授权的应用 列出了您已授予账户访问权限的应用(例如 Zapier)及其拥有的权限范围。点击 撤销 即可收回访问权限。
谁可以使用 API?
API 页面会向拥有 所有者、管理员 或 经理 角色的用户显示。令牌的权限永远不会超过创建它的用户。