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

# 员工管理 · 概述

> 在 ACTIVE 组织下创建员工并维护：提交 KYC、查询与重提、四个更新接口各改一类信息、冻结解冻，含唯一性与重新送审规则。

## 📄 正文

员工是最终持卡人，也是公司卡的托管人来源。创建员工会异步走 KYC 姓名筛查，通过后才能为其发卡。本页讲清创建、结果处理与信息维护的调用细节。

## 第一步：创建员工

`POST /open-api-corp/customer/v1/apply`（所属公司须 ACTIVE）。

| 字段                                      | 必填        | 说明                                                                                                                                                                                            |
| --------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerRef`                           | 是         | ≤64；合作伙伴侧员工唯一标识（幂等键）                                                                                                                                                                          |
| `organizationId`                        | 是         | 所属公司，须 ACTIVE                                                                                                                                                                                 |
| `firstName` / `lastName` / `middleName` | 是 / 是 / 否 | 各 ≤64；仅允许英文、数字、空格                                                                                                                                                                             |
| `phoneCountryCode` + `phoneNumber`      | 是         | 区号为两位 ISO 国家字母码（如 `HK`）；号码纯数字 ≤15                                                                                                                                                             |
| `email`                                 | 是         | ≤128                                                                                                                                                                                          |
| `addresses`                             | 否         | 地址列表，元素含 `addressType`（当前仅 `SHIPPING_ADDRESS`）/ `postalCode` / `addressLine1` / `addressLine2` / `addressLine3` / `city` / `state` / `addressCountryCode`。创建时未带可事后经更新接口补充；**无寄送地址的员工无法申请实体卡** |

<Warning>
  **唯一性规则**：同一合作伙伴下，员工邮箱与手机号（区号 + 号码）跨公司唯一，**占用后即使被拒也不释放**（`EMAIL_DUPLICATE` / `PHONE_DUPLICATE`）。地址国家命中制裁名单返回 `COUNTRY_SANCTIONED`。
</Warning>

## 第二步：拿 KYC 结果

以 Webhook `CUSTOMER_CREATED` / `CUSTOMER_REJECTED` 为主，`GET /open-api-corp/customer/v1/query-apply` 兜底（按 `customerApplyId` 或您侧的 `customerRef` 查）。`status=SUCCEED` 时返回 `customerId`（请落库）；`REJECTED` 时 `rejectMessage` 给出原因。

**被拒后重提**：`POST /open-api-corp/customer/v1/resubmit`，传 `customerApplyId` + 修正后的姓名三段，沿用同一申请重新送审；非 `REJECTED` 状态调用返回 `STATUS_CONFLICT`。

## 维护信息与状态

**查询员工详情**：`GET /open-api-corp/customer/v1/query?customerId=...`，返回姓名、联系方式、状态与地址列表（未维护过为空）。

**更新员工信息**：四类信息各走一个接口，路径即意图：

| 接口               | 携带字段                                        | 注意                                                                    |
| ---------------- | ------------------------------------------- | --------------------------------------------------------------------- |
| `update-name`    | `firstName` + `lastName` 必填、`middleName` 可选 | 姓名按三段**整体替换**；有变化即**触发重新送审 KYC**，已有在途 KYC 时返回 `KYC_IN_REVIEW`，待出结果后重试 |
| `update-phone`   | `phoneCountryCode` + `phoneNumber`（须成对）     | 唯一性规则同创建                                                              |
| `update-email`   | `email`                                     | 唯一性规则同创建                                                              |
| `update-address` | `addresses` 数组                              | 按 `addressType` 局部、按对象整份替换，不支持字段级修改                                   |

**冻结 / 解冻**：`POST /open-api-corp/customer/v1/update-restrictions`，语义与公司完全一致（`addRestrictions` / `removeRestrictions`，仅限 5 个能力域码）。**冻结员工后，该员工名下所有卡拒绝交易**。

## 关联 Webhook

`CUSTOMER_CREATED` / `CUSTOMER_REJECTED` / `CUSTOMER_STATUS_CHANGED`（携 `addRestrictions` / `removeRestrictions` 与 `remark`）。

## 下一步

* 员工 ACTIVE 后发卡：[管理卡片](./managing-cards)
* 员工改名触发的 KYC 在途冲突处理：见上文更新表格与[常见问题](../customer-success/faq)
* 本组详页：[创建员工](./employee-onboarding) · [员工信息与状态](./employee-maintenance)