员工信息与状态 - DCS Technical Documentation

📄 正文

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

查询员工详情

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`）

请求示例

GET /open-api-corp/customer/v1/query?customerId=a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c

响应示例

{
  "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；仅允许英文字母、数字与空格

{
  "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；纯数字本地号码，不含区号、不含 `+`

{
  "customerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c",
  "phoneCountryCode": "HK",
  "phoneNumber": "91234567"
}

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

更新邮箱

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

{
  "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` 必填

{
  "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"
    }
  ]
}

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

错误码	说明
`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）

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

请求参数

字段	类型	必填	说明
`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；操作备注

请求示例

冻结（加限制项）：

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

解冻（删限制项）：

{
  "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 且未被冻结时，为其发卡与管卡：管理卡片
员工状态机与冻结能力域的全貌：状态机与冻结体系

​📄 正文

​查询员工详情

​请求参数（Query String）

​响应 data

​请求示例

​响应示例

​错误码

​更新员工信息

​更新姓名

​更新手机号

​更新邮箱

​更新地址

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

​请求参数

​请求示例

​错误码

​下一步

📄 正文

查询员工详情

请求参数（Query String）

响应 `data`

请求示例

响应示例

错误码

更新员工信息

更新姓名

更新手机号

更新邮箱

更新地址

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

请求参数

请求示例

错误码

下一步