> ## 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` 用户地址保存，后续可在 `createVirtualCard` 中作为 `userAddressId` 传入。
当提供 `authUserId` 时，地址会为该授权用户所对应的底层用户保存，同时仍附加在调用方的账户上。`authUserId` 必须是调用方账户上处于 ACTIVE 状态的非所有者授权用户指派。
如果在调用方账户上，目标持卡人已存在完全相同的账单地址，则返回已存在的地址而不是创建副本。匹配基于地址字段、账户、目标用户以及 `BILLING` 类型进行。
**先决条件：** 具有 `CREATE_VIRTUALCARD` 范围的 Bearer 令牌。
**账单地址必须可验证**
此变更会存储账单地址。它必须是真实且可投递的**美国**地址（`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
}
}
```
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --------------------------------------- | ------------------------------- | -- | ----------------------------------------- |
| input | AddVirtualCardAddressInput! | 是 | 账单地址请求的包装对象。 |
| input.billingAddress | VirtualCardBillingAddressInput! | 是 | 要为虚拟卡签发保存的账单地址。 |
| input.billingAddress.streetAddressLine1 | String! | 是 | 街道地址。发行方不接受邮政信箱（PO Box）。 |
| input.billingAddress.streetAddressLine2 | String | 否 | 可选的公寓、套房或第二行地址。空值将保存为 `null`；非空值会被去除首尾空格。 |
| input.billingAddress.country | String! | 是 | 国家名称。目前发行方仅支持美国地址。 |
| input.billingAddress.city | String! | 是 | 城市。以大写形式保存。 |
| input.billingAddress.state | String! | 是 | 州名或美国两字母州代码。以大写形式保存。 |
| input.billingAddress.postalCode | String! | 是 | 5 位美国 ZIP 邮编。以大写形式保存。 |
| input.authUserId | UUID | 否 | 授权用户 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"
}
}
}
```
## 响应字段
| 字段 | 类型 | 说明 |
| -------------------- | ------ | --------------------------------------------------------- |
| `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);
```
## 错误代码
| 代码 | 消息 | 说明 |
| ----------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `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 的交易之前必须完成此步骤。