> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 员工信息与状态

> 员工存量维护的完整调用细节：query 查询详情（含地址数组），姓名 / 手机 / 邮箱 / 地址各走一个更新接口，update-restrictions 按能力域码冻结与解冻。

## 📄 正文

员工创建成功后的日常维护由六个接口承担：查询详情，姓名 / 手机 / 邮箱 / 地址各一个更新接口，以及冻结解冻。改姓名会触发重新送审 KYC，其余三类不涉及 KYC；冻结与解冻走能力域码的加删集合语义。创建与重提见[创建员工](./employee-onboarding)，状态机全貌见[状态机与冻结体系](../basic-concepts/states-and-freezing)。

## 查询员工详情

**`GET /open-api-corp/customer/v1/query`**

返回员工的姓名、联系方式、状态与地址列表（若已维护）。

### 请求参数（Query String）

| 字段           | 类型     | 必填 | 说明        |
| ------------ | ------ | -- | --------- |
| `customerId` | String | 是  | ≤36；员工 ID |

### 响应 `data`

| 字段                 | 类型     | 说明                                                                           |
| ------------------ | ------ | ---------------------------------------------------------------------------- |
| `customerId`       | String | 员工 ID                                                                        |
| `customerRef`      | String | 您侧的员工唯一编号（回显）                                                                |
| `organizationId`   | String | 所属组织                                                                         |
| `firstName`        | String | 名                                                                            |
| `middleName`       | String | 中间名                                                                          |
| `lastName`         | String | 姓                                                                            |
| `phoneCountryCode` | String | 手机号所属国家 / 地区码                                                                |
| `phoneNumber`      | String | 手机号                                                                          |
| `email`            | String | 邮箱                                                                           |
| `status`           | String | 员工状态：生命周期 `ACTIVE` / `TERMINATED`；行为状态 `SUSPENDED` / `FROZEN` / `RESTRICTED` |
| `addresses`        | Array  | 地址列表，元素结构见下表；未维护过则为空                                                         |

`addresses[]` 元素结构：

| 字段                   | 类型     | 说明                                            |
| -------------------- | ------ | --------------------------------------------- |
| `addressType`        | String | 地址用途，数组内的判别字段。当前值域仅 `SHIPPING_ADDRESS`（实体卡寄送） |
| `postalCode`         | String | 邮编（部分地区无，可为空）                                 |
| `addressLine1`       | String | 地址行 1                                         |
| `addressLine2`       | String | 地址行 2（可为空）                                    |
| `addressLine3`       | String | 地址行 3（可为空）                                    |
| `city`               | String | 城市（香港可填区域）                                    |
| `state`              | String | 州 / 省（香港填 `Hong Kong`）                        |
| `addressCountryCode` | String | 两位 ISO 国家码（如 `HK`）                            |

### 请求示例

```http theme={null}
GET /open-api-corp/customer/v1/query?customerId=a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c
```

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
    "customerRef": "emp-acme-0001",
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "firstName": "TAI MAN",
    "middleName": null,
    "lastName": "CHAN",
    "phoneCountryCode": "HK",
    "phoneNumber": "91234567",
    "email": "taiman.chan@acme.com",
    "status": "ACTIVE",
    "addresses": [
      {
        "addressType": "SHIPPING_ADDRESS",
        "postalCode": "999077",
        "addressLine1": "Flat 5, 12/F, Acme Tower",
        "addressLine2": "8 Connaught Road Central",
        "addressLine3": "Central",
        "city": "Hong Kong",
        "state": "Hong Kong",
        "addressCountryCode": "HK"
      }
    ]
  }
}
```

### 错误码

| 错误码                | 说明              |
| ------------------ | --------------- |
| `CUSTOMER_INVALID` | 员工不存在（或不属本合作伙伴） |

## 更新员工信息

四类信息各有一个接口，路径即意图，请求里只出现该类必需的字段，返回的错误码也只有该类会遇到的：

| 接口                                               | 改什么       | 是否触发 KYC     |
| ------------------------------------------------ | --------- | ------------ |
| `POST /open-api-corp/customer/v1/update-name`    | 姓名三段      | 是，姓名有变化即重新送审 |
| `POST /open-api-corp/customer/v1/update-phone`   | 手机区号 + 号码 | 否            |
| `POST /open-api-corp/customer/v1/update-email`   | 邮箱        | 否            |
| `POST /open-api-corp/customer/v1/update-address` | 地址列表      | 否            |

四个接口都是动作类，成功返回 `SYS_SUCCESS`、`data` 为 `null`。

### 更新姓名

姓名按三段**整体替换**：以本次提交的 `firstName` + `middleName` + `lastName` 为新的法定姓名，不做逐段合并——KYC 比对的是完整姓名，整体提交才能确知送审内容。`middleName` 不传即表示无中间名，原值被清除。全成或全败，无部分成功语义。

| 字段           | 类型     | 必填 | 说明                   |
| ------------ | ------ | -- | -------------------- |
| `customerId` | String | 是  | ≤36；目标员工             |
| `firstName`  | String | 是  | ≤64；仅允许英文字母、数字与空格    |
| `middleName` | String | 否  | ≤64；不传即表示无中间名（原值被清除） |
| `lastName`   | String | 是  | ≤64；仅允许英文字母、数字与空格    |

```json theme={null}
{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "firstName": "TAI MAN",
  "lastName": "CHAN"
}
```

| 错误码                | 说明                                 |
| ------------------ | ---------------------------------- |
| `CUSTOMER_INVALID` | 员工不存在或非有效状态                        |
| `KYC_IN_REVIEW`    | 该员工已有一笔在途 KYC 审核（上次送审尚未出结果），待完成后重试 |

### 更新手机号

区号与号码须成对提交。该手机号同时用作实体卡的邮寄联系方式。

| 字段                 | 类型     | 必填 | 说明                                             |
| ------------------ | ------ | -- | ---------------------------------------------- |
| `customerId`       | String | 是  | ≤36；目标员工                                       |
| `phoneCountryCode` | String | 是  | 固定 2 位；ISO-3166-1 alpha-2 两位大写（如 `HK`），须在支持列表内 |
| `phoneNumber`      | String | 是  | ≤15；纯数字本地号码，不含区号、不含 `+`                        |

```json theme={null}
{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "phoneCountryCode": "HK",
  "phoneNumber": "91234567"
}
```

| 错误码                | 说明          |
| ------------------ | ----------- |
| `CUSTOMER_INVALID` | 员工不存在或非有效状态 |

### 更新邮箱

| 字段           | 类型     | 必填 | 说明        |
| ------------ | ------ | -- | --------- |
| `customerId` | String | 是  | ≤36；目标员工  |
| `email`      | String | 是  | ≤128；联系邮箱 |

```json theme={null}
{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "email": "taiman.chan@acme.com"
}
```

| 错误码                | 说明          |
| ------------------ | ----------- |
| `CUSTOMER_INVALID` | 员工不存在或非有效状态 |

### 更新地址

更新语义是「按 `addressType` 局部、按对象整份」：只影响传入的那些 `addressType`，未传的类型保留不动；被命中的类型则整个对象替换，不支持字段级修改。

| 字段           | 类型     | 必填 | 说明                                                                                                               |
| ------------ | ------ | -- | ---------------------------------------------------------------------------------------------------------------- |
| `customerId` | String | 是  | ≤36；目标员工                                                                                                         |
| `addresses`  | Array  | 是  | 至少 1 项；元素结构同上文查询详情的 `addresses[]`，其中 `addressType` / `addressLine1` / `city` / `state` / `addressCountryCode` 必填 |

```json theme={null}
{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "addresses": [
    {
      "addressType": "SHIPPING_ADDRESS",
      "postalCode": "999077",
      "addressLine1": "Flat 5, 12/F, Acme Tower",
      "addressLine2": "8 Connaught Road Central",
      "addressLine3": "Central",
      "city": "Hong Kong",
      "state": "Hong Kong",
      "addressCountryCode": "HK"
    }
  ]
}
```

<Note>
  地址更新只影响后续的虚转实申请——受理时会把当时的地址快照进申请单，故在途或已寄出的实体卡不受本次更新影响。
</Note>

| 错误码                  | 说明                                      |
| -------------------- | --------------------------------------- |
| `CUSTOMER_INVALID`   | 员工不存在或非有效状态                             |
| `COUNTRY_SANCTIONED` | `addresses[].addressCountryCode` 命中制裁名单 |

## 冻结与解冻（更新员工限制项）

**`POST /open-api-corp/customer/v1/update-restrictions`**

对员工进行冻结或解冻，语义与组织侧完全一致：加限制项即冻结、删限制项即解冻，幂等集合语义，重复提交安全。取值仅限开放的 5 个 L1 能力域码：

| 能力域码              | 冻结后停用的范围                       |
| ----------------- | ------------------------------ |
| `ACCOUNT_FROZEN`  | 账户整体（登录、改密、改手机 / 邮箱、绑定 MFA、销户） |
| `CASH_IN_FROZEN`  | 入金 / 充值                        |
| `CASH_OUT_FROZEN` | 出金 / 提现 / 汇款                   |
| `PAYMENT_FROZEN`  | 支付 / 消费（含卡支付）                  |
| `CARD_FROZEN`     | 卡管理动作（申卡、激活、改 PIN）             |

<Warning>
  **冻结员工后，该员工名下所有卡拒绝交易**。另外，风控 / 监管 / 司法写入的受限态不可经本接口解除。
</Warning>

### 请求参数

| 字段                   | 类型             | 必填 | 说明                                                                                                                                                                                                 |
| -------------------- | -------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerId`         | String         | 是  | ≤36；目标员工                                                                                                                                                                                           |
| `addRestrictions`    | Array\<String> | 条件 | 要新增的限制项，可多传。与 `removeRestrictions` 至少传一个，两者都不传返回 `DAPI_PARAM_INVALID`；元素仅取上表 5 个 L1 能力域码，传入其它值（含 `KYC_FROZEN` / `TRANSFER_FROZEN` / L2 细粒度码 / `SUSPENDED` / `RESTRICTED`）同样返回 `DAPI_PARAM_INVALID` |
| `removeRestrictions` | Array\<String> | 条件 | 要解除的限制项，取值约束同 `addRestrictions`；与 `addRestrictions` 至少传一个                                                                                                                                          |
| `remark`             | String         | 否  | ≤256；操作备注                                                                                                                                                                                          |

### 请求示例

冻结（加限制项）：

```json theme={null}
{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "addRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "suspicious transactions"
}
```

解冻（删限制项）：

```json theme={null}
{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "removeRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "risk cleared"
}
```

### 错误码

| 错误码                | 说明                        |
| ------------------ | ------------------------- |
| `CUSTOMER_INVALID` | 员工不存在（或不属本合作伙伴）           |
| `STATUS_CONFLICT`  | 当前状态不允许该操作（如员工非 `ACTIVE`） |

关联 Webhook：`CUSTOMER_STATUS_CHANGED`，`businessId` 为 `customerId`，`data` 携带本次的 `addRestrictions` / `removeRestrictions` 与 `remark`。

## 下一步

* 员工处于 `ACTIVE` 且未被冻结时，为其发卡与管卡：[管理卡片](./managing-cards)
* 员工状态机与冻结能力域的全貌：[状态机与冻结体系](../basic-concepts/states-and-freezing)