开放平台
通过 REST API 与 Webhook，把 智享速球通 的商品、订单、库存数据接入您的系统。所有接口均采用 HMAC-SHA256 签名，安全可靠。
API 服务运行中
📖 API 概览
所有 API 均走 HTTPS，接口地址：https://kj.dxttk.cn/index.php?r=api/{controller}/{action}
| 项目 | 说明 |
|---|---|
| 请求格式 | JSON |
| 响应格式 | JSON（{ ok, ts, data }） |
| 认证方式 | HMAC-SHA256 签名（4 个请求头） |
| 限流 | 默认 60 次/分钟（可按密钥配置） |
| 时间戳窗口 | ±5 分钟 |
🔑 认证方式
每次请求必须在 Header 里带以下 4 个字段：
| Header | 说明 |
|---|---|
X-Api-App-Id | 您的 AppID（在「获取密钥」申请） |
X-Api-Timestamp | Unix 时间戳（秒），±5 分钟有效 |
X-Api-Nonce | 随机字符串（防重放） |
X-Api-Signature | HMAC-SHA256 签名（见下方算法） |
签名算法
把以下 5 段拼成字符串，用 AppSecret 做 HMAC-SHA256，最后 hex 编码：
// 待签名字符串（\n 是真实换行符）
$signStr = "METHOD" . "\n"
. "PATH" . "\n" // 不含查询串
. "TIMESTAMP" . "\n"
. "NONCE" . "\n"
. "BODY"; // 原始 JSON 字符串
$signature = hash_hmac('sha256', $signStr, $appSecret);
📦 商品 API
需要 products 权限范围。
GET
/api/v1/products/list
商品列表（支持分页、搜索、分类）
GET
/api/v1/products/detail?id=123
商品详情（含 SKU）
POST
/api/v1/products/create
创建商品
POST
/api/v1/products/update
更新商品
POST
/api/v1/products/delete
删除商品
🛒 订单 API
需要 orders 权限范围。
GET/api/v1/orders/list订单列表
GET/api/v1/orders/detail?id=X订单详情（含 items）
POST/api/v1/orders/ship订单发货
GET/api/v1/orders/stats?days=30订单统计
📊 库存 API
需要 inventory 权限范围。
GET/api/v1/inventory/list库存列表
GET/api/v1/inventory/detail?id=X单商品库存
POST/api/v1/inventory/update修改库存（stock 绝对值 或 delta 增量）
GET/api/v1/inventory/alerts?threshold=10低库存预警
🔔 Webhook
把以下事件回调到您的服务器，Header 带 X-Webhook-Signature（HMAC-SHA256，密钥为创建时返回的 Secret）。失败自动指数退避重试（60s / 5min / 30min / 2h / 8h）。
| 事件 | 说明 |
|---|---|
order.created | 订单创建 |
order.paid | 订单支付成功 |
order.shipped | 订单发货 |
order.completed | 订单完成 |
order.cancelled | 订单取消 |
refund.approved | 退款通过 |
refund.rejected | 退款拒绝 |
return.created | 退货申请 |
return.received | 退货收货 |
product.created | 商品创建 |
product.updated | 商品更新 |
product.deleted | 商品删除 |
inventory.changed | 库存变动 |
ticket.created | 工单创建 |
ticket.replied | 工单回复 |
签名校验（PHP 示例）
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$expected = hash_hmac('sha256', $ts . '.' . $body, $yourSecret);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }
// 处理事件…
⚠️ 错误码
| HTTP | 说明 |
|---|---|
200 | 成功 |
400 | 参数错误 |
401 | 认证失败（AppID / 签名 / 时间戳） |
403 | 无权限（scope 不足 / IP 不在白名单） |
404 | 资源不存在 |
429 | 超出频率限制 |
500 | 服务内部错误 |
503 | API 未启用 |
🧰 SDK 示例
cURL
APP_ID="AKXXXXXXXXXXXXXXXX"
SECRET="your_app_secret"
TS=$(date +%s)
NONCE="abc123"
METHOD="GET"
PATH="/index.php"
SIGN=$(printf "%s\n%s\n%s\n%s\n%s" "$METHOD" "$PATH" "$TS" "$NONCE" "" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X GET "https://kj.dxttk.cn/index.php?r=api/product/list" \
-H "X-Api-App-Id: $APP_ID" \
-H "X-Api-Timestamp: $TS" \
-H "X-Api-Nonce: $NONCE" \
-H "X-Api-Signature: $SIGN"
PHP
function apiCall($appId, $secret, $path, $method='GET', $body='') {
$ts = time();
$nonce = bin2hex(random_bytes(8));
$signStr = $method . "\n" . $path . "\n" . $ts . "\n" . $nonce . "\n" . $body;
$sig = hash_hmac('sha256', $signStr, $secret);
$ch = curl_init('https://kj.dxttk.cn/index.php?r=' . $path);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
"X-Api-App-Id: $appId",
"X-Api-Timestamp: $ts",
"X-Api-Nonce: $nonce",
"X-Api-Signature: $sig",
'Content-Type: application/json',
],
]);
$resp = curl_exec($ch);
curl_close($ch);
return json_decode($resp, true);
}
Python
import hashlib, hmac, time, requests, uuid
def api_call(app_id, secret, path, method='GET', body=''):
ts = str(int(time.time()))
nonce = uuid.uuid4().hex
sign_str = f"{method}\n{path}\n{ts}\n{nonce}\n{body}"
sig = hmac.new(secret.encode(), sign_str.encode(), hashlib.sha256).hexdigest()
headers = {
'X-Api-App-Id': app_id,
'X-Api-Timestamp': ts,
'X-Api-Nonce': nonce,
'X-Api-Signature': sig,
}
url = f'https://kj.dxttk.cn/index.php?r={path}'
return requests.request(method, url, headers=headers, data=body).json()