创建员工 - DCS Technical Documentation

📄 正文

员工是最终持卡人，创建员工是发卡前的必经一步。您在 ACTIVE 公司下提交员工资料，DCS 受理后异步进行个人尽职调查（KYC 姓名筛查），结果以 Webhook 通知为主、查询接口兜底；KYC 被拒时按同一 customerApplyId 修正姓名重提即可。本页覆盖创建申请、查询结果与重新提交三个接口的全部字段与示例，能力总览见管理员工。

流程总览

申请状态机只有三个状态：PENDING / SUCCEED / REJECTED。被拒后不换 ID 重发，而是沿用同一 customerApplyId 重提。

前置条件

所属公司已创建且处于 ACTIVE 状态（如尚未创建，请先阅读管理公司）。
已准备员工的姓名、手机号、邮箱；如需申请实体卡，还需准备寄送地址。

提交创建申请

POST /open-api-corp/customer/v1/apply 创建员工：提交资料，异步进行个人尽职调查（KYC 姓名筛查）。地址信息请传入寄送地址。

请求参数

字段	类型	必填	说明
`customerRef`	String	是	≤64；合作伙伴侧员工唯一标识；字符集 `^[A-Za-z0-9_-]+$`
`organizationId`	String	是	≤20；所属公司，须 `ACTIVE`
`firstName`	String	是	≤64；名；仅允许英文、数字、空格
`lastName`	String	是	≤64；姓；仅允许英文、数字、空格
`middleName`	String	否	≤64；中间名；仅允许英文、数字、空格
`phoneCountryCode`	String	是	固定 2 位；手机区号（ISO 3166-1 alpha-2 两位字母，如 `HK`；须在支持列表中）
`phoneNumber`	String	是	≤15；手机号（纯数字）
`email`	String	是	≤128；邮箱
`addresses`	Array	否	地址列表（结构见下表）。创建时携带则随开户流程落库；未携带可在开户后经更新员工地址补充维护

addresses[] 元素结构：

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

无寄送地址的员工无法申请实体卡。仅发虚拟卡可不传 addresses，后续需要实体卡时再经更新接口补充。

唯一性规则：同一合作伙伴下，员工邮箱与手机号（区号 + 号码）跨公司唯一，且占用后即使申请被拒也不释放，重复提交分别返回 EMAIL_DUPLICATE / PHONE_DUPLICATE。请在提交前确认联系方式未被其它员工（含历史被拒申请）使用。

请求示例

{
  "customerRef": "ext-employee-0001",
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "firstName": "JOHN",
  "lastName": "DOE",
  "phoneCountryCode": "HK",
  "phoneNumber": "12345678",
  "email": "finance@example.com",
  "addresses": [
    {
      "addressType": "SHIPPING_ADDRESS",
      "postalCode": "999077",
      "addressLine1": "Room 1201, Example Tower",
      "addressLine2": "1 Example Street",
      "addressLine3": "Central",
      "city": "Hong Kong",
      "state": "Hong Kong",
      "addressCountryCode": "HK"
    }
  ]
}

响应示例

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "customerApplyId": "5136744097353943553",
    "status": "PENDING"
  }
}

响应 data 中，customerApplyId 是员工创建申请 ID（后续查询与重提的关联键，请落库保存），status 受理即为 PENDING。

错误码

错误码	说明
`APPLY_DUPLICATE`	同一 `customerRef` 已存在在途 / 已成功的申请，不可重复提交
`APPLY_REJECTED_USE_RESUBMIT`	同一 `customerRef` 仅存在被拒申请，改用本页的重新提交接口（不再放行重复 apply）
`EMAIL_DUPLICATE`	同合作伙伴下该 `email` 已被占用（合作伙伴级，任意状态含被拒）
`PHONE_DUPLICATE`	同合作伙伴下该手机号（区号 + 号码）已被占用（合作伙伴级，任意状态含被拒）
`ORGANIZATION_INVALID`	所属公司不存在或非 `ACTIVE`
`COUNTRY_SANCTIONED`	携带的 `addresses[].addressCountryCode` 命中制裁名单

关联 Webhook：CUSTOMER_CREATED / CUSTOMER_REJECTED。

查询申请进度与结果

GET /open-api-corp/customer/v1/query-apply 以 Webhook 通知为主，本接口兜底轮询。

请求参数

字段	类型	必填	说明
`customerApplyId`	String	是	≤20；员工申请 ID

响应 `data`

字段	类型	说明
`customerApplyId`	String	申请 ID
`customerRef`	String	合作伙伴侧标识
`organizationId`	String	所属公司
`status`	String	`PENDING` / `SUCCEED` / `REJECTED`
`rejectMessage`	String	拒绝原因（`REJECTED` 时）
`customerId`	String	落实体后的员工 ID（`SUCCEED` 后才有）

请求示例

GET /open-api-corp/customer/v1/query-apply?customerApplyId=5136744097353943553

响应示例（审核通过）

status=SUCCEED，customerId 已下发，请落库保存：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "customerApplyId": "5136744097353943553",
    "customerRef": "ext-employee-0001",
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "status": "SUCCEED",
    "rejectMessage": null,
    "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c"
  }
}

响应示例（KYC 被拒）

status=REJECTED，rejectMessage 给出原因，可用下方重新提交接口重提：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "customerApplyId": "5136744097353943553",
    "customerRef": "ext-employee-0001",
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "status": "REJECTED",
    "rejectMessage": "name mismatch",
    "customerId": null
  }
}

错误码

错误码	说明
`APPLY_NOT_FOUND`	员工申请不存在（或不属本合作伙伴）

被拒后重新提交

POST /open-api-corp/customer/v1/resubmit KYC 被拒后修正姓名，按同一 customerApplyId 重新送审。

请求参数

字段	类型	必填	说明
`customerApplyId`	String	是	≤20；被拒的员工申请 ID
`firstName`	String	是	≤64；名；仅允许英文、数字、空格
`lastName`	String	是	≤64；姓；仅允许英文、数字、空格
`middleName`	String	否	≤64；中间名；仅允许英文、数字、空格

请求示例

{
  "customerApplyId": "5136744097353943553",
  "firstName": "JOHN",
  "lastName": "DOE"
}

响应示例

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "customerApplyId": "5136744097353943553",
    "customerRef": "ext-employee-0001",
    "status": "PENDING"
  }
}

错误码

错误码	说明
`APPLY_NOT_FOUND`	员工申请不存在（或不属本合作伙伴）
`STATUS_CONFLICT`	申请当前非 `REJECTED`，不可重新提交

关联 Webhook：CUSTOMER_CREATED / CUSTOMER_REJECTED。

员工创建成功后如需改名，走更新员工姓名接口而非 resubmit；resubmit 只服务于「申请被拒、实体尚未落地」的场景。

下一步

员工创建成功后，维护其信息与冻结状态：员工信息与状态
员工 ACTIVE 后为其发卡：管理卡片

​📄 正文

​流程总览

​前置条件

​提交创建申请

​请求参数

​请求示例

​响应示例

​错误码

​查询申请进度与结果

​请求参数

​响应 data

​请求示例

​响应示例（审核通过）

​响应示例（KYC 被拒）

​错误码

​被拒后重新提交

​请求参数

​请求示例

​响应示例

​错误码

​下一步

📄 正文

流程总览

前置条件

提交创建申请

请求参数

请求示例

响应示例

错误码

查询申请进度与结果

请求参数

响应 `data`

请求示例

响应示例（审核通过）

响应示例（KYC 被拒）

错误码

被拒后重新提交

请求参数

请求示例

响应示例

错误码

下一步