开发者接入指南

面向开发者 / 自动化玩家 · 更新于 2026-08-29

1. 开放平台概览

KaCloud 开放平台为供货商与商家提供自动化接口，核心链路：

获取令牌 POST /api/v1/open/token
进货卡密 POST /api/v1/open/inbound/cards   (Authorization: Bearer <accessToken>)

所有接口走 HTTPS + JSON，统一返回结构：

{ "code": 0, "message": "ok", "data": { ... } }

HTTP 200 只代表网关已受理，请以 code 判断业务结果（0 为成功）。

2. 创建应用

登录商家后台 → 开发者中心 → 「创建应用」，类型选择 supplier（供货）或 tool（工具）。
填写应用名称、回调地址（Webhook 接收地址）、期望权限。
提交后等待平台审核（开放应用上架审核），通过后获得 appKey / appSecret。

appSecret 仅展示一次，请妥善保存；如泄露可在开发者中心重置。

3. App 令牌

令牌有效期 24 小时，官方 SDK 已内置缓存与自动刷新，无需自行管理。手动调用：

POST /api/v1/open/token
Content-Type: application/json

{ "appKey": "your_app_key", "appSecret": "your_app_secret" }

// → { "code":0, "data":{ "accessToken":"...", "expiresIn": 86400 } }

4. 进货 API

将卡密批量导入到指定 SKU 的卡池：

POST /api/v1/open/inbound/cards
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "skuCode": "SKU_CODE",
  "cards": ["卡密1", "卡密2", "卡密3"]
}

// → { "code":0, "data":{ "poolId": 12, "batchNo": "KB123456", "count": 3 } }

skuCode：卡密归属商品的 SKU 编码（商家自有或平台共享 SKU 均可）。
cards：卡号 / 卡密字符串数组，单次上限 1000 条。
count：实际入库数。重复卡密按唯一索引跳过，不会虚增。

5. 官方 SDK

覆盖 Go / PHP / Node.js (≥18) / Python (≥3.7) 四语言，均仅使用标准库，零第三方依赖。

语言	目录	运行示例
Go	sdk/go/	`go run examples/import_cards.go -base https://c01.z-cn.top -appKey x -appSecret y -sku S -cards "A1,A2"`
PHP	sdk/php/	`php examples/import_cards.php --appKey=x --appSecret=y --sku=S --cards=A1,A2`
Node	sdk/node/	`node examples/import_cards.mjs --appKey=x --appSecret=y --sku=S --cards=A1,A2`
Python	sdk/python/	`python3 examples/import_cards.py --appKey=x --appSecret=y --sku=S --cards=A1,A2`

SDK 内置指数退避重试（默认最多 3 次）：网络错误 / HTTP 5xx 时退避 0.5s / 1s 重试；业务错误（4xx、code != 0）不重试。可通过 SetMaxAttempts / setMaxAttempts / set_max_attempts 调整次数。

6. Webhook 验签

在开发者中心订阅事件后，回调请求携带以下 Header：

Header	说明
`X-Ka-Event`	事件类型：`order.paid` / `order.refunded` / `goods.updated` / `inventory.low`
`X-Ka-Signature`	订阅时返回的 `signSecret`（防伪造回调）

收到回调后先校验 X-Ka-Signature == signSecret 再处理业务，并对 order.paid 等幂等处理（以订单号去重）。

7. 错误码

code	含义	处理建议
0	成功	-
400	参数错误	检查请求体字段与格式
401	凭据错误 / 未授权	检查 appKey / appSecret / accessToken
403	无权限	检查应用权限与租户范围
404	SKU 不存在	核对 skuCode
409	SKU 已归档 / 冲突	更换有效 SKU
429	请求过于频繁	降频或申请配额
5xx	服务端错误	SDK 自动重试，可稍后手动重试

8. 频控与限额

进货接口默认配额 5 万单 / 月，大促或自动化场景可按需申请扩容。
令牌接口与业务接口均有滑动窗口频控，超限返回 429。
调用日志可在开发者中心「调用日志」实时查询（状态 / 耗时 / 请求内容）。