01概要 02キーとリクエスト 03ストア API 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 ベース 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 の両方を確認してください。API の成功はサブスクリプションの有効化完了を意味しません。引き換えの進捗は data.status で確認します。
権限	読み取り権限には残高、商品、在庫、見積もり、自分の注文と納品コードの照会が含まれます。商品の購入とコードの引き換えには、それぞれ追加の権限が必要です。
キーの管理	各アカウントで有効な統合キーはひとつです。キーは作成時のみ表示され、保存されるのはハッシュのみです。再発行すると旧キーは無効になります。
制限	1 アカウントにつき毎分 60 リクエスト、同時実行は 1 件です。処理中は 429 を返します。統合キー独自の 1 注文あたり購入金額上限はありません。残高、在庫、商品ごとの購入数量制限は引き続き適用されます。

権限を選択しただけでは保存も課金もされません。キーの作成時に選択が反映されます。既存キーの権限を変更するには再発行し、サーバーの設定を更新してください。無効化は今後のリクエストを停止しますが、受付済みの注文を取り消したり返金したりするものではありません。

購入と引き換えは別の操作です

商品同期・注文照会：追加権限はどちらもオフのままで利用できます。
自動仕入れ：購入権限を有効にします。/order はストア残高を使用します。
顧客に代わって引き換える場合：/plans、/check、/redeem、/result 用の引き換え権限を有効にします。対象は下記サービスのみです。顧客が自分で引き換えるためにコードを販売するだけなら、この権限は不要です。

レスポンス · サンプル

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

ストア API

全エンドポイントは 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	items で取得する商品 API 識別子です。注文時は表示用 ID ではなく shared_code を使用します。
num	整数 1～10000。商品ごとの最小・最大数量も適用されます。
race / sku	現在の商品設定を使用します。バリエーションは sku[NAME]=VALUE の形式で送信します。
contact	互換性用の参照値（1～32 バイト）です。ストア側が照会用識別子を生成します。注文照会には tradeNo を使用してください。
request_no	ASCII の英数字、アンダースコア、ハイフンで 8～64 文字。アカウント内で一意にしてください。
card_id / device / password / coupon	商品ルールに従う任意の注文項目です。password は注文照会用パスワードです。item の必須 widget 項目も送信してください。

購入 · 実際の残高引き落とし

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"

仕入れは CNY 残高で決済します。USD 表示や独自の販売マージンは仕入れの決済を変更しません。secret には機密の納品情報が含まれるため、公開ログに記録しないでください。

コード引き換え

パス /partner/v1/…	必須項目	動作
`/plans`	—	対応プランを返します。利用可能性や商品との互換性を保証するものではありません。
`/check`	tradeNo, code	自分の支払い済み注文で納品された対象コードを確認します。
`/redeem`	tradeNo, code, session	顧客の同意を得て購入済みコードを引き換えます。新たな商品購入や仕入れ残高の再引き落としは行いません。
`/result`	tradeNo, code	この統合 API で送信した引き換えを照会します。旧専用キーやウェブサイトからの申請は自動移行されません。

4 つのエンドポイントすべてに引き換え権限が必要です。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 を保存してください。同一アカウントで参照番号と項目が同じリクエストは、再購入せず既存注文を返します。結果が不明な場合は処理を拒否します。引き換えコードの送信は 1 回のみ記録されます。失敗または不明な場合はサポートに照合を依頼してください。

エラー / 状態	対処
401 · INVALID_API_KEY	キーが無効・無効化済み、またはアカウントが利用できません。
403 · SCOPE_DENIED	注文には購入権限、plans / check / redeem / result には引き換え権限が必要です。権限を選択してキーを再発行し、サーバーの設定を更新してください。
403 · REDEMPTION_NOT_ALLOWED	未払いの注文、該当注文で納品されていないコード、または対象外の引き換えサービスです。
404 · PRODUCT_UNAVAILABLE / ORDER_NOT_FOUND	販売不可・非公開・API 未対応の商品、またはこのアカウントの注文ではありません。
409 · IDEMPOTENCY_CONFLICT	同じ購入参照番号が異なるパラメーターで使われました。新たな引き落としはありません。
409 · ORDER_OUTCOME_UNCERTAIN	以前のリクエストは記録済みですが、結果が確認できません。新しい参照番号を使わず、サポートに照合を依頼してください。
409 · REDEMPTION_ALREADY_SUBMITTED	引き換えは記録済みです。再送信せず result で確認してください。
429 · RATE_LIMIT / ACCOUNT_BUSY	Retry-After に従い、ランダムな待ち時間を加えて再試行してください。
タイムアウト / 5xx	書き込みは受け付けられている可能性があります。再試行前に元の注文または引き換え状態を確認してください。

ストア側の業務エラーは HTTP 200、code:0 と msg で返る場合があります。業務コードも必ず確認してください。エッジ側の IP 制限は、同じ公開 IP を使用するクライアント間で共有されます。

セキュリティと移行

キーはサーバー側だけで管理

キーをウェブページ、モバイルアプリ、URL、スクリーンショット、公開リポジトリに含めないでください。HTTPS を使用し、Authorization とリクエスト本文をログから除外してください。

必要最小限の権限

購入・引き換え権限は初期状態では無効です。読み取り専用キーでも納品コードを参照できるため、秘密として扱ってください。キーを共有せず、漏えいが疑われた場合は無効化し、残高と注文を確認してください。漏えいは有効化したすべての権限に影響します。

旧方式からの明示的な移行

旧 app_id + sign と旧ストアキーは独立しており、統合キーの権限設定では制御されません。移行後は旧キーを無効にしてください。新しい統合キーで旧ネイティブエンドポイントを直接呼び出すことはできません。

運用上の注意

現在、独立したテスト用サンドボックスはありません。読み取り専用の呼び出しから開始してください。購入と引き換えは実際に処理されます。認証や制限だけで、キーの盗難や大量アクセス攻撃を完全に防げるわけではありません。

あなたのストアに。商品と在庫を、ひとつの API で。