跳转至

员工批量同步

功能说明

  • 工号corp_code只支持字母数字，不区分大小写。建议企业用不变且唯一的标识作为工号；
  • 手机号mobile 支持国内外手机号，国外手机必填区号mobile_area，不填写区号默认为86；
  • 该接口最多支持一次性传递50名员工；

接口地址

HTTP请求方式

  • Method: POST
  • Content-Type: application/json

参数说明

  • 公有参数 > 发送请求是必须传入公共参数，详见公共参数

  • 私有参数

参数名称 是否必须 参数类型 长度限制 描述
enterprise_code 否 string [1,20] 企业编号(集团和运营商必填,企业不填)
employee_list 是 json 员工集合
employee_list.code 否 string [1,20] 员工工号
employee_list.userid 是 string [1,100] 员工第三方唯一标识，工号和唯一标识必填其一
employee_list.name 是 string [1,50] 员工姓名
employee_list.status 是 int 员工状态 1 在职 2 离职
employee_list.gender 否 int [1] 性别，1：男；2：女；3：未知
employee_list.email 否 string [1,100] 邮箱，企业内唯一
employee_list.mobile_area 否 int [1,10] 手机区号，国外手机必填，不填默认为国内手机区号(86)
employee_list.mobile 否 string [6,20] 手机，企业内唯一。默认mobile和email之间至少选填一个
employee_list.remark 否 string [0,254] 备注
employee_list.dept_code 否 string [1,50] 部门编号
employee_list.level 否 string [1,50] 员工分级（若传空字符串，则将该员工分级置空）（需先在企业后台开启该功能）
employee_list.category 否 string [] 员工分类，多个分类，用“,”分割（若传空字符串，则将该员工分类置空）（需先在企业后台开启该功能）
employee_list.birth_day 否 string [5,10] 生日，格式为yyyy-MM-dd或者MM-dd，如：1991-01-01或12-31
employee_list.entry_day 否 string [10] 入职日，格式为yyyy-MM-dd，如：2016-02-03
employee_list.card_type 否 int [1] 证件类型，1：身份证；2：护照
employee_list.card_no 否 string [1,30] 证件号码
employee_list.employee_attribute 否 string 无 扩展信息，JsonArray，格式如： List«EmployeeAttribute»（需先确认扩展信息已启用的字段，合同性质、固定电话、级别、分类等默认已启用）
employee_list.cost_center_id 否 int 无 成本中心ID，点击这里查询
  • employee_attribute中的EmployeeAttribute对象
参数名称 是否必须 参数类型 长度限制 描述
attributeCode 是 string [1,100] 扩展字段编号，如：contractNature（合同性质） taxpayerMapper（纳税人归属）taxpayerIdentifier（纳税人识别号）
attributeValue 是 string [1,100] 扩展字段值，如：contractNature对应： 正式员工，试用员工，临时员工，实习生，兼职员工，外聘员工 taxpayerMapper对应纳税人归属id

请求示例（HTTP）

POST /employee/v2/batchSynchronize?access_token=d9d6951d1b57e6cb4ddd6cf32d0d5e56&version=1.0.0&sign=4025567bf21aef6490cb3d1f9630a2b5c32fdb1d&timestamp=1640077417 HTTP/1.1

Host: //openapi.guanaitong.tech/
Content-Type: application/json
Content-Length: 721

{
    "employee_list": [{
        "code": "HB0001",
        "userid": "1",
        "name": "HB0001",
        "gender": 3,
        "status": 1,
        "mobile": "13564307640",
        "birth_day": "1990-10-11",
        "card_type":1,
        "card_no":"110101199010118618",
        "employee_attribute":"[{\"attributeCode\":\"taxpayerIdentifier\",\"attributeValue\":\"18923123654521\"}]",
        "category":"最帅",
        "level":"帅"
    }, {
        "code": "HB0002",
        "userid": "2",
        "name": "HB0002",
        "gender": 3,
        "status": 1,
        "mobile": "13564307641",
        "birth_day": "1995-01-11"
    }, {
        "code": "HB0003",
        "userid": "3",
        "name": "HB0003",
        "gender": 3,
        "status": 1,
        "mobile": "13564307642",
        "birth_day": "1999-12-11"
    }]
}

请求示例（JAVA SDK）

public class Main {
    public static OpenClient openClient = new OpenClient(Constants.BASE_URL_TEST, "xxx", "xxx");
    public static void main(String[] args) {
        EmployeeBatchSyncRequest employeeBatchSyncRequest = new EmployeeBatchSyncRequest();
        List<EmployeeInfo> employeeList = new ArrayList<>();
        employeeBatchSyncRequest.setEmployeeList(employeeList);
        EmployeeInfo employeeInfo = new EmployeeInfo();
        employeeInfo.setUserId("tom082402");
        employeeInfo.setCode("tom082402");
        employeeInfo.setName("tom082402");
        employeeInfo.setGender(1);
        employeeInfo.setStatus(1);
        employeeInfo.setDeptCode("TOM071201");
        employeeInfo.setMobile("16898989110");
        employeeInfo.setMobileArea("86");
        employeeInfo.setEmail("168989890901@tom.com");
        employeeInfo.setBirthDay("1990-07-05");
        employeeInfo.setEntryDay("2022-06-29");
        employeeInfo.setCardType(1);
        ArrayList<String> category = new ArrayList<>();
        category.add("帅哥组");
        category.add("靓妹组");
        employeeInfo.setCategory(String.join(",", category));
        employeeInfo.setCardNo("110101199003070919");
        employeeInfo.setRemark("test");
        employeeInfo.setLevel("金丹");
        ArrayList<EmployeeAttribute> employeeAttribute = new ArrayList<>();
        EmployeeAttribute e = new EmployeeAttribute();
        e.setAttributeCode("politicalVisage");
        e.setAttributeValue("群众");
        employeeAttribute.add(e);
        employeeInfo.setEmployeeAttribute(JSON.toJSONString(employeeAttribute));

        employeeList.add(employeeInfo);
        String synchronize = openClient.employeeApi().batchSynchronize(employeeBatchSyncRequest);
        System.out.println(synchronize);
    }
}

返回参数说明

参数说明 描述
code 返回码，0代表正确返回，详见错误返回码。
msg 如果错误，返回错误信息。
data 如果没有错误，返回业务数据。消息通知标识notifyId,供下次推送消息时对应匹配员工同步情况（设计时该字段长度为100位以内） 。详细请参考回调配置

正确返回示例

{
    "code": 0,
    "data": "589072095bea0f68043a7a2797476ec3",
    "msg": "OK"
}

错误返回示例

{
    "code": 1000240002,
    "msg": "enterprise_code校验失败",
    "data": null
}

常见错误码

错误码 错误信息 排查方法
1000220002 参数验证不通过 检测参数是否按要求填写
1000240002 enterprise_code校验失败 检查enterprise_code是否是已绑定的编码
other 其他公共错误码 其他公共错误码
回到页面顶部