使用者註冊 - Fluz

registerUser 會根據你既有的個人資料為某人開立 Fluz 帳戶——無需重新導向、無需託管表單、不用請使用者再次輸入姓名與出生日期。

受限存取。 此 mutation 需要 Fluz 明確核准。請聯絡你的客戶經理，為你的應用程式啟用使用者註冊功能。未啟用的應用程式呼叫將以 AUTH-0022 失敗。

所在流程

註冊是導入流程中的一個步驟，且為選用——你也可以改用小工具一次包辦。

作法	Registration	KYC	Consent	建置成本
Widget	由 Fluz 託管	由 Fluz 託管	由 Fluz 託管	數小時
Hybrid	`registerUser`	`verifyUserInformation`	Widget 或重新導向	數天
僅 API	`registerUser`	`verifyUserInformation`	OAuth 重新導向	數天，且你需處理 PII

當你已經擁有「乾淨的個人資料」且不希望使用者重複輸入時，請自行註冊使用者。若你只是為了轉交給 Fluz 才要蒐集姓名、出生日期與聯絡資訊，請改用嵌入式小工具——可將該蒐集留在 Fluz 的法遵範疇中。 API 路徑的完整流程如下：

註冊

使用姓名、電話、電子郵件與生日呼叫 registerUser。

驗證

以 verifyUserInformation 執行 KYC，或提供文件驗證連結給使用者。→ 使用者 KYC 驗證

取得授權

使用者授權你的應用程式對應的 scopes。→ 面向使用者的 OAuth 授權流程

開始操作

產生使用者 access token，並代表他們呼叫 API。→ Authentication

該 mutation

mutation RegisterUser(
  $firstName: String!
  $lastName: String!
  $phoneNumber: String!
  $regionCode: String!
  $emailAddress: String!
  $dateOfBirth: String!
) {
  registerUser(
    firstName: $firstName
    lastName: $lastName
    phoneNumber: $phoneNumber
    regionCode: $regionCode
    emailAddress: $emailAddress
    dateOfBirth: $dateOfBirth
  ) {
    success
    error {
      code
      message
    }
  }
}

error 是物件（RegisterUserError），不是字串——請務必選取 code 與 message 子欄位。僅請求 error 會無法編譯。

參數

參數	型別	必填	說明
`firstName`	String	Yes	使用者的名
`lastName`	String	Yes	使用者的姓
`phoneNumber`	String	Yes	接受數字與 `-` —— `"5551234567"` 或 `"555-123-4567"`
`regionCode`	String	Yes	該電話號碼的 ISO 3166-1 alpha-2 國碼，例如 `"US"`
`emailAddress`	String	Yes	不可已存在於任何 Fluz 帳戶
`dateOfBirth`	String	Yes	`YYYY-MM-DD`

姓名應與使用者將用於驗證的身分證件相符——不相符將在後續觸發 KYC 失敗，比起註冊時的錯誤更難排查。

會建立的內容

一個完整的 Fluz 帳戶：使用者紀錄、其錢包與餘額、以及獎勵資格。在帳戶可供驗證與使用前，無需再配置其他內容。

處理回應

失敗回傳在 data，而非 errors。 註冊失敗會是 HTTP 200 並帶有 success: false。若僅檢查 GraphQL 的 errors 陣列，將會把所有失敗誤判為成功。

Success

{ "data": { "registerUser": { "success": true, "error": null } } }

Failure

{
  "data": {
    "registerUser": {
      "success": false,
      "error": {
        "code": "AUTH-0026",
        "message": "The phone number you chose is already in use."
      }
    }
  }
}

同時處理三層回應的範例：

const res = await fetch(FLUZ.graphqlUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify({ query: REGISTER_USER, variables: profile }),
});

const body = await res.json();

// 1. Transport and GraphQL-level failures
if (body.errors?.length) {
  throw new Error(`GraphQL error: ${body.errors[0].message}`);
}

const result = body.data.registerUser;

// 2. Business-level failure — still an HTTP 200
if (!result.success) {
  switch (result.error.code) {
    case 'AUTH-0026':
    case 'AUTH-0027':
      // Not a failure. This person already has a Fluz account.
      return routeToAuthorization(profile);

    case 'AUTH-0004':
      return promptForValidPhoneNumber();

    case 'AUTH-0022':
    case 'AUTH-0030':
      // Configuration problem on your side — don't retry, alert.
      throw new ConfigurationError(result.error.code);

    default:
      throw new RetryableError(result.error.message);
  }
}

// 3. Success
return proceedToVerification(profile);

「已被使用」是導流訊號，不是錯誤

AUTH-0026（電話）與 AUTH-0027（電子郵件）表示該人已經擁有 Fluz 帳戶。這是正常且可預期的結果——Fluz 帳戶不侷限於你的應用程式，因此任何曾經使用過 Fluz 的人，無論透過任何應用或消費者產品，都已經存在。把這當成失敗是此處最常見的整合錯誤。正確作法是停止嘗試建立新帳戶，改為請求存取既有帳戶：將使用者導入 OAuth 授權流程，或開啟小工具。他們會登入既有帳戶並授權你。將「先嘗試註冊、再回退到授權」設計為常態流程，而非例外分支，如此在規模化時流程依舊順暢。

重試與重複

registerUser 不接受任何冪等鍵。重試即是全新的嘗試，逾時則代表結果未知。

若呼叫逾時或連線中斷，註冊很可能已成功。隨後以相同請求重試會回傳 AUTH-0026——與使用者原本就有帳戶之情況無法區分。只要你對兩種情況採取相同處置，此一模糊就無害：逾時時重試一次，並將 AUTH-0026 / AUTH-0027 導入授權，而非顯示錯誤。 無論是你剛建立的帳戶，或是原本就存在的帳戶，最終都會完成授權，這正是你的目標。你絕對不該在使用者第一次提供電話號碼時，向其顯示「電話號碼已被使用」。

註冊之後

已註冊的帳戶尚未通過驗證。在使用者可動用資金之前，你需要：

身分驗證。 將你持有的 SSN 與地址傳給 verifyUserInformation，或簽發文件驗證連結讓使用者完成。→ 使用者 KYC 驗證
授權同意。 代為註冊並不代表你獲得其代理權——這是分開且明確的一步。→ 面向使用者的 OAuth 授權流程
綁定你的識別碼。 在授權時傳入 external_id，之後即可用你自己的使用者 ID 來識別此人。→ 管理 External Reference IDs

資料處理

你將傳送全名、生日、電子郵件與電話號碼——足以識別真實個人的資料組合。請從你的伺服器以 TLS 傳輸、避免寫入日誌與錯誤追蹤載荷、且不要在回應中回顯給前端。特別注意生日在多數法域屬於受管制的身分資料，即使呼叫成功，它在你方仍屬敏感資料。若你不希望持有這些資料，這正是使用小工具的理由——由 Fluz 在其合規範疇中蒐集，而你完全不會接觸。

錯誤代碼

代碼	意義	處置方式
`AUTH-0004`	針對給定 `regionCode` 的電話號碼無效或無法解析	修正輸入。檢查 `regionCode` 是否與號碼所屬國家相符
`AUTH-0022`	你的應用程式未被允許註冊使用者	聯絡你的客戶經理。不要重試
`AUTH-0025`	一般性註冊失敗	可重試。若持續發生請升級處理
`AUTH-0026`	電話號碼已存在於某帳戶	導入授權——見上文
`AUTH-0027`	電子郵件已存在於某帳戶	導入授權——見上文
`AUTH-0030`	你的應用程式未啟用	至控制台檢查應用狀態。不要重試

環境

請指向對應環境的 GraphQL 主機——staging 使用 https://transactional-graph.staging.fluzapp.com/api/v1/graphql，production 使用 https://transactional-graph.fluzapp.com/api/v1/graphql。註冊權限是以應用程式為單位授予，因此 production 應用需另外啟用。→ 部署到 Production 切勿在 staging 註冊真實使用者。→ Staging 與 Live

後續步驟

使用者 KYC 驗證

驗證你剛建立的帳戶。

授權流程

取得代為操作的許可。

External reference IDs

以你自己的使用者 ID 來識別他們。

嵌入式小工具

將整個導入流程交給 Fluz。

​所在流程

​該 mutation

​參數

​會建立的內容

​處理回應

​「已被使用」是導流訊號，不是錯誤

​重試與重複

​註冊之後

​資料處理

​錯誤代碼

​環境

​後續步驟

使用者 KYC 驗證

授權流程

External reference IDs

嵌入式小工具

所在流程

該 mutation

參數

會建立的內容

處理回應

「已被使用」是導流訊號，不是錯誤

重試與重複

註冊之後

資料處理

錯誤代碼

環境

後續步驟