如何使用工作区 API Key

工作区 API Key 让你可以程序化地访问自己的证言——读取、审核、从外部源创建、或与自有产品同步。对于希望超越内置嵌入小组件的开发者来说,这就是那个集成入口。

生成 API Key

第 1 步:打开工作区管理后台

第 2 步:生成 Key

点击 Generate API Key。完整的 key 只会显示一次——请立即复制并存储到密码管理器或密钥保险库等安全位置。

离开页面后,页面上只会显示 key 的前 10 个字符。如果丢失,必须重新生成——旧 key 会随之失效。

第 3 步:安全存储

不要把 API Key 放在:

客户端 JavaScript 里(会在浏览器中可见)
公开的 GitHub 仓库
共享的 Slack 频道或文档

请把它存放在:

服务器的环境变量里(process.env.SPR_API_KEY)
密钥管理器(AWS Secrets Manager、HashiCorp Vault、Doppler)
Cloud Functions 的 Firebase Secret Manager

认证

每次请求都在 Authorization 头中以 Bearer token 的形式带上 API Key:

Authorization: Bearer YOUR_API_KEY

所有 API 请求必须通过 HTTPS。HTTP 请求会被拒绝。

Base URL

https://api.socialproof.reviews/v1

所有接口都会根据 API Key 自动限定在你的工作区范围内。

核心接口

列出证言

获取工作区中的所有证言:

GET /testimonials
Authorization: Bearer YOUR_API_KEY

可选查询参数:

参数	类型	说明
`approved`	boolean	按审核状态过滤
`rating`	number	按最低星级过滤(1–5)
`limit`	number	返回条数(默认 20,最多 100)
`offset`	number	分页偏移量

示例响应:

{
  "data": [
    {
      "id": "t_abc123",
      "reviewer": {
        "name": "Sarah Chen",
        "email": "[email protected]",
        "jobTitle": "Product Manager",
        "company": "TechCorp"
      },
      "rating": 5,
      "review": "Incredible tool. We embedded the wall on our homepage and saw a 23% lift in demo requests.",
      "approved": true,
      "submittedAt": "2026-03-10T14:22:00Z",
      "photos": [],
      "videoUrl": null
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

获取单条证言

GET /testimonials/:id
Authorization: Bearer YOUR_API_KEY

审核通过一条证言

PATCH /testimonials/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "approved": true
}

创建一条证言

从外部源导入证言(CSV 导入、旧平台迁移或完成的调查问卷):

POST /testimonials
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "reviewer": {
    "name": "Marcus Webb",
    "email": "[email protected]",
    "jobTitle": "CEO",
    "company": "Acme Corp"
  },
  "rating": 5,
  "review": "We replaced our old review widget within a day. The setup was seamless.",
  "approved": false,
  "source": "import"
}

删除一条证言

DELETE /testimonials/:id
Authorization: Bearer YOUR_API_KEY

成功返回 204 No Content。

代码示例

Node.js(fetch)

const SPR_API_KEY = process.env.SPR_API_KEY;

async function getApprovedTestimonials() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&limit=10',
    {
      headers: {
        'Authorization': `Bearer ${SPR_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );
  const data = await res.json();
  return data.data;
}

Python(requests)

import os
import requests

api_key = os.environ['SPR_API_KEY']
headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(
    'https://api.socialproof.reviews/v1/testimonials',
    headers=headers,
    params={'approved': 'true', 'rating': 5}
)
testimonials = response.json()['data']

cURL

curl -X GET \
  "https://api.socialproof.reviews/v1/testimonials?approved=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

常见集成模式

把证言拉到自己的网站

如果你需要完全自定义设计、嵌入小组件无法满足,可以从 API 拉取并自己渲染:

// Next.js 服务端示例
export async function getStaticProps() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&rating=5',
    { headers: { Authorization: `Bearer ${process.env.SPR_API_KEY}` } }
  );
  const { data } = await res.json();
  return { props: { testimonials: data }, revalidate: 3600 };
}

用 Webhook + API 自动审核高评分证言

把 Webhook 触发器与 API 结合,构建一个完全自动化的审核流程:

证言提交时,Webhook 触发
你的服务器收到载荷
如果 rating === 5,调用 PATCH /testimonials/:id 把 approved 置为 true
证言会立即出现在证言墙上

同步到 CRM

在证言提交后,用 API 拉取完整记录并作为客户备注或活动推送到 CRM:

// 由 Webhook 处理器触发
async function syncToCRM(testimonialId) {
  const testimonial = await fetchTestimonial(testimonialId);
  await crm.createNote({
    contactEmail: testimonial.reviewer.email,
    note: `Left a ${testimonial.rating}-star testimonial: "${testimonial.review}"`,
    date: testimonial.submittedAt,
  });
}

速率限制

套餐	每分钟请求数	每天请求数
Starter	30	1,000
Pro	120	10,000
Agency	300	50,000

超出速率限制的请求会收到 429 Too Many Requests 响应。请在集成中实现指数退避。

错误码参考

状态码	含义
`200`	成功
`201`	已创建
`204`	已删除
`400`	请求错误——请检查请求体
`401`	API Key 无效或缺失
`403`	该 Key 无权执行此操作
`404`	未找到对应证言
`429`	超过速率限制
`500`	服务器错误——请重试