API 对接文档
Public reference for the SocialProof API. Sign in to see your own key and pre-filled samples.
鉴权
每个 /api/v1/* endpoint authenticates with an API key and only ever returns data from that account. Replace the placeholder below with a key from Account → API keys. These two forms are equivalent:
Authorization: Bearer YOUR_API_KEY X-API-Key: YOUR_API_KEY
限流:每个 Key 每分钟 600 次,超限返回 429。
读取接口
| 方法 | 路径 | 说明 | 主要参数 |
|---|---|---|---|
| GET | /api/v1/me | 账号与套餐、配额用量 | 无 |
| GET | /api/v1/campaigns | Campaign 列表 | 无 |
| GET | /api/v1/notifications | 小部件列表与各自的计数器 | campaign_id |
| GET | /api/v1/leads | 线索(邮箱、姓名、电话、自定义字段) | campaign_id, notification_id, since, until, limit, offset |
| GET | /api/v1/events | 原始埋点事件 | type, campaign_id, notification_id, since, until, limit, offset |
| GET | /api/v1/stats | 按天聚合的展示、点击、关闭与转化 | days=7|14|30|90 |
时间参数一律用 UTC,格式为 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS;limit 上限 1000。
你的 API 密钥
这一页上印的是账号钥匙。它一直可用;此外你还可以创建带作用域的钥匙,每个对接方一把,停用其中一把不会影响其它。
| 作用域 | 允许做什么 |
|---|---|
| read | 上面所有读取接口 |
| write | 读取数据的全部权限,另外还能新建与修改 Campaign、小部件、线索与转化 |
| delete | 写入数据的全部权限,另外还能删除 Campaign 与小部件 |
用了作用域不足的钥匙,调用会以错误 insufficient_scope 结束 —— 出问题时原因永远是明确的。
写操作端点
这些地址需要带对应作用域的钥匙。请求体用 JSON 发送,Content-Type 设为 application/json。
| 方法 | 路径 | 作用域 | 说明 |
|---|---|---|---|
| POST | /api/v1/campaigns | write | 创建 Campaign |
| PUT | /api/v1/campaigns/{id} | write | 修改名称、域名或启用状态 |
| 删除 | /api/v1/campaigns/{id} | delete | 删除 Campaign,连同它下面所有小部件 |
| POST | /api/v1/notifications | write | 在某个 Campaign 下建一个小部件 |
| PUT | /api/v1/notifications/{id} | write | 修改名称、设置项或启用状态 |
| 删除 | /api/v1/notifications/{id} | delete | 删除小部件,连同它的事件与线索 |
| POST | /api/v1/leads | write | 把外部系统里的线索推进来 |
| POST | /api/v1/conversions | write | 从自己的后端回传一次转化 |
有些共享主机会在请求到达 PHP 之前就拦掉 PUT 与 DELETE。遇到这种主机,改用 POST 并带上查询参数 _method=PUT —— 请求体的读法与原来完全一样。
示例:回传一次转化
curl -s -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"notification_id": 1, "order_id": "ORDER-10231", "value": "49.90", "currency": "USD"}' \
"https://www.ccroo.com/api/v1/conversions"
同一个 order_id 重复回传是安全的:第二次会带 duplicate=true 返回,而不会把成交算两遍。
示例:拉取本月线索
curl -s \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://www.ccroo.com/api/v1/leads?since=2026-11-01&limit=100"
const res = await fetch(
"https://www.ccroo.com/api/v1/leads?since=2026-11-01&limit=100",
{ headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { data } = await res.json();
console.log(data.total, data.leads.length);
<?php
$ch = curl_init("https://www.ccroo.com/api/v1/leads?limit=100");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"],
]);
$json = json_decode(curl_exec($ch), true);
foreach ($json["data"]["leads"] as $lead) {
echo $lead["email"], PHP_EOL;
}
埋点与转化回传
下面两个端点靠随机 Key 鉴权,不需要 API Key,适合放在你的网站与服务端。
1. 嵌入像素
<script defer src="https://www.ccroo.com/pixel/your-pixel-key.js"></script>
2. 服务端回传转化
支付成功、注册成功之后调一次即可。
curl -s -X POST "https://www.ccroo.com/webhook/your-notification-key" \
-H "Content-Type: application/json" \
-d '{"order_id":"SO-10086","amount":"199.00","currency":"USD"}'
去重规则:同一小部件下、请求体完全相同的转化只计一次,重复提交会返回 duplicate。建议把订单号放进 order_id。
支付与订阅
结算是跳转到安全的托管支付页完成的,支持信用卡等主流支付方式。支付信息在支付服务商那边填写,不会经过本站服务器。
付款成功后,本账号的订阅会自动开通,无需人工激活。套餐、到期日和支付状态都从支付服务商回读,所以「订阅与账单」里显示的永远是真实扣款结果。
- 套餐、到期日与发票 —— 都在「订阅与账单」里,每次扣款一张发票。
- 支付通知 —— 每条事件都带唯一 ID,同一条通知重复送达只会被忽略,不会重复记账。
- 套餐变更 —— 升级立即生效,降级在当前周期结束后生效。