> ## 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.

# 交付方式

> 将一张开放式卡片交到收件人手中的四种方式——以及为此你需要了解的程度。

<Info>
  **简而言之：你无需了解任何收件人信息即可生成卡片。**

  只有当你希望由 *Fluz* 来完成投递时，才需要收件人的联系方式。若你自行投递链接，只需向我们提供卡片限额、一个 offer，以及一个资金账户——别无他物。收件人在托管页面上自行填写其信息。
</Info>

## 选择你的方式

<Steps>
  <Step title="你希望由 Fluz 投递链接，还是你自己投递？">
    若由你自行投递——通过你自己的电子邮件、你自己的短信、应用内、门户内，或将 URL 交给下游客户——请使用 **`GENERATE_URL`**。无需收件人数据。
  </Step>

  <Step title="如果由 Fluz 投递，方式是？">
    电子邮件（`EMAIL`）或短信（`PHONE_NUMBER`）。你需为每张卡提供一个地址或号码。
  </Step>

  <Step title="你是否已持有收件人的完整身份信息？">
    如果是——并且你希望收件人完全跳过数据录入——请向你的 Fluz 代表咨询**预填注册**。这是一个受限选项，不属于标准的 `generateVCShareLinks` 流程。
  </Step>
</Steps>

## 四种选项一览

| # | 选项              | `shareMethod`  | 你提供给 Fluz 的内容 | 谁来投递链接  | 收件人需填写的内容  |
| - | --------------- | -------------- | ------------- | ------- | ---------- |
| 1 | **生成链接**        | `GENERATE_URL` | 无需提供任何收件人信息   | **你**   | 他们自己的信息    |
| 2 | **Fluz 通过邮件发送** | `EMAIL`        | 每张卡一个电子邮箱地址   | Fluz    | 他们自己的信息    |
| 3 | **Fluz 通过短信发送** | `PHONE_NUMBER` | 每张卡一个电话号码     | Fluz    | 他们自己的信息    |
| 4 | **预填注册**        | 受限——联系你的代表     | 完整的收件人身份信息    | 你或 Fluz | 无需填写——只需领取 |

<Note>
  选项 1–3 是同一个变更操作中 `shareMethod` 字段的三个取值。在它们之间切换只需改一行代码——你并非在对接三套不同的 API。
</Note>

## 选项 1 —— 生成链接，由你投递

**大多数合作方选择此方式。** 你调用 API，拿回一组 URL，然后你可以随意处理：用你自己的系统发邮件、发短信、放进客户门户，或交给下游客户由其分发给自己的终端用户。

Fluz **不会**向任何人发送任何东西。对于这些链接，我们并未保存任何收件人联系方式，因为你从未提供给我们。

```json Generate URLs theme={null}
{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 1,
    "daysUntilExpiration": 30,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}
```

```json Response theme={null}
{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1"
      ]
    }
  }
}
```

<Warning>
  使用 `GENERATE_URL` 时，`recipientListEmail` 与 `recipientListPhone` 必须**为空或省略**。在 `GENERATE_URL` 的同时发送收件人列表将触发校验错误且不会创建任何记录。
</Warning>

<Tip>
  将 `quantity` 设为大于 1 可在一次调用中铸造一批链接。你将为每个单位获得一个唯一 URL，且每个 URL 仅可被领取一次。请按返回结果原样分发这些 URL——不要重写或再次缩短它们。
</Tip>

## 选项 2 —— 由 Fluz 通过邮件发送链接

你为每张卡提供一个邮箱地址，由 Fluz 发送邮件。收件人点击进入与选项 1 相同的托管页面，并在其中填写自己的信息。

当你已掌握收件人邮箱且不想自行构建投递能力时，可使用该方式。

```json Email theme={null}
{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "EMAIL",
    "recipientListEmail": ["mike.bennett@example.com", "dana.ruiz@example.com"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}
```

<Warning>
  `recipientListEmail` 的长度**必须等于** `quantity`。不匹配将返回校验错误且不会创建任何记录——没有部分批次。
</Warning>

## 选项 3 —— 由 Fluz 通过短信发送链接

与选项 2 相同，但通过 SMS。你以 E.164 格式为每张卡提供一个电话号码。Fluz 发送短信；在此路径上 Fluz **不会**另外发送电子邮件。

```json SMS theme={null}
{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": ["+12125550101", "+12125550102"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}
```

<Warning>
  `recipientListPhone` 的长度必须等于 `quantity`，且两种列表互斥——只发送与你的 `shareMethod` 匹配的那个，并将另一个留空。
</Warning>

## 选项 4 —— 预填注册

部分合作方希望提供“白手套”体验，使收件人无需填写任何信息。在此模式下，你向 Fluz 传递卡片注册所需的身份信息，收件人唯一的操作就是打开链接并领取卡片。

这是一个**受限选项**，不属于标准的 `generateVCShareLinks` 输入。如果你的项目需要，请与 Fluz 客户团队沟通——此方式会在你方带来额外的数据处理与合规义务，因为你是在为尚未与 Fluz 交互的个人提供其个人信息。

<Note>
  仅当你确实持有经过核验的收件人身份数据时才选择此方式。如果你选择选项 4 的动机只是为了避免向收件人索取信息，那么选项 1 几乎可以肯定才是你真正需要的。
</Note>

## 收件人需要做什么

在选项 1–3 中完全一致。无论谁来投递，链接指向的都是相同的托管页面：

<Steps>
  <Step title="打开链接">
    无需下载应用、无需 Fluz 账户、无需密码。
  </Step>

  <Step title="通过手机验证">
    一次性验证码用于确认持有该链接的人。
  </Step>

  <Step title="输入其卡片信息">
    收件人提供卡片所需的信息。在此阶段不会出现 PIN 提示。
  </Step>

  <Step title="领取、展示并消费">
    卡片在**领取时**从你的消费账户入金，而不是在生成链接时。收件人会成为该张卡片对象的授权用户——与你账户上的其他任何内容无关。卡片在领取后不会自动展示：展示时会提示收件人输入其 PIN，若尚未设置则先创建一个。
  </Step>
</Steps>

参见 [Recipient Experience](/features/open-loop-cards/open-loop-cards-recipient-experience) 获取完整流程讲解，以及当链接过期、被撤销或已被领取时收件人所见的状态。

## 常见困惑点

<AccordionGroup>
  <Accordion title="我们必须预填收件人信息吗？">
    不需要。这是对 API 参考的常见误读。收件人字段的存在是为了**让 Fluz 代表你进行投递**——它们不是卡片发行的输入。使用 `GENERATE_URL` 时，你完全不发送任何收件人数据。
  </Accordion>

  <Accordion title="每个请求都必须包含邮箱地址吗？">
    不需要。`recipientListEmail` 仅在 `shareMethod = EMAIL` 时才是必填。对于 `GENERATE_URL` 和 `PHONE_NUMBER`，它必须为空。
  </Accordion>

  <Accordion title="我们将链接传给我们的客户，由他们再传给终端用户。这样可以吗？">
    可以——这正是 `GENERATE_URL` 的模式。该 URL 属于持有式：谁先打开并完成验证，谁就领取该卡。请将链接视为敏感信息，并通过你信任的渠道进行投递。
  </Accordion>

  <Accordion title="我能在门户里生成测试链接吗？">
    目前不行。链接生成仅支持 API。请在预发布环境使用携带 `CREATE_SHARE_LINK` 范围的预发布令牌进行测试——参见 [Staging vs. Live Environment](/docs/staging-vs-live-environment)。
  </Accordion>

  <Accordion title="我之后可以切换方式吗？">
    可以。`shareMethod` 是按调用设置，而非按账户设置。你可以为这一批生成 URL，下一批让 Fluz 发送邮件。
  </Accordion>
</AccordionGroup>

## 所有方式的通用要求

| 要求    | 详情                                                         |
| ----- | ---------------------------------------------------------- |
| 认证    | 携带 `CREATE_SHARE_LINK` 范围的 Bearer 访问令牌。Basic 认证会被拒绝。       |
| 资金    | `userCashBalanceId` —— 你自己账户上的一个消费账户。尽管在模式中标记为可选，但实际上是必需的。 |
| Offer | `offerId` 必须是可分享商户的一个有效 offer。                             |
| 过期    | `daysUntilExpiration` 默认为 30。此日期同时也是该卡片的冻结日期。              |

## 后续步骤

<CardGroup cols={2}>
  <Card title="Open Loop Cards Overview" icon="credit-card" href="/features/open-loop-cards/send-open-loop-cards">
    生成、列表与停用链接的完整操作参考。
  </Card>

  <Card title="Recipient Experience" icon="user" href="/features/open-loop-cards/open-loop-cards-recipient-experience">
    你的收件人所见内容，以及管理其卡片的规则。
  </Card>
</CardGroup>