> ## 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 與該郵遞區號關聯的城市。                                 |
| `state`              | 是  | 兩碼美國州別代碼（例如 `NY`）或完整州名。                                    |
| `postalCode`         | 是  | 5 碼美國 ZIP 郵遞區號。必須屬於所提供的城市與州別。                              |
| `country`            | 是  | 國家名稱。限制依情境而定——參見[依情境的國家限制](#country-by-context)。           |

## 格式規則

以下規則適用於你在 API 任一部分提交的**每個**地址：

1. **使用結構化欄位。** 將街道放在 `streetAddressLine1`，單位放在 `streetAddressLine2`——不要把所有內容合併在同一行。
2. **使用可投遞的真實地址。** 門牌號碼必須存在於該街道上。僅有真實街道仍不足——若 Main St 的最大門牌為 `480`，則 `500 Main St` 無效。
3. **城市、州別與 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 不匹配 | 郵遞區號不屬於所提供的城市或州別。            |
| 無效的門牌號碼           | 該街道存在，但主要（建物）門牌號碼不存在於該街道上。   |
| 找不到地址             | 該街道或地址未出現在 USPS 資料中。         |
| 遺漏 / 無效的次要單位      | 對於此建物，USPS 需要公寓或套房號碼，但缺少或錯誤。 |
| 無法投遞的投遞點          | 該地址對應到空置或其他不可投遞的投遞點。         |
| 郵政信箱或非美國地址        | 由發卡機構拒絕（郵政信箱）或不受支援（美國境外）。    |

## 實例說明

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

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

**已拒絕（**`VC-0025`**）。** ZIP `10605` 屬於**White Plains, NY**（Westchester 郡），而非紐約市——因此城市與 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`。請顯示錯誤並要求使用者更正地址。
* **提交前先驗證（選用）。** 在你的介面先進行地址自動完成或驗證可降低失敗往返。
* **失敗時不會儲存任何資料**，因此修正後重試前無需清除。

## 錯誤參考

| 錯誤                        | 代碼        | 訊息                                                                                                           |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `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)。與我們的專家洽談以取得更多資訊或申請示範。