店铺共享 API 文档

通过 API 接口对接供货商商品，实现自动查询、库存同步、下单购买。

API 凭证

签名算法

所有 API 请求都需要携带 sign 参数，签名计算步骤如下：

1. 将所有请求参数（包括 app_id 和 app_key）放入数组
2. 移除 sign 字段（如果存在）
3. 按照参数名字典序排序（ksort）
4. 移除所有值为空字符串的参数
5. 拼接成 URL 查询字符串，末尾追加 &key=你的app_key
6. 对整个字符串进行 URL 解码
7. 计算 MD5 值，即为签名

function generateSignature(array $data, string $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=" . $appKey));
}

import hashlib
from urllib.parse import urlencode, unquote

def generate_signature(data: dict, app_key: str) -> str:
    if 'sign' in data:
        del data['sign']
    sorted_data = {k: v for k, v in sorted(data.items()) if v != ''}
    sign_string = unquote(urlencode(sorted_data) + "&key=" + app_key)
    return hashlib.md5(sign_string.encode('utf-8')).hexdigest()

const crypto = require('crypto');

function generateSignature(data, appKey) {
    delete data.sign;
    const sortedKeys = Object.keys(data).sort();
    const params = [];
    sortedKeys.forEach(key => {
        if (data[key] !== '') {
            params.push(`${key}=${encodeURIComponent(data[key])}`);
        }
    });
    const signString = decodeURIComponent(params.join('&') + '&key=' + appKey);
    return crypto.createHash('md5').update(signString).digest('hex');
}

API 端点

{
    "code": 200,
    "msg": "success",
    "data": {
        "shopName": "示例店铺",
        "balance": 1000.50
    }
}

{
    "code": 200,
    "data": [
        {
            "id": 1,
            "name": "游戏账号",
            "children": [
                {
                    "id": 101,
                    "code": "PROD001",
                    "name": "王者荣耀账号",
                    "description": "包含多个皮肤",
                    "price": 100.00,
                    "user_price": 95.00,
                    "factory_price": 90.00,
                    "cover": "https://your-domain.com/uploads/cover.jpg",
                    "delivery_way": 0,
                    "contact_type": 0,
                    "password_status": 0,
                    "sort": 0,
                    "config": "category[普通]=100.00\ncategory[高级]=200.00",
                    "widget": "[{\"cn\":\"区服\",\"name\":\"server\",\"type\":\"select\"}]",
                    "draft_status": 0,
                    "inventory_hidden": 0,
                    "only_user": 0,
                    "purchase_count": 0,
                    "minimum": 1,
                    "seckill_status": 0
                }
            ]
        }
    ]
}

category[普通]=100.00
category[高级]=200.00
category[豪华]=300.00

$config = parse_ini_string($item['config']);
// 结果：['category' => ['普通' => '100.00', '高级' => '200.00', '豪华' => '300.00']]
// 每个 key 为种类名称，value 为该种类价格
// 购买时通过 race 参数传递用户选择的种类名称

[
    {"cn": "游戏区服", "name": "server", "type": "select"},
    {"cn": "充值账号", "name": "account", "type": "input"}
]

// 如果 widget 包含 {"name": "server", "cn": "游戏区服"}
// 则购买时额外传递：
$params['server'] = '艾欧尼亚';

{
    "code": 200,
    "data": {
        "count": 150,
        "delivery_way": 0,
        "draft_status": 0,
        "price": 100.00,
        "user_price": 95.00,
        "factory_price": 90.00,
        "config": "category[普通]=100.00\ncategory[高级]=200.00",
        "is_category": true
    }
}

{
    "code": 200,
    "data": {
        "trade_no": "20250117123456789",
        "secret": "账号：xxx\n密码：xxx",
        "widget": {
            "server": "艾欧尼亚"
        },
        "status": 2
    }
}

$data = [
    'app_id' => $appId,  'app_key' => $appKey,
    'shared_code' => 'PROD001',  'num' => 1,  'race' => '普通',
    'request_no' => mt_rand(100,999) . date("ymdHis") . mt_rand(100,999),
    'contact' => '',  'card_id' => 0,  'device' => 0,  'password' => ''
];
$data['sign'] = generateSignature($data, $appKey);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $domain . '/shared/commodity/trade');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['code'] == 200) {
    echo "订单号：" . $result['data']['trade_no'];
    echo "卡密：" . $result['data']['secret'];
}

{
    "code": 200,
    "data": {
        "data": [
            { "id": 1001, "draft": "预览：账号等级100级" },
            { "id": 1002, "draft": "预览：账号等级80级" }
        ],
        "total": 50
    }
}

{
    "code": 200,
    "msg": "success",
    "data": {
        "status": 1,
        "secret": "账号：xxx\n密码：xxx",
        "widget": null
    }
}

PHP SDK

完整的 PHP 集成类，复制即用。

class SharedAPIClient {
    private $domain, $appId, $appKey;

    public function __construct($domain, $appId, $appKey) {
        $this->domain = rtrim($domain, '/');
        $this->appId = $appId;
        $this->appKey = $appKey;
    }

    private function generateSignature($data) {
        unset($data['sign']);
        ksort($data);
        foreach ($data as $key => $val) {
            if ($val === '') unset($data[$key]);
        }
        return md5(urldecode(http_build_query($data) . "&key=" . $this->appKey));
    }

    private function post($url, $params = []) {
        $data = array_merge($params, ['app_id' => $this->appId, 'app_key' => $this->appKey]);
        $data['sign'] = $this->generateSignature($data);

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->domain . $url);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

        $response = curl_exec($ch);
        $error = curl_error($ch);
        curl_close($ch);

        if ($error) throw new Exception("CURL Error: " . $error);
        $result = json_decode($response, true);
        if (!$result || $result['code'] != 200)
            throw new Exception($result['msg'] ?? 'Unknown error');
        return $result['data'] ?? [];
    }

    public function connect()      { return $this->post('/shared/authentication/connect'); }
    public function getItems()     { return $this->post('/shared/commodity/items'); }
    public function getItem($code) { return $this->post('/shared/commodity/item', ['sharedCode' => $code]); }

    public function getInventory($code, $race = '') {
        return $this->post('/shared/commodity/inventory', ['sharedCode' => $code, 'race' => $race]);
    }

    public function checkInventory($code, $num, $cardId = 0, $race = '') {
        return $this->post('/shared/commodity/inventoryState', [
            'shared_code' => $code, 'num' => $num, 'card_id' => $cardId, 'race' => $race
        ]);
    }

    public function purchase($code, $num, $options = []) {
        return $this->post('/shared/commodity/trade', array_merge([
            'shared_code' => $code, 'num' => $num,
            'request_no' => mt_rand(100,999) . date("ymdHis") . mt_rand(100,999),
            'contact' => '', 'card_id' => 0, 'device' => 0, 'password' => '', 'race' => ''
        ], $options));
    }

    public function getDraftCards($code, $page = 1, $limit = 20, $race = '') {
        return $this->post('/shared/commodity/draftCard', [
            'sharedCode' => $code, 'page' => $page, 'limit' => $limit, 'race' => $race
        ]);
    }
}

// 使用示例
$client = new SharedAPIClient('https://供货商域名', '你的app_id', '你的app_key');

$info = $client->connect();
echo "店铺：" . $info['shopName'] . "  余额：¥" . $info['balance'];

$order = $client->purchase('PROD001', 1, ['race' => '普通']);
echo "卡密：" . $order['secret'];

Python SDK

import requests, hashlib, time, random
from urllib.parse import urlencode, unquote

class SharedAPIClient:
    def __init__(self, domain, app_id, app_key):
        self.domain = domain.rstrip('/')
        self.app_id = app_id
        self.app_key = app_key

    def _sign(self, data):
        if 'sign' in data: del data['sign']
        sorted_data = {k: v for k, v in sorted(data.items()) if v != ''}
        return hashlib.md5(
            unquote(urlencode(sorted_data) + "&key=" + self.app_key).encode()
        ).hexdigest()

    def post(self, url, params=None):
        data = {**(params or {}), 'app_id': self.app_id, 'app_key': self.app_key}
        data['sign'] = self._sign(data)
        r = requests.post(f"{self.domain}{url}", data=data, timeout=30).json()
        if r.get('code') != 200: raise Exception(r.get('msg', 'Unknown error'))
        return r.get('data', {})

    def connect(self):    return self.post('/shared/authentication/connect')
    def get_items(self):  return self.post('/shared/commodity/items')

    def get_inventory(self, code, race=''):
        return self.post('/shared/commodity/inventory', {'sharedCode': code, 'race': race})

    def purchase(self, code, num, **opts):
        return self.post('/shared/commodity/trade', {
            'shared_code': code, 'num': num, 'contact': '', 'card_id': 0,
            'device': 0, 'password': '', 'race': '',
            'request_no': f"{random.randint(100,999)}{int(time.time())}{random.randint(100,999)}",
            **opts
        })

# 使用示例
client = SharedAPIClient('https://供货商域名', '你的app_id', '你的app_key')
info = client.connect()
print(f"店铺：{info['shopName']}  余额：¥{info['balance']}")

order = client.purchase('PROD001', 1, race='普通')
print(f"卡密：{order['secret']}")

常见问题

// 如果 widget 包含 {"name": "server", "cn": "游戏区服"}
// 则购买时额外传递：
$params['server'] = '艾欧尼亚';

category[普通]=100.00
category[高级]=200.00
category[豪华]=300.00

curl -X POST "https://你的域名/shared/authentication/connect" \
  -d "app_id=你的ID" \
  -d "app_key=你的KEY" \
  -d "sign=计算得到的签名"

错误码

常见错误信息