有赞云开放平台 Skill
覆盖商家自研和服务商最常接的业务：自用型与工具型应用的 token 获取与刷新、订单列表详情与发货、售后退款、商品创建与查询、客户积分与标签、消息推送的验签与去重。重点讲清 token 只放 URL、API 按名称加版本号拼路径、订单金额是元而商品价格是分，以及推送消息的 MD5 验签与重推去重。
安装
选你用的 Agent，复制命令。
npx -y skills add fxp/skillify --skill youzan --agent claude-code --yes装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。
npx -y skills add fxp/skillify --skill youzan --agent codex --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill youzan --agent cursor --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill youzan --agent opencode --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill youzan --agent gemini-cli --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill youzan --agent github-copilot --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill youzan --agent trae --yes装到项目的 .trae/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill youzan --agent windsurf --yes装到项目的 .windsurf/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill youzan --agent qwen-code --yes把 --agent 换成你用的 Agent 标识，可以一次写多个。skills CLI 1.5.25 共支持 79 个，例如 qwen-code、kimi-code-cli、trae-cn、qoder、lingma、cline、roo。
或者让 Agent 自己装
读 https://github.com/fxp/skillify/blob/main/skills/youzan/prompt.md 并照它执行装对了的标志：references/ 下有 7 份文档，里面 grep '<!-- Gap:' 能搜到 1 处。
装好后，可以这样问你的 Agent
这份 Skill 覆盖的典型任务。点一下复制。
7 类能力
每类能力对应一份 reference，Agent 按任务只打开需要的那份。
鉴权与 access_token
自用型与工具型换 token、code 回调、刷新与按店铺缓存、API 调用格式、IP 白名单与能力包
订单与发货
订单列表分窗口拉取、订单详情结构、状态与金额字段、发货与快递公司、订单备注
售后与退款
售后单查询、version 乐观锁、同意与拒绝退款、商家主动退款、退款状态与消息
商品
新旧商品 ID 模型、创建与编辑、上下架、详情与列表查询、改价改库存、商品消息
客户、积分与标签
yz_open_id 与两套 account_type、客户创建查询、手机号换 ID、积分幂等加减、打标签、防回环同步
消息推送
订阅配置、Event-Sign 验签、msg 解码、超时重推与熔断、乱序去重、常用消息类型
错误码与限流
三种返回结构、网关与业务错误码、限流形态与退避、单店建议 QPS、额度与欠费、统一调用封装
当前事实
整理自官方文档（抓取于 2026-09-11），还没有用真实凭证验证。
| 项 | 值 |
|---|---|
| API 地址 | POST https://open.youzanyun.com/api/{api_name}/{version}?access_token= |
| 换 token | POST /auth/token（JSON）；自用型 silent + kdt_id，工具型 authorization_code + code |
| 有效期 | access_token 7 天，expires 是毫秒时间戳；refresh_token 28 天 |
| 错误结构 | HTTP 恒为 200；网关错误在 gw_err_resp.err_code，业务错误看 success / code |
| 金额单位 | 订单、退款是元字符串；商品价格是分整数 |
| 推送验签 | Event-Sign = md5(client_id + 原始 body + client_secret)，5 秒内返回 success |
照通用经验写容易错的 7 件事
来自官方文档，还没有用真实凭证验证。
- token 不是 Bearer 头。只能拼在 URL 的 access_token 参数里；无凭证探测：放头或 body 都返回 4201 非法的请求凭证。
- 自用型和工具型换 token 方式不同。自用型用 kdt_id 直接换并用 refresh 参数刷新；工具型要接住订购回调里 2 分钟有效的 code，再用 refresh_token 续期。
- API 按名称加版本号定位。版本是路径段，同名接口不同版本字段不同；缺版本号返回 4001，版本不存在返回 4005。
- 金额单位混用且不报错。订单金额是元字符串，同一响应里储值抵扣是分；创建商品价格要传分，19.90 元传 1990。
- 推送是 MD5 验签加 urlencode 的 msg。对原始请求体算签名，msg 先解码再解析；消息会重推和乱序，用 msg_id 去重、version 丢弃旧消息。
- 待发货要听 trade_TradeBuyerPay。支付后可能是待成团或待接单，虚拟商品不触发；收到消息后等 30 秒再查订单详情。
- 写操作带版本号或幂等键。同意退款要带最新 version；主动退款和积分加减用稳定的 biz_value 防重复。
无凭证探测
- 错误响应的 HTTP 状态都是 200；/api/ 网关错误包在 gw_err_resp（err_code、err_msg、trace_id）里，不是顶层 code。
- access_token 放在 Authorization: Bearer 头或 JSON body 里都返回 4201 非法的请求凭证，只认 URL query。
- URL 带伪造 token 返回 4203，err_msg 为 Token 不存在；伪造 client_id 换 token 返回 1103 Client 不存在。
- 路径缺版本号返回 4001；API 名或版本不存在返回 4005，且先于 token 校验。
- Content-Type 为 text/plain 返回 4007；http:// 请求被 301 重定向到 https://。