API 對接文件

外部程式透過這套介面拉商品、查庫存、詢價、下單、查訂單。店鋪共享功能本身就是用它實現的。

只是想把別人的貨接進來賣，不用自己寫程式碼 —— 直接用後臺的店鋪共享。這篇是給要自己寫對接程式的人看的。

開始之前：

在對方店鋪註冊賬號，到 會員中心 → 我的主頁 拿 商戶 ID（app_id）和 商戶金鑰（app_key）
對方商品的 API 對接 開關要開啟，否則拉不到
你拿到的價格由你在對方店裡的會員等級決定

開啟共享對接後，外部程式可以透過本介面拉取商品、讀取庫存、詢價、下單以及查詢訂單。

基礎說明

請求方式：POST
請求格式：推薦 application/x-www-form-urlencoded
鑑權方式：公共引數 app_id + sign
成功響應：code = 200
失敗響應：通常為 code = 0，具體錯誤原因見 msg

簽名演算法

php

/**
 * 獲取資料簽名
 * @param array $data
 * @param string $appKey
 * @return string
 */
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": {}
}

失敗示例：

json

{
  "code": 0,
  "msg": "金鑰錯誤"
}

業務欄位說明

race：商品種類，對應商品配置中的 [category] 節點鍵名，例如 月卡、年卡
sku：商品SKU組合，建議按陣列提交，例如 sku[機身顏色]=黑色&sku[儲存容量]=256GB
card_id：預選卡ID，僅當商品詳情中的 draft_status=1 時才有意義
widget：商品自定義控制元件，若商品詳情返回了 widget，下單時需要把每個控制元件的 name 欄位作為請求引數一起提交
request_no：請求冪等號，雖然程式碼裡不是強制必填，但強烈建議每次下單都傳唯一值，避免重複下單

獲取全部商品列表

POST /shared/commodity/items

Body引數：無額外業務引數，只需要公共引數 app_id、sign
返回說明

data 為分類陣列，每個分類下的 children 為商品列表，常見欄位如下：

欄位名稱	型別	說明
id	int	分類ID或商品ID
name	string	分類名稱或商品名稱
children	array	當前分類下可對接商品列表
code	string	商品編碼，下單和詳情介面會用到
price	string/float	商品遊客價
user_price	string/float	商品會員價/代理價
stock	int	自動發貨商品會附帶庫存
delivery_way	int	發貨方式
draft_status	int	是否支援預選

獲取單個商品詳情

POST /shared/commodity/item

Body引數

引數名稱	必選	型別	說明
code	是	string	商品編碼

返回核心欄位

data 為商品詳情物件，核心欄位如下：

欄位名稱	型別	說明
id	int	商品ID
name	string	商品名稱
description	string	商品介紹
code	string	商品編碼
price	string/float	商品遊客價
user_price	string/float	商品會員價/代理價
stock	int/string	當前庫存
delivery_way	int	發貨方式
contact_type	int	聯絡方式型別，`0=不限`、`1=手機`、`2=郵箱`、`3=QQ`
password_status	int	是否啟用查單密碼，`0=否`、`1=是`
draft_status	int	是否支援預選，`0=否`、`1=是`
draft_premium	string/float	預選附加價格
minimum	int	最低購買數量，`0` 表示不限制
maximum	int	單次最多購買數量，`0` 表示不限制
config	object	已解析後的商品配置，通常包含 `category`、`sku`、`wholesale` 等
widget	array/null	自定義控制元件配置，下單時要把控制元件的 `name` 對應值一起提交
seckill_status	int	是否秒殺商品
seckill_start_time	string	秒殺開始時間
seckill_end_time	string	秒殺結束時間
owner	object	供貨商資訊
service_url	string	客服連結
service_qq	string	客服QQ
share_url	string	商品分享連結

檢查庫存狀態

POST /shared/commodity/inventoryState

Body引數

引數名稱	必選	型別	說明
shared_code	是	string	商品編碼
num	是	int	購買數量
card_id	否	int	預選卡ID，不預選時傳 `0` 或不傳
race	否	string	商品種類

返回說明

請求成功表示當前庫存或預選卡狀態滿足下單條件，例如：

json

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

如果庫存不足、商品不存在、商品停售或預選卡已被佔用，會直接返回失敗資訊。

獲取庫存與基礎配置

POST /shared/commodity/inventory

Body引數

引數名稱	必選	型別	說明
sharedCode	是	string	商品編碼
race	否	string	商品種類，不傳時按預設種類處理

返回核心欄位

欄位名稱	型別	說明
count	int	當前庫存數量
delivery_way	int	發貨方式
draft_status	int	是否支援預選
price	string/float	商品基礎售價
user_price	string/float	會員售價
config	string	商品配置，返回的是INI文字
factory_price	string/float	當前對接身份下的拿貨價
is_category	bool	是否為種類商品

注意：這個介面返回的 config 是配置文字，不是 item 介面裡那種已解析物件。

獲取實時庫存

POST /shared/commodity/stock

Body引數

引數名稱	必選	型別	說明
code	是	string	商品編碼
race	否	string	商品種類
sku	否	array	SKU組合

返回示例

json

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

詢價

POST /shared/commodity/valuation

Body引數

引數名稱	必選	型別	說明
code	是	string	商品編碼
num	是	int	購買數量
race	否	string	商品種類
sku	否	array	SKU組合
card_id	否	int	預選卡ID

返回示例

json

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

獲取預選卡列表

POST /shared/commodity/draftCard

Body引數

引數名稱	必選	型別	說明
code	是	string	商品編碼
page	建議	int	頁碼，建議從 `1` 開始
limit	否	int	每頁數量，預設 `10`
race	否	string	商品種類
sku	否	array	SKU組合

返回核心欄位

欄位名稱	型別	說明
list	array	預選卡列表
total	int	總數量
list[].id	int	預選卡ID
list[].draft	string	預覽資訊
list[].draft_premium	string/float	該預選卡附加價格

只有當商品詳情中的 draft_status=1 時，這個介面才可用。

獲取單個預選卡詳情

POST /shared/commodity/draft

Body引數

引數名稱	必選	型別	說明
code	是	string	商品編碼
card_id	是	int	預選卡ID

返回核心欄位

欄位名稱	型別	說明
draft_premium	string/float	該預選卡附加價格

下單

POST /shared/commodity/trade

該介面內部強制使用餘額支付

Body引數

引數名稱	必選	型別	說明
shared_code	是	string	商品編碼
num	是	int	購買數量
request_no	否	string	請求冪等號，建議每次下單都傳唯一值
contact	否	string	聯絡方式，佔位傳值即可
race	否	string	商品種類
sku	否	array	SKU組合
card_id	否	int	預選卡ID
password	否	string	查單密碼
coupon	否	string	優惠券程式碼
device	否	int	裝置型別，未特殊區分時可傳 `0`

如果商品詳情返回了 widget，還需要把每個控制元件的 name 欄位作為附加引數一起提交。

返回核心欄位

欄位名稱	型別	說明
tradeNo	string	系統訂單號
amount	string/float	實際扣費金額
secret	string/null	發貨內容，若為手動發貨則可能返回等待發貨提示
stock	string/int	下單後的剩餘庫存

返回示例：

json

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

訂單查詢

POST /shared/commodity/query

Body引數

引數名稱	必選	型別	說明
tradeNo	是	string	系統訂單號，注意這裡欄位名是 `tradeNo`，不是 `trade_no`

返回核心欄位

欄位名稱	型別	說明
secret	string	發貨內容或卡密內容
widget	object/null	下單時提交的自定義控制元件值
status	int	訂單支付狀態，`0=未支付`、`1=已支付`

對接建議流程

先呼叫 items 或 item 拉取商品資訊。
如果商品有 category 或 sku，先確定 race 和 sku。
如果商品支援預選，先呼叫 draftCard 獲取可選項，需要時再呼叫 draft 獲取附加價格。
正式下單前，建議先呼叫 stock、valuation 或 inventoryState 做一次庫存與價格確認。
呼叫 trade 下單。
如果你需要輪詢發貨結果，再呼叫 query 查詢訂單狀態和發貨內容。

補充說明

若只是測試鑑權是否可用，可額外請求 /shared/authentication/connect。
商品詳情介面返回的 config 是解析後的物件，而 inventory 介面返回的 config 是INI文字，這不是文件寫錯，是當前程式本身的實現差異。
如果你打算完全相容本專案自帶共享客戶端，建議優先按本文件中的欄位名和返回結構實現，不要自行把 tradeNo 改成 trade_no 這類名字。

API 對接文件 ​

基礎說明 ​

簽名演算法 ​

公共請求引數 ​

公共響應格式 ​

業務欄位說明 ​

獲取全部商品列表 ​

獲取單個商品詳情 ​

檢查庫存狀態 ​

獲取庫存與基礎配置 ​

獲取實時庫存 ​

詢價 ​

獲取預選卡列表 ​

獲取單個預選卡詳情 ​

下單 ​

訂單查詢 ​

對接建議流程 ​

補充說明 ​

API 對接文件

基礎說明

簽名演算法

公共請求引數

公共響應格式

業務欄位說明

獲取全部商品列表

獲取單個商品詳情

檢查庫存狀態

獲取庫存與基礎配置

獲取實時庫存

詢價

獲取預選卡列表

獲取單個預選卡詳情

下單

訂單查詢

對接建議流程

補充說明