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

# 地址格式要求

在 Fluz API 的多个位置需要提交地址——用户身份验证（KYC）、企业注册（KYB）、资金来源，以及虚拟卡签发。本文定义了地址字段的格式要求以确保被接受，并说明了专门针对卡片签发的额外校验。

<Tip>
  **适用范围**

  地址字段在整个 API 中结构一致。下面的**格式规则**适用于所有场景。**卡片签发要求**（仅限美国、不可使用邮政信箱、Smarty 校验）仅在注明的地方适用。
</Tip>

## 地址字段

每个地址对象都使用相同的结构化字段。根据具体调用，对象可能命名为 `billingAddress`、`businessLegalAddress`，或为所有者/个人地址，但字段名称保持一致。

| 字段                   | 是否必填 | 格式                                                       |
| -------------------- | ---- | -------------------------------------------------------- |
| `streetAddressLine1` | 是    | 主街道地址（门牌号 + 街道）。必须为真实、可投递的街道地址。                          |
| `streetAddressLine2` | 否    | 公寓、套房、单元或楼层。使用标准的二级标识（`Apt`、`Ste`、`Unit`、`Rm`、`Fl`、`#`）。 |
| `city`               | 是    | 城市名称。必须为 USPS 与该 ZIP 码关联的城市。                             |
| `state`              | 是    | 两位美国州代码（例如 `NY`）或完整州名。                                   |
| `postalCode`         | 是    | 5 位美国 ZIP 码。必须与所提供的城市和州相匹配。                              |
| `country`            | 是    | 国家名称。约束因上下文而异——参见 [按上下文的国家要求](#country-by-context)。      |

## 格式规则

以下规则适用于你在 API 任意部分提交的**所有**地址：

1. **使用结构化字段。** 将街道放在 `streetAddressLine1`，将单元放在 `streetAddressLine2`——不要把所有内容合并到一行。
2. **使用真实、可投递的地址。** 门牌号必须存在于所述街道上。仅有真实街道不够——如果 Main St 的最高门牌是 `480`，则 `500 Main St` 无效。
3. **保持城市、州和 ZIP 一致。** ZIP 码必须与该城市和州匹配。ZIP 不匹配是地址被拒的最常见原因。
4. **使用 USPS 缩写。** 标准后缀（`St`、`Ave`、`Blvd`、`Dr`、`Ln`、`Rd`、`Ct`、`Pkwy`）和方位（`N`、`S`、`E`、`W`、`NE`、`NW`、`SE`、`SW`）最可靠。
5. **将单元/公寓/套房放在** `streetAddressLine2` 并使用可识别的标识符。若 USPS 要求某栋建筑提供二级单元而未提供，地址可能无法通过校验。
6. **美国地址请发送 5 位 ZIP**。标准化过程中会自动添加 ZIP+4。

## 卡片签发的额外要求

虚拟卡账单地址在保存前会通过 [Smarty](https://www.smarty.com/)（USPS 投递点校验）进行验证与标准化。此要求适用于 [添加虚拟卡地址](/features/add-billing-address)、[创建虚拟卡](/features/create-card)，以及[为授权用户签发虚拟卡](/features/create-virtual-card-for-authorized-user)。

* **仅限美国地址。** 将 `country` 设为 `United States`。
* **不可使用邮政信箱（PO Box）。** 发卡方不接受邮政信箱地址，即使 USPS 认为其可投递。
* **必须通过 Smarty 验证。** 如果地址无法匹配到真实、可投递的美国投递点，请求将以 `VC-0025` 被拒，且**不会保存任何地址**。使用相同值重试仍会失败——必须更改地址本身。

银行卡账单地址（[添加资金来源](/features/add-bank-card)）使用相同的字段结构，并应与发卡行备案地址一致。账单地址不匹配可能在地址验证（AVS）检查时导致卡片被拒。

## 按上下文的国家要求

并非所有地址都仅限美国。请根据你所进行的调用使用正确的约束：

| 场景                              | 国家约束                                           |
| ------------------------------- | ---------------------------------------------- |
| 虚拟卡账单地址                         | 仅限美国（`United States`）。                         |
| 银行卡账单地址                         | 应与发卡行备案一致（通常为美国）。                              |
| 企业注册（KYB）`businessLegalAddress` | 接受国际地址（国家名称、ISO 3166）。某些国家在 KYB 中受限（例如俄罗斯、伊朗）。 |
| 用户 KYC 验证                       | 用户的居住地址。                                       |

## 地址被拒的原因（`VC-0025`）

对于卡片签发，当 Smarty 无法确认地址为可投递的美国投递点时，会判定失败。最常见的原因：

| 原因           | 含义                         |
| ------------ | -------------------------- |
| 城市/州/ZIP 不匹配 | 提供的 ZIP 码不属于该城市或州。         |
| 无效的门牌号       | 街道存在，但该主门牌号在该街道上不存在。       |
| 找不到地址        | USPS 数据中不存在该街道或地址。         |
| 缺失/无效的二级单元   | USPS 要求该建筑提供公寓或套房号，但缺失或错误。 |
| 不可投递点        | 地址对应空置或其他不可投递的投递点。         |
| 邮政信箱或非美国地址   | 被发卡方拒绝（邮政信箱）或不受支持（美国以外）。   |

## 实际示例

### 示例 1 — 城市/ZIP 不匹配

```text theme={null}
2581 Oakwood Avenue, New York, NY 10605
```

**已拒绝（**`VC-0025`**）。** ZIP 码 `10605` 属于**White Plains, NY**（威彻斯特县），而非纽约市——因此城市与 ZIP 不匹配。此外，`2581 Oakwood Avenue` 并非该 ZIP 中的已确认投递点。Smarty 未返回有效匹配，故地址未被保存。

**修正方法：** 提交 USPS 为该城市分配的 ZIP（或与 ZIP 匹配的城市），以及在该街道上存在的门牌号。

### 示例 2 — 无效门牌号

```text theme={null}
896 S State St, Dover, DE 19904
```

**已拒绝（**`VC-0025`**）。** `S State St` 存在于 Dover, DE，但 `896` 并不是该街道与 ZIP 的 USPS 已确认投递点。由于无法验证具体门牌号，Smarty 未返回可投递匹配。

**修正方法：** 确认精确的门牌号以及覆盖该街道街区的 ZIP。

### 有效提交示例

```json theme={null}
{
  "billingAddress": {
    "streetAddressLine1": "1600 Amphitheatre Pkwy",
    "streetAddressLine2": "",
    "country": "United States",
    "city": "Mountain View",
    "state": "CA",
    "postalCode": "94043"
  }
}
```

保存并标准化（城市、州和邮编以大写存储；自动添加 ZIP+4）：

```json theme={null}
{
  "streetAddressLine1": "1600 Amphitheatre Pkwy",
  "streetAddressLine2": null,
  "country": "United States",
  "city": "MOUNTAIN VIEW",
  "state": "CA",
  "postalCode": "94043"
}
```

## 在集成中处理 `VC-0025`

* **以结构化字段收集地址**，而非单个自由文本字段，这样你可以提示修正具体有问题的部分。
* **不要盲目重试。** 相同的地址会持续返回 `VC-0025`。请将错误呈现给用户并要求其更正地址。
* **提交前先校验（可选）。** 在你的 UI 中运行地址自动完成或验证步骤可减少失败的往返请求。
* **失败时不会保存任何内容**，因此在用更正后的值重试前无需清理。

## 错误参考

| 错误                        | 代码        | 消息                                                                                                           |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `INVALID_BILLING_ADDRESS` | `VC-0025` | The billing address could not be verified. Please check the street, city, state, and ZIP code and try again. |

完整列表参见[虚拟卡错误代码](/features/virtual-card-error-codes)。

## 下一步

<CardGroup cols={2}>
  <Card title="测试地址" icon="flask-conical" href="/test-addresses">
    在预发布环境中用于覆盖所有校验结果的有效与无效地址集合。
  </Card>

  <Card title="通用 API 错误代码" icon="triangle-alert" href="/get-started/general-api-error-codes">
    地址错误在更广泛错误代码命名空间中的位置。
  </Card>
</CardGroup>

***

**想了解更多？** 通过 [partnerships@fluz.app](mailto:partnerships@fluz.app) 联系我们。与我们的专家交流以获取更多信息或申请演示。