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/campaignsCampaign 列表无
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/campaignswrite创建 Campaign
PUT/api/v1/campaigns/{id}write修改名称、域名或启用状态
删除/api/v1/campaigns/{id}delete删除 Campaign,连同它下面所有小部件
POST/api/v1/notificationswrite在某个 Campaign 下建一个小部件
PUT/api/v1/notifications/{id}write修改名称、设置项或启用状态
删除/api/v1/notifications/{id}delete删除小部件,连同它的事件与线索
POST/api/v1/leadswrite把外部系统里的线索推进来
POST/api/v1/conversionswrite从自己的后端回传一次转化

有些共享主机会在请求到达 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。

支付与订阅

结算是跳转到安全的托管支付页完成的,支持信用卡等主流支付方式。支付信息在支付服务商那边填写,不会经过本站服务器。

付款成功后,本账号的订阅会自动开通,无需人工激活。套餐、到期日和支付状态都从支付服务商回读,所以「订阅与账单」里显示的永远是真实扣款结果。