对接文档
CPS 开放平台提供推广位管理、订单查询、流量查询与结算账单四类能力。 所有接口均为 HTTPS + JSON,用 accessKey / secret 做 HMAC 签名。
快速开始
三步接入:拿到密钥 → 拼签名 → 调 /ping 验证连通。
1. 拿到 accessKey 与 secret
由平台方在后台创建。secret 只在创建时展示一次,请存进服务端配置或密钥管理系统, 不要写进前端代码、不要提交到 Git。
2. 每个请求带上四个头
| 请求头 | 说明 |
|---|---|
| X-Ak | 你的 accessKey |
| X-Ts | 当前 Unix 时间戳(秒,不是毫秒) |
| X-Nonce | 随机串,8–64 位,10 分钟内不可重复 |
| X-Sign | 见下方签名算法 |
3. 先打一次 ping
返回你的客户编码、绑定的媒体位和限流额度。这一步通了,后面都不会有问题。 可以直接用页面下方的调试台。
签名与鉴权
签名内容是一段四行的字符串,用 secret 做 HMAC-SHA256,输出小写十六进制:
accessKey + "\n" + timestamp + "\n" + nonce + "\n" + 请求体原始字节
JSON.stringify(body) 存成字符串,签名和发送都用这一个字符串。
4004。
这是对接中最常见的一个坑。
Node.js
const crypto = require('crypto');
const AK = process.env.CPS_AK;
const SK = process.env.CPS_SK;
function call(path, body) {
const ts = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(8).toString('hex');
const raw = JSON.stringify(body);
const sign = crypto.createHmac('sha256', SK)
.update([AK, ts, nonce, raw].join('\n'))
.digest('hex');
return fetch('https://your-host/open/v1' + path, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Ak': AK, 'X-Ts': ts, 'X-Nonce': nonce, 'X-Sign': sign
},
body: raw
}).then(r => r.json());
}
Python
import hmac, hashlib, json, os, secrets, time, requests
AK, SK = os.environ["CPS_AK"], os.environ["CPS_SK"]
def call(path, body):
ts = str(int(time.time()))
nonce = secrets.token_hex(8)
raw = json.dumps(body, separators=(",", ":"), ensure_ascii=False)
payload = "\n".join([AK, ts, nonce, raw])
sign = hmac.new(SK.encode(), payload.encode(), hashlib.sha256).hexdigest()
r = requests.post("https://your-host/open/v1" + path,
data=raw.encode("utf-8"),
headers={"Content-Type": "application/json", "X-Ak": AK,
"X-Ts": ts, "X-Nonce": nonce, "X-Sign": sign})
return r.json()
curl
TS=$(date +%s)
NONCE=$(openssl rand -hex 8)
BODY='{"startTime":"2026-11-01 00:00:00","endTime":"2026-12-01 00:00:00"}'
SIGN=$(printf '%s\n%s\n%s\n%s' "$CPS_AK" "$TS" "$NONCE" "$BODY" \
| openssl dgst -sha256 -hmac "$CPS_SK" -r | cut -d' ' -f1)
curl -X POST "https://your-host/open/v1/orders/query" \
-H "Content-Type: application/json" \
-H "X-Ak: $CPS_AK" -H "X-Ts: $TS" -H "X-Nonce: $NONCE" -H "X-Sign: $SIGN" \
-d "$BODY"
4006)。
错误码
响应体固定为 { code, msg, reqId },
code === "0" 表示成功。出错时 HTTP 状态码也会相应变化,
但请以 code 字段为准做判断。排障时把 reqId 提供给平台方即可定位。
| code | HTTP | 含义 | 怎么处理 |
|---|---|---|---|
| 0 | 200 | 成功 | — |
| 4000 | 400 | 请求体不是合法 JSON | 检查是否有尾部逗号、单引号 |
| 4001 | 400 | 参数错误 | 看 msg 里点名的字段 |
| 4002 | 401 | accessKey 无效或已停用 | 确认 AK 没写错、没被轮换 |
| 4003 | 401 | 客户已暂停 | 联系平台方商务 |
| 4004 | 401 | 时间戳偏差超过 300 秒 | 校准服务器时钟,用秒级时间戳 |
| 4005 | 401 | 签名校验失败 | 检查待签串拼法与请求体是否一致 |
| 4006 | 401 | nonce 已被使用 | 每次请求生成新 nonce |
| 4010 | 403 | 尚未绑定媒体位 | 联系平台方开通 |
| 4011 | 400 | 查询命中数超过单次上限 | 缩小时间区间或加推广位条件 |
| 4029 | 429 | 请求过于频繁 | 看 Retry-After 头,退避后重试 |
| 4040 | 404 | 接口路径不存在 | 核对版本前缀 /open/v1 |
| 5000 | 500 | 服务内部错误 | 带 reqId 联系平台方 |
连通性测试
无请求参数。建议在接入第一步、以及每次上线前调用一次。
推广位列表
无请求参数。返回的是你账号范围内的全部推广位,不需要也不能指定别人。
响应示例
{
"code": "0", "msg": "ok", "reqId": "r8f2a…",
"data": {
"total": 2,
"items": [
{ "code": "AAA01", "name": "杭州主城区",
"media_code": "AAA", "status": "active",
"url": "https://…", "note": null }
]
}
}
订单查询
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| startTime* | string | 是 | 创单时间起,含。yyyy-MM-dd HH:mm:ss 或 ISO 8601 均可 |
| endTime* | string | 是 | 创单时间止,不含。跨度不能超过 92 天 |
| promotionCode | string | 否 | 只查某个推广位,如 AAA01 |
| status | string | 否 | waiting 待结算 / adjusted 金额已调整 /
canceled 已取消 / invalid 无效单 |
| page | int | 否 | 从 1 开始,默认 1 |
| pageSize | int | 否 | 默认 50,最大 200 |
ext_order_no 覆盖,
而不是只拉「上次之后的新单」——否则一笔三天后才退款的订单你会一直不知道。
响应示例
{
"code": "0",
"data": {
"page": 1, "pageSize": 50, "total": 222,
"items": [
{
"ext_order_no": "JJ85848F28B34930F6",
"promotion_code": "AAA01",
"order_amount": 109.90,
"settle_amount": 2.60,
"refund_amount": 0.00,
"status": "waiting",
"status_text": "待结算",
"create_time": "2026-11-18T02:31:07.000Z",
"pay_time": "2026-11-18T02:31:40.000Z",
"canceled_time": null
}
]
}
}
订单汇总
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| startTime* | string | 是 | 同订单查询 |
| endTime* | string | 是 | 同订单查询 |
| groupBy | string | 否 | day(默认)或 promotion |
流量查询
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| startDate* | string | 是 | 起始日期,含 |
| endDate* | string | 是 | 结束日期,不含。跨度不能超过 92 天 |
| promotionCode | string | 否 | 只查某个推广位 |
账单列表
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| limit | int | 否 | 返回最近几期,默认 12,最大 36 |
payableAmount,等于该账期内订单
settle_amount 的合计(不含已取消单)。对不上可以直接找平台方。
订单推送
除了主动拉取,平台会在订单状态变化时主动 POST 到你配置的地址。 推荐使用推送而不是轮询:实时性更好,也不会浪费你的调用额度。
eventId 或(data.ext_order_no + event)做去重,
重复推送是正常的,不是故障。
请求格式
平台向你发送 POST,Content-Type: application/json,请求头:
| 请求头 | 说明 |
|---|---|
| X-Cps-Event | 事件类型,如 order.updated |
| X-Cps-Ts | Unix 时间戳(秒) |
| X-Cps-Sign | HMAC-SHA256(secret, X-Cps-Ts + "\n" + 原始请求体),小写十六进制 |
JSON.parse。
如果框架先解析了 JSON 你再 JSON.stringify 回去,键序和空格可能变,签名就对不上。
事件类型
| event | 触发时机 |
|---|---|
| order.created | 新订单产生 |
| order.updated | 订单状态或金额变化(含退款、履约推进) |
| order.canceled | 订单取消 |
推送体
{
"event": "order.updated",
"eventId": "9c1f…",
"occurredAt": "2026-11-19T07:52:10.000Z",
"data": {
"ext_order_no": "JJ85848F28B34930F6",
"promotion_code": "AAA01",
"order_amount": 109.90,
"settle_amount": 2.60,
"refund_amount": 0.00,
"status": "waiting",
"status_text": "待结算",
"create_time": "2026-11-18T02:31:07.000Z",
"pay_time": "2026-11-18T02:31:40.000Z",
"canceled_time": null
}
}
data 的字段与「订单查询」接口返回的订单对象完全一致,
没有任何额外字段,也没有任何上游信息。
验签示例(Node.js)
const crypto = require('crypto');
const express = require('express');
const app = express();
app.post('/cps/callback', express.raw({ type: '*/*' }), (req, res) => {
const raw = req.body.toString('utf8'); // ⚠️ 用原始串验签
const ts = req.header('X-Cps-Ts');
const sign = req.header('X-Cps-Sign');
const expect = crypto.createHmac('sha256', process.env.CPS_HOOK_SECRET)
.update(ts + '\n' + raw).digest('hex');
if (expect !== sign) return res.status(401).send('bad sign');
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).send('stale');
const evt = JSON.parse(raw);
// 按 evt.eventId 去重后落库
console.log(evt.event, evt.data.ext_order_no, evt.data.settle_amount);
res.json({ ok: true }); // 必须尽快 2xx
});
重试与熔断
| 情况 | 平台行为 |
|---|---|
| 你返回 2xx | 视为成功 |
| 你返回 4xx / 5xx | 按 1 → 5 → 15 → 60 → 240 分钟退避重试,共 5 次 |
| 5 次都失败 | 该条标记为放弃,可在后台查看 |
| 端点连续失败 10 次 | 自动暂停该端点并通知平台方,避免持续冲击你的服务 |
| 网络层偶发故障 | 立即重发一次,不计入退避次数 |
字段说明
订单对象
| 字段 | 类型 | 说明 |
|---|---|---|
| ext_order_no | string | 订单唯一标识,20 位。同一笔订单永远返回同一个值,可用于幂等与对账 |
| promotion_code | string | 推广位编码 |
| order_amount | number | 用户实付金额(元),商品页标价口径 |
| settle_amount | number | 该单你的结算金额(元,两位小数)。已扣除退款部分;取消单为 0 |
| refund_amount | number | 该单退款金额(元) |
| status | string | waiting / adjusted / canceled / invalid |
| status_text | string | 状态中文,可直接展示给终端用户 |
| create_time | string | 创单时间,ISO 8601(UTC) |
| pay_time | string | 支付时间,未支付为 null |
| canceled_time | string | 取消时间,未取消为 null |
状态流转
| status | 含义 | 会不会变 |
|---|---|---|
| waiting | 订单有效,等待结算周期 | 可能变 adjusted 或 canceled |
| adjusted | 发生过退款,结算金额已按退款比例下调 | 退款补充后可能再变 |
| canceled | 订单已取消,不产生结算 | 终态 |
| invalid | 无法归属到你的推广位,不计入结算 | 终态 |
settle_amount 为唯一依据。
不要用 order_amount 乘任何比例去算,那样算出来一定对不上。
限流与配额
两层限流同时生效,任一层触发都会返回 4029:
| 维度 | 默认额度 | 说明 |
|---|---|---|
| accessKey | 120 次 / 分钟 | 按密钥计,多个服务共用一个密钥时共享额度 |
| 来源 IP | 600 次 / 分钟 | 防止单一出口打爆 |
被限流时响应会带 Retry-After 头,单位秒。
建议按指数退避重试(1s → 2s → 4s),不要立即重打。
翻页建议
订单查询单次最多 200 条、单次区间最多 92 天、总计最多 2 万条。 做全量对账时请按天切分区间、逐页拉取,不要一次拉一个季度。