Skip to main content
建立應用程式會完成註冊；進一步「設定」才是真正讓它運作。 本頁依你應該填寫的順序，逐一說明應用程式編輯器的四個分頁，並解釋每個欄位實際控管的內容。請先把這些設定正確無誤，再著手建立授權流程 — 多數 OAuth 整合失敗的主因是「設定不匹配」，而不是程式碼問題。
從開發者控制台的 「Your apps」 進入編輯器，或直接前往 https://fluz.app/for-developers/overview/{appId}。內嵌小工具使用相同分頁，並額外多一個 Installation 分頁 — 參見設定 App Widget。
從 Your apps 中選擇要設定的應用程式

​
各分頁有哪些內容

​
Overview 分頁

這裡有兩類東西，受眾截然不同。

​
你的憑證

Client ID 與 Client Secret 位於此分頁。凡是本節其他頁面要你用 Authorization: Basic base64(client_id:client_secret) 來驗證請求的，就是指這兩個值。API Key 與 API Secret 也在這裡 — 它們是另一組、負責不同工作。各種憑證用途請見 OAuth Applications。請把它們存入你的機密管理工具。絕對不要放進瀏覽器打包檔、行動裝置二進位檔，或版本控制的原始碼中。

​
你的公開識別

名稱、副標、描述、頭像與標誌，都是使用者在「同意畫面」上會看到的內容，並據此決定是否授權你的應用程式存取他們的資金。請把這些當成產品對外文案，而不是內部標籤。
即使你覺得在建立時已填寫，也請再檢查此分頁。建立精靈會先收集三個文字欄位，很容易先打個暫填內容就跳過 — 然後就這樣上了同意畫面。

​
Permissions 分頁

此分頁設定你的權限範圍上限（scope ceiling）：應用程式未來可向任何使用者請求的最大權限集合。它不是指某位使用者實際授予你的權限。 Permissions 分頁中的範圍勾選

​
已選取的範圍如何呈現給使用者

使用者不會看到原始的列舉值。你所選的範圍會歸類在可讀的頂層標題底下，而使用者看到並同意的是該標題。未勾選的範圍不會出現在同意畫面，也不會成為你的應用程式未來可請求的內容。 群組化的範圍在同意畫面上的呈現方式

​
必要的範圍

某些範圍對你正在設定的應用程式或小工具類型是強制性的 — 沒有它們流程就無法運作。這些會被整理在分頁底部，且使用者在同意畫面上無法取消勾選。你會在此處看到它們；但不需由你選擇。

​
選擇你的範圍

請從當前流程的實際需求出發，而非未來可能會需要什麼。 完整參考： Application Scopes。
範圍越少，轉換越高。 同意畫面往往是整合流程中流失最高的一步，而其長度由此分頁決定。較窄的上限也能在權杖外洩時縮小影響範圍。只要求今日流程所需；等到建立下一個功能時再擴大上限。

​
你無法自行選取的範圍

PCI_COMPLIANCE 由 Fluz 在應用程式層級管理，僅授予已證明符合 PCI DSS 的開發者，且在產生權杖時無法請求。如果你需要自行處理原始卡片資料，請聯絡你的 Fluz 客戶經理。若不希望自行處理，請使用內嵌小工具 — 卡片資料的輸入會在 Fluz 的 PCI 範疇內完成。

​
之後再變更範圍

權限模型是「應用程式層級上限」與「每位使用者實際授權」的交集，實務上有兩個影響：
  • 在此處新增範圍，並不會回溯賦予既有權杖。既有使用者必須重新授權，新的範圍才會對其生效。
  • 在此處移除範圍，會立刻縮小所有使用者的有效存取，不論他們先前同意過什麼。
把範圍變更當作綱要（schema）遷移來規劃，而不是當作設定微調。

​
OAuth 分頁

OAuth 分頁中的重新導向 URI 設定

​
Origin

將承載流程的網域 — 例如 example.com、app.example.com。對內嵌小工具而言，這是小工具渲染所在的頁面，必須相符，否則小工具不會載入。

​
Redirect URIs

使用者同意或拒絕後，我們的授權伺服器允許傳送使用者前往的位置。
  • 必須是我們伺服器可存取的公開 URL。
  • 註冊的 URI 上不可含有查詢參數。請改用 state 參數承載情境資訊。
  • 你可以註冊任意多個 — 每個環境一個、每種流程變體一個。
  • 你在 /authorize 使用的 URI 必須在此處註冊，且你送往 /token/exchange 的 URI 必須與你在 /authorize 使用的 URI 位元組完全相同。
對授權伺服器而言，以下四個 URI 彼此不同：
請選定一種正規寫法，將其存成單一常數，並在授權步驟與交換步驟都使用同一個常數。手動各寫一次最容易出現不一致。
請明確註冊你的本機回呼 — 例如 http://localhost:3035/oauth/finalize。未列入清單就不會生效，而本機 URI 不應留在正式環境的應用程式上。

​
Webhook URLs

從 Fluz 接收事件的公開 REST 端點 — 讓你在不需輪詢的情況下，得知轉帳完成、使用者關閉 modal、或驗證已處理的方式。
  • 你可以新增任意多個 URL。
  • 將各個 URL 訂閱到特定事件，以便把不同事件家族導向不同服務。
  • 未勾選任何事件的 URL 會成為總攬（catch-all），接收所有事件。開發期方便，正式環境會很吵。
你的端點應快速回應並以非同步處理。只做接收事件所需的最小工作，接著交給佇列處理 — 緩慢的 webhook 處理器最後會變成投遞問題。

​
建置之前先驗證

花五分鐘，省下一個下午在授權流程上的除錯時間。
1

憑證已離開控制台並進入你的機密儲存

Client ID、Client Secret、API Key、API Secret。確認沒有落在被 git 追蹤的 .env 檔中。
2

同意畫面文字清楚易讀

名稱、副標、描述、頭像、標誌皆已填妥，且以使用者為對象撰寫。
3

程式碼會呼叫的每個範圍都在 Permissions 勾選

走過你預期的 API 呼叫，確認每一個所需的範圍都有啟用。若你請求了此處未啟用的範圍，它會被靜默忽略而非被拒絕 — 錯誤會晚點以令人困惑的權限錯誤浮現。
4

你的重新導向 URI 以完全正規的形式註冊

包含通訊協定、主機大小寫、以及是否有結尾斜線。
5

手動組一個 authorize URL 並打開

用 response_type=code、你的 client_id、已註冊的 redirect_uri，與你的範圍組合 /authorize，然後在瀏覽器開啟。若同意畫面以你的品牌與預期的範圍顯示，代表設定正確。若出錯，訊息會指出哪裡不匹配 — 而你在寫任何程式碼前就已發現。→ 面向客戶的 OAuth 授權流程

​
Staging 與 Production 是不同的應用程式

各環境不共用設定。Production 應用程式需獨立註冊，具有自己的 Client ID、Client Secret、API Key 與 API Secret，並且其重新導向 URI 與 webhook 端點也要指向正式主機。 Staging 上沒有任何設定會自動帶到 Production — 包含範圍選擇。上線前請針對你的正式應用程式重新檢核本頁所有內容。請見部署到 Production。

​
疑難排解

​
下一步

面向客戶的授權流程

建立 authorize URL 並處理回呼。

交換授權碼

將代碼換成 access token 與 refresh token。

應用程式範圍

完整的範圍參考。

部署到 Production

重新在正式主機註冊並上線。