管理外部参考 ID

外部参考 ID 是你为某个 Fluz 用户自定义的标识符。它让你可以用系统中现有的 ID 操作 Fluz API —— 而无需为每个用户存储或传递 Fluz 的内部 userId 和 accountId。当用户授权你的应用时，你将自己的标识符附加到该授权上。Fluz 会将你的标识符与该用户的 Fluz 账户配对，并限定在你的应用作用域内。从此以后，在生成令牌、发送转账、匹配 webhook 事件时，你都可以用自己的 ID 引用该用户。实际收益：你无需构建 Fluz-ID 对照表。 一个 webhook 到达，携带你的用户 ID，你直接路由即可。无需关联、无需缓存、无需对账任务。

一个值，三个字段名

同一个值会在不同界面下以不同字段名出现。这是本页最常见的困惑来源，值得在开始前记住。

界面	字段名	方向
OAuth 授权 URL	`external_id`（查询参数）	你 → Fluz
组件预批准交易令牌	`externalId`（JWT 声明）	你 → Fluz
GraphQL API	`externalReferenceId`	双向
Webhook 事件负载	`externalReferenceId`	Fluz → 你
OAuth 访问令牌	嵌入在已签发令牌中	Fluz → 你

由于它被嵌入在访问令牌中，这种关联可以在刷新令牌后继续保留——你在授权时分配一次，它将持续存在。

如何选择标识符

切勿使用 PII。 不要用电子邮箱、手机号或姓名。两个非常现实的原因。其一，它们会变更——人们会更换邮箱和手机号，而该值一旦设置即不可变，映射会永久失效。其二，该值会出现在查询字符串和 JWT 声明中，因此会落入浏览器历史、引用头、代理日志，以及你自己的应用日志中。不要把个人数据放在那里。

可用	避免	原因
你的数据库主键	邮箱地址、手机号	可变，且在 URL 中属于 PII
你为每个用户生成的 UUID	连续整数	可枚举；还会泄露你的用户数量
类似 `usr_8f3d2a91` 的不透明前缀 ID	订单 ID、会话 ID 或交易 ID	映射到单个事件，而非单个人——见下文

代价最高的错误是把它绑定到了错误的对象上。 外部参考 ID 永久标识的是一个_人_，而不是一笔交易、一次打款批次、一次会话或一个订单。如果你传了一个按交易生成的标识，第一次转账会成功，第二次会为同一人创建第二个映射，于是你把一个用户分叉成了多个，且无法合并。如果你发现自己每次操作都在生成新值，那你需要的是幂等键，而不是外部参考 ID。

规则

属性	规则
类型	任意字符串。Fluz 不强加格式。
唯一性	在你的应用内必须对每个用户唯一。一个外部参考 ID 只能映射到一个 Fluz 用户。
作用域	限定在你的 OAuth 客户端内。同一 Fluz 用户在其他开发者的应用中可以携带不同的外部参考 ID，且其他应用无法看到或使用你的值。
稳定性	实际上不可变。一旦设置在授权上，将不会被覆盖。
环境	映射跟随应用存在，预发布与生产环境的映射完全独立。你在预发布创建的任何内容在生产中都不存在。

如何分配

标准 OAuth 应用

当你将用户引导至同意页时，在授权 URL 上追加 external_id（参考面向客户端的 OAuth 授权流程）：

https://fluz.app/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scopes=MAKE_DEPOSIT%20LIST_PAYMENT&state=<STATE>&external_id=usr_8f3d2a91

当用户完成授权后，Fluz 会把 usr_8f3d2a91 记录到该用户对你应用的授权上。此步骤可选，但强烈推荐。后续才采用意味着需要逐个让用户重新授权以回填。

组件应用

必填。 所有组件应用类型——充值、提现、支付入金、虚拟卡、礼品卡目录、账单支付以及外部提现——都需要外部参考 ID 来建立用户会话。缺少它的请求会被拒绝：

External reference ID is required for <type> applications

对于组件，该值以**externalId 声明出现在已签名的预批准交易令牌**中，与金额和交易类型并列。你需要在服务端生成它；它不是客户端的初始化选项。参见设置你的服务器。

import jwt from 'jsonwebtoken';
import { v4 as uuidv4 } from 'uuid';

const generatedToken = jwt.sign(
  {
    amount,
    apiKey: process.env.FLUZ_API_KEY,
    transactionType,           // DEPOSIT (Pay-In) or WITHDRAW (Payout)
    externalId: 'usr_8f3d2a91', // your user, stable across every session
    jti: uuidv4(),              // unique per transaction — not the same thing
  },
  process.env.FLUZ_API_SECRET,
  { expiresIn: '1 day' }
);

externalId 和 jti 在同一令牌中相邻，回答的是不同问题。externalId 表示_谁_——在用户整个生命周期内保持稳定。jti 表示_哪笔交易_——每次都不同。重用 jti 会破坏幂等性；更改 externalId 会把你的用户分叉。

如何使用

指定转账目标

当创建到另一个 Fluz 账户的钱包转账时（见转账到另一个 Fluz 钱包），用你自己的 ID 来标识收款方，而不是 Fluz 账户 ID：

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

请提供 destination.accountId 或 destination.externalReferenceId 其中之一——绝不能同时提供。目标用户必须已授权你的应用，否则转账会被拒绝。

将 webhook 事件匹配到你的用户

Webhook 负载会携带 externalReferenceId，因此你无需对照表即可路由事件：

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

注意该字段可能缺失。对于未在授权上关联外部参考 ID 的用户，或被标记为私有的事件，externalReferenceId 会被省略。若你的处理器假设该字段总是存在，将会在这些投递上抛错——而抛错的 webhook 处理器意味着这个 webhook 没被处理。

参见配置应用组件以设置 webhook。

获取用户作用域令牌

generateUserAccessToken 并不接受 externalReferenceId —— 它通过 userId 和 accountId 来标识用户（参见生成用户访问令牌）。对于你用自有 ID 引用的用户，请使用 OAuth 流程。授权已经携带你的标识符，你在 /token/exchange 以授权码交换获得的令牌会针对该用户签发，并嵌入该关联。参见交换 OAuth 授权码。

端到端

一个用户，一个标识符，四个界面。

你的系统已认识此人

你数据库中的用户 usr_8f3d2a91 点击 连接 Fluz。

在同意时分配

你跳转到 /authorize，并带上 external_id=usr_8f3d2a91。他们登录、必要时完成验证并批准你的作用域。Fluz 将 usr_8f3d2a91 绑定到他们的账户，仅对你的应用可见。

交换令牌

你的回调用 code 交换获得 accessToken 和 refreshToken。该关联被嵌入，因此能在后续每次刷新中保持。你将令牌与 usr_8f3d2a91 一并存储——你的架构中不需要 Fluz 的 UUID。

操作

你用 destination: { externalReferenceId: "usr_8f3d2a91" } 向他打款，使用你自己的 ID 作为地址。

对账

完成回调的 webhook 携带 externalReferenceId: "usr_8f3d2a91" 到达。你将其直接路由到该用户记录并标记提现结清。无需关联、无需查表、无需缓存。

生命周期

回填现有授权

如果某用户在你采用外部参考 ID 之前就已授权你的应用，那么在其后续授权时提供一个外部参考 ID，Fluz 会将其回填到现有授权上——前提是该授权尚未携带外部参考 ID。已存在的值永不被覆盖。

使用不同的值重新授权

由于已存在的值永不覆盖，对已存在外部参考 ID 的用户再次传入一个_不同_的 external_id 并不会改变映射。请将第一次的值视为永久。如果你的用户 ID 不稳定，请为 Fluz 专门铸造一个不可变 ID，而不是复用可能迁移的内容。

在你方删除用户

切勿回收标识符。如果你硬删除了一个用户，随后又把同一个主键重新发给不同的人，那么新的人会继承旧的映射——以及旧人的 Fluz 账户。请使用 UUID，或永不回退的单调递增序列。

校验规则与错误

场景	结果
在你的应用下找不到 `externalReferenceId`	`No user found with externalReferenceId <value>.`
转账目标同时提供了 `accountId` 和 `externalReferenceId`	`Provide either destination.accountId or destination.externalReferenceId, not both.`
转账目标用户尚未授权你的应用	`Destination account has not authorized this application.`
未提供外部参考 ID 就创建组件会话	`External reference ID is required for <type> applications`

故障排查

症状	最常见原因
对你确认存在的用户报 `No user found with externalReferenceId`	环境错误——映射创建在预发布而你在调用生产，或反之
同一人显示为多个 Fluz 用户	传入了按交易或按会话的值，而非按用户的值
重新授权时你传入的值未生效	授权已携带一个值；现有值永不覆盖
Webhook 处理器间歇性崩溃	某些投递缺少该字段——未建立关联的授权，或被标记为私有的事件
组件会话被拒绝	组件类型要求 `patToken` 中包含 `externalId` 声明；确认它在签名负载里，而不仅是初始化选项中
转账被拒绝为未授权	目标用户尚未授权你的应用，与是否存在映射无关

外部参考 ID 不是什么

不是 Fluz 的 userId 或 accountId。那些是 Fluz 签发的 UUID；这个由你签发。
不是幂等键。那是 API 调用里的 idempotencyKey 和组件令牌里的 jti，且对每次操作唯一。此处对每个人唯一。
不是 OAuth 流程中的 state 参数。state 用于每次授权尝试的 CSRF 防护，并不会被存储。
不是提现记录或关联资金来源上出现的外部账户标识符。那些引用的是银行与处理方记录，而非用户。

下一步

授权流程

在此为 OAuth 应用分配标识符。

设置你的服务器

在此为组件应用分配标识符。

转账到另一个 Fluz 钱包

用你自己的 ID 指定转账目标。

配置应用 webhooks

接收并携带该标识符返回的事件。

​一个值，三个字段名

​如何选择标识符

​规则

​如何分配

​标准 OAuth 应用

​组件应用

​如何使用

​指定转账目标

​将 webhook 事件匹配到你的用户

​获取用户作用域令牌

​端到端

​生命周期

​回填现有授权

​使用不同的值重新授权

​在你方删除用户

​校验规则与错误

​故障排查

​外部参考 ID 不是什么

​下一步

授权流程

设置你的服务器

转账到另一个 Fluz 钱包

配置应用 webhooks

一个值，三个字段名

如何选择标识符

规则

如何分配

标准 OAuth 应用

组件应用

如何使用

指定转账目标

将 webhook 事件匹配到你的用户

获取用户作用域令牌

端到端

生命周期

回填现有授权

使用不同的值重新授权

在你方删除用户

校验规则与错误

故障排查

外部参考 ID 不是什么

下一步