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

# 钱包转账收款方查询

用于检索用于转账资金的 `account_id`。

<br />

### 概览

用于查找转账操作收款方的两个查询：

* `lookupUser` - 通过电话或邮箱查找用户
* `lookupBusiness` - 通过公司名称查找企业

***

### lookupUser

查找个人用户收款方。

#### 查询（UserLookupInput）

```graphql theme={null}
lookupUser(input: UserLookupInput!): UserLookupResult!
```

**需要**：`QUERY_RECIPIENT` 权限范围。

#### 输入

| 字段          | 类型     | 必填  | 说明                                 |
| :---------- | :----- | :-- | :--------------------------------- |
| phoneNumber | String | 否\* | 收款方的电话号码，E.164 格式（例如：+14155551234） |
| email       | String | 否\* | 收款方的电子邮箱地址                         |

*仅提供且必须提供一个字段*

#### 响应（UserLookupResult）

| 字段          | 类型      | 说明                 |
| :---------- | :------ | :----------------- |
| recipientId | UUID!   | 收款方账户 ID           |
| displayName | String! | 显示名称（"First Last"） |

#### 示例

**按电话：**

```graphql theme={null}
query {
  lookupUser(input: { phoneNumber: "+14155551234" }) {
    recipientId
    displayName
  }
}
```

**按邮箱：**

```graphql theme={null}
query {
  lookupUser(input: { email: "jane@example.com" }) {
    recipientId
    displayName
  }
}
```

**成功：**

```json theme={null}
{
  "data": {
    "lookupUser": {
      "recipientId": "a2c02ec6-357b-41cf-9229-4da34e727019",
      "displayName": "John Doe"
    }
  }
}
```

**未找到：**

```json theme={null}
{
  "errors": [{
    "message": "No recipient found with the provided information.",
    "extensions": { "code": "RC-0001" }
  }]
}
```

#### 错误代码

| 代码      | 说明       |
| :------ | :------- |
| RC-0001 | 未找到收款方   |
| RC-0002 | 多个匹配（少见） |
| AR-0001 | 输入无效/缺失  |
| GE-9999 | 服务器错误    |

***

### lookupBusiness

按公司名称查找企业收款方。

#### 查询

```graphql theme={null}
lookupBusiness(input: BusinessLookupInput!): [BusinessLookupResult!]!
```

**需要**：`QUERY_RECIPIENT` 权限范围。

#### 输入

| 字段          | 类型     | 必填 | 说明                |
| :---------- | :----- | :- | :---------------- |
| companyName | String | 是  | 公司名称（不区分大小写，精确匹配） |

**注意：** 同时搜索注册企业名称与 DBA 名称。必须精确匹配（不区分大小写）。

#### 响应

| 字段          | 类型      | 说明                              |
| :---------- | :------ | :------------------------------ |
| recipientId | UUID!   | 收款方账户 ID                        |
| displayName | String! | 显示名称（若有 DBA 则为 DBA，否则为公司名）      |
| companyName | String! | 格式化名称："Company Name (DBA Name)" |
| state       | String  | 企业法定地址所在州                       |

#### 示例

```graphql theme={null}
query {
  lookupBusiness(input: { companyName: "acme corporation" }) {
    recipientId
    displayName
    companyName
    state
  }
}
```

**单个匹配：**

```json theme={null}
{
  "data": {
    "lookupBusiness": [
      {
        "recipientId": "c4e24ge8-579d-63eh-b451-6fc56g949241",
        "displayName": "Acme Corporation",
        "companyName": "Acme Corporation",
        "state": "CA"
      }
    ]
  }
}
```

**多个匹配（同名，不同 DBA）：**

```json theme={null}
{
  "data": {
    "lookupBusiness": [
      {
        "recipientId": "c4e24ge8-579d-63eh-b451-6fc56g949241",
        "displayName": "Acme Retail",
        "companyName": "Acme Corporation (Acme Retail)",
        "state": "CA"
      },
      {
        "recipientId": "d5f35hf9-680e-74fi-c562-7gd67h050352",
        "displayName": "Acme Wholesale",
        "companyName": "Acme Corporation (Acme Wholesale)",
        "state": "NY"
      }
    ]
  }
}
```

**未找到：**

```json theme={null}
{
  "errors": [{
    "message": "No recipient found with the provided information.",
    "extensions": { "code": "RC-0001" }
  }]
}
```

#### 错误代码

| 代码      | 说明      |
| :------ | :------ |
| RC-0001 | 未找到收款方  |
| AR-0001 | 输入无效/缺失 |
| GE-9999 | 服务器错误   |

***

<br />

### 重要说明

#### lookupUser

* 电话号码必须为 E.164 格式（例如：+14155551234）
* 美国 10 位号码会自动规范化
* 邮箱不区分大小写
* 未找到则抛出错误

### lookupBusiness

* 不区分大小写的精确匹配——"acme corporation" 可匹配 "ACME CORPORATION" 或 "Acme Corporation"
* 同时搜索企业名称与 DBA 名称
* 返回数组（可能包含多个同名企业）
* 未匹配到则抛出错误
* 当 DBA 与企业名称不同，`companyName` 格式为 "Business Name (DBA Name)"