员工管理 · 概述 - DCS Technical Documentation

📄 正文

员工是最终持卡人，也是公司卡的托管人来源。创建员工会异步走 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`。创建时未带可事后经更新接口补充；无寄送地址的员工无法申请实体卡

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

第二步：拿 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 后发卡：管理卡片
员工改名触发的 KYC 在途冲突处理：见上文更新表格与常见问题
本组详页：创建员工 · 员工信息与状态

​📄 正文

​第一步：创建员工

​第二步：拿 KYC 结果

​维护信息与状态

​关联 Webhook

​下一步

📄 正文

第一步：创建员工

第二步：拿 KYC 结果

维护信息与状态

关联 Webhook

下一步