快手电商开放平台API集成笔记

!!! note "" 快手电商开放平台（open.kuaixiaodian.com）API 集成方案， 基于 Node.js 网关服务，已上线稳定运行。

---

应用信息

鉴权与 Token 管理

OAuth2 接入流程

快手电商 API 采用 access_token + refresh_token 的双 Token 机制：

1. 商家授权 → 获取 auth_code
2. auth_code → access_token（通过 PHP 回调接收并持久化）
3. access_token 自动续期（refresh_token 永不过期，但会在每次刷新时更新）

Token 刷新机制

Token 管理器（token-manager.js）实现了无人值守的自动续期：

access_token 有效期     → 默认 86400s（24h）
提前续期窗口           → 到期前 600s（10分钟）
刷新失败重试间隔       → 5分钟
刷新请求               → POST application/x-www-form-urlencoded

刷新请求参数：

Token 持久化：

刷新后的新 refresh_token 会同步写入两个路径：

• /home/openclaw/clawd/kuaishou-server/data/refresh_token.json — 服务自身使用
• /tmp/kuaishou_refresh_token.json — 给 PHP 回调进程共享

关键密钥

!!! warning "请勿外泄" 以下密钥已从公开渠道移除，仅作字段名示例：

API 签名规范

!!! info "" 签名规范通过反编译快手官方 SDK JAR 逆向分析得出，已用抓包验证一致性。

签名流程（三步法）

步骤 1：收集签名参数

从完整请求参数中提取 6 个固定字段 作为签名素材：

注意 sign 字段本身不参与签名。

步骤 2：排序拼接（sortAndJoin）

将所有参数按 key 升序排序，用 key=value& 拼接成字符串：

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0

步骤 3：加盐 → HMAC-SHA256 → Base64

const fullStr = metaStr + '&signSecret=' + signSecret;
const sign = crypto.createHmac('sha256', signSecret)
  .update(fullStr)
  .digest('base64');

请求方式

API 支持 GET 和 POST 两种请求方式：

GET 请求

所有参数（含 sign）拼在 URL query string 中。

GET /open/item/list/get?method=open.item.list.get&appkey=xxx&access_token=xxx&...&sign=xxx

POST 请求（form-urlencoded）

• URL：只带 appkey，路径由 method 转换（. → /）
• Body：剩余所有参数（不含 appkey）作为 application/x-www-form-urlencoded

POST /open/item/list/get?appkey=ks710724317041866789
Content-Type: application/x-www-form-urlencoded

method=open.item.list.get&access_token=xxx&sign=xxx&...

路径转换规则：

method = open.item.list.get
   ↓
路径   = /open/item/list/get

QPS 限流

网关内置令牌桶限流器，默认可配置：

globalQps: 5  // 每秒最多 5 个请求

已实现的 API 接口

商品接口

商品列表请求示例：

GET /open/item/list/get?method=open.item.list.get&appkey=xxx&access_token=xxx&signMethod=HMAC_SHA256&version=0&timestamp=xxx&param={"pageNumber":1,"pageSize":50}&sign=xxx

商品详情请求参数：

{
  "kwaiItemId": "商品ID"
}

店铺接口

订单接口

订单列表请求参数：

{
  "type": 1,
  "currentPage": 1,
  "pageSize": 10,
  "queryType": 1,
  "beginTime": 1700000000000,
  "endTime": 1700600000000
}

备注： 订单数据通过本地缓存 + 订单轮询服务保持同步，减少重复调用。

评价接口

客服接口

网关架构

文件布局

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
0

请求生命周期

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
1

API 客户端重试策略

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
2

错误码处理

安全防护机制

网关内置安全防护层（safety.js），对以下高危操作增加二次确认：

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
3

工作流程：

1. 高危操作请求 → 创建待确认记录写入 pending_confirm.json
2. 需手动调用 POST /api/safety/confirm 或 POST /api/safety/reject
3. 确认后执行，拒绝后丢弃

Webhook 回调

!!! note "" 快手平台的事件推送通过 /kuaishou.php 路径接收，Nginx 反代指向 Express。

• 支持 application/json 和 application/x-www-form-urlencoded
• 使用 messageSecret 进行消息解密
• 事件记录到 webhookStore，可通过 GET /api/webhook/events 查看

健康检查

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
4

返回示例：

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
5

生产部署

启动服务

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
6

环境变量

优雅关闭

// 伪代码
keys.sort(); // 字母升序
metaStr = keys.map(k => k + '=' + metaParams[k]).join('&');
// 结果示例：
// access_token=xxx&appkey=ksxxx&method=open.item.list.get&param={...}&signMethod=HMAC_SHA256&timestamp=1700000000000&version=0
7

经验总结

1. 签名是反编译 SDK 挖出来的 — 官方文档未完整公开签名细节，通过反编译快手 SDK JAR 分析 getSignParam + sortAndJoin 流程，再用抓包验证确认
2. refresh_token 会更新 — 每次刷新 access_token 时，refresh_token 也可能一起更新，不持久化会导致重启后 token 链断裂
3. POST vs GET 的选择 — 快手 SDK 默认用 GET，但 open.item.edit 等写接口强制用 POST（form-urlencoded），且 POST 时 URL 只带 appkey
4. 双路径持久化 — refresh_token 同时写入服务目录和 /tmp，解决 Node.js 和 PHP 两个进程间的共享问题
5. 令牌桶限流 — 全局 QPS 5 是安全阈值，超限会被平台限流，需合理使用

---

参考资料： 快手开放平台文档：https://open.kwaixiaodian.com