公共套餐查询

更新：2026-10-28。公共接口实现已完成，正在等待后端发布与线上验收；文档可读不表示接口已经上线。旧版本可能返回接口不存在，客户端应显示可重试的加载状态，不展示内部错误。

用途与权限

所有客户端共用同一 SaaS 套餐数据源，不需要管理员的套餐管理权限；必须携带有效的平台登录 token。“公共”指跨业务共用，不是匿名访问。

此接口只展示套餐，不创建订单、不发放权益、不证明当前用户已订阅，也不授权购买。下架套餐可用于预览；归档套餐不返回。Apple 结算价格需以 StoreKit 商品信息为准。

请求

GET https://work.zingyang.com/api/sys/saas/plan/catalog

请求头：X-Access-Token: <平台登录token>。客户端仍可携带当前 X-Tenant-Id；目录是全局套餐定义，不返回任何租户的订阅信息。

参数	类型	说明
planCodes	字符串	必填，逗号分隔1–20个套餐编码；每个1–100字符，只允许英文字母、数字、下划线和连字符

curl --get 'https://work.zingyang.com/api/sys/saas/plan/catalog' \
  --header 'X-Access-Token: <平台登录token>' \
  --data-urlencode 'planCodes=cofree_plus_monthly,cofree_pro_monthly'

以下为结构示例，不是线上实测响应：

{
  "success": true,
  "code": 200,
  "message": "",
  "result": [
    {
      "id": "<后台套餐ID>",
      "name": "CoFree Plus 月付",
      "code": "cofree_plus_monthly",
      "billingCycle": "month",
      "price": 69,
      "currency": "CNY",
      "appleProductId": "com.zingyang.Cofree.plus.monthly"
    }
  ]
}

字段	说明
id / code / name	后台套餐ID、编码、名称
billingCycle	month、year、trial、custom；不要把未知周期显示为月付
price	后台配置价格，可能为空；不是最终Apple结算报价
currency	配置币种，可能为空；缺失时不要猜测币种
appleProductId	Apple商品ID，可能为空；存在也不表示商品已审核或可购买

结果按后台价格升序排列。编码不存在、归档或没有匹配项时返回空数组。接口不返回内部备注、Apple管理日志和密钥，也不返回尚未配置的额度或编造赠送权益。

错误和客户端行为

缺失/过期token：登录失败，按平台登录机制处理。
参数缺失或格式非法：请求错误（400），不要自动改成查询全部套餐。
网络或服务失败：显示友好的加载失败与重试按钮，不直接显示服务端路径或异常栈。
切换账号或组织时取消旧请求并清空旧状态，丢弃旧会话的迟到响应。
每次进入页面重新读取；失败不能悄悄回退到写死价格。

与已有接口的关系

/sys/saas/plan/list 仍是管理员管理接口，不供普通App获取套餐。 /dashboard/analysis/current-plan 查询当前组织已有订阅，不是待选择的套餐目录。 /talk/v1/subscription/plans 属于ZingTalk，包含Talk专属套餐和订阅逻辑，CoFree不应串用。先前新增的 /sys/saas/cofree/plans 已从新版代码撤除，请使用本公共接口。