> ## 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.
# 新增虛擬卡地址
在呼叫者的帳戶上儲存用於虛擬卡發行的帳單地址。該地址會以 `BILLING` 使用者地址儲存，之後可作為 `userAddressId` 傳入 `createVirtualCard`。
當提供 `authUserId` 時，地址會儲存至該授權使用者所對應的底層使用者，同時仍附加在呼叫者的帳戶上。`authUserId` 必須是呼叫者帳戶上處於 ACTIVE 狀態、且非 OWNER 的授權使用者指派。
如果呼叫者帳戶上，目標持卡人的相同帳單地址已存在，將會回傳現有地址，而不是建立重複項。比對會依據地址欄位、帳戶、目標使用者，以及 `BILLING` 類型進行。
**先決條件：** 具備 `CREATE_VIRTUALCARD` 權限範圍的 Bearer 權杖。
**帳單地址必須可驗證**
此 mutation 會儲存帳單地址。必須是實際可投遞的**美國**地址（`US`、`USA` 或 `United States`），且城市、州別與郵遞區號需正確，並且**不接受郵政信箱（PO Box）**。USPS/Smarty 檢查會在建立虛擬卡時進行——無法在該處驗證的地址，會導致卡片建立以 `VC-0025` 失敗。完整欄位規則與範例請參見 [地址格式要求](/concepts/address-formatting-requirements)。
```graphql theme={null}
mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) {
addVirtualCardAddress(input: $input) {
userAddressId
streetAddressLine1
streetAddressLine2
country
city
state
postalCode
}
}
```
## 參數
| Parameter | Type | Required | Description |
| --------------------------------------- | ------------------------------- | -------- | ----------------------------------------- |
| input | AddVirtualCardAddressInput! | Yes | 用於帳單地址請求的包裝物件。 |
| input.billingAddress | VirtualCardBillingAddressInput! | Yes | 要儲存以供虛擬卡發行使用的帳單地址。 |
| input.billingAddress.streetAddressLine1 | String! | Yes | 街道地址。發卡機構不接受郵政信箱。 |
| input.billingAddress.streetAddressLine2 | String | No | 選填的公寓、套房或次要地址行。空值會儲存為 `null`；非空值會被去除前後空白。 |
| input.billingAddress.country | String! | Yes | 國家名稱。目前發卡機構僅支援美國地址。 |
| input.billingAddress.city | String! | Yes | 城市。會以大寫儲存。 |
| input.billingAddress.state | String! | Yes | 州名或兩碼美國州別代碼。會以大寫儲存。 |
| input.billingAddress.postalCode | String! | Yes | 5 碼美國 ZIP 郵遞區號。會以大寫儲存。 |
| input.authUserId | UUID | No | 授權使用者 ID（UAC 角色指派 ID）。提供時，地址會儲存給該授權持卡人。 |
## 回應
```json theme={null}
{
"data": {
"addVirtualCardAddress": {
"userAddressId": "1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70",
"streetAddressLine1": "123 Main St",
"streetAddressLine2": "Apt 5",
"country": "United States",
"city": "NEW YORK",
"state": "NY",
"postalCode": "10001"
}
}
}
```
## 回應欄位
| Field | Type | Description |
| -------------------- | ------ | --------------------------------------------------------- |
| `userAddressId` | UUID | 已儲存的帳單地址 ID。將此值作為 `userAddressId` 傳給 `createVirtualCard`。 |
| `streetAddressLine1` | String | 地址第一行。 |
| `streetAddressLine2` | String | 地址第二行，或在未提供時為 `null`。 |
| `country` | String | 國家名稱。 |
| `city` | String | 儲存在地址上的城市。 |
| `state` | String | 儲存在地址上的州別。 |
| `postalCode` | String | 儲存在地址上的郵遞區號。 |
## 範例請求
為呼叫者儲存帳單地址：
```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
"variables": {
"input": {
"billingAddress": {
"streetAddressLine1": "123 Main St",
"streetAddressLine2": "Apt 5",
"country": "United States",
"city": "New York",
"state": "NY",
"postalCode": "10001"
}
}
}
}'
```
為授權使用者儲存帳單地址：
```bash cURL theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
"variables": {
"input": {
"authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
"billingAddress": {
"streetAddressLine1": "456 Market St",
"streetAddressLine2": "Suite 200",
"country": "United States",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105"
}
}
}
}'
```
```typescript TypeScript theme={null}
const response = await fetch('https://transactional-graph.staging.fluzapp.com/api/v1/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({
query: `
mutation AddVirtualCardAddress(
$input: AddVirtualCardAddressInput!
) {
addVirtualCardAddress(input: $input) {
userAddressId
streetAddressLine1
streetAddressLine2
country
city
state
postalCode
}
}
`,
variables: {
input: {
authUserId: '8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d',
billingAddress: {
streetAddressLine1: '456 Market St',
streetAddressLine2: 'Suite 200',
country: 'United States',
city: 'San Francisco',
state: 'CA',
postalCode: '94105',
},
},
},
}),
});
const data = await response.json();
console.log('Virtual card address saved:', data.data.addVirtualCardAddress);
```
## 錯誤代碼
| Code | Message | Description |
| ----------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `ARG-0001` | Invalid arguments received | 缺少必要的地址欄位、某個值為空，或 `authUserId` 不是有效的 UUID。 |
| `AUTH-0008` | Invalid user access | Bearer 權杖無法解析為呼叫者。請確認權杖有效。 |
| `AUTH-0031` | The requested scopes must be granted by the user first. | 權杖缺少儲存虛擬卡地址所需的 `CREATE_VIRTUALCARD` 權限範圍。 |
| `AUTH-0034` | No authorized user found with this id on the caller's account. | `authUserId` 並不存在於呼叫者的帳戶、非 ACTIVE，或指向 OWNER 指派。 |
| `VC-0001` | Please try another payment method. If you continue experiencing issues, please contact our support team. | 儲存帳單地址時發生一般性失敗。請重試或聯絡支援。 |
## 後續步驟
將回傳的 `userAddressId` 傳入 `createVirtualCard`。
在卡片可用於面對面或需要輸入 PIN 的交易前必須先設定。