Yach用户管理

创建用户

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/user/create?access_token=ACCESS_TOKEN
请求方式	POST
参数	见【参数】
返回值	见【返回值】

请求包结构体

{
    "userid": "yach076421",
    "name": "张三",
    "dept_info" : [
            {
                "user_type":"全职员工",
                "dept_id":"6912",
                "empl_rcd":"0",
                "position":"效能与系统管理部研发工程师",
                "level":"2.1",
                "whether_flag":"false"
          },
          {
               "user_type":"兼职员工",
               "dept_id":"5",
               "empl_rcd":"1"
          }
    ],
    "mobile": "1xxxxxxxxxx",
    "email": "lucy@tal.com",
    "work_code": "076421",
    "whether_flag": false,
    "ex": {
        "okr":"xxxx",
        "未来人才":"xxxxxx"
    }
}

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
userid	String	否	员工在当前企业内的唯一标识，也称staffId。由企业在创建时指定，并代表一定含义比如工号，创建后不可修改，企业内必须唯一。长度为1~64个字符
name	String	是	成员名称。长度为1~64个字符
phone_area_code	String	否	手机号区号 +86 中国大陆、 +852 中国香港 、+853 中国澳门、 +886 中国台湾 、+1美国 或 加拿大 、+44 英国
sex	String	否	性别
dept_info	JSON	是	json字符串 （包含empl_rcd、dept_id、position、user_type、level、whether_flag）
└ empl_rcd	String	是	岗位：0、1、3 等
└ dept_id	String	是	部门id
└ position	String	否	职位信息。长度为0~64个字符
└ user_type	String	是	员工类型：全职员工、全职教师、兼职员工、兼职教师、在编实习、专职教师、外包员工、其他
└ level	String	否	职级 1.1 、2.1
└ whether_flag	String	否	是否高管模式，true表示是，false表示不是。
mobile	String	是	手机号码，企业内必须唯一，不可重复。
email	String	否	邮箱。长度为0~64个字符。企业内必须唯一，不可重复
pic	String	否	头像url
work_code	String	否	员工工号，对应显示到OA后台和客户端个人资料的工号栏目。长度为0~64个字符
ex	JSON	否	移动端-扩展属性，可以设置多种属性（在手机端个人信息页面显示）
ex_pc	JSON	否	PC端-扩展属性，可以设置多种属性（在手机端个人信息页面显示）
office_addr	String	否	办公地点，json字符串 （包含country、province、city、area、office_building、office_floor、other_addr）
└ country	String	否	国家
└ province	String	否	省份
└ city	String	否	城市名称
└ area	String	否	城区名称
└ office_building	String	否	楼宇名称
└ office_floor	String	否	楼层
└ other_addr	String	否	其他

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "userid": "yach076421"
     }
}

更新用户

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/user/update?access_token=ACCESS_TOKEN
请求方式	POST
参数	见【参数】
返回值	见【返回值】

请求包结构体

{
    "userid": "yach076421",
    "name": "张三",
    "dept_info" : [
            {
                "user_type":"全职员工",
                "dept_id":"6912",
                "empl_rcd":"0",
                "position":"效能与系统管理部研发工程师",
                "level":"2.1",
                "whether_flag":"false"
          },
          {
              "user_type":"兼职员工",
              "dept_id":"5",
              "empl_rcd":"1"
          }
    ],
    "mobile": "1xxxxxxxxxx",
    "email": "lucy@tal.com",
    "work_code": "076421",
    "whether_flag": false,
    "ex": {
        "okr":"xxxx",
        "未来人才":"xxxxxx"
    }
}

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
userid	String	否	员工在当前企业内的唯一标识，也称staffId。由企业在创建时指定，并代表一定含义比如工号，创建后不可修改，企业内必须唯一。长度为1~64个字符
name	String	是	成员名称。长度为1~64个字符
phone_area_code	String	否	手机号区号 +86 中国大陆、 +852 中国香港 、+853 中国澳门、 +886 中国台湾 、+1美国 或 加拿大 、+44 英国
sex	String	否	性别
dept_info	JSON	是	json字符串 （包含empl_rcd、dept_id、position、user_type、level、whether_flag）
└ empl_rcd	String	是	岗位：0、1、3 等
└ dept_id	String	是	部门id
└ position	String	否	职位信息。长度为0~64个字符
└ user_type	String	是	员工类型：全职员工、全职教师、兼职员工、兼职教师、在编实习、专职教师、外包员工、其他
└ level	String	否	职级 1.1 、2.1
└ whether_flag	String	否	是否高管模式，true表示是，false表示不是。
mobile	String	是	手机号码，企业内必须唯一，不可重复。
email	String	否	邮箱。长度为0~64个字符。企业内必须唯一，不可重复
pic	String	否	头像url
work_code	String	否	员工工号，对应显示到OA后台和客户端个人资料的工号栏目。长度为0~64个字符
ex	JSON	否	移动端-扩展属性，可以设置多种属性（在手机端个人信息页面显示）
ex_pc	JSON	否	PC端-扩展属性，可以设置多种属性（在手机端个人信息页面显示）
office_addr	String	否	办公地点，json字符串 （包含country、province、city、area、office_building、office_floor、other_addr）
└ country	String	否	国家
└ province	String	否	省份
└ city	String	否	城市名称
└ area	String	否	城区名称
└ office_building	String	否	楼宇名称
└ office_floor	String	否	楼层
└ other_addr	String	否	其他

返回值

{
    "code": 200,
    "msg": ""
}

删除用户

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/user/delete?access_token=ACCESS_TOKEN
请求方式	GET
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
userid	String	是	员工userid

返回值

{
    "code": 200,
    "msg": ""
}

封禁用户

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/user/forbidden?access_token=ACCESS_TOKEN
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
user_id	String	是	要禁用的用户yachid
operator_uid	String	是	操作人的用户yachid
status	String	是	用户状态（4:封禁 1:解禁)，目前只支持这两种设置
reason	String	是	操作原因说明
text	String	是	跟已禁用的用户聊天时的自动回复文本
at_user_list	String	否	@人列表，传work_code，通过"|"分开

返回值

{
    "code": 200,
    "msg": "",
    "obj": []
}

通过userid获取用户详情

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/user/get?access_token=ACCESS_TOKEN
请求方式	GET
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
userid	String	是	员工id

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "userid": "Yach076429",
        "dept_info": [
            {
                "user_type": "全职员工",
                "empl_rcd": "0",
                "position": "效能与系统管理部研发工程师",
                "level": "2.2",
                "whether_flag": false,
                "dept_id": "6912"
            },
            {
                "user_type": "兼职员工",
                "empl_rcd": "1",
                "position": null,
                "level": "0.0",
                "whether_flag": false,
                "dept_id": "5"
            }
        ],
        "work_code": "076429",
        "name": "邢晋刚",
        "mobile": "18601242463",
        "email": "xingjingang@tal.com",
        "pic": "https://yach-static.zhiyinlou.com/yach/avatar1/a5133760d21ba0e8c36fefef957963f4_s120.jpg",
        "sex": "男",
        "ex":"{\"okr\":\"http:\\/\\/www.zhiyinlou.com21111\",\"\未\来\人\才\":\"http:\\/\\/sso.100tal.com\"}"
    }
}

通过工号获取用户详情

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/user/get_by_workcode?access_token=ACCESS_TOKEN
请求方式	GET
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
work_code	String	是	员工工号

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "userid": "Yach076429",
        "dept_info": [
            {
                "user_type": "全职员工",
                "empl_rcd": "0",
                "position": "效能与系统管理部研发工程师",
                "level": "2.2",
                "whether_flag": false,
                "dept_id": "6912"
            },
            {
                "user_type": "兼职员工",
                "empl_rcd": "1",
                "position": null,
                "level": "0.0",
                "whether_flag": false,
                "dept_id": "5"
            }
        ],
        "work_code": "076429",
        "name": "邢晋刚",
        "mobile": "18601242463",
        "email": "xingjingang@tal.com",
        "pic": "https://yach-static.zhiyinlou.com/yach/avatar1/a5133760d21ba0e8c36fefef957963f4_s120.jpg",
        "sex": "男",
        "ex":"{\"okr\":\"http:\\/\\/www.zhiyinlou.com21111\",\"\未\来\人\才\":\"http:\\/\\/sso.100tal.com\"}"
    }
}

通过手机号查询用户详情

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/user/get_by_mobile?access_token=ACCESS_TOKEN
请求方式	GET
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
mobile	String	是	员工手机号

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "userid": "Yach076429",
        "dept_info": [
            {
                "user_type": "全职员工",
                "empl_rcd": "0",
                "position": "效能与系统管理部研发工程师",
                "level": "2.2",
                "whether_flag": false,
                "dept_id": "6912"
            },
            {
                "user_type": "兼职员工",
                "empl_rcd": "1",
                "position": null,
                "level": "0.0",
                "whether_flag": false,
                "dept_id": "5"
            }
        ],
        "work_code": "076429",
        "name": "邢晋刚",
        "mobile": "18601242463",
        "email": "xingjingang@tal.com",
        "pic": "https://yach-static.zhiyinlou.com/yach/avatar1/a5133760d21ba0e8c36fefef957963f4_s120.jpg",
        "sex": "男",
        "ex":"{\"okr\":\"http:\\/\\/www.zhiyinlou.com21111\",\"\未\来\人\才\":\"http:\\/\\/sso.100tal.com\"}"
    }
}

获取用户的分组列表

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/team/index/lists
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
work_code	String	是	员工工号

返回值

{
    "code": 200,
    "msg": "",
    "obj": [
        {
            "id": 477245,
            "name": "我的上级和平级",
            "type": 0,
            "uid": 228215,
            "del_tag": 0,
            "create_time": 1601289285,
            "user_count": "16",
            "ex": "",
            "sub_type": 0
        },
        {
            "id": 470323,
            "name": "未来样儿",
            "type": 1,
            "uid": 228215,
            "del_tag": 0,
            "create_time": 1601238863,
            "user_count": 0,
            "ex": "",
            "sub_type": 1
        },
        {
            "id": 477247,
            "name": "我的关注",
            "type": 1,
            "uid": 228215,
            "del_tag": 0,
            "create_time": 1601289285,
            "user_count": "1",
            "ex": "",
            "sub_type": 0
        }
    ]
}

获取分组成员列表

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/team/index/members
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
team_id	String	是	分组id
op_uid	String	是	当前操作用户的id(分组拥有人的id)，“获取用户的分组列表”接口返回的uid字段
page	String	否	页码，默认为1
size	String	否	每页个数，默认为20

返回值

{
    "code": 200,
    "msg": "",
    "obj": [
         {
            "id": 299468,
            "name": "秦正云",
            "work_code": "176742",
            "pic": "https://yach-static.zhiyinlou.com/yach/avatar1/92f8e69e705e750191461e33f24d6630.jpg",
            "uuid": "Yach176742",
            "dept_full_name": "好未来教育科技集团-集团总部-刘亚超-效能与流程系统部-研发团队-Yach研发组"
        }
    ]
}

添加分组成员

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/team/index/add/user
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
team_id	String	是	分组id
op_uid	String	是	当前操作用户的 uid
uid	String	是	添加人 uuid, 多个以英文 | 拼接

返回值

{
  "code": 200,
  "msg": "",
  "obj": []
}

删除分组成员

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/team/index/del/user
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
team_id	String	是	分组id
op_uid	String	是	当前操作用户的 uid
uid	String	是	添加人 uuid, 多个以英文 | 拼接

返回值

{
  "code": 200,
  "msg": "",
  "obj": []
}

根据部门、职级、族群ID查询群组成员

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境

概述

名称	值
地址	/oapi/user/label/list
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
dept_id	String	是	部门id
level	String	否	职级，示例：1.2
fetch_child	String	否	1为递归查询子节点的用户，0为不递归，只查询当前节点下的员工，默认为0
only_id	String	否	是否只返回ID，0为否，1为是，默认为0
page	String	否	页码，默认为1
size	String	否	每页个数，默认为20

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "list": [{
            "id": 309206,
            "name": "云信6",
            "name_en": "",
            "name_nick": "",
            "name_pinyin": "yunxin",
            "work_code": "997905",
            "dept_id": "",
            "dept_ids": "",
            "dept_all_ids": null,
            "dept_name": "好未来教育科技集团",
            "dept_names": "",
            "sex": null,
            "position": "研发工程师",
            "birthday": null,
            "emptype": null,
            "dd_id": "",
            "pic": "https://yach-static.zhiyinlou.com/yach/avatar1/12982bf25ec614dd264dd0a80699b9f0.jpg",
            "mobile": "19888880013",
            "email": "",
            "sign": "",
            "status": 1,
            "phone_area_code": "+86",
            "cloudtoken": "6918407fe5ffd60a57d25f53ead8d15c",
            "level": "2.1",
            "whether_flag": 0,
            "type": 0,
            "cdate": "2021-03-25 14:40:25",
            "cuser_id": 0,
            "cuser_name": "",
            "udate": "2021-03-25 14:59:26",
            "uuser_id": 0,
            "uuser_name": "",
            "del_tag": 0,
            "job_code": "0",
            "cp_id": 1,
            "user_type": 1,
            "uuid": "yach999771",
            "ex": "",
            "space_addr": "",
            "avatar_color": "",
            "avatar_label": "",
            "avatar_type": 0,
            "user_type_sub": 1,
            "dept_info": [{
                "id": 218806,
                "user_id": 309206,
                "user_type": 1,
                "og_id": 6912,
                "empl_rcd": 0,
                "user_type_name": "全职员工"
            }]
        }],
        "total": "192",
        "visible_total": "192"
    }
}

设置手机号变更订阅（目前只开放给好未来）

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境 (具备调试条件)

概述

名称	值
地址	/corp/set/notify?access_token=ACCESS_TOKEN
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
notify_url	String	是	回调地址
common_key	String	是	用于回调时，生成签名的加密key

回调签名加密方法（php）

function signGenerate($params, $common_key)
{
    ksort($params);
    reset($params);
    $paramsJoin = [];
    foreach($params as $key => $value) {
        if ($key === 'sign' || $key === 'signature') {
            continue;
        }
        $paramsJoin[] = "{$key}={$value}";
    }
    $paramsJoin[] = 'key=' . $common_key;
    $paramsString = implode('&', $paramsJoin);
    return strtolower(md5($paramsString));
}

返回值

{
    "code": 200,
    "msg": "",
    "obj": []
}

修改用户手机号（目前只开放给好未来）

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境 (具备调试条件)

概述

名称	值
地址	/corp/modify/mobile?access_token=ACCESS_TOKEN
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
user_id	String	是	用户的yach ID
mobile	String	是	用户的新手机号
phone_area_code	String	否	国家码，带+，无该参数默认是'+86'

返回值

{
    "code": 200,
    "msg": "",
    "obj": []
}

我的伙伴创建

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境 (具备调试条件)

概述

名称	值
地址	/partner/index/create?access_token=ACCESS_TOKEN
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
name	String	是	分组名称
type	String	是	分组类型（0:正式分组(名称和成员不可修改)，1:我的关注(名称不可修改，成员可修改)，2:自定义分组(名称和成员都可以修改)）
op_uid	String	是	分组拥有人的yach ID
members	String	是	组成员的yach ID，多个以英文 | 拼接

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "id": 1277327,
        "has_before": 0
    }
}

更新我的伙伴

host: https://yach-oapi.zhiyinlou.com 正式环境

host: https://yach-oapi-test.zhiyinlou.com 测试环境 (具备调试条件)

概述

名称	值
地址	/partner/index/update?access_token=ACCESS_TOKEN
请求方式	POST
参数	见【参数】
返回值	见【返回值】

参数

参数	参数类型	必须	说明
access_token	String	是	调用接口凭证
team_id	String	是	分组ID
op_uid	String	是	分组拥有人的yach ID
name	String	否	分组名称，只有2类型的分组才有权限修改
members	String	否	需要被操作的分组成员yach ID，多个以英文 | 拼接。只有1、2类型的分组才有权限修改
op_type	String	否	对成员的操作类型：add-添加，delete-删除；当members参数有值时，该参数必传

返回值

{
    "code": 200,
    "msg": "",
    "obj": []
}