管理 External Reference ID

External reference ID 是你為 Fluz 使用者設定的自有識別碼。它讓你能用系統中已存在的 ID 來操作 Fluz API——而不必為每位使用者儲存或傳遞 Fluz 的內部 userId 與 accountId。當使用者授權你的應用程式時，你會將自己的識別碼附加到該授權上。Fluz 會儲存你的識別碼與該使用者的 Fluz 帳戶之間的配對關係，且侷限於你的應用程式範圍內。從此之後，你在產生權杖、發送轉帳，以及對應 webhook 事件時，都可以用你自己的 ID 來引用該使用者。

📘 你會在哪裡看到它 此欄位在 OAuth 授權 URL 中為 external_id，在 GraphQL API 與 webhook 負載中為 externalReferenceId。它們代表相同的值。

它可以是什麼？

Property	Rule
Type	任何字串。Fluz 不強制格式。
Uniqueness	在你的應用程式內必須對每位使用者唯一。一個 external reference ID 只對應到一位 Fluz 使用者。
Scope	侷限於你的 OAuth 用戶端。相同的 Fluz 使用者在其他開發者的應用程式中可以擁有不同的 external reference ID，而其他應用程式無法看見或使用你的 ID。
Stability	視為不可變。請使用你的系統中的穩定識別碼——例如內部使用者 ID 或 UUID。

⚠️ 請勿使用 PII 作為 external reference ID 避免使用電子郵件、電話號碼或姓名。這些可能會隨時間改變，導致對應失效，且不必要地在 URL 與權杖中傳送個資。UUID 或你的資料庫主鍵才是正確選擇。

我們在哪裡使用它？

External reference ID 會出現在四個面向：

Surface	Field	Direction
OAuth authorization URL	`external_id` query parameter	You → Fluz
`generateUserAccessToken` mutation	`externalReferenceId` argument	You → Fluz
Wallet transfers (`createTransfer`)	`destination.externalReferenceId`	You → Fluz
Webhook event payloads	`externalReferenceId`	Fluz → You

它也會被嵌入到發給使用者的 OAuth access token 中，因此在更新權杖期間關聯仍會持續存在。

我們如何使用它？

1. 在 OAuth 授權流程中指定它

當你引導終端使用者前往授權 URL（參見 Client facing OAuth grant flow），將你的識別碼以 external_id 查詢參數附加上去：

https://uni.staging.fluzapp.com/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scopes=MAKE_DEPOSIT%20LIST_PAYMENT&external_id=usr_8f3d2a91

當使用者完成授權後，Fluz 會將 usr_8f3d2a91 記錄在該使用者對你應用程式的授權上。啟動嵌入式元件時也適用相同參數——請參見 Widget Overview。

🚧 Widget 應用程式為必填 所有 widget 應用程式類型（deposit、payouts、payins、virtual card、gift card catalog、bill pay，以及 external payout widgets）在建立使用者工作階段時都必須提供 external reference ID。若遺漏，請求會以 External reference ID is required for <type> applications 被拒絕。對於標準 OAuth 應用程式則為選填，但強烈建議提供。

2. 用它產生使用者 access token

一旦關聯建立，generateUserAccessToken 可接受 externalReferenceId 來取代 userId 與 accountId：

mutation {
  generateUserAccessToken(
    externalReferenceId: "usr_8f3d2a91"
    scopes: [MAKE_DEPOSIT, LIST_PAYMENT]
  ) {
    token
    refreshToken
    scopes
  }
}

如常以你應用程式的 Basic 認證來驗證此呼叫——請參見 Generate a User Access Token。你可以同時傳入 userId/accountId 與 externalReferenceId，但它們必須與該 external reference ID 解析出的使用者相符。若不相符，請求將被拒絕。

3. 用它指定轉帳的目標

當建立轉帳到另一個 Fluz 錢包時（參見 Transfer to Another Fluz Account），目標可以用 external reference ID 來識別，而不必使用 Fluz 的帳戶 ID：

mutation {
  createTransfer(input: {
    idempotencyKey: "1f7c5a2e-9b14-4c6d-8e3f-2a90d4b7c1aa"
    amount: 25.00
    destination: { externalReferenceId: "usr_8f3d2a91" }
  }) {
    transferId
  }
}

請提供 destination.accountId 或 destination.externalReferenceId 其中之一——切勿同時提供。目標使用者必須已授權你的應用程式；否則轉帳會被拒絕。

4. 將 webhook 事件對應回你的使用者

Webhook 負載包含 externalReferenceId，因此你可以將 Fluz 事件與你的使用者紀錄相關聯，而無需維護 Fluz ID 的對照表：

{
  "userId": "5070d5a1-d71a-4190-91b0-f116eec51771",
  "accountId": "9c2e1b44-7a3d-4f08-b6e5-d18a3c7f0e22",
  "externalReferenceId": "usr_8f3d2a91",
  "eventType": "DEPOSIT_COMPLETE",
  "amount": 100.00
}

關於 webhook 的設定與傳遞細節，請參見 Configure App Widget。

📘 隱私注意事項 當使用者的授權沒有關聯任何 external reference ID，或事件被標記為私有時，webhook 負載中會省略 externalReferenceId。

驗證規則與錯誤

Scenario	Result
權杖請求同時未提供 `externalReferenceId` 與 `userId` + `accountId`	`Provide either externalReferenceId or both userId and accountId.`
在你的應用程式範圍內找不到 `externalReferenceId`	`No user found with externalReferenceId <value>.`
與 `externalReferenceId` 一同提供的 `userId` 指向不同使用者	`Provided userId does not match the user associated with the externalReferenceId.`
與 `externalReferenceId` 一同提供的 `accountId` 指向不同帳戶	`Provided accountId does not match the account associated with the externalReferenceId.`
轉帳目標同時提供 `accountId` 與 `externalReferenceId`	`Provide either destination.accountId or destination.externalReferenceId, not both.`
轉帳目標使用者未授權你的應用程式	`Destination account has not authorized this application.`
未提供 external reference ID 即建立 widget session	`External reference ID is required for <type> applications`

為現有授權新增 external reference ID

若使用者在你採用 external reference ID 之前已授權你的應用程式，你可以在後續的授權或權杖請求中提供一個，Fluz 會將它回填到現有的授權上——前提是該授權尚未具有 external reference ID。既有的 external reference ID 永遠不會被覆寫。

什麼不是 external reference ID

它不是 Fluz 的 userId 或 accountId。那些是 Fluz 核發的 UUID；external reference ID 是由你核發。
它不是在提款紀錄或 API 其他地方之已連結資金來源上出現的 external_id 或外部帳戶識別碼。那些是指銀行與處理方的紀錄，而非使用者。[TBD：請確認這些是否公開於公開綱要中，並是否應在此交互參照]

​它可以是什麼？

​我們在哪裡使用它？

​我們如何使用它？

​1. 在 OAuth 授權流程中指定它

​2. 用它產生使用者 access token

​3. 用它指定轉帳的目標

​4. 將 webhook 事件對應回你的使用者

​驗證規則與錯誤

​為現有授權新增 external reference ID

​什麼不是 external reference ID