优易点统一门户开发文档

这页解决什么问题：帮助你先确定《优易点统一门户》的唯一推荐接入路线。
适用场景：标准托管用户，希望尽快完成网页支付与托管登录接入。
完成后你将得到什么：一条可直接交给 AI 或开发者执行的默认实现路径。

优易点统一门户提供什么

优易点统一门户负责托管以下能力：

• 产品、价格与支付渠道配置
• 产品列表、产品下权益与实时库存的统一读取
• 托管支付页面与订单创建链路
• 面向数值型权益的自定义金额余额 / 点数充值
• 面向可过期积分与兜底积分的有序扣取
• 对公转账已到账订单补录
• 托管登录页面与多渠道身份接入
• 微信公众号模板消息绑定与服务端发送
• 基于已验证手机号或后端直传手机号的短信模板通知
• 服务端订单、权益与登录校验 API
• 周期性订阅权益的自动维护与周期更新

本文档覆盖的 SDK 版本为 @youidian/sdk v3.6.3。

唯一推荐接入路径

默认只讲一条路线：

1. 安装 @youidian/sdk
2. 前端从 @youidian/sdk/client 使用 PaymentUI 打开托管支付
3. 前端从 @youidian/sdk/client 使用 LoginUI 打开托管登录
4. 后端从 @youidian/sdk/server 使用 PaymentClient
5. 支付成功后由你的后端查询订单、读取权益并完成业务发放
6. 登录成功后由你的后端校验 loginToken，再建立本地用户与会话

默认路径中：

• 支付前通常先拉产品列表，再用 productCode 发起支付
• 余额充值产品可以通过 metadata.customAmount 暴露托管输入或集成方自有输入所需配置
• 登录使用 loginToken
• 不要求业务侧先创建订单
• 用户权益默认由统一平台托管
• 不要求配置 apiUrl、checkoutUrl、loginUrl、baseUrl

从 SDK v3.5.0 开始，价格页应在后端调用 getSubscriptionUpgradeOptions(userId, options) 获取平台确认的升级目标，不再自行比较套餐等级；下单时通过 subscriptionIntent: "STANDARD" | "UPGRADE" 区分普通购买和升级。

从 SDK v3.2.0 开始，LoginUI 会为 OAuth 重定向自动生成同源登录回调 URL。标准登录接入不需要自建回调页面。

从 SDK v3.2.2 开始，登录回调不再把 callbackUrl 放进 query 参数。SDK 会通过 hash/window.name 传递回调上下文，默认避开 popup.closed 轮询，也不会强制回调页执行 window.close()。

从 SDK v3.3.0 开始，LoginUI 支持使用 iframe 模态窗口打开托管登录页。如需保留旧版完整弹窗流程，可传入 displayMode: "popup"。

从 SDK v3.4.0 开始，LoginUI 默认使用 displayMode: "auto"：桌面端使用 iframe 模态窗口，移动端、iPadOS 与微信内浏览器会跳转到托管登录页。请在前端初始化时调用 handleLoginCallbackIfPresent()，让基于跳转的登录能够恢复最终结果。

从 SDK v3.3.2 开始，根包也会导出服务端手机号绑定请求与响应类型。当你的后端需要在自己的账号设置流程里让已登录的托管用户绑定手机号时，使用 PaymentClient.sendPhoneVerificationCode(...) 和 PaymentClient.bindPhoneNumber(...)。

从 SDK v3.3.10 开始，PaymentClient.createOrder(...) 支持 merchantPricing，用于后端计算优惠券、会员价、活动价或企业采购价后再创建订单。如果最终应付金额为 0，请使用 FREE 渠道创建订单，再打开既有订单收银台。

如果客户已经在线下完成对公转账，并且财务或业务系统确认到账，请使用 PaymentClient.createBankTransferOrder(...) 补录已支付订单。完整流程见对公转账订单。

从 SDK v3.3.10 开始，PaymentClient 还提供实时库存查询：在后端调用 getProductStock(...) 或 getProductStocks(...)，再决定是否展示购买按钮。限购产品如果在用户下单前已售罄，createOrder(...) 会返回 OUT_OF_STOCK（409）。完整库存生命周期和参数说明见库存限购产品。

从 SDK v3.3.10 开始，托管支付弹窗在用户取消或关闭待支付订单时，会尽力发送取消请求。对于库存限购产品，这会更快释放待支付订单占用的库存，而不必等库存占用超时。

从 SDK v3.4.1 开始，PaymentClient.consumeEntitlementPool(...) 可以按 key 顺序扣取数值型权益，getEntitlementCreditBuckets(...) 可以列出会优先扣取的有效积分桶。适用于订阅积分先扣、永久积分兜底的场景。详见权益积分池。

从 SDK v3.4.1 开始，PaymentClient.createWechatMessageBinding(...) 和 sendMessage(...) 支持微信公众号模板消息推送。未绑定用户可先通过 MessageUI.openWechatBinding(...) 打开托管绑定页。详见微信公众号消息推送。

从 SDK v3.4.2 开始，PaymentClient.getPhoneBinding(...) 和 updatePhoneNumber(...) 支持在后端查询和修改托管登录用户的已验证手机号。短信通知模板需要用户先绑定手机号时，使用这组方法完成前置检查和修改。详见短信消息推送。

从 SDK v3.4.4 开始，PaymentClient.sendMessage(...) 支持 phoneNumber、phoneCountryCode、phoneE164 等直传短信接收人字段。直传手机号发送成功后，可以把手机号回写到本次识别出的托管登录用户。

巴西葡萄牙语别名

从 SDK v3.6.3 开始，SDK 选项接受 locale 时，可以传 pt 或 pt-BR。两者共用同一套巴西葡萄牙语文案、应用渠道可见性规则和 BRL 定价。托管页面也可以直接使用 /pt-BR/... URL，地址栏不会改成其他语言代码。如果产品没有葡萄牙语价格，则返回已配置的默认价格。

特殊控制需求、私有部署、自定义域名与显式建单，请看高级接入。

推荐支付流程总览

你的后端
  -> getProducts(...)
  -> 如产品限购，再调用 getProductStock(...) 或 getProductStocks(...)
  -> 你的价格页展示产品、价格、产品权益
  -> 你的前端 PaymentUI.openPayment({ appId, userId, productCode })
  -> 优易点统一门户托管支付页
  -> 用户确认产品并完成支付
  -> 优易点统一门户创建并推进订单
  -> 前端收到成功回调 orderId
  -> 你的后端查询订单 / 权益
  -> 你的系统发放权益、刷新账户状态或读取更新后的余额

推荐登录流程总览

你的前端
  -> LoginUI.openLogin({ appId })
  -> 优易点统一门户托管登录页
  -> 用户完成登录
  -> 前端收到 loginToken
  -> 前端把 loginToken 提交给你的后端
  -> 你的后端 verifyLoginToken(loginToken)
  -> 你的系统匹配或创建本地用户并建立会话

文档阅读顺序

1. 安装
2. 支付集成
3. 自定义金额余额充值
4. 对公转账订单
5. 库存限购产品
6. 权益积分池
7. 登录集成
8. 自动登录回调
9. 高级接入
10. 支付渠道参考
11. 微信公众号消息推送
12. 短信消息推送
13. 微信小程序集成
14. 接入 Checklist

常见错误避免项

• 不要把 @youidian/sdk/login 当成默认入口
• 不要在默认支付路径里先写自建订单流程
• 不要信任前端登录结果本身，必须校验 loginToken
• 不要把高级覆盖项当成标准托管接入的必填项