商品对接 API

本文档面向希望对接 DCShop 系统作为货源的第三方站点开发者。通过以下 API，你可以从货源站（主站）拉取商品、代为下单、实时查询发货状态，实现完全自动化的商品分销。任何语言和系统（如彩虹云、晴玖云等）均可对接。

对接流程概览

一个完整的对接集成通常按以下步骤进行：

1. 获取 API 密钥 — 在主站注册账号，联系主站管理员开通 API 权限，获取 api_key
2. 充值余额 — 在主站账号中充值余额，用于后续 API 采购商品时自动扣费
3. 拉取商品分类 — 调用 goods_category 获取主站所有允许对接的商品分类
4. 拉取商品列表 — 调用 goods_list 按分类获取商品，同步到本地
5. 拉取商品详情 — 调用 goods_detail 获取单个商品的完整规格、价格、库存信息
6. 用户下单后代采 — 本地用户支付成功后，调用 order_buy 向主站下单并扣费
7. 轮询发货状态 — 对于人工发货类商品，调用 order_query 定时查询是否已发货
8. 查询余额 — 调用 user_info 查询当前账户余额及会员等级

鉴权方式 (双模鉴权)

为了兼顾开发便捷性与系统安全性，API 支持两种鉴权模式。推荐在生产环境中使用“安全签名模式”。

模式一：安全签名模式 (推荐)

通过对请求参数签名并包含时间戳，防止请求被篡改和重放攻击（重放窗口为 5 分钟）。

签名算法说明

1. 筛选与排序：将所有请求参数（排除 sign 参数本身）按参数名（Key）的 ASCII 码升序排序。
2. 拼接字符串：将排好序的参数按照 key1=value1&key2=value2&... 的格式拼接。
3. 追加密钥：在拼接好的字符串末尾追加 &key=YOUR_API_KEY。
4. 计算哈希：对最终的字符串计算 MD5 哈希值（32位小写），作为 sign 传入。

// 待签名的请求参数
$params = [
    'action'    => 'user_info',
    'api_key'   => 'YOUR_API_KEY',
    'timestamp' => time()
];

// 1. 按键名升序排序
ksort($params);

// 2. 拼接参数
$signStr = '';
foreach ($params as $k => $v) {
    $signStr .= $k . '=' . $v . '&';
}

// 3. 追加 key
$signStr .= 'key=YOUR_API_KEY';

// 4. MD5 签名
$params['sign'] = md5($signStr);

模式二：普通密钥模式 (兼容)

直接在请求中传递 api_key，不进行签名校验。适合开发调试或简单的内部对接。

统一响应格式

成功响应

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

错误响应

{
    "code": 1,
    "msg": "错误描述信息",
    "data": ""
}

价格与金额说明

所有接口中的价格字段均以 元 为单位（如 9.90），保留两位小数。在对接端存储时建议转为整数分（× 100）以避免浮点精度问题。