去购物
登录 创建账号
API开发文档 共 11 个接口

本文仅提供 /shared/ 签名对接接口，供第三方网站、ERP 和自动采购程序使用。示例均为演示值，实际可用接口和权限以部署版本与账号配置为准。

开始接入

基础地址为当前网站的 HTTPS 域名。主站、分站的商品可见范围和价格可能不同，请始终使用同一站点完成查询与下单。

签名接口流程：连接与余额 → 商品目录 / 详情 → 选择类别与规格 → 库存 / 报价 → 余额下单 → 查单。商品数字 ID 与对接 CODE 不可混用。

所有接口使用 POST 和表单编码 application/x-www-form-urlencoded。嵌套规格例：sku[时长]=月付。不要把 JSON 请求体直接替代表单。

成功以 JSON 中 code=200 判断，HTTP 200 不代表业务成功。失败通常为 {"code":0,"msg":"错误说明"}，失败时可能没有 data。下方响应示例只展示关键字段。

订单号请按字符串保存。订单 status：0 未支付、1 已支付、2 接口退款、3 网站退款、4 拼团退款；发货 delivery_status：0 未发货、1 已发货、2 预订待补货、3 待成团、4 已退款不发货。支付成功不等于已发货。

商品目录返回 data[]，预选卡列表返回 data.list / data.total，其余接口按各自字段说明读取。金额可能为数字或小数字符串，请按十进制处理。

签名认证与 PHP 接入示例

公共参数：app_id 为会员 ID，sign 为小写 MD5 签名；使用会员自己的 API 密钥 app_key。密钥只在调用方服务端使用，示例从环境变量读取，不在文档中展示真实密钥。

签名步骤：移除 sign → 对顶层参数按键名 ksort 排序 → 仅移除值严格等于空字符串的项（保留 0）→ 使用 PHP 默认 http_build_query 序列化 → 拼接 &key=密钥 → 对整个字符串 urldecode → MD5。数组字段也参与签名，必须与实际提交数据一致。

app_key 无需作为公共表单字段发送；旧客户端若发送了 app_key，该字段同样参与签名。签名接口不使用登录 Cookie 或 CSRF。此处是现有协议，不是易支付的支付回调签名。

<?php
// Run on your server. Set credentials in environment variables.
$base = rtrim((string)getenv('MALL_API_BASE'), '/'); // HTTPS site URL
$appKey = (string)getenv('MALL_APP_KEY');
$data = ['app_id' => (string)getenv('MALL_APP_ID'), 'code' => 'PRODUCT_CODE', 'num' => 1];
unset($data['sign']);
ksort($data);
foreach ($data as $key => $value) {
    if ($value === '') unset($data[$key]); // Keep 0; do not use array_filter().
}
$data['sign'] = md5(urldecode(http_build_query($data) . '&key=' . $appKey));
$ch = curl_init($base . '/shared/commodity/valuation');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
curl_close($ch);
$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
if ((int)($result['code'] ?? 0) !== 200) throw new RuntimeException($result['msg'] ?? 'API request failed');
echo json_encode($result['data'], JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
常见错误与重试

“商户ID不存在 / 密钥错误”请核对 app_id、API 密钥、参数排序和签名内容；“库存不足”请重新读取库存与规格；“余额不足”请检查签名账号的余额账户，硬币不能用于余额支付。

403、413、429 或非 JSON 响应可能来自防火墙、请求大小限制或频率限制。请使用接口返回的 msg 排查业务错误。

查询接口请缓存并适度轮询。创建订单超时不代表没有扣款，不要直接重复购买；先用已知 tradeNo 查单，无法确认时联系管理员核对。request_no 用于重复请求检测，不保证重复请求返回原结果。

请在调用方服务端使用签名示例测试接口。余额下单会实际扣款，调用前请先确认商品、规格、数量和报价。

连接与余额 POST /shared/authentication/connect
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

所有 /shared 接口都需要公共签名参数；返回余额不包含硬币。

业务参数：无。签名接口仍须携带 app_id 与 sign。

请求示例（业务参数；认证按上方说明补充）
POST /shared/authentication/connect
返回字段
data.shopName：平台店铺名称
data.balance：签名账号的余额
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "shopName": "示例商城",
        "balance": "100.00"
    }
}
可对接商品目录 POST /shared/commodity/items
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

仅包含上架、启用 API 且当前账号可见的商品。多维规格实际价格请调用 valuation。

业务参数：无。签名接口仍须携带 app_id 与 sign。

请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/items
返回字段
data[]：分类数组；children[] 为分类下可对接商品
children[].id / code / name：商品 ID、对接 CODE、名称
price / user_price / factory_price：当前签名账号在当前网站的拿货价格
config：INI 字符串；price_selection：默认类别与规格
成功响应示例（节选）
{
    "code": 200,
    "data": [
        {
            "id": 1,
            "name": "示例分类",
            "children": []
        }
    ]
}
商品详情 POST /shared/commodity/item
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

类别、规格及动态下单控件应读取本接口，不能用示例规格硬编码。

参数类型必填说明示例值
codestring是商品对接 CODE，不是商品数字 IDPRODUCT_CODE
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/item
code=PRODUCT_CODE
返回字段
data：商品详情对象；含 id、code、name、价格、config、stock 等
config：解析后的配置对象，与 items / inventory 的 INI 字符串不同
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "id": 1,
        "code": "PRODUCT_CODE",
        "name": "示例商品",
        "config": [],
        "price_selection": {
            "race": "",
            "sku": []
        }
    }
}
库存与价格 POST /shared/commodity/inventory
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

库存会变化，下单前建议重新校验。兼容参数 shared_code 与 sharedCode 二选一。

参数类型必填说明示例值
sharedCodestring是对接 CODE；兼容 shared_codePRODUCT_CODE
racestring否商品类别名称，原样使用商品配置返回值
skuobject否规格名到选项值的映射。表单示例：sku[规格名]=选项值
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/inventory
sharedCode=PRODUCT_CODE
返回字段
data.count：当前规格库存
delivery_way：0 自动发货，1 人工发货；draft_status：是否支持预选
price / user_price / factory_price：签名账号价格；config：INI 字符串；price_selection：报价选择
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "count": 10,
        "delivery_way": 0,
        "draft_status": 0,
        "price": "3.00",
        "user_price": "3.00",
        "factory_price": "3.00",
        "config": "",
        "price_selection": {
            "race": "",
            "sku": []
        }
    }
}
库存数量 POST /shared/commodity/stock
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

适合仅需库存的场景。

参数类型必填说明示例值
codestring是商品对接 CODE，不是商品数字 IDPRODUCT_CODE
racestring否商品类别名称，原样使用商品配置返回值
skuobject否规格名到选项值的映射。表单示例：sku[规格名]=选项值
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/stock
code=PRODUCT_CODE
返回字段
data.stock：库存数量；可能以字符串返回
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "stock": "10"
    }
}
库存可用性校验 POST /shared/commodity/inventoryState
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

仅校验，不锁库存。远程供货分支的规格校验能力取决于上游实现。

参数类型必填说明示例值
shared_codestring是商品对接 CODEPRODUCT_CODE
numinteger是购买数量，正整数1
card_idinteger是预选卡 ID；非预选填 00
racestring否商品类别名称，原样使用商品配置返回值
skuobject否规格名到选项值的映射。表单示例：sku[规格名]=选项值
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/inventoryState
shared_code=PRODUCT_CODE&num=1&card_id=0
返回字段
code=200 表示校验通过；失败读取 msg
成功响应示例（节选）
{
    "code": 200,
    "data": []
}
精确报价 POST /shared/commodity/valuation
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

使用当前签名账号、当前网站的实际价格。非单价接口；需要单价请 num=1。

参数类型必填说明示例值
codestring是商品对接 CODE，不是商品数字 IDPRODUCT_CODE
numinteger是购买数量，正整数1
racestring否商品类别名称，原样使用商品配置返回值
skuobject否规格名到选项值的映射。表单示例：sku[规格名]=选项值
card_idinteger否预选卡 ID；不预选传 00
couponstring否优惠券码
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/valuation
code=PRODUCT_CODE&num=1&card_id=0
返回字段
data.price：所选数量和规格的商品报价
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "price": "3.00"
    }
}
预选卡列表 POST /shared/commodity/draftCard
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

仅支持已启用预选的商品；不会返回未售卡密正文。

参数类型必填说明示例值
codestring是商品对接 CODE，不是商品数字 IDPRODUCT_CODE
pageinteger否页码，从 1 开始1
limitinteger否每页数量，建议 10；上限以接口说明为准10
racestring否商品类别名称，原样使用商品配置返回值
skuobject否规格名到选项值的映射。表单示例：sku[规格名]=选项值
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/draftCard
code=PRODUCT_CODE&page=1&limit=10
返回字段
data.list[]：id、draft（预选描述）、draft_premium（预选加价）
data.total：总数
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "list": [
            {
                "id": 1,
                "draft": "示例描述",
                "draft_premium": "0.00"
            }
        ],
        "total": 1
    }
}
预选卡详情 POST /shared/commodity/draft
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

该接口不是最终报价，最终应以 valuation / trade 为准。

参数类型必填说明示例值
codestring是商品对接 CODE，不是商品数字 IDPRODUCT_CODE
card_idinteger是预选卡 ID1
racestring否商品类别名称，原样使用商品配置返回值
skuobject否规格名到选项值的映射。表单示例：sku[规格名]=选项值
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/draft
code=PRODUCT_CODE&card_id=1
返回字段
data.draft_premium：预选加价；data.cost：该卡记录的 cost 字段
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "draft_premium": "0.00",
        "cost": "0.00"
    }
}
余额下单（实际扣款） POST /shared/commodity/trade
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：创建订单、扣余额、可能发货

强制使用签名账号余额付款，不接受 pay_id 切换。商品须允许余额支付。动态控件按商品 widget 中的 name 直接提交；数量、联系方式和查单密码受商品配置限制。request_no 重复会报错，不会返回旧订单；超时后先核对既有订单，勿盲目更换请求号重复购买。

参数类型必填说明示例值
shared_codestring是商品对接 CODEPRODUCT_CODE
numinteger是购买数量，正整数1
deviceinteger是设备：0 电脑、1 安卓、2 iOS、3 iPad0
contactstring否按商品要求填写联系方式
racestring否商品类别名称，原样使用商品配置返回值
skuobject否规格名到选项值的映射。表单示例：sku[规格名]=选项值
card_idinteger否预选卡 ID；不预选传 00
couponstring否优惠券码
passwordstring否查单密码；按商品配置要求填写
request_nostring否调用方请求号，最长 19 字符；建议使用唯一数字请求号
reservation_confirminteger否库存不足且确需预订时传 1
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/trade
shared_code=PRODUCT_CODE&num=1&device=0&card_id=0
返回字段
data.tradeNo：生成的订单号；amount：订单应付金额
secret：即时交付内容；url：支付跳转地址（余额单通常为空）
stock：下单后的库存；leave_message：已支付订单的商家留言
group_buy_team_id / group_buy_free_open / group_buy_share_url：拼团信息
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "tradeNo": "123261103120000456",
        "amount": "3.00",
        "url": "",
        "secret": "示例交付内容",
        "leave_message": "",
        "stock": "9"
    }
}
查询本人订单 POST /shared/commodity/query
分组：签名对接 API　认证：签名 app_id + sign
请求编码：application/x-www-form-urlencoded　操作：查询

只能查询 owner 为当前签名账号的订单。未支付或未交付时 secret 可能为空。

参数类型必填说明示例值
tradeNostring是平台返回的订单号，不是 request_no123261103120000456
请求示例（业务参数；认证按上方说明补充）
POST /shared/commodity/query
tradeNo=123261103120000456
返回字段
data.status：订单状态
data.secret：交付内容；widget：下单控件内容或 null
data.leave_message：仅已支付订单返回商家留言
成功响应示例（节选）
{
    "code": 200,
    "data": {
        "status": 1,
        "secret": "示例交付内容",
        "widget": null,
        "leave_message": ""
    }
}