> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# 引导并连接客户
> 端到端运行平台主路径——注册客户、通过 OAuth 连接其账户、验证身份，并代表其执行操作。
本快速入门是“构建平台”的可运行版本。你将以编程方式注册一名客户，走完 OAuth 授权以获取限定于他们账户的令牌，使用沙盒 KYC 流程验证其身份，并通过代表他们发行一张虚拟卡来证明连接——使用与你在自己账户上相同的 API。
**前提条件**
* 一个**带有预发布应用的 Fluz 账户**——任一快速入门的步骤 1–2，或参见[准备你的账户](/get-started/prepare-accounts)和[API 凭证](/get-started/api-credentials)。
* 一个**已配置 OAuth 的应用**：`client_id`、`client_secret` 和已注册的 `redirect_uri`——参见[创建 OAuth 应用](/create-an-o-auth-app)和[配置 OAuth 应用](/configure-o-auth-app)。
* 请求指向**沙盒**——没有真实资金、没有真实 PII。参见[预发布与生产环境](/concepts/environments)。
**注册用户需要特殊权限。** `registerUser` 变更按应用受限（若未启用则返回 `AUTH-0022`）——联系你的客户经理启用该权限。尚无注册访问？跳过步骤 1，使用任一现有预发布用户运行流程。
## 完整流程
使用 `registerUser` 配置完整用户——账户、余额与推荐能力——并使用**你的应用**令牌进行认证。
```graphql Mutation theme={null}
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 }
}
}
```
```json Variables theme={null}
{
"firstName": "Jane",
"lastName": "Doe",
"phoneNumber": "5551234567",
"regionCode": "US",
"emailAddress": "jane.doe@example.com",
"dateOfBirth": "1990-05-15"
}
```
此变更会将错误**放在响应数据中**，不会作为 GraphQL 错误返回——务必检查 `success` 并处理 `error` 对象。常见失败：`AUTH-0026` / `AUTH-0027`（手机号或邮箱已被使用）、`AUTH-0004`（无效手机号）。完整列表：[用户注册](/user-registration)。
客户通过访问托管的授权页面来授权你的应用。使用你的 OAuth 设置和集成所需的作用域来构建该 URL：
```text Authorization URL theme={null}
https://uni.staging.fluzapp.com/authorize
?response_type=code
&client_id=
&redirect_uri=
&scopes=CREATE_VIRTUALCARD%20REVEAL_VIRTUALCARD
&state=
```
* `scopes` 以**空格分隔**（URL 编码为 `%20`），且必须是你应用已启用作用域的子集——未知作用域会被静默忽略。
* `state` 会原样回传——用它来将重定向与会话关联。
客户会看到 Fluz 权限界面，批准后会被重定向到你的 `redirect_uri`，并带有 `?code=...&state=...`。该 `code` 只能使用一次——请在服务端捕获。
完整参数参考：[面向客户端的 OAuth 授权流程](/client-facing-o-auth-grant-flow)。
将授权码交换为限定客户范围的 `accessToken`（以及 `refreshToken`）。该调用使用**基本认证**：`client_id:client_secret` 的 base64。
```bash Exchange (cURL) theme={null}
curl -X GET "https://uni.staging.fluzapp.com/token/exchange?code=&redirect_uri=" \
-H "Authorization: Basic "
```
```json Response (truncated) theme={null}
{
"accessToken": "eyJhbGciOi...",
"accessTokenExpiresAt": "2026-07-13T21:05:30.673Z",
"refreshToken": "8ec16c25951616150b0332a4a6d66547",
"refreshTokenExpiresAt": "2026-08-13T20:55:30.738Z",
"scope": ["CREATE_VIRTUALCARD", "REVEAL_VIRTUALCARD"],
"user": { "id": "5070d5a1-d71a-4190-91b0-f116eec51771" }
}
```
`redirect_uri` 必须与授权步骤**完全**一致。存储 `refreshToken` 并在 `accessTokenExpiresAt` 之前轮换——参见[刷新 OAuth 访问令牌](/refresh-o-auth-access-token)。
要引导大量客户？在授权 URL 上追加你的自有标识符为 `external_id`，以将 Fluz 账户与系统中的记录关联——参见[管理外部引用 ID](/managing-external-reference-ids)。
涉及资金流动需要已验证的身份。使用**客户的令牌**调用 `verifyUserInformation`——令牌决定要验证的人。在预发布环境中，此测试身份始终返回 `APPROVED`：
```graphql Mutation theme={null}
mutation VerifyUserInformation($input: VerifyUserInformationInput!) {
verifyUserInformation(input: $input) {
status
message
}
}
```
```json Variables (approved test identity) theme={null}
{
"input": {
"firstName": "John",
"lastName": "Smith",
"streetLine1": "222333 Peachtree Place",
"streetLine2": "",
"city": "Atlanta",
"state": "GA",
"postalCode": "30318",
"country": "United States",
"dateOfBirth": "02/28/1975",
"ssnLast4": "3333"
}
}
```
\*\*最多三次尝试限制：\*\*同一用户最多可提交 3 次，之后将返回 `ERROR`——不要在你需要的用户身上浪费尝试次数。完整沙盒结果： [测试 KYC 流程](/test-kyc-flows)。
这是关键：使用**客户的令牌**运行任意 Fluz 操作，它将针对**他们**的账户执行。`createVirtualCard` 就是 `createVirtualCard`——没有单独的平台 API。
```graphql theme={null}
mutation {
createVirtualCard(
input: {
idempotencyKey: "1b7de2f8-c0a9-4532-9881-3ab5857bbe15"
offerId: "ed669305-5e43-40a0-9a25-7a15ed174628"
spendLimit: 50.00
lockCardNextUse: true
cardNickname: "First card on a connected account"
}
) {
virtualCardId
virtualCardLast4
status
}
}
```
返回 `ACTIVE` 卡片意味着闭环已完成：已注册 → 已连接 → 已验证 → 可操作。客户通过令牌在你的系统中可见；他们从未获得对“你”的账户的访问权限，而你仅持有他们授予的作用域。
## 大功告成 🎉
你已端到端完成客户的引导与连接。接下来：
完整的平台架构——令牌路径、功能与模式。
让已连接用户发起请求，由所有者审批。
使用你的自有 ID 而非 Fluz 账户 ID 来标识客户。
不止个人，也可引导企业。
**想了解更多？** 通过 [support@fluz.app](mailto:support@fluz.app) 联系我们，与专家沟通或申请演示。