检测中…

对接文档

CPS 开放平台提供推广位管理、订单查询、流量查询与结算账单四类能力。 所有接口均为 HTTPS + JSON,用 accessKey / secret 做 HMAC 签名。

REST / JSON HMAC-SHA256 签名 单接口 ±300 秒时钟容差 默认 120 次 / 分钟

快速开始

三步接入:拿到密钥 → 拼签名 → 调 /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 文本,不是解析后再序列化的结果。 顺序、空格、缩进都必须和发送时完全一致,否则签名对不上。 最稳妥的做法是先 JSON.stringify(body) 存成字符串,签名和发送都用这一个字符串。
时间戳必须用秒。用毫秒会导致 ±300 秒校验失败、返回 4004。 这是对接中最常见的一个坑。

Node.js

javascript
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

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

bash
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"
重试要换 nonce。同一个 nonce 用过一次就作废,重试时 timestamp 和 nonce 都要重新生成、重新签名, 否则会被当作重放攻击拒绝(4006)。

错误码

响应体固定为 { code, msg, reqId }, code === "0" 表示成功。出错时 HTTP 状态码也会相应变化, 但请以 code 字段为准做判断。排障时把 reqId 提供给平台方即可定位。

codeHTTP含义怎么处理
0200成功—
4000400请求体不是合法 JSON检查是否有尾部逗号、单引号
4001400参数错误看 msg 里点名的字段
4002401accessKey 无效或已停用确认 AK 没写错、没被轮换
4003401客户已暂停联系平台方商务
4004401时间戳偏差超过 300 秒校准服务器时钟,用秒级时间戳
4005401签名校验失败检查待签串拼法与请求体是否一致
4006401nonce 已被使用每次请求生成新 nonce
4010403尚未绑定媒体位联系平台方开通
4011400查询命中数超过单次上限缩小时间区间或加推广位条件
4029429请求过于频繁看 Retry-After 头,退避后重试
4040404接口路径不存在核对版本前缀 /open/v1
5000500服务内部错误带 reqId 联系平台方

连通性测试

POST /open/v1/ping 验证密钥与网络,返回客户信息与限流额度

无请求参数。建议在接入第一步、以及每次上线前调用一次。

在线调试需要先在右上角填入密钥

推广位列表

POST /open/v1/promotions/list 返回你名下所有推广位与推广链接

无请求参数。返回的是你账号范围内的全部推广位,不需要也不能指定别人。

响应示例
json
{
  "code": "0", "msg": "ok", "reqId": "r8f2a…",
  "data": {
    "total": 2,
    "items": [
      { "code": "AAA01", "name": "杭州主城区",
        "media_code": "AAA", "status": "active",
        "url": "https://…", "note": null }
    ]
  }
}
在线调试无参数

订单查询

POST /open/v1/orders/query 按创单时间分页拉取订单明细
参数类型必填说明
startTime*string是 创单时间起,含。yyyy-MM-dd HH:mm:ss 或 ISO 8601 均可
endTime*string是 创单时间止,不含。跨度不能超过 92 天
promotionCodestring否只查某个推广位,如 AAA01
statusstring否 waiting 待结算 / adjusted 金额已调整 / canceled 已取消 / invalid 无效单
pageint否从 1 开始,默认 1
pageSizeint否默认 50,最大 200
按创单时间筛,不是按更新时间。退款、取消这类后续变更不会改变订单的创单时间, 所以如果你想持续对账,建议每天都把最近 7 天重新拉一遍并按 ext_order_no 覆盖, 而不是只拉「上次之后的新单」——否则一笔三天后才退款的订单你会一直不知道。
响应示例
json
{
  "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
      }
    ]
  }
}
在线调试时间区间默认最近 7 天

订单汇总

POST /open/v1/orders/summary 按天或按推广位聚合,做报表直接用这个
参数类型必填说明
startTime*string是同订单查询
endTime*string是同订单查询
groupBystring否day(默认)或 promotion
在线调试默认最近 7 天按天

流量查询

POST /open/v1/traffic/query 按天返回曝光、登录、下单人数
参数类型必填说明
startDate*string是起始日期,含
endDate*string是结束日期,不含。跨度不能超过 92 天
promotionCodestring否只查某个推广位
流量是 T+1 的。今天查不到今天的数据,最早只能看到昨天。 如果你在跑日报,请在次日上午之后拉取。
在线调试默认最近 2 天

账单列表

POST /open/v1/bill/list 按账期返回应结金额与结算状态
参数类型必填说明
limitint否返回最近几期,默认 12,最大 36
账单金额与订单明细始终一致。 任意一期账单的 payableAmount,等于该账期内订单 settle_amount 的合计(不含已取消单)。对不上可以直接找平台方。
在线调试默认最近 12 期

订单推送

除了主动拉取,平台会在订单状态变化时主动 POST 到你配置的地址。 推荐使用推送而不是轮询:实时性更好,也不会浪费你的调用额度。

投递语义是「至少一次」。网络重试可能导致同一条推送重复到达。 请按 eventId 或(data.ext_order_no + event)做去重, 重复推送是正常的,不是故障。

请求格式

平台向你发送 POST,Content-Type: application/json,请求头:

请求头说明
X-Cps-Event事件类型,如 order.updated
X-Cps-TsUnix 时间戳(秒)
X-Cps-SignHMAC-SHA256(secret, X-Cps-Ts + "\n" + 原始请求体),小写十六进制
验签要用原始请求体字符串。先把 body 读成字符串、验签,再 JSON.parse。 如果框架先解析了 JSON 你再 JSON.stringify 回去,键序和空格可能变,签名就对不上。

事件类型

event触发时机
order.created新订单产生
order.updated订单状态或金额变化(含退款、履约推进)
order.canceled订单取消

推送体

json
{
  "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)

javascript
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 次自动暂停该端点并通知平台方,避免持续冲击你的服务
网络层偶发故障立即重发一次,不计入退避次数
请务必在 8 秒内返回 2xx。处理逻辑建议先落库再异步处理,不要在这个接口里做重活。 超时会被当成失败,进而触发重试,最后你的服务会被同一批数据压垮。
推送地址与密钥由平台方在后台配置并提供。如需更换地址或轮换密钥,联系对接人即可, 平台方会保证切换期间旧地址仍可用。

字段说明

订单对象

字段类型说明
ext_order_nostring订单唯一标识,20 位。同一笔订单永远返回同一个值,可用于幂等与对账
promotion_codestring推广位编码
order_amountnumber用户实付金额(元),商品页标价口径
settle_amountnumber该单你的结算金额(元,两位小数)。已扣除退款部分;取消单为 0
refund_amountnumber该单退款金额(元)
statusstringwaiting / adjusted / canceled / invalid
status_textstring状态中文,可直接展示给终端用户
create_timestring创单时间,ISO 8601(UTC)
pay_timestring支付时间,未支付为 null
canceled_timestring取消时间,未取消为 null

状态流转

status含义会不会变
waiting订单有效,等待结算周期可能变 adjusted 或 canceled
adjusted发生过退款,结算金额已按退款比例下调退款补充后可能再变
canceled订单已取消,不产生结算终态
invalid无法归属到你的推广位,不计入结算终态
金额以 settle_amount 为唯一依据。 不要用 order_amount 乘任何比例去算,那样算出来一定对不上。

限流与配额

两层限流同时生效,任一层触发都会返回 4029:

维度默认额度说明
accessKey120 次 / 分钟按密钥计,多个服务共用一个密钥时共享额度
来源 IP600 次 / 分钟防止单一出口打爆

被限流时响应会带 Retry-After 头,单位秒。 建议按指数退避重试(1s → 2s → 4s),不要立即重打。

翻页建议

订单查询单次最多 200 条、单次区间最多 92 天、总计最多 2 万条。 做全量对账时请按天切分区间、逐页拉取,不要一次拉一个季度。