01接入概覽 02密鑰與請求 03商城接口 04兌換接口 05重試與錯誤 06安全與兼容

UNIFIED PARTNER API / V1

你的網站。
我們的商品與庫存。

用一把 API 密鑰查詢商品、用商城餘額進貨，再爲客戶使用適用的兌換碼。你保留自己的品牌、售價和收款方式。

HTTPS · POST FORM · JSON · CNY

首次調用 · 僅查詢餘額

curl -X POST "https://yunshutoken.com/partner/v1/connect" \
  -H "Authorization: Bearer $YUNSHU_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data ""

01 / ACCOUNT登錄並創建密鑰

先查詢商品。需要自動進貨或代客戶兌換時，再開啓對應權限。

02 / INTEGRATE先查商品與報價

在你的服務端調用，密鑰不進入瀏覽器。

03 / FULFIL交付兌換碼，或代客戶兌換

按你的售價收款；進貨按本賬號供貨價結算，兌換僅限支持的商品。

API BASE URLhttps://yunshutoken.com/partner/v1

兌換服務來源 · 非通用兌換站redeem.yunshutoken.com

密鑰與請求

所有接口統一使用下列請求約定，無需傳入 app_id、計算 MD5 簽名，也無需單獨申請兌換 Agent Key。

項目	約定
身份驗證 · Authorization	`Bearer ysu_…`
請求方式與格式	`POST` · `application/x-www-form-urlencoded` · UTF-8
響應判斷	同時檢查 HTTP 200 與 code === 200。它們表示本次接口成功，不代表訂閱已開通；兌換進度須再檢查 data.status。
接口權限	默認可查詢餘額、商品、庫存、報價和本賬號訂單（含兌換碼）。購買商品與代客戶兌換須分別勾選授權。
創建與更換	每賬號一把有效統一密鑰。新密鑰僅顯示一次，服務端只存其哈希；重置後舊密鑰失效。
調用頻率	每賬號每分鐘最多 60 次請求；同一賬號同時只處理一個請求，繁忙返回 429。統一密鑰不另設單筆採購金額上限；仍需滿足餘額、庫存和商品數量規則。

勾選權限不會自動保存或扣款。創建密鑰時應用選擇；已有密鑰需生成新密鑰並替換後生效，同時更新你的程序。停用只阻止後續請求，不會取消已受理訂單或自動退款。

購買 ≠ 兌換：按你的業務選擇

只同步商品或查詢訂單：兩項都不勾選。
自動向商城進貨：開啓購買權限；調用 /order 會從你的商城餘額扣款。
程序替客戶使用兌換碼：開啓兌換權限；支持 /plans、/check、/redeem、/result，僅限下方指定兌換站。只把碼賣給客戶自行兌換，不需要這一權限。

響應格式 · 僅爲示例

{"code":200,"data":{"shopName":"SHOP_NAME","balance":"0.00"}}

商城接口

以下均爲 POST。? 表示可選；所需規格和 widget 字段以商品詳情爲準。庫存可能變化，下單前先覈對報價。

路徑 /partner/v1/…	用途	參數	返回與約束
`/connect`	連接與餘額	—	返回 shopName、balance。
`/items`	商品與庫存快照	—	分類樹 data[].children[]；只含公開上架、已開放 API 的商品。
`/item`	商品詳情	code	規格、數量限制、widget、redemption_host。
`/stock`	實時庫存	code; race?, sku?	data.stock；不預留庫存。
`/quote`	採購報價	code, num; race?, sku?, card_id?	data.price 爲數量合計，currency_code 爲結算幣種；報價不鎖價。
`/order`	購買商品 · 扣餘額	shared_code, num, contact, request_no	需開啓“用我的商城餘額購買商品”。真實扣款；返回 tradeNo、amount、status、secret。
`/orderStatus`	本人訂單	tradeNo	只查詢本賬號訂單；status 是商城支付狀態，不是兌換狀態。

字段說明

字段	規則
code / shared_code	商品 API 標識，來自 items；下單字段名爲 shared_code，不是前臺商品序號。
num	1–10000 的整數，同時遵守商品 minimum / maximum。
race / sku	按 item 返回的配置填寫。sku 使用表單 sku[規格名]=規格值。
contact	兼容字段，填寫業務標識（1–32 字節）；系統生成訂單查詢標識，查單請使用 tradeNo。
request_no	8–64 位字母、數字、下劃線或連字符，本賬號內唯一。
card_id / device / password / coupon	下單可選；按商品要求填寫。password 是訂單查詢密碼。額外 widget 字段按 item 配置填寫。

購買商品 · 真實扣款

curl -X POST "https://yunshutoken.com/partner/v1/order" \
  -H "Authorization: Bearer $YUNSHU_API_KEY" \
  --data-urlencode "shared_code=PRODUCT_CODE" \
  --data-urlencode "num=5" \
  --data-urlencode "contact=YOUR_ORDER_CONTACT" \
  --data-urlencode "request_no=YOUR_UNIQUE_REFERENCE"

人民幣餘額結算。頁面美元展示不改變扣款幣種；你的零售加價不改變供貨價。secret 是敏感交付內容，不要寫入公開日誌。

兌換接口

路徑 /partner/v1/…	必填字段	說明
`/plans`	—	讀取支持的套餐，不保證當前庫存或所有商品均適配。
`/check`	tradeNo, code	覈對本人已付款訂單中的適用兌換碼。
`/redeem`	tradeNo, code, session	使用已購碼爲客戶充值，須獲得客戶授權；不會新購商品或再次扣商城採購餘額。
`/result`	tradeNo, code	查詢經統一接口提交的兌換結果；舊獨立密鑰或網頁提交的記錄不會自動遷移。

這四個接口都需要開啓兌換權限。session 爲客戶授權的 sessionToken，或包含 sessionToken / session_token 的 JSON 字符串；只有 accessToken 不足以兌換。儘量讓客戶在官方兌換頁面操作，減少你的系統接觸敏感憑據。

提交兌換 · 真實操作

curl -X POST "https://yunshutoken.com/partner/v1/redeem" \
  -H "Authorization: Bearer $YUNSHU_API_KEY" \
  --data-urlencode "tradeNo=YOUR_PAID_ORDER" \
  --data-urlencode "code=CODE_DELIVERED_IN_THAT_ORDER" \
  --data-urlencode "session=$CUSTOMER_AUTHORIZED_SESSION"

兌換結果 · 僅爲示例

{"code":200,"data":{"ok":true,"order_id":null,"status":"processing",
 "payment_status":"pending","plus_active":null,"auto_renewal_status":"unknown"}}

status 可爲 processing / completed / action_required / failed。paid 只代表支付事實，不代表訂閱已開通；plus_active 爲 null 表示未知或不適用。

重試與錯誤

購買前在你的系統中保存唯一訂單編號 request_no。同賬號、同編號、同參數的重複請求只返回已存在的訂單，不再採購；沒有可確認結果時保守拒絕重試。兌換同一碼只允許登記一次提交，失敗或不確定時需覈對後由支持處理。

錯誤或信號	處理
401 · INVALID_API_KEY	密鑰無效、已停用或賬號不可用。
403 · SCOPE_DENIED	下單需購買權限；plans / check / redeem / result 均需兌換權限。在控制檯選擇後替換密鑰，並更新程序。
403 · REDEMPTION_NOT_ALLOWED	訂單未付款、兌換碼不屬於該訂單，或商品不在指定兌換範圍。
404 · PRODUCT_UNAVAILABLE / ORDER_NOT_FOUND	商品未開放、隱藏、停售，或訂單不屬於當前賬號。
409 · IDEMPOTENCY_CONFLICT	同一採購流水號對應不同參數，不會再次扣款。
409 · ORDER_OUTCOME_UNCERTAIN	此前請求已登記但尚無法確認訂單。聯繫客服覈對，不要換編號重複下單。
409 · REDEMPTION_ALREADY_SUBMITTED	已登記兌換提交；調用 result 查詢，不要重複提交。
429 · RATE_LIMIT / ACCOUNT_BUSY	等待 Retry-After 指定的秒數，再加入少量隨機延遲重試；不要連續快速請求。
Timeout / 5xx	寫請求結果可能不確定。先查原訂單或兌換狀態，不要盲目重試。

原生商城業務錯誤可能使用 HTTP 200 + code:0，並在 msg 中說明原因，因此必須同時檢查業務碼。站點邊緣另按 IP 限流，同一出口共享額度。

安全與兼容

密鑰只放服務端

不要放入網頁、移動端包、URL、截圖或公開倉庫。使用 HTTPS；關閉請求體與 Authorization 日誌。

權限按需開啓

購買與兌換權限默認關閉。僅查詢也能讀取本賬號已交付的兌換碼，因此只讀密鑰同樣需要保密。不要向他人轉交自己的密鑰；發現泄露立即停用並覈對餘額、訂單。共享密鑰泄露會影響其已啓用的全部權限。

舊版兼容，不靜默切換

舊 app_id + sign 接口及舊商城密鑰獨立保留，不受本頁統一密鑰權限設置控制。遷移完成後，在舊版密鑰頁停用舊密鑰。新統一密鑰不能直接用於舊原生接口。

先查詢，再測試真實業務

目前沒有獨立測試沙箱。先用只讀接口聯調，採購與兌換均爲真實業務。身份校驗、限流不等於絕對安全，也不能消除密鑰泄露或大流量攻擊風險。

你的網站。我們的商品與庫存。