優易點統一入口開發文件

這頁解決什麼問題：幫助你先確定《優易點統一入口》的唯一推薦接入路線。
適用場景：標準託管用戶，希望盡快完成網頁支付與託管登入整合。
完成後你將得到什麼：一條可直接交給 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
• 不要把高級覆寫項當成標準託管接入的必填項