通讯录同步开发指南

本指导适用于开发者将企业通讯录数据同步到WeLink用户管理。

准备：

1. 调用通讯录接口都需要在应用开发——接口权限中打开“通讯录同步”接口权限。
   

开发步骤建议：

1. 先同步部门再同步人员
   
2. 选择一个部门同步，先调用部门同步接口，再调用状态查询接口确保调用成功
   
3. 调用部门人员同步接口同步人员，再调用状态查询接口确保调用成功
   
4. 间隔3s调用一次接口
   
5. 扩大部门范围，先手动同步不开户（通过管理后台手动开户）
   
6. 将手动同步改成自动同步
   
7. 同步的过程中，需要记录userId和corpUserId的映射关系，因为WeLink其他开放接口一般接受userId参数
   

名词解释

• userId： WeLink生成用户***标识, 在同步通讯录过程中，需要记录corpUserId和userId的映射关系，避免重复查询WeLink
  
• deptCode： WeLink中创建部门时生成部门编码标识
  
• corpUserId： 企业用户***标识，用户的工号或者可以指向用户***身份的标识
  
• corpDeptCode：企业部门***标识
  
• corpParentCode：企业部门***标识，相对于当前部门的上级部门标识
  
• userNameEn：用户英文名，没有英文名可取拼音如zhangsan
  
• valid：1表示存在，0表示删除。如果要删除该用户或者部门则指定为“0”
  
• isOpenAccount: 1表示开户，用户将收到开户短信。0表示不开户，需要管理员手动未用户开户，可批量选择。
  

字段映射说明：

1. 同步部门

部门的层级关系说明：

部门同步接口：查看文档

https://open.welink.huaweicloud.com/api/contact/v2/departments/bulk

以财经部门同步数据为例：

{
     'corpParentCode': 'Z201',
     'corpDeptCode': 'Z301',
     'deptLevel': '4'
     ...
}

要点说明

• 先创建一层部门，然后再挂靠一层部门各级子部门
  
• 一层部门的corpParentCode为0
  
• 完成部门同步后开始往部门中挂靠人员信息
  
• 人员信息的核心字段corpDeptCode必需在WeLink系统中已经维护，否则人员挂靠不成功
  

同步接口为异步接口，接口仅返回当前请求是否成功，并不返回业务结果，此时可调用查询状态接口查询同步部门状态：

• 当部门同步成功，对应的接口状态码为47119
  
• 状态码为其他值同步失败，根据对应状态码查找失败原因
  

2. 同步人员

人员同步接口：查看文档

https://open.welink.huaweicloud.com/api/contact/v2/users/bulk

以财经部门同步人员数据为例：

{
  'corpDeptCode': 'Z301',
  'corpUserId': 'l00224455', // 员工***标识
  ...// 手机号、邮箱
}

要点说明

• 完成部门同步后开始往部门中挂靠人员信息
  
• 人员信息的核心字段corpDeptCode必需在WeLink系统中已经维护，否则人员挂靠不成功
  
• isOpenAccount：0； 默认不开户
  
• valid字段：0；表示删户
  

同步接口为异步接口，接口仅返回当前请求是否成功，并不返回业务结果，此时可调用查询状态接口查询同步人员状态：

• 当isOpenAccount是0时，即只同步不开户，对应的接口状态码为47107
  
• 当isOpenAccount是1时，同步变开户，对应的接口状态码为47109
  
• 状态码为其他值同步失败，根据对应状态码查找失败原因
  
• 当用户同步完成后，可以调用查询用户userId查询用户对应的userId，并存储userId和corpUserId的映射关系，避免后期重复查询
  

3. 同步周期和同步方式

• 基于常见场景封装方法：如新建部门、新建用户、将用户添加到部门、变更用户到新部门、删除用户、删除部门、更新用户、更新部门
  

// 例如组织架构调整，调用封装方法
def main():
  ...
  createNewDept(deptInfo) // 新建部门
  changeUserToNewDept(userList, corpDeptCode) // 变更人员到新部门
  deleteDept(corpDeptCode) // 删除部门
  ...

• 每3s调用一次接口，1小时可同步12000人
  
• 后续改为增量同步
  
• 先手动验证，再验证自动
  

4. 常见问题说明

• Q: 体验阶段已经手动创建了一些部门，如何获取该部门的corpDeptCode？A: 手动创建的时候，部门ID字段为空，如果要做同步，请手动填充该字段。
  
• Q: WeLink中公司名称是什么含义，一层组织怎么挂靠到公司下？A: WeLink默认公司的corpDeptCode为0，用户在同步一层部门时，请指定该部门的corpParentCode为0。
  
• Q: 更改部门或者人员数据用什么接口？A: 也是使用上述的接口，该接口通过corpUserId来标识用户，修改时修改字段值再次同步即可，如需删除用户或者部门则指定Valid字段位0。
  
• Q: 英文名作用是啥？没有该字段怎么办？A: 用户切换英文版后通讯录中用户将显示英文名，当前英文名还用来生成用户id，建议通过“中文转拼音”的方式或者从“用户邮箱”中提取用户英文名。
  
• Q: 部门架构发生变更，该如何切换？A: 比如要删除一个旧的部门新建新的部门，同时要做人员调整。规则建议：先创建新的部门，然后变更人员的corpDeptCode到该部门，再删除旧部门。
  
• Q: 调用接口时报501？ A: 请确认是否已经申请对应的API权限