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 接口及旧商城密钥独立保留，不受本页统一密钥权限设置控制。迁移完成后，在旧版密钥页停用旧密钥。新统一密钥不能直接用于旧原生接口。

先查询，再测试真实业务

目前没有独立测试沙箱。先用只读接口联调，采购与兑换均为真实业务。身份校验、限流不等于绝对安全，也不能消除密钥泄露或大流量攻击风险。

你的网站。我们的商品与库存。