跳转至

员工新增

功能说明

  • 工号corp_code只支持字母数字，不区分大小写。新版本以废弃改用userid；
  • 手机号mobile 支持国内外手机号，国外手机必填区号mobile_area，不填写区号默认为86；

接口地址

HTTP请求方式

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded

参数说明

  • 公有参数

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

  • 私有参数
参数名称 是否必须 参数类型 长度限制 描述
userid 是 string [1,100] 员工第三方唯一标识，不会变更
enterprise_code 否 string [1,20] 企业编号(集团和运营商必填,企业不填)
name 是 string [1,50] 员工姓名，若想加密传输该字段，请联系关爱通人员配置
code 否 string [1,20] 员工工号
gender 否 int [1] 性别，1：男；2：女；3：未知
email 否 string [1,100] 邮箱，企业内唯一
mobile_area 否 int [1,10] 手机区号，国外手机必填，不填默认为国内手机区号(86)
mobile 否 string [6,20] 手机，企业内唯一，默认mobile和email之间至少选填一个
send_invite 否 int [1] 是否发送登录邀请, 1:发送，2:不发送。默认不发送。
remark 否 string [0,254] 备注
dept_code 否 string [1,50] 部门编号
level 否 string [1,50] 员工分级（若传空字符串，则将该员工分级置空）（需先在企业后台开启该功能）
category 否 string [] 员工分类，多个分类，用“,”分割（若传空字符串，则将该员工分类置空）（需先在企业后台开启该功能）
birth_day 否 string [10] 生日，格式为yyyy-MM-dd或者MM-dd，如：1991-01-01或者01-21
entry_day 否 string [10] 入职日，格式为yyyy-MM-dd，如：2016-02-03
card_type 否 int [1] 证件类型，1：身份证；2：护照
card_no 否 string [1,30] 证件号码
allow_simple_pwd 否 int [1] 是否设置简单密码：1.是；2.否。（需提前联系关爱通人员，开通企业设置简单密码的权限）
password 否 string [6,20] 初始密码（字母数字），只有当allow_simple_pwd=1时，生效
employee_attribute 否 string 无 扩展信息，JsonArray，格式如： List«EmployeeAttribute»（需先确认扩展信息已启用的字段，合同性质、固定电话、级别、分类等默认已启用）
cost_center_id 否 int [1,10] 成本中心id,取值范围1~2147483647之间的整数
  • employee_attribute中的EmployeeAttribute对象
参数名称 是否必须 参数类型 长度限制 描述
attributeCode 是 string [1,100] 扩展字段枚举值，如：contractNature（合同性质）； taxpayerMapper（纳税人归属id，一般不用）；taxpayerIdentifier（纳税人识别号））
attributeValue 是 string [1,100] 扩展字段值，如：contractNature对应： 正式员工，试用员工，临时员工，实习生，兼职员工，外聘员工； taxpayerMapper对应纳税人归属id ；taxpayerIdentifier对应纳税人识别号

请求示例（HTTP）

POST /employee/add HTTP/1.1
Host: openapi.guanaitong.tech
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

access_token=1ba50b8f418a3ceeba989d7b789de149&birth_day=1991-02-20&card_no=371322199105204626&
card_type=1&corp_code=SN112&cost_center_id=1234&email=12345678@qq.com&entry_day=2016-10-01&dept_code=A001&level=S1&
timestamp=1492671463&send_invite=1&mobile_area=86&mobile=15588652444&sign=ada2316deb82816d61a7a40dfba3553a34a2e82e&
gender=1&remark=添加员工&name=zhangfei1&userid=1001

请求示例（JAVA SDK）

public class Main {
    public static OpenClient openClient = new OpenClient(Constants.BASE_URL_TEST, "xxx", "xxx");
    public static void main(String[] args) {
        EmployeeAddRequest employeeAddRequest = new EmployeeAddRequest();
        employeeAddRequest.setUserId("tom082401");
        employeeAddRequest.setCode("tom082401");
        employeeAddRequest.setName("tom082401");
        employeeAddRequest.setGender(1);
        employeeAddRequest.setDeptCode("TOM071201");
        employeeAddRequest.setMobile("16898989110");
        employeeAddRequest.setEmail("168989890901@tom.com");
        employeeAddRequest.setBirthDay("1990-07-05");
        employeeAddRequest.setEntryDay("2022-06-29");
        employeeAddRequest.setCardType(1);
        ArrayList<String> category = new ArrayList<>();
        category.add("帅哥组");
        employeeAddRequest.setCategory(category);
        employeeAddRequest.setCardNo("110101199003070919");
        employeeAddRequest.setRemark("test");
        employeeAddRequest.setLevel("金丹");
        ArrayList<EmployeeAttribute> employeeAttribute = new ArrayList<>();
        EmployeeAttribute e = new EmployeeAttribute();
        e.setAttributeCode("politicalVisage");
        e.setAttributeValue("群众");
        employeeAttribute.add(e);
        employeeAddRequest.setEmployeeAttribute(employeeAttribute);

        String userid = openClient.employeeApi().add(employeeAddRequest);
        System.out.println(userid);
    }
}

返回参数说明

参数说明 描述
code 返回码，0代表正确返回
msg 如果错误，返回错误信息。
data 员工第三方唯一标识userid

正确返回示例

{
  "code": 0,
  "data": "1001",
  "msg": "OK"
}

错误返回示例

{
  "code": 1002219003,
  "msg": "员工工号已存在",
  "data": null
}

常见错误码

错误码 错误信息 排查方法
1000220002 参数验证不通过 检测参数是否符合要求，如：entryDay日期格式错误, 需要yyyy-MM-dd的日期格式
1002219003 员工工号已存在 员工工号已存在，工号企业下唯一
1000220010 dept_code not exists ! 部门编号不存在，校验是否对应部门已添加
1002218004 会员：邮箱已存在 邮箱已存在，邮箱企业下唯一
1002218007 会员：手机已存在 手机已存在，手机号企业下唯一
1002219046 员工身份证号码错误 身份证类型是大陆身份，不符合大陆身份证号格式

护照，只能为1-20位大小写字母和数字
1000220030 该员工分级未设置 需要去企业管理后台设置
1000210028 该员工分类未设置 需要去企业管理后台设置
1000220072 politicalVisage1未启用,扩展信息字段attributeCode错误或未启用 需要去企业管理后台设置
1000240002 enterprise_code校验失败 检查enterprise_code是否是已绑定的编码
1002219069 员工国际区号不存在 对应手机号区号，检查是否是正确的国际电话区号
other 其他公共错误码 其他公共错误码
回到页面顶部