ACGV3 Shared API

本站商品目录、库存、询价、预选卡与余额订单标准对接协议。

POSTapp_id + signx-www-form-urlencoded成功 code = 200

基础说明

请求方式	POST
请求格式	推荐 `application/x-www-form-urlencoded`
鉴权方式	公共参数 `app_id` + `sign`
响应状态	成功 code = 200，失败通常 code = 0

签名算法

PHPgenerateSignature

/** 获取数据签名 */
public static function generateSignature(array $data, $appKey): string
{
    unset($data['sign']);
    ksort($data);
    foreach ($data as $key => $val) {
        if ($val === '') {
            unset($data[$key]);
        }
    }
    return md5(urldecode(http_build_query($data) . "&key=" . (string)$appKey));
}

公共请求与响应

请求参数

参数	必选	类型	说明
`app_id`	是	string/int	商户 ID，可在用户中心商户资料中获取
`sign`	是	string	本次请求全部 POST 参数的签名

app_key 仅用于本地签名，不建议上传到对方服务器。数组参数（如 sku）也必须参与签名，且须与实际提交内容一致。

响应字段

字段	类型	说明
code	int	成功时为 200
msg	string	可选提示信息
data	mixed	业务数据

JSON成功 / 失败

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

{ "code": 0, "msg": "密钥错误" }

业务字段说明

字段	说明
`race`	商品种类，对应 `[category]` 节点键名
`sku`	SKU 数组，如 `sku[机身颜色]=黑色&sku[存储容量]=256GB`
`card_id`	预选卡 ID，仅 draft_status=1 时有效
`widget`	自定义控件；下单时提交每个控件 name 对应的值
`request_no`	幂等号，强烈建议每笔订单使用唯一值

POST/shared/commodity/items

无额外业务参数，只需 app_id、sign。data 为分类数组，children 为商品列表。

字段	类型	说明
id / name	int / string	分类或商品 ID / 名称
children	array	可对接商品列表
code	string	商品编码
price / user_price	string/float	游客价 / 会员或代理价
stock	int	自动发货库存
delivery_way / draft_status	int	发货方式 / 是否支持预选

POST/shared/commodity/item

Body 参数

参数	必选	类型	说明
code	是	string	商品编码

返回核心字段

字段	类型	说明
id / name / description / code	mixed	商品基础资料
price / user_price	string/float	游客价 / 会员或代理价
stock	int/string	当前库存
delivery_way	int	发货方式
contact_type	int	0不限、1手机、2邮箱、3QQ
password_status	int	是否启用查单密码
draft_status / draft_premium	mixed	预选状态 / 附加价格
minimum / maximum	int	购买数量限制，0 表示不限
config	object	解析后的 category、sku、wholesale 等配置
widget	array/null	自定义控件
seckill_status / 时间	mixed	秒杀状态与时间
owner / service / share	mixed	供货商、客服及分享信息

POST/shared/commodity/inventoryState

参数	必选	类型	说明
shared_code	是	string	商品编码
num	是	int	购买数量
card_id	否	int	预选卡 ID
race	否	string	商品种类

JSONResponse

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

库存不足、商品不存在、停售或预选卡被占用时直接返回失败。

POST/shared/commodity/inventory

参数	必选	类型	说明
sharedCode	是	string	商品编码
race	否	string	商品种类

返回 count、delivery_way、draft_status、price、user_price、factory_price、is_category，以及 INI 文本格式的 config。

inventory 的 config 是 INI 文本；item 的 config 是已解析对象。

POST/shared/commodity/stock

参数	必选	类型	说明
code	是	string	商品编码
race	否	string	商品种类
sku	否	array	SKU 组合

JSONResponse

{ "code": 200, "data": { "stock": "15" } }

POST/shared/commodity/valuation

参数	必选	类型	说明
code	是	string	商品编码
num	是	int	购买数量
race / sku / card_id	否	mixed	种类、SKU、预选卡 ID

JSONResponse

{ "code": 200, "data": { "price": "99.00" } }

POST/shared/commodity/draftCard

参数	必选	类型	说明
code	是	string	商品编码
page	建议	int	从 1 开始
limit / race / sku	否	mixed	分页、种类、SKU

返回 list、total，以及 list[].id、list[].draft、list[].draft_premium。仅 draft_status=1 时可用。

POST/shared/commodity/draft

参数	必选	类型	说明
code	是	string	商品编码
card_id	是	int	预选卡 ID

核心返回字段 draft_premium 为预选卡附加价格。

POST/shared/commodity/trade

该接口强制使用余额支付。

参数	必选	类型	说明
shared_code	是	string	商品编码
num	是	int	购买数量
request_no	否	string	唯一幂等号，强烈建议提交
contact	否	string	联系方式
race / sku / card_id	否	mixed	种类、SKU、预选卡
password / coupon / device	否	mixed	查单密码、优惠券、设备类型

存在 widget 时，还需提交各控件 name 对应的值。返回 tradeNo、amount、secret、stock。

JSONResponse

{
  "code": 200,
  "msg": "success",
  "data": {
    "url": null,
    "amount": "10.00",
    "tradeNo": "123260422101010888",
    "secret": "卡密内容",
    "stock": "14"
  }
}

POST/shared/commodity/query

参数	必选	类型	说明
tradeNo	是	string	系统订单号，字段名不是 trade_no

返回 secret、widget、status；status 0=未支付，1=已支付。

对接建议流程

调用 items 或 item 拉取商品。
确定 category/race 和 sku。
支持预选时调用 draftCard，需要时调用 draft。
调用 stock、valuation 或 inventoryState 确认库存与价格。
调用 trade 下单。
调用 query 轮询订单状态和发货内容。

测试鉴权可请求 /shared/authentication/connect。请严格使用文档字段名，不要将 tradeNo 改成 trade_no。