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

查詢個人使用者收款人。

#### Query (UserLookupInput)

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

**需要**：`QUERY_RECIPIENT` 權限範圍。

#### Input

| 欄位          | 型別     | 必填  | 說明                                 |
| :---------- | :----- | :-- | :--------------------------------- |
| phoneNumber | String | 否\* | 收款人的電話號碼，E.164 格式（例如：+14155551234） |
| email       | String | 否\* | 收款人的電子郵件地址                         |

*請僅提供其中一個欄位*

#### Response (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

依公司名稱查詢企業收款人。

#### Query

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

**需要**：`QUERY_RECIPIENT` 權限範圍。

#### Input

| 欄位          | 型別     | 必填 | 說明                |
| :---------- | :----- | :- | :---------------- |
| companyName | String | 是  | 公司名稱（不分大小寫，需精確相符） |

**注意：** 同時搜尋登記的企業法定名稱與 DBA 名稱。必須精確相符（不分大小寫）。

#### Response

| 欄位          | 型別      | 說明                              |
| :---------- | :------ | :------------------------------ |
| 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)"