Shared API 文档

基础规则

{
  "code": 200,
  "msg": "success",
  "data": {}
}

鉴权规则

除特别说明外，下面所有接口都需要 Shared API 鉴权。

字段必填说明
app_id是供货商/上游账号的用户 ID
sign是请求签名

签名算法：

  1. 从请求参数中移除 sign。
  2. 按参数名升序排序。
  3. 移除值为空字符串 '' 的参数。
  4. 使用 http_build_query 生成 query string。
  5. 末尾追加 &key={用户 app_key}。
  6. 计算 md5(urldecode(query_string + "&key=" + app_key))。

PHP 示例：

function makeSign(array $data, string $appKey): string
{
    unset($data['sign']);
    ksort($data);

    foreach ($data as $key => $value) {
        if ($value === '') {
            unset($data[$key]);
        }
    }

    return md5(urldecode(http_build_query($data) . '&key=' . $appKey));
}

注意：如果请求体里传了 app_key 字段，它也会参与签名，因为签名逻辑会对除 sign 以外的所有非空字段签名。

接口列表

连接测试

POST /shared/authentication/connect

用于测试 Shared API 凭据是否有效。

字段必填说明
app_id是用户 ID
sign是签名
返回字段说明
shopName网站店铺名称
balance当前用户余额

分类列表

POST /shared/commodity/categories

获取主站已启用的商品分类。

字段必填说明
app_id是用户 ID
sign是签名
 
[
  { "id": 1, "name": "Demo" }
]

指定分类商品

POST /shared/commodity/categoryItems

获取指定分类及其已启用 API 对接的商品。

字段必填说明
app_id是用户 ID
sign是签名
category_id是分类 ID
返回字段说明
category分类对象
items该分类下的商品列表

全部商品

POST /shared/commodity/items

获取已启用分类及其已启用 API 对接的商品。返回分类数组，每个分类包含 children 商品列表。

字段必填说明
app_id是用户 ID
sign是签名

按商品代码查询商品

POST /shared/commodity/item

根据本地商品 API 代码查询商品。

字段必填说明
app_id是用户 ID
sign是签名
sharedCode是本地商品 code

返回结构与 /shared/commodity/items 相同，但只包含匹配商品。

库存可购买检测

POST /shared/commodity/inventoryState

检测指定商品数量是否可以购买。

字段必填说明
app_id是用户 ID
sign是签名
shared_code是本地商品 code
card_id否预选卡密 ID，不预选传 0
num是购买数量
race否商品分类/规格名称
 
{
  "code": 200,
  "msg": "success",
  "data": []
}

常见错误：商品不存在、商品已停售、预选卡密不可用、库存不足。

库存详情

POST /shared/commodity/inventory

获取单个商品的库存、发货方式、预选状态、价格和配置。

字段必填说明
app_id是用户 ID
sign是签名
sharedCode是本地商品 code 或 shared_code
race否商品分类/规格名称
返回字段说明
count可用库存数量
delivery_way发货方式，0 自动发货，其他值为手动/插件发货
draft_status是否开启预选卡密
price商品未登录价格
user_price商品会员价格
config商品配置，包含重新计算后的规格成本价
factory_price无规格商品时，当前鉴权用户的计算成本价
is_category是否为规格/分类价格商品

创建订单

POST /shared/commodity/trade

创建订单，并强制使用余额支付。

字段必填说明
app_id是用户 ID
sign是签名
shared_code是本地商品 code
contact是买家联系方式
num是购买数量
card_id否预选卡密 ID，不预选传 0
device否设备标识
password否查询密码
coupon否优惠券代码
from否推广用户 ID
race否商品分类/规格名称
request_no建议客户端请求号，用于幂等
额外 widget 字段视商品而定如果商品配置了控件，需要提交对应字段
返回字段说明
url支付地址；因为强制余额支付，通常为 null
amount订单金额
tradeNo本地订单号
secret如果立即发货，则返回发货内容

预选卡密列表

POST /shared/commodity/draftCard

获取商品可预选的卡密列表。

字段必填说明
app_id是用户 ID
sign是签名
sharedCode是本地商品 code
page是页码
limit是每页数量
race否商品分类/规格名称

返回 data 为分页卡密数据，只包含 id 和 draft。

按订单号查询订单

POST /shared/commodity/query

根据本地订单号查询订单。

字段必填说明
app_id是用户 ID
sign是签名
tradeNo是本地订单号
返回字段说明
secret发货内容
widget下单提交的控件值；没有则为 null
status本地订单状态

按请求号查询订单

POST /shared/commodity/query2

根据客户端请求号查询订单。

字段必填说明
app_id是用户 ID
sign是签名
requestNo是客户端请求号

返回 data 与 /shared/commodity/query 相同。

错误说明

业务错误会抛出 JSONException，框架通常会返回 JSON 错误响应。