Shared API 文档

基础规则

• 基础地址：卡网域名，例如 https://example.com
• 接口返回 JSON：

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

鉴权规则

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

签名算法：

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 凭据是否有效。

分类列表

POST /shared/commodity/categories

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

[
  { "id": 1, "name": "Demo" }
]

指定分类商品

POST /shared/commodity/categoryItems

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

全部商品

POST /shared/commodity/items

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

• factory_price 会按当前鉴权用户重新计算。
• 如果商品存在分类/规格价格，config.category_factory 会包含每个分类/规格重新计算后的成本价。
• 返回结果会移除 leave_message 和 delivery_message。

按商品代码查询商品

POST /shared/commodity/item

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

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

库存可购买检测

POST /shared/commodity/inventoryState

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

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

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

库存详情

POST /shared/commodity/inventory

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

创建订单

POST /shared/commodity/trade

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

预选卡密列表

POST /shared/commodity/draftCard

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

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

按订单号查询订单

POST /shared/commodity/query

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

按请求号查询订单

POST /shared/commodity/query2

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

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

错误说明

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

• 缺少 app_id
• 缺少 sign
• 用户 ID 不存在
• 签名错误
• 商品不存在或已停售
• 库存不足
• 余额支付失败
• 订单不存在